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.

26.9 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { execFileSync } from 'node:child_process'
import { existsSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { PROCESS_ENGINES } from '../engines/types.js'
import { buildEngineCommandArgv, buildEngineLaunchArgv } from '../lib/engineLaunch.js'
import { buildLaunchOverrides } from '../lib/launchOverrides.js'
import type { InstalledDsh } from './installed.js'
import { HARNESS_ADAPTERS, HARNESS_BOOTSTRAP, harnessAdapter } from './adapters.js'
import { compatibleHarnessEngines } from './compatibility.js'
import { incompatibleHarnessEngine } from './compatibility.js'
import { storeLaunchPort } from '../services/storeLaunch.js'
import { forkRuntimeKey, harnessRuntimeDir, migrateHarnessInstructions, prepareHarnessLaunch } from './runtime.js'
import { gridLaunchInProcess } from '../testing/gridLaunchInProcess.js'
import { HARNESS_INSTRUCTIONS, joinedInstructions } from '../lib/agentAttribution.js'
import { env } from '../config/env.js'
import { setAgentSettingsForTest, signedOutForTest } from '../testing/agentSettings.js'

// Harness's status line rides every Claude launch beside what these pin (engines/claude/statusLine.spec.ts).
vi.mock('../engines/kit/statusLine.js', async (original) => ({ ...await original<object>(), statusLineSetting: () => null }))

let root: string
let ws: string
let pkg: InstalledDsh
const write = (path: string, text: string) => {
  mkdirSync(join(path, '..'), { recursive: true })
  writeFileSync(path, text)
}
beforeEach(() => {
  root = realpathSync(mkdtempSync(join(tmpdir(), 'portable harness-')))
  ws = join(root, 'project with spaces')
  mkdirSync(ws)
  const dir = join(root, 'package')
  write(join(dir, 'AGENTS.md'), '# Make a drawing\nRead the draw skill before working.\n')
  write(join(dir, 'skills/draw/SKILL.md'), '# Draw\nRun the toolchain and write .harness/verdict.json.\n')
  pkg = { id: 'acme/draw', dir, realDir: dir, source: dir, ref: null, commit: null, linked: true, installedAt: 1,
    manifest: { spec: 1, id: 'acme/draw', name: 'Drawing', engine: 'claude',
      agent: { instructions: 'AGENTS.md', skills: ['skills'], args: ['--add-dir', '${workspace}/input'],
        env: { TOOLCHAIN: '${dsh}/tools', OLD_SKILLS: '${workspace}/.claude/skills', OTHER_SKILLS: '${workspace}/.agents/skills', HARNESS_DSH: 'spoofed' } } } }
})
afterEach(() => { rmSync(root, { recursive: true, force: true }); signedOutForTest() })

describe('portable harness adapters', () => {
  it('has a contract for every process engine, with no package allowlist', () => {
    expect(Object.keys(HARNESS_ADAPTERS)).toEqual(PROCESS_ENGINES)
    for (const engine of PROCESS_ENGINES) {
      expect(compatibleHarnessEngines({ engine })[0]).toBe(engine)
      expect(new Set(compatibleHarnessEngines({ engine }))).toEqual(new Set(PROCESS_ENGINES))
    }
    expect(compatibleHarnessEngines({})).toEqual([])
    expect(compatibleHarnessEngines({ kind: 'viewer', engine: 'claude' })).toEqual([])
    expect(compatibleHarnessEngines({ engine: 'terminal' })).toEqual([])
    expect(() => harnessAdapter('terminal')).toThrow('Terminal cannot run')
  })

  for (const engine of PROCESS_ENGINES) it(`${engine}: binds the same harness and preserves the engine at launch`, () => {
    const launch = prepareHarnessLaunch(pkg, ws, engine, engine)
    const bootstrap = engine === 'claude' ? 'CLAUDE.md' : 'AGENTS.md'
    expect(readFileSync(join(ws, bootstrap), 'utf8')).toContain(HARNESS_BOOTSTRAP)
    expect(readFileSync(launch.env.HARNESS_CONTEXT_FILE!, 'utf8')).toContain('# Make a drawing')
    expect(readFileSync(launch.env.HARNESS_CONTEXT_FILE!, 'utf8')).toContain(join(launch.env.HARNESS_SKILLS_DIR!, 'draw/SKILL.md'))
    expect(readlinkSync(join(launch.env.HARNESS_SKILLS_DIR!, 'draw'))).toBe(join(pkg.realDir, 'skills/draw'))
    expect(launch.env).toMatchObject({ HARNESS_DSH: pkg.id, HARNESS_DSH_DIR: pkg.realDir, HARNESS_WORKSPACE: ws,
      TOOLCHAIN: join(pkg.realDir, 'tools'), OLD_SKILLS: launch.env.HARNESS_SKILLS_DIR, OTHER_SKILLS: launch.env.HARNESS_SKILLS_DIR })
    expect(launch.args.includes('--add-dir')).toBe(engine === 'claude')
    expect(buildEngineCommandArgv(engine, { extraArgs: launch.args }).slice(-launch.args.length || Infinity)).toEqual(launch.args)
    expect(existsSync(join(ws, '.claude/skills'))).toBe(false)
    expect(existsSync(join(ws, '.agents/skills'))).toBe(false)
  })

  for (const [engine, file] of [['codex', 'AGENTS.override.md'], ['pi', 'CLAUDE.md'], ['hermes', '.hermes.md'], ['hermes', '.cursorrules'], ['opencode', 'CLAUDE.md'], ['agy', 'GEMINI.md']] as const) {
    it(`${engine}: respects existing ${file} and preserves its bytes`, () => {
      write(join(ws, file), '# My project rules')
      const first = prepareHarnessLaunch(pkg, ws, engine, 'session')
      const once = readFileSync(join(ws, file), 'utf8')
      expect(once.startsWith('# My project rules\n')).toBe(true)
      expect(once).toContain(HARNESS_BOOTSTRAP)
      expect(prepareHarnessLaunch(pkg, ws, engine, 'session')).toEqual(first)
      expect(readFileSync(join(ws, file), 'utf8')).toBe(once)
    })
  }
})

describe('session isolation and lifecycle', () => {
  it('makes legacy skill commands executable without redirecting upstream source paths', () => {
    write(join(pkg.realDir, 'AGENTS.md'), 'You are Codex in this workspace.\n' +
      '```sh\ncat .agents/skills/draw/SKILL.md\n```\n' +
      'Read `.claude/skills/draw/SKILL.md`. Keep `$STUDIO_UPSTREAM/.claude/skills/reference/` and `runtime/.agents/skills/source/` and `.agents/skills-other`.\n')
    const launch = prepareHarnessLaunch(pkg, ws, 'codex', 'legacy-paths')
    const content = readFileSync(launch.env.HARNESS_CONTEXT_FILE!, 'utf8')
    expect(content).toContain('You are an agent in this workspace.')
    expect(content).toContain('`"$HARNESS_SKILLS_DIR"/draw/SKILL.md`')
    expect(content).toContain('$STUDIO_UPSTREAM/.claude/skills/reference/')
    expect(content).toContain('runtime/.agents/skills/source/')
    expect(content).toContain('.agents/skills-other')
    const command = content.match(/```sh\n([^`]+)```/)![1]!
    expect(execFileSync('/bin/sh', ['-c', command], { encoding: 'utf8', env: { PATH: process.env.PATH, ...launch.env } })).toContain('# Draw')
  })

  it('does not inherit the previous account private grid on a harness relaunch', async () => {
    const result = await buildLaunchOverrides({ machine: () => ({ hermesSystemManaged: false }), gridLaunch: gridLaunchInProcess(),
      writeGridConfigDir: async () => '/unused', capabilities: async () => ({ sessionEnv: true }),
      installCodexHooks: () => true, dshLaunch: async () => ({ ok: true, launch: prepareHarnessLaunch(pkg, ws, 'claude', 'new-account') }),
    }, 'claude', { dsh: pkg.id, cwd: ws }, 'agent')
    if (!result.ok) throw new Error(result.detail)
    const [, , script] = buildEngineLaunchArgv('claude', { clearEnv: result.overrides.clearEnv }, '/bin/sh', undefined, undefined, null)
    const seen = execFileSync('/bin/sh', ['-c', script!, 'harness-engine', '/bin/sh', '-c',
      'test -z "${HARNESS_PRIVATE_GRID+x}" || exit 9; printf "%s" "$HARNESS_CONTEXT_FILE"'], {
      encoding: 'utf8', env: { ...process.env, HARNESS_PRIVATE_GRID: 'another-account', ...result.overrides.env }, stdio: ['ignore', 'pipe', 'pipe'],
    })
    expect(seen).toBe(result.overrides.env.HARNESS_CONTEXT_FILE)
  })

  it('hands Codex every harness variable as a flag, since its commands run outside the launched process', () => {
    pkg.manifest.agent!.env = { ...pkg.manifest.agent!.env, QUOTED: 'say "hi" \\ bye', 'NOT-A-KEY': 'x' }
    const launch = prepareHarnessLaunch(pkg, ws, 'codex', 'env-flags')
    const set = (name: string) => `shell_environment_policy.set.${name}=${JSON.stringify(launch.env[name])}`
    for (const name of ['HARNESS_CONTEXT_FILE', 'HARNESS_SKILLS_DIR', 'HARNESS_WORKSPACE', 'HARNESS_DSH', 'TOOLCHAIN']) {
      expect(launch.args[launch.args.indexOf(set(name)) - 1]).toBe('-c')
    }
    expect(launch.args).toContain('shell_environment_policy.set.QUOTED="say \\"hi\\" \\\\ bye"')
    expect(launch.args.some(arg => arg.includes('NOT-A-KEY'))).toBe(false)
    // Every other engine runs its commands under the process Harness launched, which already has them.
    expect(prepareHarnessLaunch(pkg, ws, 'claude', 'env-flags-claude').args.some(arg => arg.startsWith('shell_environment_policy'))).toBe(false)
  })

  it('keeps two harnesses in one project separate, leaving no harness content in project rules', () => {
    write(join(ws, 'AGENTS.md'), '# My project rules\n')
    const a = prepareHarnessLaunch(pkg, ws, 'codex', 'a')
    const second: InstalledDsh = { ...pkg, id: 'acme/music', manifest: { ...pkg.manifest, id: 'acme/music', name: 'Music' } }
    write(join(pkg.realDir, 'AGENTS.md'), '# Make music\n')
    const b = prepareHarnessLaunch(second, ws, 'codex', 'b')
    expect(a.env.HARNESS_CONTEXT_FILE).not.toBe(b.env.HARNESS_CONTEXT_FILE)
    expect(readFileSync(a.env.HARNESS_CONTEXT_FILE!, 'utf8')).toContain('# Make a drawing')
    expect(readFileSync(b.env.HARNESS_CONTEXT_FILE!, 'utf8')).not.toContain('# Make a drawing')
    expect(readFileSync(join(ws, 'AGENTS.md'), 'utf8')).toBe(`# My project rules\n\n${HARNESS_BOOTSTRAP}`)
  })

  it('resumes and forks the original engine/content/env/args despite package changes, refreshing account facts', async () => {
    // With what every harness is told once the account lets agents start agents (off by default), joined with its own.
    setAgentSettingsForTest(env.ADAPTER_DATA_DIR, { agentsStartAgents: true })
    const first = prepareHarnessLaunch(pkg, ws, 'claude', 'original', { privateGrid: 'old-grid' })
    pkg.manifest.engine = 'codex'
    pkg.manifest.agent!.args = ['--new-flag']
    pkg.manifest.agent!.env = { TOOLCHAIN: 'changed' }
    write(join(pkg.realDir, 'AGENTS.md'), '# Updated instructions\n')
    const deps = { machine: () => ({ hermesSystemManaged: false }), gridLaunch: gridLaunchInProcess(), writeGridConfigDir: async () => '/cfg',
      capabilities: async () => ({ sessionEnv: true }), installCodexHooks: () => true,
      dshLaunch: async (_id: string, workspace: string, engine: typeof PROCESS_ENGINES[number] | 'terminal', key: string) =>
        ({ ok: true as const, launch: prepareHarnessLaunch(pkg, workspace, engine, key, { privateGrid: 'new-grid' }) }) }
    const result = await buildLaunchOverrides(deps, 'claude', { dsh: pkg.id, cwd: ws, dshRuntime: 'original' }, 'registry-agent-id')
    expect(result.ok && result.overrides.env.HARNESS_CONTEXT_FILE).toBe(first.env.HARNESS_CONTEXT_FILE)
    expect(result.ok && result.overrides.env.HARNESS_PRIVATE_GRID).toBe('new-grid')
    // Its own argv as it first launched, its context prompt and what every harness is told joined into one.
    expect(result.ok && result.overrides.extraArgs).toEqual(joinedInstructions('claude', [...first.args, '--append-system-prompt', HARNESS_INSTRUCTIONS]))
    const fork = prepareHarnessLaunch(pkg, ws, 'claude', 'fork', {}, 'original')
    expect(fork.env.HARNESS_CONTEXT_FILE).not.toBe(first.env.HARNESS_CONTEXT_FILE)
    expect(readFileSync(fork.env.HARNESS_CONTEXT_FILE!, 'utf8')).toContain('# Make a drawing')
    expect(fork.env.TOOLCHAIN).toBe(first.env.TOOLCHAIN)
    expect(fork.env.HARNESS_PRIVATE_GRID).toBeUndefined()
    const fresh = prepareHarnessLaunch(pkg, ws, 'codex', 'fresh')
    expect(readFileSync(fresh.env.HARNESS_CONTEXT_FILE!, 'utf8')).toContain('# Updated instructions')
    expect(fresh.args).toEqual(['--new-flag', ...HARNESS_ADAPTERS.codex.envArgs!(fresh.env)])
  })

  it('keeps older rows stable using their agent id and supports package renames', async () => {
    const deps = { machine: () => ({ hermesSystemManaged: false }), gridLaunch: gridLaunchInProcess(), writeGridConfigDir: async () => '/cfg',
      capabilities: async () => ({ sessionEnv: true }), installCodexHooks: () => true,
      dshLaunch: async (_id: string, workspace: string, engine: typeof PROCESS_ENGINES[number] | 'terminal', key: string) => ({ ok: true as const, launch: prepareHarnessLaunch(pkg, workspace, engine, key) }) }
    const first = await buildLaunchOverrides(deps, 'codex', { dsh: pkg.id, cwd: ws }, 'old-agent')
    pkg.manifest.formerly = [pkg.id]
    pkg.id = 'acme/drawing'
    const next = await buildLaunchOverrides(deps, 'codex', { dsh: pkg.id, cwd: ws }, 'old-agent')
    expect(next).toEqual(first)
  })

  it('reports preparation failures, missing dependencies, or no resolver before a relaunch', async () => {
    const deps = { machine: () => ({ hermesSystemManaged: false }), gridLaunch: gridLaunchInProcess(), writeGridConfigDir: async () => '/cfg',
      capabilities: async () => ({ sessionEnv: true }), installCodexHooks: () => true }
    expect(await buildLaunchOverrides(deps, 'codex', { dsh: pkg.id, cwd: ws }, 'key')).toMatchObject({ ok: false, error: 'DSH_NOT_INSTALLED' })
    expect(await buildLaunchOverrides({ ...deps, dshLaunch: () => { throw new Error('broken context') } }, 'codex', { dsh: pkg.id, cwd: ws }, 'key'))
      .toMatchObject({ ok: false, error: 'DSH_RUNTIME_FAILED', detail: 'Error: broken context' })
  })
})

