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.

33.2 KB
Raw Blame
/**
 * What every launch of an engine hands tmux, byte for byte: the pane's argv, the script a POSIX login shell
 * sources from its one-time file, the engine's own command, and the environment, extra argv and cleared
 * variables a relaunch is built with. Recorded from the launch code as it stood before Claude Code's and
 * Codex's launch specifics became declared data on their launch contracts, applied by the kit
 * (docs/design/2026-10-08-engine-launch.md): the Codex pane script's owned-process probe and startup retry,
 * its own-login provider, and the two engines' harness context and environment flags.
 *
 * The shapes are the callers': create (a first prompt, a harness, a grid, an install when missing), the
 * adoption of a terminal's conversation (resume, waiting out its turn), fork, restart and its fresh fallback,
 * restore, resume, retarget onto a grid, every permission mode, a Codex profile (CODEX_HOME), a moved engine
 * home, an engine at an overridden path (npm's Codex wrapper), a remote Codex server's flag passed through,
 * every login shell family, with and without the daemon's tmux. Every other engine is recorded in the common
 * shapes too, since they share the wrapper.
 *
 * Paths that differ between machines are written as placeholders (`<home>`, `<data>`, `<daemon-node>`, the
 * one-time file's name). What the launch says differs by platform (a folder the shell cannot read names macOS's
 * privacy settings, else the folder's permissions), so every case is recorded on darwin and on linux, with
 * `process.platform` pinned, whichever machine runs the spec: linux's cases are stored where they differ. A script is kept once, by its hash, since most shapes differ only in argv, and as
 * runs of a table of its distinct lines: the 170 scripts share 243 lines. A command that is the end of its
 * argv is kept as its length. Each case is compared as full text, so a failure shows the script itself.
 *
 * `RECORD_LAUNCH_GOLDEN=1` writes the fixture. Record it again only for a change meant to alter what a launch
 * hands tmux, and say so in that change.
 */
import { createHash } from 'node:crypto'
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { homedir, tmpdir } from 'node:os'
import { dirname, join } from 'node:path'
import { fileURLToPath } from 'node:url'
import { afterAll, beforeAll, describe, expect, it } from 'vitest'
import { env } from '../config/env.js'
import { harnessAdapter, HARNESS_ADAPTERS } from '../dsh/adapters.js'
import { DSH_SESSION_ENV, harnessEnvToClear } from '../dsh/launch.js'
import { baseNode } from '../harnessd/baseNode.js'
import { engineInstallRecipe } from '../lib/engineInstall.js'
import {
  buildEngineCommandArgv, buildEngineLaunchArgv, PERMISSION_MODES, supportsFirstPrompt, type LaunchCommandOptions,
} from '../lib/engineLaunch.js'
import { GRID_CONFLICTING_ENV_VARS, type GridLaunchOverride } from '../lib/gridLaunch.js'
import { buildLaunchOverrides, type LaunchOverridesDeps, type LaunchSource } from '../lib/launchOverrides.js'
import { ENGINES, type AgentEngine } from './types.js'
import { gridLaunchInProcess } from '../testing/gridLaunchInProcess.js'

const GOLDEN = fileURLToPath(new URL('./__fixtures__/launch-argv.golden.json', import.meta.url))
const RECORD = process.env.RECORD_LAUNCH_GOLDEN === '1'

const SHELLS = {
  zsh: '/bin/zsh', bash: '/bin/bash', sh: '/bin/sh', ksh: '/bin/ksh', fish: '/opt/homebrew/bin/fish', tcsh: '/bin/tcsh',
  // No login shell the daemon can use: a plain engine runs as its bare command.
  none: '', relative: 'zsh',
} as const
type Shell = keyof typeof SHELLS
const TMUX = { tmux: '/opt/homebrew/bin/tmux', none: null, relative: 'tmux' } as const
type Tmux = keyof typeof TMUX
const RUNTIME_NODE = '/opt/harness/runtime/node-v22/bin/node'
const GRID_BIN = { bare: 'grid', managed: '/opt/harness/runtime/grid/bin/grid' } as const

const PROMPT = `Fix the "parser" — it's broken; $HOME stays literal, as does \`date\` and a 'quote' ✓`
const GRID_ARGS = ['-c', 'model_providers.grid.base_url="https://grid.example/relay/v1"', '-m', 'gpt-5']
const REMOTE_ARGS = ['--remote', 'ws://127.0.0.1:4500']
const CWD = "/work/my project's folder"
const CLEAR_GRID = ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY', ...harnessEnvToClear({})]

/** A caller's options, as each one assembles them (core/agents/create.ts, fork.ts, restart.ts, swap.ts,
 *  lib/resumeAgentService.ts, the restore in core/main.ts). `null` for a shape this engine cannot take. */
