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.

32.6 KB
Raw Blame
/**
 * What preparing a launch writes into a person's files, byte for byte, in every state those files are found
 * in. Recorded from the code as it stood before Claude Code's and Codex's launch preparation became declared
 * data applied by the kit (docs/design/2026-10-08-engine-launch.md, (c2)):
 *
 *  - folder trust: Claude Code's `.claude.json` (`projects[<path>].hasTrustDialogAccepted`, inherited by
 *    folders below) and Codex's `config.toml` (`[projects."<path>"]`, `trust_level = "trusted"`, exact only),
 *    read and recorded twice, in the default, a moved and a profile's home;
 *  - Codex's rollout made resumable (its reasoning items made portable), with its backup and atomic
 *    replacement, and every refusal;
 *  - the instruction file a harness's bootstrap goes into, and the one the saved APIs' note goes into.
 *
 * Each case keeps what was returned or thrown, and every file left behind: its bytes (a hash past 4 KiB), its
 * mode, a symlink kept or replaced, a temporary file or backup left over. Paths are placeholders.
 *
 * `RECORD_LAUNCH_PREP_GOLDEN=1` writes the fixture. Record it again only for a change meant to alter what
 * lands in a person's files, and say so in that change.
 */
import { createHash } from 'node:crypto'
import { chmodSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, symlinkSync, unlinkSync, 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 type { InstalledDsh } from '../dsh/installed.js'
import { prepareHarnessLaunch } from '../dsh/runtime.js'
import type { ApiConnections } from '../lib/apiConnections.js'
import { prepareApiInstructions } from '../lib/apiInstructions.js'
import { resetEngineHomes } from '../lib/engineHomes.js'
import { folderTrust, prepareResume, type ResumeSource } from './launchPrep.js'
import { PROCESS_ENGINES, type AgentEngine } from './types.js'

const GOLDEN = fileURLToPath(new URL('./__fixtures__/launch-prep.golden.json', import.meta.url))
const RECORD = process.env.RECORD_LAUNCH_PREP_GOLDEN === '1'
/** Permission cases mean nothing to root, which may read and write anywhere. */
const ROOT_USER = process.getuid?.() === 0

type Snapshot = Record<string, unknown>
interface Golden { trust: Record<string, unknown>; resume: Record<string, unknown>; instructions: Record<string, unknown> }

let root = ''
let savedUmask: number | null = null
const savedEnv: Record<string, string | undefined> = {}
const saved: { dataDir?: string; codexHome?: string } = {}
/** The throwaway profile: HOME and USERPROFILE both point here, so the default-home cases never touch the real one. */
let testHome = ''

beforeAll(() => {
  // Files the code writes without a mode take the process's umask: the usual one, on every machine.
  try { savedUmask = process.umask(0o022) } catch { savedUmask = null }
  root = realpathSync(mkdtempSync(join(tmpdir(), 'launch-prep-golden-')))
  saved.dataDir = env.ADAPTER_DATA_DIR
  saved.codexHome = env.CODEX_HOME
  env.ADAPTER_DATA_DIR = join(root, 'data')
  mkdirSync(env.ADAPTER_DATA_DIR)
  for (const name of ['CLAUDE_CONFIG_DIR', 'CODEX_HOME']) { savedEnv[name] = process.env[name]; delete process.env[name] }
  testHome = join(root, 'home')
  mkdirSync(testHome)
  for (const name of ['HOME', 'USERPROFILE']) { savedEnv[name] = process.env[name]; process.env[name] = testHome }
  resetEngineHomes()
})

afterAll(() => {
  env.ADAPTER_DATA_DIR = saved.dataDir!
  env.CODEX_HOME = saved.codexHome!
  for (const [name, value] of Object.entries(savedEnv)) {
    if (value === undefined) delete process.env[name]
    else process.env[name] = value
  }
  resetEngineHomes()
  if (savedUmask !== null) process.umask(savedUmask)
  chmodTree(root)
  rmSync(root, { recursive: true, force: true })
})

/** Undo the permission cases, so the folder can be read and removed. */
function chmodTree(path: string): void {
  try {
    const stat = lstatSync(path)
    if (stat.isSymbolicLink()) return
    chmodSync(path, stat.isDirectory() ? 0o755 : 0o644)
    if (stat.isDirectory()) for (const name of readdirSync(path)) chmodTree(join(path, name))
  } catch { /* gone */ }
}

const normalize = (text: string): string => text
  .split(testHome).join('<home>')
  .split(root).join('<root>')
  .split(homedir()).join('<home>')
  .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g, '<uuid>')
  .split(`.harness-${process.pid}.`).join('.harness-<pid>.')