describe('runtime validation and file ownership', () => {
  it('retries the same fork without replacing an occupied destination with another snapshot', () => {
    prepareHarnessLaunch(pkg, ws, 'codex', 'source')
    const fork = prepareHarnessLaunch(pkg, ws, 'codex', 'fork', {}, 'source')
    expect(prepareHarnessLaunch(pkg, ws, 'codex', 'fork', {}, 'source')).toEqual(fork)
    const before = readFileSync(fork.env.HARNESS_CONTEXT_FILE!, 'utf8')
    write(join(pkg.realDir, 'AGENTS.md'), '# Different instructions\n')
    prepareHarnessLaunch(pkg, ws, 'codex', 'other-source')
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'fork', {}, 'other-source')).toThrow('fork destination already has a different harness runtime')
    expect(readFileSync(fork.env.HARNESS_CONTEXT_FILE!, 'utf8')).toBe(before)
    const file = join(harnessRuntimeDir(ws, 'fork'), 'runtime.json')
    const saved = readFileSync(file, 'utf8')
    write(file, '{corrupt')
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'fork', {}, 'source')).toThrow()
    write(file, saved)
    rmSync(file)
    symlinkSync(join(root, 'missing'), file)
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'fork', {}, 'source')).toThrow('snapshot is a symlink')
  })

  it('keeps runtime snapshots out of Git while preserving existing ignore rules', () => {
    write(join(ws, '.harness/.gitignore'), '# User rules\nmy-data');
    prepareHarnessLaunch(pkg, ws, 'codex', 'key');
    expect(readFileSync(join(ws, '.harness/.gitignore'), 'utf8')).toBe('# User rules\nmy-data\nruntime/\nlegacy-AGENTS.md\n/.gitignore\n');
    prepareHarnessLaunch(pkg, ws, 'codex', 'key');
    expect(readFileSync(join(ws, '.harness/.gitignore'), 'utf8').match(/runtime\//g)).toHaveLength(1);
  })

  it('supports a minimal harness and deduplicates repeated skill roots', () => {
    pkg.manifest.agent = undefined
    const launch = prepareHarnessLaunch(pkg, ws, 'codex', '../../outside')
    expect(launch.env.HARNESS_CONTEXT_FILE).toContain(join(ws, '.harness/runtime'))
    expect(readFileSync(launch.env.HARNESS_CONTEXT_FILE!, 'utf8')).toContain('## Harness skills')
    pkg.manifest.agent = { skills: ['skills', 'skills/draw'] }
    const next = prepareHarnessLaunch(pkg, ws, 'codex', 'dedup')
    expect(readFileSync(next.env.HARNESS_CONTEXT_FILE!, 'utf8').match(/- draw:/g)).toHaveLength(1)
    expect(() => harnessRuntimeDir(ws, '')).toThrow('session key')
  })

  it('imports existing AGENTS rules for Claude once and normalizes legacy engine introductions', () => {
    write(join(ws, 'AGENTS.md'), '# Repository rules\n')
    write(join(pkg.realDir, 'AGENTS.md'), 'You are Claude Code in a drawing workspace.\n')
    const launch = prepareHarnessLaunch(pkg, ws, 'claude', 'first')
    expect(readFileSync(launch.env.HARNESS_CONTEXT_FILE!, 'utf8')).toContain('You are an agent in a drawing workspace.')
    expect(readFileSync(join(ws, 'CLAUDE.md'), 'utf8')).toContain('@AGENTS.md\n')
    write(join(ws, 'CLAUDE.md'), '# Claude project rules\n@AGENTS.md\n')
    prepareHarnessLaunch(pkg, ws, 'claude', 'second')
    expect(readFileSync(join(ws, 'CLAUDE.md'), 'utf8').match(/@AGENTS.md/g)).toHaveLength(1)
  })

  it('rejects terminal/viewer, missing instructions/skills, and duplicate skill names', () => {
    expect(() => prepareHarnessLaunch(pkg, ws, 'terminal', 'key')).toThrow('Terminal cannot run')
    pkg.manifest.kind = 'viewer'
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).toThrow('viewer')
    delete pkg.manifest.kind
    pkg.manifest.agent!.instructions = 'missing.md'
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).toThrow('ENOENT')
    delete pkg.manifest.agent!.instructions
    pkg.manifest.agent!.skills = ['missing']
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).toThrow('No SKILL.md')
    write(join(pkg.realDir, 'other/draw/SKILL.md'), '# Other draw')
    pkg.manifest.agent!.skills = ['skills', 'other']
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).toThrow('Duplicate harness skill')
    expect(existsSync(join(ws, 'AGENTS.md'))).toBe(false)
  })

  it('refuses a different saved engine or package, corrupt snapshots and missing fork sources', () => {
    prepareHarnessLaunch(pkg, ws, 'codex', 'key')
    expect(() => prepareHarnessLaunch(pkg, ws, 'claude', 'key')).toThrow('runtime belongs')
    expect(() => prepareHarnessLaunch({ ...pkg, id: 'acme/other' }, ws, 'codex', 'key')).toThrow('runtime belongs')
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'fork', {}, 'missing')).toThrow('original harness runtime is missing')
    const file = join(harnessRuntimeDir(ws, 'key'), 'runtime.json')
    write(file, '{broken')
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).toThrow()
    write(file, '{"version":2}')
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).toThrow()
    rmSync(file)
    symlinkSync(join(root, 'outside'), file)
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).toThrow('snapshot is a symlink')
  })

  for (const target of ['.harness', '.harness/runtime', 'bundle', 'skills']) it(`refuses symlinked ${target} directories`, () => {
    const path = target === 'bundle' ? harnessRuntimeDir(ws, 'key') : target === 'skills' ? join(harnessRuntimeDir(ws, 'key'), 'skills') : join(ws, target)
    mkdirSync(join(path, '..'), { recursive: true })
    symlinkSync(join(root, 'does-not-exist'), path)
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).toThrow('not a plain directory')
  })

  it('refuses directory collisions, user links, edited bootstraps and modified context links', () => {
    write(join(ws, '.harness'), 'user file')
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).toThrow('not a plain directory')
    rmSync(join(ws, '.harness'))
    write(join(root, 'my-rules'), '# My rules')
    symlinkSync(join(root, 'my-rules'), join(ws, 'AGENTS.md'))
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).toThrow('Refusing to replace a symlink')
    expect(readFileSync(join(root, 'my-rules'), 'utf8')).toBe('# My rules')
    rmSync(join(ws, 'AGENTS.md'))
    write(join(ws, 'AGENTS.md'), '<!-- harness:runtime v1 -->\nedited')
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).toThrow('bootstrap')
    rmSync(join(ws, 'AGENTS.md'))
    const launch = prepareHarnessLaunch(pkg, ws, 'codex', 'key')
    rmSync(launch.env.HARNESS_CONTEXT_FILE!)
    symlinkSync(join(root, 'my-rules'), launch.env.HARNESS_CONTEXT_FILE!)
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).toThrow('Refusing to replace a symlink')
  })

  it('refuses missing skills and occupied skill paths without touching them', () => {
    const launch = prepareHarnessLaunch(pkg, ws, 'codex', 'key')
    const skill = join(launch.env.HARNESS_SKILLS_DIR!, 'draw')
    unlinkSync(skill)
    mkdirSync(skill)
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).toThrow('already occupied')
    rmSync(skill, { recursive: true })
    symlinkSync(join(root, 'user-skill'), skill)
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).toThrow('already occupied')
    rmSync(join(pkg.realDir, 'skills/draw/SKILL.md'))
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).toThrow('Harness skill is missing')
  })

  // An exact string compare refused a link to the same folder written another way as "already occupied".
  it('relaunches over its own skill link however the link writes the same folder', () => {
    const launch = prepareHarnessLaunch(pkg, ws, 'codex', 'key')
    const skill = join(launch.env.HARNESS_SKILLS_DIR!, 'draw')
    unlinkSync(skill)
    symlinkSync(`${join(pkg.realDir, 'skills/draw')}/`, skill)
    expect(() => prepareHarnessLaunch(pkg, ws, 'codex', 'key')).not.toThrow()
    expect(readFileSync(join(skill, 'SKILL.md'), 'utf8')).toContain('# Draw')
  })
})