function shapes(engine: AgentEngine): Record<string, LaunchCommandOptions | null> {
  const install = engineInstallRecipe(engine)
  const prompt = supportsFirstPrompt(engine)
  return {
    'new': {},
    'new, approving': { bypassPermission: true },
    'new, not approving': { bypassPermission: false },
    'new, a mode the engine lacks': { permissionMode: 'no-such-mode', bypassPermission: true },
    ...Object.fromEntries(Object.keys(PERMISSION_MODES[engine] ?? {}).map((mode) => [`new, mode ${mode}`, { permissionMode: mode }])),
    'first prompt': prompt ? { firstPrompt: PROMPT } : null,
    'resume': { resumeSessionId: 'sess-0001' },
    'resume, approving': { resumeSessionId: 'sess-0001', bypassPermission: true },
    'fork': { forkSessionId: 'src-0001' },
    'fork outranks resume': { forkSessionId: 'src-0001', resumeSessionId: 'sess-0001', bypassPermission: true },
    'fork with a prompt': prompt ? { forkSessionId: 'src-0001', firstPrompt: PROMPT } : null,
    'grid argv': { extraArgs: GRID_ARGS, clearEnv: CLEAR_GRID },
    'remote server argv passed through': { extraArgs: REMOTE_ARGS },
    'install first': { installFirst: 'npm install -g example-engine' },
    'create': {
      bypassPermission: true, permissionMode: Object.keys(PERMISSION_MODES[engine] ?? {})[0], extraArgs: GRID_ARGS,
      installIfMissing: install, clearEnv: CLEAR_GRID, cwd: CWD, harnessNode: true,
      ...(prompt ? { firstPrompt: PROMPT } : {}), terminalHint: { machineName: 'studio-mac' },
    },
    'create, plain': { bypassPermission: true, installIfMissing: install, clearEnv: harnessEnvToClear(undefined), cwd: CWD, terminalHint: { machineName: 'studio-mac' } },
    'adopt, waiting out the turn': {
      bypassPermission: true, resumeSessionId: 'sess-0001', installIfMissing: install, clearEnv: harnessEnvToClear(undefined), cwd: CWD,
      waitForPid: { pid: 4242, name: 'Codex "cli"; rm -rf' },
    },
    'adopt, now, carrying on': prompt ? { bypassPermission: true, resumeSessionId: 'sess-0001', firstPrompt: 'continue', cwd: CWD } : null,
    'fork shape': {
      clearEnv: harnessEnvToClear(undefined), bypassPermission: true, extraArgs: ['-c', 'model_provider="openai"'], installIfMissing: install,
      cwd: CWD, forkSessionId: 'src-0001', ...(prompt ? { firstPrompt: PROMPT } : {}),
    },
    'restart': {
      bypassPermission: true, resumeSessionId: 'sess-0001', cwd: CWD, extraArgs: GRID_ARGS, clearEnv: CLEAR_GRID, harnessNode: true,
    },
    'restart, fresh fallback': { bypassPermission: false, cwd: CWD, extraArgs: GRID_ARGS, clearEnv: CLEAR_GRID },
    'restore': {
      resumeSessionId: 'sess-0001', bypassPermission: true, installIfMissing: install, cwd: CWD,
      extraArgs: ['-c', 'model_provider="openai"'], clearEnv: harnessEnvToClear(undefined), harnessNode: true,
    },
    'resume service': {
      resumeSessionId: 'sess-0001', bypassPermission: false, permissionMode: 'ask', cwd: CWD, clearEnv: harnessEnvToClear(undefined),
      installIfMissing: install,
    },
    'retarget onto a grid': { bypassPermission: true, resumeSessionId: 'sess-0001', cwd: CWD, extraArgs: GRID_ARGS, clearEnv: CLEAR_GRID },
  }
}

interface ArgvRecord { argv?: string[]; command?: string[]; script?: string; throws?: string }
/** One platform's record. */
interface Cases {
  argv: Record<string, ArgvRecord>
  overrides: Record<string, unknown>
  adapters: Record<string, unknown>
}
/** darwin's cases, and linux's where they differ, over one table of scripts. */
interface Golden extends Cases {
  scripts: Record<string, string>
  linux: Cases
}
type StoredArgv = Record<string, Omit<ArgvRecord, 'command'> & { command?: string[] | number }>
/** As stored: scripts as runs of `lines`, and a command that ends its argv as its length. */
interface Stored {
  lines: string[]
  scripts: Record<string, string>
  argv: StoredArgv
  overrides: Record<string, unknown>
  adapters: Record<string, unknown>
  linux: { argv: StoredArgv; overrides: Record<string, unknown>; adapters: Record<string, unknown> }
}