/** Every entry under `dir`: a file's bytes (or hash), its mode, a link's target, what could not be read. */
function snapshot(dir: string): Snapshot {
  const out: Snapshot = {}
  const walk = (path: string, rel: string): void => {
    let names: string[]
    try { names = readdirSync(path).sort() } catch (error) { out[rel || '.'] = { unreadable: (error as NodeJS.ErrnoException).code }; return }
    for (const name of names) {
      const full = join(path, name)
      const key = normalize(rel ? `${rel}/${name}` : name)
      const stat = lstatSync(full)
      if (stat.isSymbolicLink()) { out[key] = { link: normalize(readlinkSync(full)) }; continue }
      if (stat.isDirectory()) { out[key] = { dir: true, mode: (stat.mode & 0o777).toString(8) }; walk(full, rel ? `${rel}/${name}` : name); continue }
      const mode = (stat.mode & 0o777).toString(8)
      let bytes: Buffer
      try { bytes = readFileSync(full) } catch (error) { out[key] = { mode, unreadable: (error as NodeJS.ErrnoException).code }; continue }
      out[key] = bytes.length > 4096
        ? { mode, size: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex') }
        : { mode, text: normalize(bytes.toString('utf8')) }
    }
  }
  walk(dir, '')
  return out
}

function attempt<T>(run: () => T): { value: T } | { threw: string } {
  try { return { value: run() } } catch (error) { return { threw: normalize(error instanceof Error ? error.message : String(error)) } }
}

const write = (path: string, text: string | Buffer, mode = 0o644): void => {
  mkdirSync(dirname(path), { recursive: true })
  writeFileSync(path, text)
  chmodSync(path, mode)
}

/** A fresh folder for one case, named by the case alone: a case left out (root skips the permission cases)
 *  changes no other case's paths. */
const fresh = (name: string): string => {
  const dir = join(root, `case-${createHash('sha256').update(name).digest('hex').slice(0, 10)}`)
  mkdirSync(dir, { recursive: true })
  return dir
}

// ---------------------------------------------------------------------------------------------- folder trust

const TARGET = '/work/new project'
const PROBES = [TARGET, `${TARGET}/sub`, '/work', `${TARGET}x`, `${TARGET}/`]
interface TrustCase { name: string; file?: (home: string, elsewhere: string) => void; noHome?: boolean; permissions?: boolean; target?: string }

const pretty = (value: unknown): string => JSON.stringify(value, null, 2)
const CLAUDE_CASES: TrustCase[] = [
  { name: 'no file' },
  { name: 'no home folder', noHome: true },
  { name: 'empty file', file: (home) => write(join(home, '.claude.json'), '') },
  { name: 'whitespace only', file: (home) => write(join(home, '.claude.json'), '  \n') },
  { name: 'malformed JSON', file: (home) => write(join(home, '.claude.json'), '{not-json') },
  { name: 'byte order mark', file: (home) => write(join(home, '.claude.json'), '{}') },
  ...['null', '[]', '"text"', '42'].map((json) => ({ name: `JSON ${json}`, file: (home: string) => write(join(home, '.claude.json'), json) })),
  { name: 'an empty object', file: (home) => write(join(home, '.claude.json'), '{}') },
  ...['[]', '"x"', 'null', '7'].map((json) => ({ name: `projects is ${json}`, file: (home: string) => write(join(home, '.claude.json'), `{"projects":${json},"keep":1}`) })),
  { name: 'projects empty', file: (home) => write(join(home, '.claude.json'), pretty({ projects: {} })) },
  ...['"x"', '[]', 'null', 'true'].map((json) => ({ name: `the entry is ${json}`, file: (home: string) => write(join(home, '.claude.json'), `{"projects":{${JSON.stringify(TARGET)}:${json}}}`) })),
  { name: 'the entry is empty', file: (home) => write(join(home, '.claude.json'), pretty({ projects: { [TARGET]: {} } })) },
  { name: 'the entry says no', file: (home) => write(join(home, '.claude.json'), pretty({ projects: { [TARGET]: { allowedTools: ['Bash'], hasTrustDialogAccepted: false, mcpServers: { a: 1 } } } })) },
  { name: 'the entry says yes', file: (home) => write(join(home, '.claude.json'), pretty({ projects: { [TARGET]: { hasTrustDialogAccepted: true } } })) },
  { name: 'the entry says "true"', file: (home) => write(join(home, '.claude.json'), pretty({ projects: { [TARGET]: { hasTrustDialogAccepted: 'true' } } })) },
  { name: 'a parent says yes', file: (home) => write(join(home, '.claude.json'), pretty({ projects: { '/work': { hasTrustDialogAccepted: true } } })) },
  { name: 'a parent with a trailing slash says yes', file: (home) => write(join(home, '.claude.json'), pretty({ projects: { '/work//': { hasTrustDialogAccepted: true } } })) },
  { name: 'a longer sibling says yes', file: (home) => write(join(home, '.claude.json'), pretty({ projects: { '/work/new proj': { hasTrustDialogAccepted: true }, [`${TARGET}x`]: { hasTrustDialogAccepted: true } } })) },
  { name: 'a parent says no', file: (home) => write(join(home, '.claude.json'), pretty({ projects: { '/work': { hasTrustDialogAccepted: false }, '/': 'odd' } })) },
  {
    name: 'other settings', file: (home) => write(join(home, '.claude.json'),
      pretty({ numStartups: 12, theme: 'dark', note: 'café ✓ 🎉', nested: { list: [1, 2.5, null] }, projects: { '/other': { allowedTools: [], hasTrustDialogAccepted: true } } })),
  },
  { name: 'minified', file: (home) => write(join(home, '.claude.json'), JSON.stringify({ a: 1, projects: { '/other': {} } })) },
  { name: 'duplicate keys', file: (home) => write(join(home, '.claude.json'), `{"projects":{},"projects":{${JSON.stringify(TARGET)}:{"x":1}}}`) },
  { name: 'unicode target', target: '/work/café ✓ "q"', file: (home) => write(join(home, '.claude.json'), '{}') },
  {
    name: 'a symlink to dotfiles', file: (home, elsewhere) => {
      write(join(elsewhere, 'claude.json'), pretty({ projects: {} }))
      symlinkSync(join(elsewhere, 'claude.json'), join(home, '.claude.json'))
    },
  },
  { name: 'a dangling symlink', file: (home, elsewhere) => symlinkSync(join(elsewhere, 'missing.json'), join(home, '.claude.json')) },
  { name: 'a private file', file: (home) => write(join(home, '.claude.json'), '{}', 0o600) },
  { name: 'a read-only file', permissions: true, file: (home) => write(join(home, '.claude.json'), '{}', 0o444) },
  { name: 'an unreadable file', permissions: true, file: (home) => write(join(home, '.claude.json'), '{}', 0o200) },
  { name: 'a read-only folder', permissions: true, file: (home) => { write(join(home, '.claude.json'), '{}'); chmodSync(home, 0o555) } },
  { name: 'the file is a folder', file: (home) => mkdirSync(join(home, '.claude.json'), { recursive: true }) },
  { name: 'a leftover temporary file', file: (home) => { write(join(home, '.claude.json'), '{}'); write(join(home, '.claude.json.harness-1.tmp'), 'old') } },
]

const toml = (text: string) => (home: string): void => write(join(home, 'config.toml'), text)
const T = JSON.stringify(TARGET)
const CODEX_CASES: TrustCase[] = [
  { name: 'no file' },
  { name: 'no home folder', noHome: true },
  { name: 'empty file', file: toml('') },
  { name: 'settings, no newline at the end', file: toml('model = "gpt-5"') },
  { name: 'trailing blank lines and spaces', file: toml('model = "gpt-5"\n\n\n  \t\n') },
  { name: 'CRLF', file: toml('model = "gpt-5"\r\n[profiles.work]\r\nmodel = "o3"\r\n') },
  { name: 'trusted already', file: toml(`[projects.${T}]\ntrust_level = "trusted"\n`) },
  { name: 'listed, untrusted', file: toml(`[projects.${T}]\ntrust_level = "untrusted"\n`) },
  { name: 'single-quoted key', file: toml(`[projects.'${TARGET}']\ntrust_level = 'trusted'\n`) },
  { name: 'spaced header', file: toml(`  [ projects . ${T} ]  \n  trust_level   =   "trusted"\n`) },
  { name: 'escaped key', file: toml('[projects."/work/new\\u0020project"]\ntrust_level = "trusted"\n') },
  { name: 'a key JSON cannot read', file: toml('[projects."/work/\\U0001F600"]\ntrust_level = "trusted"\n') },
  { name: 'an inline table', file: toml('projects = { "/other" = { trust_level = "trusted" } }\n') },
  { name: 'dotted keys', file: toml('projects."/other".trust_level = "trusted"\n') },
  { name: 'a bare projects table', file: toml('[projects]\n"/other" = 1\n') },
  { name: 'other projects', file: toml(`model = "x"\n\n[projects."/other"]\ntrust_level = "trusted"\n\n[projects."/work"]\ntrust_level = "trusted"\n`) },
  { name: 'trust in a sub-table', file: toml(`[projects.${T}.sub]\ntrust_level = "trusted"\n`) },
  { name: 'trust only in the next table', file: toml(`[projects.${T}]\nnote = "x"\n[other]\ntrust_level = "trusted"\n`) },
  { name: 'a commented header', file: toml(`# [projects.${T}]\n# trust_level = "trusted"\n`) },
  { name: 'unicode, a quote, a backslash and DEL', target: '/work/q"uote\\back\x7fdel é', file: toml('model = "x"\n') },
  {
    name: 'a symlink to dotfiles', file: (home, elsewhere) => {
      write(join(elsewhere, 'config.toml'), 'model = "x"\n')
      symlinkSync(join(elsewhere, 'config.toml'), join(home, 'config.toml'))
    },
  },
  { name: 'a dangling symlink', file: (home, elsewhere) => symlinkSync(join(elsewhere, 'missing.toml'), join(home, 'config.toml')) },
  { name: 'a private file', file: (home) => write(join(home, 'config.toml'), 'model = "x"\n', 0o600) },
  { name: 'a read-only file', permissions: true, file: (home) => write(join(home, 'config.toml'), 'model = "x"\n', 0o444) },
  { name: 'an unreadable file', permissions: true, file: (home) => write(join(home, 'config.toml'), 'model = "x"\n', 0o200) },
  { name: 'a read-only folder', permissions: true, file: (home) => { write(join(home, 'config.toml'), 'model = "x"\n'); chmodSync(home, 0o555) } },
  { name: 'the file is a folder', file: (home) => mkdirSync(join(home, 'config.toml'), { recursive: true }) },
]

/** How the engine's home is found: the daemon's default, the one the person's shell moves, an agent's profile. */
type Where = 'moved' | 'default' | 'profile'

/** Claude Code's files in the (throwaway) home folder, where its `.claude.json` is by default. */
const homeFolderFiles = (): Snapshot => Object.fromEntries(Object.entries(snapshot(homedir()))
  .filter(([name]) => name.startsWith('.claude.json')).map(([name, value]) => [`<home>/${name}`, value]))
const clearHomeFolder = (): void => {
  for (const name of readdirSync(homedir())) {
    if (!name.startsWith('.claude.json')) continue
    const path = join(homedir(), name)
    // rmSync leaves a dangling link in place; a link is removed by itself.
    if (lstatSync(path).isSymbolicLink()) unlinkSync(path)
    else rmSync(path, { recursive: true, force: true })
  }
}

function trustCase(engine: AgentEngine, scenario: TrustCase, where: Where): unknown {
  const dir = fresh(`${engine}-${where}-${scenario.name}`)
  const home = join(dir, 'home')
  const elsewhere = join(dir, 'elsewhere')
  mkdirSync(elsewhere)
  if (!scenario.noHome) mkdirSync(home)
  const before = { CLAUDE_CONFIG_DIR: process.env.CLAUDE_CONFIG_DIR, CODEX_HOME: process.env.CODEX_HOME, config: env.CODEX_HOME }
  try {
    if (engine === 'claude') {
      // Claude Code's `.claude.json` is in CLAUDE_CONFIG_DIR, else the home folder itself.
      if (where === 'moved') process.env.CLAUDE_CONFIG_DIR = home
    } else if (where === 'moved') process.env.CODEX_HOME = home
    else if (where === 'default') env.CODEX_HOME = home
    const inHomeFolder = engine === 'claude' && where === 'default'
    const atHome = inHomeFolder ? homedir() : home
    if (inHomeFolder) clearHomeFolder()
    scenario.file?.(atHome, elsewhere)
    const trust = folderTrust(engine, where === 'profile' ? home : null)
    const target = scenario.target ?? TARGET
    const probes = [...PROBES, target].filter((path, index, all) => all.indexOf(path) === index)
    const result = {
      before: probes.map((path) => attempt(() => trust!.trusts(path))),
      first: attempt(() => trust!.record(target)),
      second: attempt(() => trust!.record(target)),
      after: probes.map((path) => attempt(() => trust!.trusts(path))),
      files: inHomeFolder ? { ...snapshot(dir), ...homeFolderFiles() } : snapshot(dir),
    }
    if (inHomeFolder) clearHomeFolder()
    return result
  } finally {
    if (before.CLAUDE_CONFIG_DIR === undefined) delete process.env.CLAUDE_CONFIG_DIR
    else process.env.CLAUDE_CONFIG_DIR = before.CLAUDE_CONFIG_DIR
    if (before.CODEX_HOME === undefined) delete process.env.CODEX_HOME
    else process.env.CODEX_HOME = before.CODEX_HOME
    env.CODEX_HOME = before.config
  }
}

function trustCases(): Record<string, unknown> {
  const cases: Record<string, unknown> = {}
  for (const [engine, scenarios, wheres] of [
    ['claude', CLAUDE_CASES, ['moved', 'default']],
    ['codex', CODEX_CASES, ['profile', 'moved', 'default']],
  ] as const) {
    for (const scenario of scenarios) {
      for (const where of wheres) {
        // The default and moved homes need only the common states: the file's handling is the profile's.
        if (where !== wheres[0] && scenario.permissions) continue
        if (scenario.permissions && ROOT_USER) continue
        cases[`${engine} · ${where} · ${scenario.name}`] = trustCase(engine, scenario, where)
      }
    }
  }
  // An engine that asks no such question.
  for (const engine of PROCESS_ENGINES.filter((name) => name !== 'claude' && name !== 'codex')) cases[`${engine} · no folder trust`] = folderTrust(engine, '/profile')
  // A relative or `~` CLAUDE_CONFIG_DIR is not the one Claude Code would read from every folder: the home folder is.
  for (const moved of ['relative/claude', '~/claude']) {
    const dir = fresh(`claude-moved-${moved}`)
    process.env.CLAUDE_CONFIG_DIR = moved
    try {
      clearHomeFolder()
      write(join(homedir(), '.claude.json'), '{}')
      const trust = folderTrust('claude')!
      cases[`claude · moved to ${moved}`] = { first: attempt(() => trust.record(TARGET)), files: { ...snapshot(dir), ...homeFolderFiles() } }
    } finally {
      delete process.env.CLAUDE_CONFIG_DIR
      clearHomeFolder()
    }
  }
  return cases
}

// ---------------------------------------------------------------------------------------- resumable history

const SESSION = '01a0a3cd-a374-71f2-a11a-1fc1cc41b36d'
const record = (type: string, payload: unknown): string => JSON.stringify({ timestamp: '2026-10-08T06:43:10.580Z', type, payload })
const meta = (id = SESSION) => record('session_meta', { id, cwd: '/workspace', model_provider: 'openai' })
const summary = [{ type: 'summary_text', text: 'Prior summary.' }]
const reasoning = (extra: Record<string, unknown> = {}) => ({ type: 'reasoning', id: 'msg_aY9suLof0GA06VzeKPXLM7rj', summary, content: [], ...extra })
const message = { type: 'message', id: 'msg_1', role: 'assistant', content: [{ type: 'output_text', text: 'Hello ✓.' }] }
const item = (payload: unknown): string => record('response_item', payload)
const rolloutName = (id = SESSION) => `rollout-2026-10-08T06-43-10-${id}.jsonl`

interface ResumeCase {
  name: string
  /** The rollout's text; null for none. */
  text?: string | Buffer | null
  /** Where the rollout is, under the case folder. */
  at?: string
  /** What the source says. */
  source?: (dir: string) => Partial<ResumeSource>
  setup?: (dir: string) => void
}

const LONG = (() => {
  // Past one 64 KiB read, with a three-byte character across the boundary and a repair after it.
  const head = `${meta()}\n${item(message)}\n`
  const filler = 'é'.repeat(70_000)
  return `${head}${record('event_msg', { type: 'agent_message', message: filler })}\n${item(reasoning({ content: [{ text: 'late' }] }))}\n`
})()

const RESUME_CASES: ResumeCase[] = [
  { name: 'another engine', source: () => ({ engine: 'claude' }), text: `${meta()}\n${item(reasoning())}\n` },
  { name: 'no session id', source: () => ({ sessionId: '' }), text: `${meta()}\n${item(reasoning())}\n` },
  { name: 'a reasoning id', text: `${meta()}\n${item(reasoning())}\n${item(message)}\n` },
  { name: 'nothing to repair', text: `${meta()}\n${item(message)}\n${item({ type: 'reasoning', summary, content: [] })}\n` },
  { name: 'reasoning content becomes the summary', text: `${meta()}\n${item(reasoning({ summary: [], content: [{ text: 'one ' }, { type: 'x', text: 'two' }, 'odd', { text: 3 }] }))}\n` },
  { name: 'content beside a summary', text: `${meta()}\n${item(reasoning({ content: [{ text: 'dup' }] }))}\n` },
  { name: 'content with no text', text: `${meta()}\n${item(reasoning({ id: undefined, summary: [], content: [{ type: 'x' }] }))}\n` },
  { name: 'encrypted reasoning kept', text: `${meta()}\n${item(reasoning({ encrypted_content: 'opaque', content: [{ text: 'v' }] }))}\n` },
  {
    name: 'compacted history and other records',
    text: `${meta()}\n${record('compacted', { message: 'sum', replacement_history: [reasoning(), message, 'odd', null] })}\n`
      + `${record('compacted', { message: 'none' })}\n${record('event_msg', { type: 'agent_reasoning', metadata: reasoning() })}\n${record('turn_context', { cwd: '/w' })}\n`,
  },
  { name: 'CRLF, blank lines and no newline at the end', text: `${meta()}\r\n\r\n${item(reasoning())}\r\n   \n${item(reasoning({ id: 'rs_2' }))}` },
  { name: 'past one read', text: LONG },
  { name: 'another session\'s rollout', text: `${meta('ffffffff-0000-0000-0000-000000000000')}\n${item(reasoning())}\n` },
  { name: 'no session metadata first', text: `${item(reasoning())}\n${meta()}\n` },
  { name: 'session metadata with no payload', text: `${record('session_meta', null)}\n` },
  { name: 'invalid JSON', text: `${meta()}\n${item(reasoning())}\n{"type": "response_item", "payload": {"text": "secret words"\n` },
  { name: 'a record that is not an object', text: `${meta()}\n[1,2]\n` },
  { name: 'an empty rollout', text: '' },
  { name: 'blank lines only', text: '\n\n' },
  { name: 'no rollout at all', text: null, source: () => ({ transcriptPath: null }) },
  { name: 'found by id', source: () => ({ transcriptPath: null }), text: `${meta()}\n${item(reasoning())}\n` },
  { name: 'a stale path, found by id', source: (dir) => ({ transcriptPath: join(dir, 'profile/sessions/old/gone.jsonl') }), text: `${meta()}\n${item(reasoning())}\n` },
  { name: 'a stale path, nothing by id', source: (dir) => ({ transcriptPath: join(dir, 'profile/sessions/old/gone.jsonl'), sessionId: 'abcdefab-0000-0000-0000-00000000dead' }), text: `${meta()}\n${item(reasoning())}\n` },
  { name: 'an id too short to look up', source: () => ({ transcriptPath: null, sessionId: 'short' }), text: `${meta('short')}\n${item(reasoning())}\n` },
  {
    name: 'outside the profile', source: (dir) => ({ transcriptPath: join(dir, 'elsewhere', rolloutName()) }),
    setup: (dir) => write(join(dir, 'elsewhere', rolloutName()), `${meta()}\n${item(reasoning())}\n`), text: null,
  },
  {
    name: 'a symlinked rollout', text: null, source: (dir) => ({ transcriptPath: join(dir, 'profile/sessions/2026/10/08', rolloutName()) }),
    setup: (dir) => {
      write(join(dir, 'profile/sessions/real.jsonl'), `${meta()}\n${item(reasoning())}\n`)
      mkdirSync(join(dir, 'profile/sessions/2026/10/08'), { recursive: true })
      symlinkSync(join(dir, 'profile/sessions/real.jsonl'), join(dir, 'profile/sessions/2026/10/08', rolloutName()))
    },
  },
  { name: 'a folder where the rollout is', text: null, source: (dir) => ({ transcriptPath: join(dir, 'profile/sessions') }), setup: (dir) => mkdirSync(join(dir, 'profile/sessions'), { recursive: true }) },
  { name: 'a world-readable rollout', text: `${meta()}\n${item(reasoning())}\n`, setup: () => undefined },
  { name: 'a leftover backup and temporary file', text: `${meta()}\n${item(reasoning())}\n`, setup: (dir) => write(join(dir, 'profile/sessions/2026/10/08', `${rolloutName()}.reasoning-tmp-old`), 'x') },
]

/** Where the agent's Codex home is: its own profile, the daemon's, or one the person moved (remembered). */
function resumeCase(scenario: ResumeCase, where: Where): unknown {
  const dir = fresh(`resume-${where}-${scenario.name}`)
  const home = join(dir, where === 'profile' ? 'profile' : where === 'default' ? 'daemon' : 'moved')
  mkdirSync(join(home, 'sessions'), { recursive: true })
  mkdirSync(join(dir, 'elsewhere'), { recursive: true })
  const before = env.CODEX_HOME
  resetEngineHomes()
  try {
    if (where === 'default') env.CODEX_HOME = home
    else env.CODEX_HOME = join(dir, 'daemon-empty')
    if (where === 'moved') writeFileSync(join(env.ADAPTER_DATA_DIR, 'engine-homes.json'), JSON.stringify({ claude: [], codex: [home] }) + '\n')
    else rmSync(join(env.ADAPTER_DATA_DIR, 'engine-homes.json'), { force: true })
    const file = join(home, 'sessions/2026/10/08', rolloutName())
    if (scenario.text !== null && scenario.text !== undefined) write(file, scenario.text, scenario.name === 'a world-readable rollout' ? 0o644 : 0o600)
    // Only the profile's cases name paths of their own (setup, source); the others run in their own home.
    scenario.setup?.(dir)
    const source: ResumeSource = { engine: 'codex', sessionId: SESSION, transcriptPath: file, codexHome: where === 'profile' ? home : null, ...scenario.source?.(dir) }
    const result = attempt(() => prepareResume(source))
    return { result: JSON.parse(normalize(JSON.stringify(result))), files: snapshot(dir) }
  } finally {
    env.CODEX_HOME = before
    rmSync(join(env.ADAPTER_DATA_DIR, 'engine-homes.json'), { force: true })
    resetEngineHomes()
  }
}

function resumeCases(): Record<string, unknown> {
  const cases: Record<string, unknown> = {}
  for (const scenario of RESUME_CASES) cases[`profile · ${scenario.name}`] = resumeCase(scenario, 'profile')
  for (const name of ['a reasoning id', 'found by id', 'nothing to repair', 'no rollout at all']) {
    const scenario = RESUME_CASES.find((candidate) => candidate.name === name)!
    for (const where of ['default', 'moved'] as const) cases[`${where} · ${name}`] = resumeCase(scenario, where)
  }
  return cases
}

// ------------------------------------------------------------------------------------- instruction files

const INSTRUCTION_FILES = ['CLAUDE.md', 'AGENTS.md', 'AGENTS.override.md', 'GEMINI.md', '.hermes.md', '.cursorrules']
const WORKSPACE_STATES: Record<string, Record<string, string>> = {
  'an empty workspace': {},
  'CLAUDE.md': { 'CLAUDE.md': '# Claude rules' },
  'AGENTS.md': { 'AGENTS.md': '# Shared rules\n' },
  'CLAUDE.md and AGENTS.md': { 'CLAUDE.md': '# Claude rules\n', 'AGENTS.md': '# Shared rules\n' },
  'CLAUDE.md importing AGENTS.md': { 'CLAUDE.md': '# Claude rules\n  @AGENTS.md  \n', 'AGENTS.md': '# Shared rules\n' },
  'AGENTS.override.md and AGENTS.md': { 'AGENTS.override.md': '# Override', 'AGENTS.md': '# Shared rules' },
  'GEMINI.md and .hermes.md': { 'GEMINI.md': '# Gemini', '.hermes.md': '# Hermes' },
}

function harnessPackage(dir: string): InstalledDsh {
  const pkg = join(dir, 'package')
  write(join(pkg, 'AGENTS.md'), '# Draw\nRead the draw skill.\n')
  write(join(pkg, 'skills/draw/SKILL.md'), '# Draw skill\n')
  return {
    id: 'acme/draw', dir: pkg, realDir: pkg, source: pkg, ref: null, commit: null, linked: true, installedAt: 1,
    manifest: { spec: 1, id: 'acme/draw', name: 'Drawing', engine: 'claude', agent: { instructions: 'AGENTS.md', skills: ['skills'] } },
  } as InstalledDsh
}

function instructionFiles(ws: string): Snapshot {
  const all = snapshot(ws)
  return Object.fromEntries(Object.entries(all).filter(([name]) => INSTRUCTION_FILES.includes(name)))
}

function instructionCases(): Record<string, unknown> {
  const cases: Record<string, unknown> = {}
  const deep = new Set<AgentEngine>(['claude', 'codex', 'opencode', 'hermes'])
  for (const engine of PROCESS_ENGINES) {
    for (const [state, files] of Object.entries(WORKSPACE_STATES)) {
      if (!deep.has(engine) && state !== 'an empty workspace' && state !== 'AGENTS.md') continue
      const dir = fresh(`harness-${engine}-${state}`)
      const ws = join(dir, 'workspace')
      mkdirSync(ws)
      for (const [name, text] of Object.entries(files)) write(join(ws, name), text)
      const pkg = harnessPackage(dir)
      const first = attempt(() => { prepareHarnessLaunch(pkg, ws, engine, 'runtime-1'); return 'prepared' })
      const after = instructionFiles(ws)
      const second = attempt(() => { prepareHarnessLaunch(pkg, ws, engine, 'runtime-1'); return 'prepared' })
      cases[`harness · ${engine} · ${state}`] = { first, second, after, again: instructionFiles(ws) }
    }
  }
  // An edited bootstrap is refused, and a symlinked instruction file is never replaced.
  for (const engine of ['claude', 'codex'] as const) {
    const file = engine === 'claude' ? 'CLAUDE.md' : 'AGENTS.md'
    const dir = fresh(`harness-${engine}-edited`)
    const ws = join(dir, 'workspace')
    mkdirSync(ws)
    write(join(ws, file), '# Rules\n<!-- harness:runtime v1 -->\nedited\n')
    cases[`harness · ${engine} · an edited bootstrap`] = { first: attempt(() => prepareHarnessLaunch(harnessPackage(dir), ws, engine, 'runtime-1') && 'prepared'), after: instructionFiles(ws) }
    const linked = fresh(`harness-${engine}-linked`)
    const lws = join(linked, 'workspace')
    mkdirSync(lws)
    write(join(linked, 'shared.md'), '# Shared\n')
    symlinkSync(join(linked, 'shared.md'), join(lws, file))
    cases[`harness · ${engine} · a symlinked instruction file`] = { first: attempt(() => prepareHarnessLaunch(harnessPackage(linked), lws, engine, 'runtime-1') && 'prepared'), after: instructionFiles(lws), shared: snapshot(linked)['shared.md'] }
  }
  // The saved APIs' note.
  const withApis = { list: () => [{ id: 'openrouter' }] } as unknown as ApiConnections
  const noApis = { list: () => [] } as unknown as ApiConnections
  const states: Record<string, (ws: string, file: string) => void> = {
    'no file': () => undefined,
    'a file of the person\'s': (ws, file) => write(join(ws, file), '# Mine\n\n\n'),
    'a file already noted': (ws, file) => write(join(ws, file), '# Mine\n<!-- harness:apis -->\nold note\n'),
    'a symlinked file': (ws, file) => { write(join(ws, '..', 'target.md'), '# Target\n'); symlinkSync(join(ws, '..', 'target.md'), join(ws, file)) },
    'a folder by that name': (ws, file) => mkdirSync(join(ws, file)),
  }
  for (const engine of [...PROCESS_ENGINES, 'terminal', 'gemini']) {
    for (const [state, setup] of Object.entries(states)) {
      if (engine !== 'claude' && engine !== 'codex' && engine !== 'gemini' && state !== 'no file') continue
      for (const [apis, store] of [['saved APIs', withApis], ['no saved APIs', noApis]] as const) {
        if (apis === 'no saved APIs' && state !== 'no file') continue
        const dir = fresh(`apis-${engine}-${state}-${apis}`)
        const ws = join(dir, 'workspace')
        mkdirSync(ws)
        const file = engine === 'claude' ? 'CLAUDE.md' : engine === 'gemini' ? 'GEMINI.md' : 'AGENTS.md'
        setup(ws, file)
        const first = attempt(() => { prepareApiInstructions(store, ws, engine); return 'done' })
        const second = attempt(() => { prepareApiInstructions(store, ws, engine); return 'done' })
        cases[`apis · ${engine} · ${state} · ${apis}`] = { first, second, files: snapshot(dir) }
      }
    }
  }
  return cases
}

describe('launch preparation writes what it did before Claude Code and Codex declared it', () => {
  it('folder trust, resumable history and instruction files match the record', () => {
    const actual: Golden = { trust: trustCases(), resume: resumeCases(), instructions: instructionCases() }
    if (RECORD) {
      if (ROOT_USER) throw new Error('record as a user other than root: the permission cases are part of the record')
      const block = (cases: Record<string, unknown>): string => Object.entries(cases).map(([key, value]) => ` ${JSON.stringify(key)}: ${JSON.stringify(value)}`).join(',\n')
      writeFileSync(GOLDEN, `{\n"trust": {\n${block(actual.trust)}\n},\n"resume": {\n${block(actual.resume)}\n},\n"instructions": {\n${block(actual.instructions)}\n}\n}\n`)
      return
    }
    const golden = JSON.parse(readFileSync(GOLDEN, 'utf8')) as Golden
    for (const section of ['trust', 'resume', 'instructions'] as const) {
      // Compared case by case, so a failure names it. Root skips the permission cases it cannot reproduce.
      const expected = Object.keys(golden[section]).filter((key) => !ROOT_USER || key in actual[section])
      expect(Object.keys(actual[section]).sort(), section).toEqual(expected.sort())
      for (const key of expected) expect(actual[section][key], `${section} · ${key}`).toEqual(golden[section][key])
    }
  }, 120_000)

  it('records no machine-specific path', () => {
    const text = readFileSync(GOLDEN, 'utf8')
    expect(text).not.toContain(tmpdir())
    expect(text).not.toMatch(/\/Users\/|\/home\/runner/)
  })
})