describe('non-destructive legacy migration', () => {
  const legacy = () => `# User rules\n\n<!-- harness:dsh ${pkg.id} -->\n${readFileSync(join(pkg.realDir, 'AGENTS.md'), 'utf8').trim()}\n\n# User additions\n`

  it('archives exact bytes, removes only known instructions and owned native skill links, and is idempotent', () => {
    const before = legacy()
    write(join(ws, 'AGENTS.md'), before)
    for (const native of ['.claude/skills', '.agents/skills']) {
      mkdirSync(join(ws, native), { recursive: true })
      symlinkSync(join(pkg.realDir, 'skills/draw'), join(ws, native, 'draw'))
      symlinkSync(join(root, 'user-owned'), join(ws, native, 'mine'))
    }
    migrateHarnessInstructions(ws, pkg)
    expect(readFileSync(join(ws, 'AGENTS.md'), 'utf8')).toBe('# User rules\n\n\n# User additions\n')
    expect(readFileSync(join(ws, '.harness/legacy-AGENTS.md'), 'utf8')).toBe(before)
    expect(existsSync(join(ws, '.claude/skills/draw'))).toBe(false)
    expect(readlinkSync(join(ws, '.claude/skills/mine'))).toBe(join(root, 'user-owned'))
    write(join(ws, 'AGENTS.md'), before)
    migrateHarnessInstructions(ws, pkg)
    migrateHarnessInstructions(ws, pkg)
    expect(readFileSync(join(ws, '.harness/legacy-AGENTS.md'), 'utf8')).toBe(before)
  })

  it('handles renamed and other installed harnesses and preserves non-owned skill paths', () => {
    write(join(ws, 'AGENTS.md'), legacy())
    const old = pkg.id
    pkg.id = 'acme/renamed'
    pkg.manifest.formerly = [old]
    mkdirSync(join(ws, '.claude/skills/draw'), { recursive: true })
    mkdirSync(join(ws, '.agents/skills'), { recursive: true })
    symlinkSync(join(root, 'my-draw'), join(ws, '.agents/skills/draw'))
    migrateHarnessInstructions(ws, pkg)
    expect(readlinkSync(join(ws, '.agents/skills/draw'))).toBe(join(root, 'my-draw'))
    write(join(ws, 'AGENTS.md'), legacy())
    migrateHarnessInstructions(ws, { ...pkg, id: 'acme/another', manifest: { ...pkg.manifest, formerly: undefined } }, id => id === pkg.id ? pkg : null)
    expect(readFileSync(join(ws, 'AGENTS.md'), 'utf8')).not.toContain('harness:dsh')
  })

  it('preserves native directories reached through symlinks, even when their skill links match', () => {
    write(join(ws, 'AGENTS.md'), legacy())
    mkdirSync(join(root, 'external/skills'), { recursive: true })
    symlinkSync(join(pkg.realDir, 'skills/draw'), join(root, 'external/skills/draw'))
    symlinkSync(join(root, 'external'), join(ws, '.claude'))
    mkdirSync(join(ws, '.agents'))
    symlinkSync(join(root, 'external/skills'), join(ws, '.agents/skills'))
    migrateHarnessInstructions(ws, pkg)
    expect(readlinkSync(join(root, 'external/skills/draw'))).toBe(join(pkg.realDir, 'skills/draw'))
  })

  it('leaves edited or unknown legacy sections intact and returns an actionable failure', () => {
    write(join(ws, 'AGENTS.md'), legacy().replace('# Make a drawing', '# My edits'))
    expect(() => migrateHarnessInstructions(ws, pkg)).toThrow('were edited')
    write(join(ws, 'AGENTS.md'), '<!-- harness:dsh gone/away -->\n# Lost instructions\n')
    expect(() => migrateHarnessInstructions(ws, pkg, () => null)).toThrow('restore the package')
    expect(() => migrateHarnessInstructions(ws, pkg, () => ({ ...pkg, manifest: { ...pkg.manifest, agent: undefined } }))).toThrow('restore the package')
    expect(readFileSync(join(ws, 'AGENTS.md'), 'utf8')).toContain('# Lost instructions')
  })

  it('migrates instruction-only harnesses without replacing an existing backup symlink', () => {
    delete pkg.manifest.agent!.skills
    write(join(ws, 'AGENTS.md'), legacy())
    mkdirSync(join(ws, '.harness'))
    symlinkSync(join(root, 'my-backup'), join(ws, '.harness/legacy-AGENTS.md'))
    migrateHarnessInstructions(ws, pkg)
    expect(readlinkSync(join(ws, '.harness/legacy-AGENTS.md'))).toBe(join(root, 'my-backup'))
  })
})