const PLATFORMS = ['darwin', 'linux'] as const
type Platform = (typeof PLATFORMS)[number]

/** Runs `run` with `process.platform` reading `platform`, which the launch reads as it builds the script. */
async function onPlatform<T>(platform: Platform, run: () => T | Promise<T>): Promise<T> {
  const real = Object.getOwnPropertyDescriptor(process, 'platform')!
  Object.defineProperty(process, 'platform', { ...real, value: platform })
  try { return await run() } finally { Object.defineProperty(process, 'platform', real) }
}

/** The cases of `other` whose record differs from `base`'s. */
function differences<T>(base: Record<string, T>, other: Record<string, T>): Record<string, T> {
  return Object.fromEntries(Object.entries(other).filter(([name, value]) => JSON.stringify(value) !== JSON.stringify(base[name])))
}

/** A platform's full record: darwin's, with linux's differences over it. */
function casesOn(golden: Golden, platform: Platform): Cases {
  if (platform === 'darwin') return { argv: golden.argv, overrides: golden.overrides, adapters: golden.adapters }
  return {
    argv: { ...golden.argv, ...golden.linux.argv },
    overrides: { ...golden.overrides, ...golden.linux.overrides },
    adapters: { ...golden.adapters, ...golden.linux.adapters },
  }
}

function store(golden: Golden): Stored {
  const lines: string[] = []
  const index = new Map<string, number>()
  const scripts: Record<string, string> = {}
  for (const [hash, text] of Object.entries(golden.scripts).sort(([a], [b]) => a.localeCompare(b))) {
    const ids = text.split('\n').map((line) => {
      if (!index.has(line)) { index.set(line, lines.length); lines.push(line) }
      return index.get(line)!
    })
    const runs: string[] = []
    for (let i = 0; i < ids.length;) {
      let j = i
      while (j + 1 < ids.length && ids[j + 1] === ids[j]! + 1) j++
      runs.push(i === j ? `${ids[i]}` : `${ids[i]}-${ids[j]}`)
      i = j + 1
    }
    scripts[hash] = runs.join(',')
  }
  const compact = (argv: Record<string, ArgvRecord>): StoredArgv => Object.fromEntries(Object.entries(argv).map(([name, value]) => {
    const tail = value.argv && value.command && value.command.length <= value.argv.length
      && JSON.stringify(value.argv.slice(value.argv.length - value.command.length)) === JSON.stringify(value.command)
    return [name, tail ? { ...value, command: value.command!.length } : value]
  }))
  return {
    lines, scripts, argv: compact(golden.argv), overrides: golden.overrides, adapters: golden.adapters,
    linux: { argv: compact(golden.linux.argv), overrides: golden.linux.overrides, adapters: golden.linux.adapters },
  }
}

function load(stored: Stored): Golden {
  const scripts = Object.fromEntries(Object.entries(stored.scripts).map(([hash, runs]) => [hash, runs.split(',').flatMap((run) => {
    const [from, to = from] = run.split('-').map(Number)
    return Array.from({ length: to! - from! + 1 }, (_, k) => stored.lines[from! + k]!)
  }).join('\n')]))
  const expand = (argv: StoredArgv): Record<string, ArgvRecord> => Object.fromEntries(Object.entries(argv).map(([name, value]) => [name, typeof value.command === 'number'
    ? { ...value, command: value.argv!.slice(value.argv!.length - value.command) }
    : value as ArgvRecord]))
  return {
    argv: expand(stored.argv), scripts, overrides: stored.overrides, adapters: stored.adapters,
    linux: { argv: expand(stored.linux.argv), overrides: stored.linux.overrides, adapters: stored.linux.adapters },
  }
}

/** One case a line, so a re-record's diff names the cases it changed. */
function serialize(stored: Stored): string {
  const block = (entries: Array<[string, unknown]>): string => entries.map(([key, value]) => ` ${JSON.stringify(key)}: ${JSON.stringify(value)}`).join(',\n')
  return `{\n"lines": [\n${stored.lines.map((line) => ` ${JSON.stringify(line)}`).join(',\n')}\n],\n`
    + `"scripts": {\n${block(Object.entries(stored.scripts))}\n},\n`
    + `"argv": {\n${block(Object.entries(stored.argv))}\n},\n`
    + `"overrides": {\n${block(Object.entries(stored.overrides))}\n},\n`
    + `"adapters": {\n${block(Object.entries(stored.adapters))}\n},\n`
    + `"linux": {\n"argv": {\n${block(Object.entries(stored.linux.argv))}\n},\n`
    + `"overrides": {\n${block(Object.entries(stored.linux.overrides))}\n},\n`
    + `"adapters": {\n${block(Object.entries(stored.linux.adapters))}\n}\n}\n}\n`
}

let root = ''
let dataDir = ''
const saved: Record<string, string | undefined> = {}
const savedEnv: Record<string, string | undefined> = {}
const ENGINE_PATHS = ['CLAUDE_PATH', 'CURSOR_PATH', 'OPENCODE_PATH', 'PI_PATH', 'HERMES_PATH', 'COMMANDCODE_PATH', 'DEVIN_PATH', 'MUSE_PATH',
  'AMP_PATH', 'KILO_PATH', 'GROK_PATH', 'AGY_PATH', 'COPILOT_PATH'] as const
const PROCESS_VARS = ['CODEX_PATH', 'CODEX_HOME', 'ZDOTDIR', 'HARNESS_OS', 'HARNESS_GRID_BIN', 'SHELL'] as const
const config = env as unknown as Record<string, string | undefined>

beforeAll(() => {
  root = mkdtempSync(join(tmpdir(), 'launch-golden-'))
  dataDir = join(root, 'data')
  mkdirSync(dataDir)
  saved.ADAPTER_DATA_DIR = env.ADAPTER_DATA_DIR
  saved.CODEX_HOME = env.CODEX_HOME
  env.ADAPTER_DATA_DIR = dataDir
  // The profile is a throwaway one (HOME for POSIX, USERPROFILE for Windows), so no engine home is the person's.
  mkdirSync(join(root, 'home'))
  for (const name of ['HOME', 'USERPROFILE']) { savedEnv[name] = process.env[name]; process.env[name] = join(root, 'home') }
  env.CODEX_HOME = join(homedir(), '.codex')
  for (const name of ENGINE_PATHS) { savedEnv[`config:${name}`] = config[name]; config[name] = undefined }
  for (const name of PROCESS_VARS) { savedEnv[name] = process.env[name]; delete process.env[name] }
  // A zsh user with a startup file of their own: the plain launch. The new-user guard has its own shape below.
  const zdotdir = join(root, 'zdotdir')
  mkdirSync(zdotdir)
  writeFileSync(join(zdotdir, '.zshrc'), '')
  process.env.ZDOTDIR = zdotdir
})

afterAll(() => {
  env.ADAPTER_DATA_DIR = saved.ADAPTER_DATA_DIR!
  env.CODEX_HOME = saved.CODEX_HOME!
  for (const name of ENGINE_PATHS) config[name] = savedEnv[`config:${name}`]
  for (const name of [...PROCESS_VARS, 'HOME', 'USERPROFILE']) {
    if (savedEnv[name] === undefined) delete process.env[name]
    else process.env[name] = savedEnv[name]
  }
  rmSync(root, { recursive: true, force: true })
})

/** The POSIX shell a launch with no login shell of its own runs its script in (engineLaunch.ts `posixRunner`). */
const posixRunner = (): string => existsSync('/bin/dash') ? '/bin/dash' : '/bin/sh'

function placeholders(text: string): string {
  const node = baseNode(process.execPath)
  // Quoted, as every script quotes them: a Node in /usr/bin must not turn `/usr/bin/env` into a placeholder.
  return text
    .split(`'${node}'`).join("'<daemon-node>'")
    .split(`'${dirname(node)}'`).join("'<daemon-node-dir>'")
    .split(dataDir).join('<data>')
    .split(homedir()).join('<home>')
    .split(root).join('<root>')
    .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.sh/g, '<one-time>.sh')
    .split(`exec ${posixRunner()} '`).join("exec <posix-runner> '")
}