// The decisions the daemon's create and fork handlers make about a harness launch. They live here,
// not inline in cli.ts, because that file is never loaded by a unit test and these are the cases a
// refused launch depends on.
describe('create and fork decisions', () => {
  it('names what WOULD run when an engine cannot run the harness', () => {
    expect(incompatibleHarnessEngine('acme/draw', pkg.manifest, 'codex')).toBeNull()
    expect(incompatibleHarnessEngine('acme/draw', pkg.manifest, 'claude')).toBeNull()
    const refusal = incompatibleHarnessEngine('acme/draw', pkg.manifest, 'terminal')
    expect(refusal).toMatch(/^acme\/draw supports claude, /)
    expect(refusal).toMatch(/; terminal is not compatible$/)
  })

  it('refuses every engine for something that is not a runnable harness', () => {
    for (const manifest of [{ kind: 'viewer', engine: 'claude' as const }, {}, { engine: 'terminal' as const }]) {
      expect(incompatibleHarnessEngine('acme/view', manifest, 'claude')).toBe('acme/view cannot run as an agent')
    }
  })

  it('forks the runtime the source recorded', () => {
    expect(forkRuntimeKey({ cwd: ws, agentId: 'a1', dshRuntime: 'harness-claude-x' })).toBe('harness-claude-x')
  })

  it('forks a pre-key session from the bundle under its agent id, and otherwise starts fresh', () => {
    const source = { cwd: ws, agentId: 'a1', dshRuntime: null }
    expect(forkRuntimeKey(source)).toBeNull()
    expect(forkRuntimeKey({ cwd: ws, agentId: 'a1' })).toBeNull()
    prepareHarnessLaunch(pkg, ws, 'claude', 'a1')
    expect(existsSync(join(harnessRuntimeDir(ws, 'a1'), 'runtime.json'))).toBe(true)
    expect(forkRuntimeKey(source)).toBe('a1')
    // An empty recorded key is no key: it must not shadow the bundle that exists.
    expect(forkRuntimeKey({ ...source, dshRuntime: '' })).toBe('a1')
  })

  it('the Store turns a runtime that cannot be prepared into a refusal', async () => {
    const store = storeLaunchPort(() => pkg)
    const request = { dsh: pkg.id, workspace: ws, engine: 'claude' as const, key: 'k', account: {} }
    expect((await store.dshLaunch(request)).ok).toBe(true)
    rmSync(join(pkg.realDir, 'skills/draw/SKILL.md'))
    const refused = await store.dshLaunch({ ...request, key: 'fresh' })
    expect(refused).toMatchObject({ ok: false, error: 'DSH_RUNTIME_FAILED' })
    expect(refused.ok ? '' : refused.detail).not.toMatch(/^Error: /)
  })
})