/** The script a launch's argv names, from its one-time file, and the argv with the file's name as a placeholder. */
function record(argv: string[], scripts: Record<string, string>, noLoginShell: boolean): ArgvRecord {
  const out = argv.map((arg, index) => index === 0 && noLoginShell && arg === posixRunner() ? '<posix-runner>' : placeholders(arg))
  let script: string | undefined
  for (const arg of argv) {
    const sourced = /^\. '(.+)'$/s.exec(arg)?.[1] ?? /^exec \S+ '(.+)'$/s.exec(arg)?.[1]
    if (sourced) script = readFileSync(sourced.replace(/'"'"'/g, "'"), 'utf8')
  }
  if (script === undefined) {
    // On the command line: a direct `-c` script (no data folder, or a shell given its script inline).
    const flag = argv.findIndex((arg) => arg === '-lic' || arg === '-ic' || arg === '-c')
    if (flag >= 0 && argv[flag + 1] !== undefined && !/^\. '/.test(argv[flag + 1]!)) script = argv[flag + 1]
  }
  if (script === undefined) return { argv: out }
  const text = placeholders(script)
  const hash = createHash('sha256').update(text).digest('hex').slice(0, 16)
  scripts[hash] = text
  return { argv: out.map((arg) => arg === placeholders(script!) ? `<script ${hash}>` : arg), script: hash }
}

function launch(engine: AgentEngine, opts: LaunchCommandOptions, shell: Shell, tmux: Tmux, grid: keyof typeof GRID_BIN, scripts: Record<string, string>): ArgvRecord {
  try {
    const argv = buildEngineLaunchArgv(engine, opts, SHELLS[shell], RUNTIME_NODE, GRID_BIN[grid], TMUX[tmux])
    const command = buildEngineCommandArgv(engine, opts).map(placeholders)
    return { ...record(argv, scripts, shell === 'none' || shell === 'relative'), command }
  } catch (error) {
    return { throws: error instanceof Error ? `${error.name}: ${error.message}` : String(error) }
  }
}

/** Runs `run` with these variables set (`config:` names the daemon's settings), and puts them back once it
 *  has settled: a relaunch reads the moved home after its first await. */
function withEnv<T>(vars: Record<string, string | undefined>, run: () => T): T {
  const before: Record<string, string | undefined> = {}
  for (const [name, value] of Object.entries(vars)) {
    if (name.startsWith('config:')) {
      const key = name.slice('config:'.length)
      before[name] = config[key]
      config[key] = value
    } else {
      before[name] = process.env[name]
      if (value === undefined) delete process.env[name]
      else process.env[name] = value
    }
  }
  const restore = (): void => {
    for (const [name, value] of Object.entries(before)) {
      if (name.startsWith('config:')) config[name.slice('config:'.length)] = value
      else if (value === undefined) delete process.env[name]
      else process.env[name] = value
    }
  }
  let result: T
  try { result = run() } catch (error) { restore(); throw error }
  if (result instanceof Promise) return result.finally(restore) as T
  restore()
  return result
}

function argvCases(scripts: Record<string, string>): Record<string, ArgvRecord> {
  const cases: Record<string, ArgvRecord> = {}
  // Claude Code and Codex in every caller's shape, every other engine in the common ones, from zsh with the
  // daemon's tmux.
  const common = new Set(['new', 'new, approving', 'first prompt', 'resume', 'fork', 'create', 'adopt, waiting out the turn', 'restart'])
  for (const engine of ENGINES) {
    for (const [name, opts] of Object.entries(shapes(engine))) {
      if (!opts || (engine !== 'claude' && engine !== 'codex' && !common.has(name) && !name.startsWith('new, mode '))) continue
      cases[`${engine} · ${name} · zsh · tmux`] = launch(engine, opts, 'zsh', 'tmux', 'bare', scripts)
    }
  }
  // Claude Code and Codex in every shell family, with and without a usable tmux, plain and as created.
  for (const engine of ['claude', 'codex'] as const) {
    const all = shapes(engine)
    for (const shell of Object.keys(SHELLS) as Shell[]) {
      for (const tmux of Object.keys(TMUX) as Tmux[]) {
        for (const shape of ['new', 'create', 'restart']) {
          cases[`${engine} · ${shape} · ${shell} · ${tmux}`] ??= launch(engine, all[shape]!, shell, tmux, 'bare', scripts)
        }
      }
    }
    for (const shape of ['new', 'create']) cases[`${engine} · ${shape} · zsh · tmux · managed grid`] = launch(engine, all[shape]!, 'zsh', 'tmux', 'managed', scripts)
    for (const shape of Object.keys(all)) {
      if (all[shape]) cases[`${engine} · ${shape} · bash · no tmux`] = launch(engine, all[shape]!, 'bash', 'none', 'bare', scripts)
    }
    // An engine at a path of the person's choosing; for Codex, npm's Node wrapper.
    const override = engine === 'claude'
      ? { 'config:CLAUDE_PATH': '/opt/claude code/bin/claude' }
      : { CODEX_PATH: '/usr/local/lib/node_modules/@openai/codex/bin/codex.js' }
    for (const shape of ['new', 'resume', 'fork', 'restart']) {
      cases[`${engine} · ${shape} · zsh · tmux · engine at its own path`] = withEnv(override, () => launch(engine, all[shape]!, 'zsh', 'tmux', 'bare', scripts))
    }
    // zsh's new-user menu kept out: no startup file in ZDOTDIR, so Harness's own .zshenv goes first.
    const emptyZdotdir = join(root, 'zdotdir-empty')
    mkdirSync(emptyZdotdir, { recursive: true })
    for (const shape of ['new', 'create']) {
      cases[`${engine} · ${shape} · zsh · tmux · zsh new user`] = withEnv({ ZDOTDIR: emptyZdotdir }, () => launch(engine, all[shape]!, 'zsh', 'tmux', 'bare', scripts))
    }
    // No data folder to write a one-time file in: the script goes on the command line.
    for (const shape of ['new', 'create']) {
      const savedDir = env.ADAPTER_DATA_DIR
      env.ADAPTER_DATA_DIR = '/dev/null/no-data-folder'
      try { cases[`${engine} · ${shape} · bash · tmux · no data folder`] = launch(engine, all[shape]!, 'bash', 'tmux', 'bare', scripts) }
      finally { env.ADAPTER_DATA_DIR = savedDir }
    }
  }
  // A terminal tile: no engine, the person's shell with its banner.
  for (const shell of ['zsh', 'bash', 'fish', 'none'] as Shell[]) {
    cases[`terminal · new tile · ${shell}`] = launch('terminal', { cwd: CWD, terminalHint: { machineName: 'studio-mac' }, clearEnv: harnessEnvToClear(undefined) }, shell, 'tmux', 'bare', scripts)
  }
  return cases
}

const GRID: GridLaunchOverride = {
  networkId: 'grid-abc', networkName: 'Team grid', baseUrl: 'https://grid.example/grid-abc/relay/v1', apiKey: 'gridkey-abc123', model: 'gpt-5',
}
const GRID_FULL: GridLaunchOverride = { ...GRID, mcpUrl: 'https://control.example/v1/grid/web-mcp/', contextWindow: 131072 }
const API: GridLaunchOverride = { networkId: 'api:openrouter', networkName: 'OpenRouter', baseUrl: 'https://openrouter.ai/api/v1', apiKey: 'sk-or-1', model: 'qwen/qwen3-coder' }

/** Codex `config.toml`s a relaunch reads its own provider from. */
const CODEX_CONFIGS: Record<string, string | null> = {
  'no config': null,
  'its own provider': 'model_provider = "azure"\n',
  'single quotes and a comment': "model = 'gpt-5'\nmodel_provider = 'local' # mine\n",
  'only under a profile': '[profiles.work]\nmodel_provider = "work"\n',
  'commented out': '# model_provider = "azure"\n',
  'empty value': 'model_provider = ""\n',
  'a quote in single quotes': `model_provider = 'a"b'\n`,
}

async function overridesCases(): Promise<Record<string, unknown>> {
  const cases: Record<string, unknown> = {}
  const run = async (engine: AgentEngine, source: LaunchSource, config: string | null = null, deps: Partial<LaunchOverridesDeps> = {}) => {
    const calls: string[] = []
    const result = await buildLaunchOverrides({
      machine: () => ({ hermesSystemManaged: false, opencodeMajor: null }), gridLaunch: gridLaunchInProcess(),
      writeGridConfigDir: async (key, files) => { calls.push(`writeGridConfigDir ${key} ${files.map((file) => file.name).join(',')}`); return `/state/grid-engine-config/${key}` },
      capabilities: async () => ({ sessionEnv: true }),
      installCodexHooks: (home) => { calls.push(`installCodexHooks ${home}`); return true },
      readCodexConfig: (path) => { calls.push(`readCodexConfig ${path}`); return config },
      dshLaunch: async (dsh, workspace, eng, key) => {
        calls.push(`dshLaunch ${dsh} ${workspace} ${eng} ${key}`)
        // As dsh/runtime.ts prepareHarnessLaunch ends: the package's argv, then the engine's context and env flags.
        const launchEnv = { HARNESS_DSH: dsh, HARNESS_WORKSPACE: workspace, HARNESS_CONTEXT_FILE: `${workspace}/.harness/runtime/${key}/CONTEXT.md`, STUDIO_MODE: 'pro "x"' }
        const adapter = harnessAdapter(eng)
        return { ok: true, launch: { env: launchEnv, args: ['--studio', ...(adapter.contextArgs?.(launchEnv.HARNESS_CONTEXT_FILE) ?? []), ...(adapter.envArgs?.(launchEnv) ?? [])] } }
      },
      ...deps,
    }, engine, source, 'agent-0001')
    return JSON.parse(placeholders(JSON.stringify({ result, calls })))
  }
  for (const engine of ['claude', 'codex', 'opencode', 'pi'] as const) {
    cases[`${engine} · own login`] = await run(engine, {})
    cases[`${engine} · own login, its model back`] = await run(engine, { subscriptionModel: engine === 'claude' ? 'opus' : 'gpt-5.5' })
    cases[`${engine} · grid`] = await run(engine, { gridLaunch: GRID })
    cases[`${engine} · grid with web tools and a window`] = await run(engine, { gridLaunch: GRID_FULL, subscriptionModel: 'ignored' })
    cases[`${engine} · saved API`] = await run(engine, { gridLaunch: API })
    cases[`${engine} · harness`] = await run(engine, { dsh: 'acme/studio', cwd: '/work/studio', dshRuntime: 'harness-runtime-1' })
    cases[`${engine} · harness without a workspace`] = await run(engine, { dsh: 'acme/studio', cwd: null })
    cases[`${engine} · harness on a grid, as git, as a named agent`] = await run(engine, { gridLaunch: GRID, dsh: 'acme/studio', cwd: '/work/studio', scmLaunch: { kind: 'git' }, agent: 'harness-compute' })
  }
  for (const [name, config] of Object.entries(CODEX_CONFIGS)) {
    cases[`codex · own login · ${name}`] = await run('codex', {}, config)
    cases[`codex · profile · ${name}`] = await run('codex', { codexHome: '/profiles/work' }, config)
    cases[`codex · profile, its model back · ${name}`] = await run('codex', { codexHome: '/profiles/work', subscriptionModel: 'gpt-5.5' }, config)
    cases[`codex · profile on a grid · ${name}`] = await run('codex', { codexHome: '/profiles/work', gridLaunch: GRID }, config)
  }
  // The home the person's shell moves Codex to, as the daemon reads it at launch (lib/engineHomes.ts launchCodexHome).
  for (const [name, moved] of Object.entries({ 'moved home': '/moved/codex', 'moved home, relative': 'relative/codex', 'moved home, tilde': '~/codex', 'moved home, trailing slash': '/moved/codex/' })) {
    cases[`codex · own login · ${name}`] = await withEnv({ CODEX_HOME: moved }, () => run('codex', {}, 'model_provider = "moved"\n'))
    cases[`codex · profile · ${name}`] = await withEnv({ CODEX_HOME: moved }, () => run('codex', { codexHome: '/profiles/work' }, null))
  }
  // The real file, read from the daemon's own Codex home and from a profile.
  const daemonHome = env.CODEX_HOME
  mkdirSync(daemonHome, { recursive: true })
  writeFileSync(join(daemonHome, 'config.toml'), 'model_provider = "from-file"\n')
  const profile = join(root, 'profile-home')
  mkdirSync(profile, { recursive: true })
  writeFileSync(join(profile, 'config.toml'), "model_provider = 'profile-file'\n")
  cases['codex · own login · the daemon home\'s file'] = await run('codex', {}, null, { readCodexConfig: undefined })
  cases['codex · profile · the profile\'s file'] = await run('codex', { codexHome: profile }, null, { readCodexConfig: undefined })
  cases['codex · profile without a file'] = await run('codex', { codexHome: join(root, 'no-such-profile') }, null, { readCodexConfig: undefined })
  rmSync(join(daemonHome, 'config.toml'))
  // Started by another agent: the pull request line last, from the person's settings as each engine reads them
  // (lib/agentAttribution.ts, kit/attribution.ts), and none for an engine with no way to say it.
  const settings = (files: Record<string, string>) => ({ readAttribution: (path: string) => files[path.split(homedir()).join('<home>')] ?? null })
  for (const engine of ['claude', 'codex', 'opencode'] as const) {
    cases[`${engine} · started by an agent`] = await run(engine, { startedBy: 'agent', cwd: '/work/app' }, null, settings({}))
    cases[`${engine} · started by an agent, a harness on a grid as a named agent`] = await run(engine,
      { startedBy: 'agent', gridLaunch: GRID, dsh: 'acme/studio', cwd: '/work/studio', agent: 'harness-compute' }, null, settings({}))
  }
  cases['claude · started by an agent, the folder\'s own pull request text'] = await run('claude', { startedBy: 'agent', cwd: '/work/app' }, null,
    settings({ '/work/app/.claude/settings.json': '{"attribution":{"pr":"Made in the app"}}' }))
  cases['claude · started by an agent, attribution hidden'] = await run('claude', { startedBy: 'agent', cwd: '/work/app' }, null,
    settings({ '<home>/.claude/settings.json': '{"attribution":false}' }))
  cases['codex · started by an agent, the person\'s own instructions'] = await run('codex', { startedBy: 'agent', cwd: '/work/app' }, null,
    settings({ '<home>/.codex/config.toml': 'developer_instructions = "Be terse."\n' }))
  cases['codex · profile, started by an agent, instructions it cannot keep exactly'] = await run('codex', { startedBy: 'agent', codexHome: '/profiles/work', cwd: '/work/app' }, null,
    settings({ '/profiles/work/config.toml': 'developer_instructions = """\nmine\n"""\n' }))
  cases['claude · not started by an agent'] = await run('claude', { startedBy: null, cwd: '/work/app' }, null, settings({}))
  return cases
}

function adapterCases(): Record<string, unknown> {
  const contextFile = '/work/my "studio"/.harness/runtime/agent-1/CONTEXT.md'
  const sessionEnv: Record<string, string> = {
    HARNESS_DSH: 'acme/studio', HARNESS_CONTEXT_FILE: contextFile, HARNESS_SKILLS_DIR: '/work/.harness/skills',
    STUDIO_MODE: 'say "hi"\n\ttab \\ back', UNICODE: 'café ✓ 🎉', EMPTY: '', 'BAD-NAME': 'x', '1LEADING': 'y', 'a.b': 'z', _under: 'u',
  }
  return Object.fromEntries(Object.keys(HARNESS_ADAPTERS).map((engine) => {
    const adapter = HARNESS_ADAPTERS[engine as keyof typeof HARNESS_ADAPTERS]
    return [engine, {
      instructionFiles: adapter.instructionFiles,
      contextArgs: 'contextArgs' in adapter && adapter.contextArgs ? adapter.contextArgs(contextFile) : null,
      envArgs: 'envArgs' in adapter && adapter.envArgs ? adapter.envArgs(sessionEnv) : null,
      envArgsEmpty: 'envArgs' in adapter && adapter.envArgs ? adapter.envArgs({}) : null,
    }]
  }))
}

describe('every launch hands tmux what it did before Claude Code and Codex declared their launches', () => {
  it('argv, scripts, relaunch overrides and harness adapter flags match the record', async () => {
    const scripts: Record<string, string> = {}
    const run = (platform: Platform): Promise<Cases> => onPlatform(platform, async () => ({
      argv: argvCases(scripts), overrides: await overridesCases(), adapters: adapterCases(),
    }))
    const darwin = await run('darwin')
    const linux = await run('linux')
    const actual: Golden = {
      ...darwin,
      scripts: Object.fromEntries(Object.entries(scripts).sort(([a], [b]) => a.localeCompare(b))),
      linux: { argv: differences(darwin.argv, linux.argv), overrides: differences(darwin.overrides, linux.overrides), adapters: differences(darwin.adapters, linux.adapters) },
    }
    if (RECORD) {
      writeFileSync(GOLDEN, serialize(store(actual)))
      return
    }
    const golden = load(JSON.parse(readFileSync(GOLDEN, 'utf8')) as Stored)
    // The stored form loses nothing.
    expect(load(store(actual))).toEqual(actual)
    // Compared piece by piece, so a failure names the platform and the case.
    for (const platform of PLATFORMS) {
      const got = casesOn(actual, platform)
      const want = casesOn(golden, platform)
      expect(Object.keys(got.argv).sort(), platform).toEqual(Object.keys(want.argv).sort())
      for (const [name, value] of Object.entries(want.argv)) {
        const mine = got.argv[name]!
        expect({ ...mine, script: mine.script && actual.scripts[mine.script] }, `${platform} · ${name}`)
          .toEqual({ ...value, script: value.script && golden.scripts[value.script] })
      }
      for (const [name, value] of Object.entries(want.overrides)) {
        // Launch preparation intentionally asks the Store before publishing grid files. Keep the
        // former artifact intact and pin this one ordering change explicitly, including its old
        // trace. Every result field, call argument and other case still compares byte-for-byte.
        const changedOrder: Record<string, readonly [string, string]> = {
          'opencode · harness on a grid, as git, as a named agent': [
            'writeGridConfigDir agent-0001 opencode.json',
            'dshLaunch acme/studio /work/studio opencode agent-0001',
          ],
          'pi · harness on a grid, as git, as a named agent': [
            'writeGridConfigDir agent-0001 grid-provider.ts',
            'dshLaunch acme/studio /work/studio pi agent-0001',
          ],
        }
        const order = changedOrder[name]
        let expected = value
        if (order) {
          const former = value as { calls: string[] }
          expect(former.calls, `${platform} · ${name} · former order`).toEqual(order)
          expected = { ...former, calls: [order[1], order[0]] }
        }
        expect(got.overrides[name], `${platform} · ${name}`).toEqual(expected)
      }
      expect(Object.keys(got.overrides).sort(), platform).toEqual(Object.keys(want.overrides).sort())
      expect(got.adapters, platform).toEqual(want.adapters)
    }
    expect(actual.scripts).toEqual(golden.scripts)
  }, 120_000)

  it('records no machine-specific path', () => {
    const text = readFileSync(GOLDEN, 'utf8')
    expect(text).not.toContain(homedir())
    expect(text).not.toContain(tmpdir())
    expect(text).not.toMatch(/\/Users\/[^<]/)
    for (const name of DSH_SESSION_ENV) expect(text).toContain(name)
    expect(text).toContain(GRID_CONFLICTING_ENV_VARS[0]!)
  })
})