Skip to content

The agent that grows with you

74.7 KB
Raw Blame
import assert from 'node:assert/strict'
import { exec as execCallback, spawn } from 'node:child_process'
import { chmod, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
import os from 'node:os'
import path from 'node:path'
import { promisify } from 'node:util'

import { test } from 'vitest'

import { profileSshOverride } from './connection-config'
import {
  assertRemoteInstallUpdateClear,
  buildSpawnCommand,
  classifySshReuseProof,
  cleanupStale,
  connect,
  DEFAULT_READY_TIMEOUT_MS,
  disconnect,
  expandRemotePath,
  fingerprintToken,
  isForwardBindCollision,
  isLockfileSkew,
  listRemoteHermesProfiles,
  locateHermes,
  LOCKFILE_SCHEMA_VERSION,
  lockfilePath,
  MIN_READY_TIMEOUT_MS,
  openForward,
  ownershipDirectory,
  pidIsOurDashboard,
  probeHermesVersion,
  probeRemotePlatform,
  PROTOCOL_VERSION,
  readLockfile,
  readRemoteInstallId,
  READY_RE,
  remotePidAlive,
  remoteSupportsSshOwnership,
  resolveReadyTimeoutMs,
  scrapeReadyPort,
  spawnLogPath,
  spawnRemoteDashboard,
  spawnTokenPath,
  terminateOwnedDashboardForUpdate,
  validateRemotePath,
  writeLockfile
} from './remote-lifecycle'
import type { SshConnection } from './ssh-connection'

const OWNERSHIP_ID = '0123456789abcdef0123456789abcdef'
const SPAWN_NONCE = '0123456789abcdef'
const exec = promisify(execCallback)

test('SSH reuse proof rejects a backend whose runtime was replaced', () => {
  assert.equal(
    classifySshReuseProof(
      { ok: true, sshOwnerNonce: SPAWN_NONCE, protocolVersion: 1, runtimeIntact: false },
      SPAWN_NONCE
    ),
    'authenticated-stale'
  )
})

test('SSH reuse proof remains compatible when runtime state is absent', () => {
  assert.equal(
    classifySshReuseProof({ ok: true, sshOwnerNonce: SPAWN_NONCE, protocolVersion: 1 }, SPAWN_NONCE),
    'authenticated-ok'
  )
})

function ownedLock(over: any = {}) {
  return {
    schemaVersion: LOCKFILE_SCHEMA_VERSION,
    protocolVersion: PROTOCOL_VERSION,
    ownershipId: OWNERSHIP_ID,
    spawnNonce: SPAWN_NONCE,
    pid: 333,
    port: 40000,
    profile: '',
    hermesPath: '~/.local/bin/hermes',
    hermesHome: '~/.hermes',
    logPath: spawnLogPath(OWNERSHIP_ID, SPAWN_NONCE),
    tokenFingerprint: fingerprintToken('stored-token'),
    startedAt: '2026-07-14T00:00:00.000Z',
    creationTime: 'linux:123456',
    ...over
  }
}

// A fake SshConnection whose exec() is matched against an ordered list of
// [regex|fn, response|fn] rules. First match wins; unmatched commands return ''.
function fakeSsh(rules: any[] = []) {
  const calls: string[] = []

  return {
    calls,
    async exec(cmd) {
      calls.push(cmd)

      // Existing lifecycle fixtures predate the install-wide relaunch gate.
      // Their default remote has no update marker; focused marker tests below
      // use explicit SSH doubles to exercise live/uncertain transitions.
      const mutexWrapped = /setsid|nohup/.test(cmd) // spawn payloads run under the relaunch probe's marker gate

      if (cmd.includes('.hermes-update-in-progress') && !mutexWrapped) {
        return 'CLEAR'
      }

      const applicableRules = rules.filter(([matcher]) => {
        if (mutexWrapped && matcher instanceof RegExp && /kill -0/.test(matcher.source)) {
          return false
        }

        return !(mutexWrapped && matcher instanceof RegExp && /python3 -c/.test(matcher.source))
      })

      if (
        (cmd.includes('os.kill(pid') && !cmd.includes('pidfd_open') && !mutexWrapped) ||
        cmd.includes('printf TERMINATED')
      ) {
        return 'TERMINATED'
      }

      for (const [matcher, resp] of applicableRules) {
        const hit = typeof matcher === 'function' ? matcher(cmd) : matcher.test(cmd)

        if (hit) {
          const out = typeof resp === 'function' ? resp(cmd) : resp

          if (out instanceof Error) {
            throw out
          }

          return out
        }
      }

      return ''
    }
  }
}

test('POSIX relaunch gate refuses live and uncertain install markers without executing Hermes', async () => {
  for (const observation of ['LIVE:4242', 'UNCERTAIN']) {
    const calls: string[] = []

    const ssh = {
      async exec(command) {
        calls.push(command)

        if (command === 'uname -s; uname -m') {
          return 'Linux\nx86_64\n'
        }

        if (command.includes('HERMES_HOME')) {
          return '/home/alice/.hermes\n'
        }

        if (command.includes('.hermes-update-in-progress')) {
          return observation
        }

        throw new Error(`unexpected command after update gate: ${command}`)
      }
    }

    await assert.rejects(
      () => connect(connectDeps(ssh)),
      (error: any) => error.kind === 'update-in-progress'
    )
    assert.equal(
      calls.some(command => /\[ -x |--version|lock\.json|serve --help|setsid/.test(command)),
      false
    )
  }
})

test('POSIX relaunch gate permits absent/dead markers and normalizes named-profile homes install-wide', async () => {
  const commands: string[] = []

  const ssh = {
    async exec(command) {
      commands.push(command)

      return 'CLEAR'
    }
  }

  await assertRemoteInstallUpdateClear(ssh, '/home/alice/.hermes/profiles/research')
  assert.ok(commands[0].endsWith(" '/home/alice/.hermes/.hermes-update-in-progress'"), commands[0].slice(-80))
})

test('POSIX relaunch gate rechecks after token upload immediately before process creation', async () => {
  const calls: string[] = []
  let markerChecks = 0

  const ssh = {
    async exec(command) {
      calls.push(command)

      if (command === 'uname -s; uname -m') {
        return 'Linux\nx86_64\n'
      }

      if (command.includes('HERMES_HOME')) {
        return '/home/alice/.hermes\n'
      }

      if (command.includes('.hermes-update-in-progress')) {
        markerChecks += 1

        return markerChecks >= 3 ? 'LIVE:4242' : 'CLEAR'
      }

      if (/\[ -x /.test(command)) {
        return 'OK'
      }

      if (command.includes('serve --help')) {
        return 'YES\n'
      }

      if (command.includes('python3 -c')) {
        return ''
      }

      if (command.includes('lock.json')) {
        return ''
      }

      return ''
    }
  }

  await assert.rejects(
    () => connect(connectDeps(ssh)),
    (error: any) => error.kind === 'update-in-progress'
  )
  assert.equal(markerChecks, 3)
  assert.equal(
    calls.some(command => /setsid|nohup/.test(command)),
    false
  )
})

test('readRemoteInstallId reads the backend identity without spawning a dashboard or minting one', async () => {
  const ssh = fakeSsh([
    [/HERMES_HOME/, '/Users/zillajr/.hermes\n'],
    [/cat .*install_id/, '0f8a1c2b3d4e5f60718293a4b5c6d7e8\n']
  ])

  assert.equal(await readRemoteInstallId(ssh), '0f8a1c2b3d4e5f60718293a4b5c6d7e8')
  // Read-only: identity is the install's to mint, never a visiting client's.
  assert.equal(
    ssh.calls.some(cmd => /serve|dashboard|>\s*\S*install_id|tee|uuidgen/.test(cmd)),
    false
  )
})

test('readRemoteInstallId reports the INSTALL root id for a profile-pinned home', async () => {
  // The whole point of the id: two ssh connections to one machine — one pinned at a profile,
  // one at the root — must report the SAME backend so their roster rows collapse.
  const pinned = fakeSsh([
    [/HERMES_HOME/, '/Users/zillajr/.hermes/profiles/dixie\n'],
    [/cat .*install_id/, '0f8a1c2b3d4e5f60718293a4b5c6d7e8\n']
  ])

  assert.equal(await readRemoteInstallId(pinned), '0f8a1c2b3d4e5f60718293a4b5c6d7e8')
  assert.equal(
    pinned.calls.some(cmd => cmd.includes('/Users/zillajr/.hermes/install_id')),
    true
  )
  assert.equal(
    pinned.calls.some(cmd => cmd.includes('/profiles/dixie/install_id')),
    false
  )
})

test('readRemoteInstallId reports no id rather than a bad one', async () => {
  for (const payload of ['', 'not-an-id\n', 'ABCDEF\n', '0f8a1c2b3d4e5f60718293a4b5c6d7e8extra\n']) {
    const ssh = fakeSsh([
      [/HERMES_HOME/, '/Users/zillajr/.hermes\n'],
      [/cat .*install_id/, payload]
    ])

    // An older backend (or one that has never been started) simply has no identity: the roster
    // falls back to a per-connection key, exactly as before.
    assert.equal(await readRemoteInstallId(ssh), undefined, payload)
  }
})

test('listRemoteHermesProfiles inventories Mini-style profile dirs without spawning a dashboard', async () => {
  const ssh = fakeSsh([
    [/HERMES_HOME/, '/Users/zillajr/.hermes\n'],
    [/ls -1/, 'bob\ndixie\ngoose\nrambo\nbob.rollback-old\n']
  ])

  assert.deepEqual(await listRemoteHermesProfiles(ssh), ['default', 'bob', 'dixie', 'goose', 'rambo'])
  assert.equal(
    ssh.calls.some(cmd => cmd.includes('serve') || cmd.includes('dashboard')),
    false
  )
})

test('listRemoteHermesProfiles rejects a hostile HERMES_HOME', async () => {
  const ssh = fakeSsh([[/HERMES_HOME/, '/tmp/x; echo pwned\n']])

  await assert.rejects(
    () => listRemoteHermesProfiles(ssh),
    (err: any) => {
      assert.equal(err.kind, 'unsafe-path')

      return true
    }
  )
  assert.equal(
    ssh.calls.some(cmd => cmd.includes('ls -1')),
    false
  )
})

test('locateHermes prefers the explicit profile path when executable', async () => {
  const ssh = fakeSsh([[/\[ -x .*\/opt\/hermes/, 'OK']])
  assert.equal(await locateHermes(ssh, '/opt/hermes'), '/opt/hermes')
})

test('locateHermes throws (no silent fallback) when an EXPLICIT path is not executable', async () => {
  // command -v WOULD find a different install, but an explicit path must not
  // silently fall back to it — that is the "connected to the wrong hermes" bug.
  const ssh = fakeSsh([
    [/command -v hermes/, '/home/u/.local/bin/hermes\n'],
    [/\[ -x .*\.local\/bin\/hermes/, 'OK']
  ])

  await assert.rejects(
    () => locateHermes(ssh, '/bad/path/hermes'),
    (err: any) => {
      assert.equal(err.kind, 'hermes-not-found')
      assert.match(err.message, /\/bad\/path\/hermes/)

      return true
    }
  )
})

test('locateHermes falls back to the login-shell command -v probe', async () => {
  const ssh = fakeSsh([
    [/command -v hermes/, '/home/u/.local/bin/hermes\n'],
    [/\[ -x .*\.local\/bin\/hermes/, 'OK']
  ])

  assert.equal(await locateHermes(ssh, ''), '/home/u/.local/bin/hermes')
})

test('locateHermes preserves an installer wrapper instead of resolving its interpreter', async () => {
  // install.sh venv mode writes: exec "$HERMES_BIN" "$HERMES_ENTRYPOINT" "$@",
  // where $HERMES_BIN is the venv python. The old canonicalization returned
  // that interpreter, so `<python> --version` printed "Python x.y.z" and
  // `<python> serve --help` failed outright (#74411). The wrapper itself is
  // executable and forwards args correctly — return it untouched.
  const ssh = fakeSsh([
    [/command -v hermes/, '/home/u/.local/bin/hermes\n'],
    [/\[ -x .*\.local\/bin\/hermes/, 'OK'],
    // If the removed python3 wrapper-parser were ever reintroduced, this rule
    // would reward it with an interpreter path and the assertions below fail.
    [/python3 -c/, '/home/u/.hermes/hermes-agent/venv/bin/python\n']
  ])

  assert.equal(await locateHermes(ssh, ''), '/home/u/.local/bin/hermes')
  assert.ok(
    !ssh.calls.some(cmd => cmd.includes('python3 -c')),
    'locateHermes must not shell out to a python3 parser to rewrite the launcher'
  )
})

test('locateHermes returns an explicit remoteHermesPath unchanged', async () => {
  // The override half of #74411: an explicit remoteHermesPath pointing at a
  // wrapper was also canonicalized to its interpreter, so overriding to
  // ~/.local/bin/hermes changed nothing for affected users.
  const ssh = fakeSsh([
    [/\[ -x .*\.local\/bin\/hermes/, 'OK'],
    [/python3 -c/, '/home/u/.hermes/hermes-agent/venv/bin/python\n']
  ])

  assert.equal(await locateHermes(ssh, '~/.local/bin/hermes'), '~/.local/bin/hermes')
  assert.ok(!ssh.calls.some(cmd => cmd.includes('python3 -c')), 'an explicit remoteHermesPath must never be rewritten')
})

test('locateHermes falls back to ~/.local/bin/hermes when the login-shell probe misses', async () => {
  // ~/.local/bin is the non-root installer's command location (scripts/install.sh).
  const ssh = fakeSsh([
    [/command -v hermes/, ''],
    [/\[ -x .*\.local\/bin\/hermes/, 'OK']
  ])

  assert.equal(await locateHermes(ssh, ''), '~/.local/bin/hermes')
})

test('locateHermes tries the conventional venv path last', async () => {
  const ssh = fakeSsh([[/\[ -x .*venv\/bin\/hermes/, 'OK']])
  assert.equal(await locateHermes(ssh, ''), '~/.hermes/hermes-agent/venv/bin/hermes')
})

test('locateHermes throws a hermes-not-found error with an install hint', async () => {
  const ssh = fakeSsh([]) // nothing is executable
  await assert.rejects(
    () => locateHermes(ssh, ''),
    (err: any) => {
      assert.equal(err.kind, 'hermes-not-found')
      assert.match(err.message, /install/i)

      return true
    }
  )
})

test('locateHermes uses a login shell for the command -v probe', async () => {
  const ssh = fakeSsh([
    [/command -v hermes/, '/x/hermes'],
    [/\[ -x/, 'OK']
  ])

  await locateHermes(ssh, '')
  assert.ok(
    ssh.calls.some(c => /bash -lc/.test(c)),
    'must probe in a login shell (PATH pitfall)'
  )
})

test('probeRemotePlatform accepts Linux and macOS', async () => {
  assert.deepEqual(await probeRemotePlatform(fakeSsh([[/uname/, 'Linux\nx86_64']])), {
    os: 'Linux',
    arch: 'x86_64'
  })
  assert.deepEqual(await probeRemotePlatform(fakeSsh([[/uname/, 'Darwin\narm64']])), {
    os: 'Darwin',
    arch: 'arm64'
  })
})

test('probeRemotePlatform rejects unsupported remote platforms', async () => {
  await assert.rejects(
    () => probeRemotePlatform(fakeSsh([[/uname/, 'MINGW64_NT\nx86_64']])),
    (err: any) => {
      assert.equal(err.kind, 'unsupported-platform')

      return true
    }
  )
})

test('ownership paths are isolated by ownership ID and spawn nonce', () => {
  assert.equal(ownershipDirectory(OWNERSHIP_ID), `~/.hermes/desktop-ssh/${OWNERSHIP_ID}`)
  assert.equal(lockfilePath(OWNERSHIP_ID), `~/.hermes/desktop-ssh/${OWNERSHIP_ID}/backend.lock.json`)
  assert.equal(spawnLogPath(OWNERSHIP_ID, SPAWN_NONCE), `~/.hermes/desktop-ssh/${OWNERSHIP_ID}/${SPAWN_NONCE}.log`)
})

test('readLockfile returns null ONLY for a missing/empty lockfile', async () => {
  assert.equal(await readLockfile(fakeSsh([[/cat/, '']]), OWNERSHIP_ID), null)
  const good = ownedLock({ pid: 1, port: 2 })
  assert.deepEqual(await readLockfile(fakeSsh([[/cat/, JSON.stringify(good)]]), OWNERSHIP_ID), good)
})

// #95532 fail-closed guard: a lockfile that EXISTS but doesn't match what this
// build writes is SKEW (foreign fork build, corruption, or a future schema) —
// it must be distinguishable from "no lockfile" so no reap/overwrite path can
// treat foreign live state as reapable.
test('readLockfile classifies existing-but-foreign lockfiles as skew, never null', async () => {
  // (a) foreign-schema lockfile (fork build wrote a different shape)
  const foreign = await readLockfile(fakeSsh([[/cat/, 'not json at all']]), OWNERSHIP_ID)
  assert.equal(isLockfileSkew(foreign), true)

  // (b) truncated lockfile (partial write / corruption)
  const truncated = await readLockfile(fakeSsh([[/cat/, JSON.stringify(ownedLock()).slice(0, 40)]]), OWNERSHIP_ID)

  assert.equal(isLockfileSkew(truncated), true)

  // (c) future schemaVersion (newer build owns this remote)
  const future = await readLockfile(
    fakeSsh([[/cat/, JSON.stringify(ownedLock({ schemaVersion: LOCKFILE_SCHEMA_VERSION + 1 }))]]),
    OWNERSHIP_ID
  )

  assert.equal(isLockfileSkew(future), true)
  // unknown schema number entirely
  const unknown = await readLockfile(fakeSsh([[/cat/, JSON.stringify({ schemaVersion: 999 })]]), OWNERSHIP_ID)
  assert.equal(isLockfileSkew(unknown), true)

  // missing ownershipId / foreign ownership
  const foreignOwner = await readLockfile(
    fakeSsh([[/cat/, JSON.stringify(ownedLock({ ownershipId: undefined }))]]),
    OWNERSHIP_ID
  )

  assert.equal(isLockfileSkew(foreignOwner), true)

  // every skew carries a diagnosable reason and is never a valid lock
  for (const skew of [foreign, truncated, future, unknown, foreignOwner]) {
    assert.equal(typeof (skew as any).reason, 'string')
    assert.notEqual(skew, null)
  }

  // a valid lock and a missing lockfile are NOT skew
  assert.equal(isLockfileSkew(await readLockfile(fakeSsh([[/cat/, '']]), OWNERSHIP_ID)), false)
  assert.equal(isLockfileSkew(await readLockfile(fakeSsh([[/cat/, JSON.stringify(ownedLock())]]), OWNERSHIP_ID)), false)
})

// #95532: on skew the reap pass must FAIL CLOSED — no kill, no lockfile
// removal/overwrite, no fresh spawn on top of foreign live state.
test('connect() fails closed on lockfile schema/ownership skew: skips reap, touches nothing', async () => {
  const skewShapes: Array<[string, string]> = [
    ['foreign-schema lockfile', '{"pid":333,"owner":"some-fork-desktop","version":"9.9.9"}'],
    ['truncated lockfile', JSON.stringify(ownedLock()).slice(0, 40)],
    ['future schemaVersion', JSON.stringify(ownedLock({ schemaVersion: LOCKFILE_SCHEMA_VERSION + 1 }))]
  ]

  for (const [label, raw] of skewShapes) {
    const ssh = fakeSsh([
      [/uname/, 'Linux\nx86_64'],
      [/\[ -x/, 'OK'],
      [/cat .*lock\.json/, raw],
      [/kill -0/, 'ALIVE'],
      [/print\("OWNED"/, 'OWNED\n']
    ])

    await assert.rejects(
      () => connect(connectDeps(ssh, { reuseToken: 'stored-token' })),
      (error: any) => error.kind === 'remote-lockfile-skew',
      `${label}: connect must refuse with remote-lockfile-skew`
    )
    assert.ok(
      // Any signal, a literal pid: the probe watchdog's `kill -9 $__htp`
      // targets its own child, not a lockfile pid.
      !ssh.calls.some(c => /(^|[^-\d])kill(?: -\w+)? \d/.test(c) && !/kill -0/.test(c)),
      `${label}: must not kill any pid`
    )
    assert.ok(!ssh.calls.some(c => /rm -f/.test(c)), `${label}: must not remove any remote file`)
    assert.ok(!ssh.calls.some(c => /setsid|nohup/.test(c)), `${label}: must not spawn on top of foreign state`)
    assert.ok(!ssh.calls.some(c => /printf '%s' '.*schemaVersion/.test(c)), `${label}: must not overwrite the lockfile`)
  }
})

test('disconnect() fails closed on lockfile skew: never reaps, never drops the foreign lockfile', async () => {
  const ssh = fakeSsh([
    [/cat .*lock\.json/, JSON.stringify(ownedLock({ schemaVersion: LOCKFILE_SCHEMA_VERSION + 1 }))],
    [/kill -0/, 'ALIVE'],
    [/print\("OWNED"/, 'OWNED\n']
  ])

  await disconnect(ssh, OWNERSHIP_ID)
  assert.ok(!ssh.calls.some(c => /(^|[^-\d])kill -?9? ?\d/.test(c) && !/kill -0/.test(c)), 'must not kill any pid')
  assert.ok(!ssh.calls.some(c => /rm -f/.test(c)), 'must not remove the foreign lockfile or logs')
})

test('cleanupStale is inert when handed a skew sentinel (defense in depth)', async () => {
  const ssh = fakeSsh([[/print\("OWNED"/, 'OWNED\n']])
  await cleanupStale(ssh, OWNERSHIP_ID, { skew: true, reason: 'schema-version' } as any)
  assert.equal(ssh.calls.length, 0, 'skew must short-circuit before any remote command')
})

test('writeLockfile mkdir -ps and stamps the schema version', async () => {
  const ssh = fakeSsh([])
  await writeLockfile(ssh, OWNERSHIP_ID, ownedLock({ pid: 7, port: 9 }))
  const cmd = ssh.calls.join('\n')
  assert.match(cmd, /mkdir -p/)
  assert.match(cmd, new RegExp(`"schemaVersion":${LOCKFILE_SCHEMA_VERSION}`))
})

test('remotePidAlive maps kill -0 ALIVE/DEAD', async () => {
  assert.equal(await remotePidAlive(fakeSsh([[/kill -0/, 'ALIVE']]), 123), true)
  assert.equal(await remotePidAlive(fakeSsh([[/kill -0/, 'DEAD']]), 123), false)
  assert.equal(await remotePidAlive(fakeSsh([]), null), false)
})

test('metadata and process proof transport failures remain indeterminate', async () => {
  const failure = new Error('connection reset')
  await assert.rejects(
    () => readLockfile(fakeSsh([[/cat/, failure]]), OWNERSHIP_ID),
    (error: any) => error.kind === 'transient-transport-error'
  )
  await assert.rejects(
    () => remotePidAlive(fakeSsh([[/kill -0/, failure]]), 123),
    (error: any) => error.kind === 'transient-transport-error'
  )
  await assert.rejects(
    () => pidIsOurDashboard(fakeSsh([[/print\("OWNED"/, failure]]), 5, SPAWN_NONCE, '/x/hermes'),
    (error: any) => error.kind === 'transient-transport-error'
  )
})

test('pidIsOurDashboard requires the exact serve ownership nonce', async () => {
  const ours = `/x/hermes serve --isolated --ssh-owner-nonce ${SPAWN_NONCE}`
  assert.equal(await pidIsOurDashboard(fakeSsh([[/print\("OWNED"/, 'OWNED\n']]), 5, SPAWN_NONCE, '/x/hermes'), true)
  assert.equal(
    await pidIsOurDashboard(
      fakeSsh([[/print\("OWNED"/, command => (command.includes('fedcba9876543210') ? 'FOREIGN\n' : 'OWNED\n')]]),
      5,
      'fedcba9876543210',
      '/x/hermes'
    ),
    false
  )
  assert.equal(await pidIsOurDashboard(fakeSsh([[/print\("OWNED"/, 'FOREIGN\n']]), 5, SPAWN_NONCE, '/x/hermes'), false)
})

test('pidIsOurDashboard accepts the venv entrypoint an installer wrapper execs into', async () => {
  let ownershipProbe = ''

  const ssh = fakeSsh([
    [
      /python3 -c/,
      (command: string) => {
        ownershipProbe = command

        return 'OWNED\n'
      }
    ]
  ])

  assert.equal(
    await pidIsOurDashboard(ssh, 5, SPAWN_NONCE, '~/.local/bin/hermes', '/Users/cd9c/.hermes', OWNERSHIP_ID, 'ops'),
    true
  )
  assert.match(ownershipProbe, /hermes-agent.*venv.*bin.*hermes/)
  assert.match(ownershipProbe, /desktop-ssh.*0123456789abcdef\.token/)
  assert.match(ownershipProbe, /expected_profile=.*ops/)
})

test.skipIf(process.platform === 'win32')(
  'pidIsOurDashboard recognizes an installer wrapper after it execs python + entrypoint',
  async (): Promise<void> => {
    const shell: string = (await exec('command -v bash', { shell: 'bash' })).stdout.trim()
    const temp: string = await mkdtemp(path.join(os.tmpdir(), 'hermes wrapper ownership '))
    const installDir = path.join(temp, 'install dir')
    const venvBin = path.join(installDir, 'venv', 'bin')
    const pythonLink = path.join(venvBin, 'python')
    const entrypoint = path.join(installDir, 'hermes')
    const launcher = path.join(temp, 'hermes launcher')
    const python: string = (await exec('command -v python3', { shell })).stdout.trim()
    const tokenPath: string = path.join(temp, spawnTokenPath(OWNERSHIP_ID, SPAWN_NONCE).replace(/^~\//, ''))
    const env: NodeJS.ProcessEnv = { ...process.env, HOME: temp, HERMES_HOME: temp }

    await mkdir(venvBin, { recursive: true })
    await symlink(python, pythonLink)
    await writeFile(entrypoint, 'import time\ntime.sleep(30)\n', 'utf8')
    await writeFile(launcher, `#!${shell}\nexec "${pythonLink}" "${entrypoint}" "$@"\n`, 'utf8')
    await chmod(launcher, 0o755)

    const backendFlags = [
      '--host',
      '127.0.0.1',
      '--port',
      '0',
      '--ssh-session-token-file',
      tokenPath,
      '--ssh-owner-nonce',
      SPAWN_NONCE
    ]

    const children: ReturnType<typeof spawn>[] = []

    const spawnInstaller = (args: string[]): ReturnType<typeof spawn> => {
      const process: ReturnType<typeof spawn> = spawn(launcher, args, { stdio: 'ignore', env })

      children.push(process)

      return process
    }

    const child = spawnInstaller(['--profile', 'ops', 'serve', '--isolated', ...backendFlags])

    const ssh: Pick<SshConnection, 'exec'> = {
      exec: async (command: string): Promise<string> => (await exec(command, { shell, env })).stdout
    }

    const waitForEntrypoint = async (process: ReturnType<typeof spawn>): Promise<boolean> => {
      for (let attempt: number = 0; attempt < 100; attempt += 1) {
        const command: string = (await exec(`ps -ww -o command= -p ${process.pid}`, { shell, env })).stdout

        if (command.includes(entrypoint)) {
          return true
        }

        await new Promise(resolve => setTimeout(resolve, 25))
      }

      return false
    }

    try {
      assert.equal(await waitForEntrypoint(child), true, 'wrapper must exec into the fake installer entrypoint')
      assert.equal(
        await pidIsOurDashboard(ssh, child.pid, SPAWN_NONCE, launcher, '/unrelated/hermes-home', OWNERSHIP_ID, 'ops'),
        true
      )
      assert.equal(
        await pidIsOurDashboard(
          ssh,
          child.pid,
          SPAWN_NONCE,
          launcher,
          '/unrelated/hermes-home',
          'fedcba9876543210fedcba9876543210',
          'ops'
        ),
        false
      )
      assert.equal(
        await pidIsOurDashboard(
          ssh,
          child.pid,
          SPAWN_NONCE,
          launcher,
          '/unrelated/hermes-home',
          OWNERSHIP_ID,
          'wrong-profile'
        ),
        false
      )

      const misplacedIsolated = spawnInstaller(['--profile', 'ops', '--isolated', 'serve', ...backendFlags])

      assert.equal(await waitForEntrypoint(misplacedIsolated), true)
      assert.equal(
        await pidIsOurDashboard(
          ssh,
          misplacedIsolated.pid,
          SPAWN_NONCE,
          launcher,
          '/unrelated/hermes-home',
          OWNERSHIP_ID,
          'ops'
        ),
        false,
        '--isolated before serve must remain foreign'
      )

      const conflictingProfile = spawnInstaller([
        '--profile',
        'ops',
        'serve',
        '--isolated',
        ...backendFlags,
        '--profile',
        'foreign'
      ])

      assert.equal(await waitForEntrypoint(conflictingProfile), true)
      assert.equal(
        await pidIsOurDashboard(
          ssh,
          conflictingProfile.pid,
          SPAWN_NONCE,
          launcher,
          '/unrelated/hermes-home',
          OWNERSHIP_ID,
          'ops'
        ),
        false,
        'a duplicate conflicting profile must remain foreign'
      )

      const serveNamedProfile = spawnInstaller(['--profile', 'serve', 'serve', '--isolated', ...backendFlags])

      assert.equal(await waitForEntrypoint(serveNamedProfile), true)
      assert.equal(
        await pidIsOurDashboard(
          ssh,
          serveNamedProfile.pid,
          SPAWN_NONCE,
          launcher,
          '/unrelated/hermes-home',
          OWNERSHIP_ID,
          'serve'
        ),
        true,
        'a profile named "serve" must not mask the real serve subcommand'
      )
      assert.equal(
        await pidIsOurDashboard(
          ssh,
          serveNamedProfile.pid,
          SPAWN_NONCE,
          launcher,
          '/unrelated/hermes-home',
          OWNERSHIP_ID,
          'ops'
        ),
        false,
        'a "serve"-named profile must still match the expected profile exactly'
      )
    } finally {
      for (const process of children) {
        process.kill('SIGTERM')
      }

      await rm(temp, { force: true, recursive: true })
    }
  }
)

test.skipIf(process.platform !== 'linux')(
  'terminateOwnedDashboardForUpdate SIGTERMs a serve pinned to a "serve"-named profile',
  async () => {
    const temp = await mkdtemp(path.join(os.tmpdir(), 'hermes wrapper ownership '))
    const installDir = path.join(temp, 'install dir')
    const venvBin = path.join(installDir, 'venv', 'bin')
    const pythonLink = path.join(venvBin, 'python')
    const entrypoint = path.join(installDir, 'hermes')
    const launcher = path.join(temp, 'hermes launcher')
    const python = (await exec('command -v python3')).stdout.trim()
    const tokenPath = path.join(os.homedir(), spawnTokenPath(OWNERSHIP_ID, SPAWN_NONCE).replace(/^~\//, ''))

    await mkdir(venvBin, { recursive: true })
    await symlink(python, pythonLink)
    await writeFile(entrypoint, 'import time\ntime.sleep(30)\n', 'utf8')
    await writeFile(launcher, `#!/usr/bin/env bash\nexec "${pythonLink}" "${entrypoint}" "$@"\n`, 'utf8')
    await chmod(launcher, 0o755)

    const child = spawn(
      launcher,
      [
        '--profile',
        'serve',
        'serve',
        '--isolated',
        '--host',
        '127.0.0.1',
        '--port',
        '0',
        '--ssh-session-token-file',
        tokenPath,
        '--ssh-owner-nonce',
        SPAWN_NONCE
      ],
      { stdio: 'ignore' }
    )

    const exited = new Promise(resolve => child.once('exit', resolve))

    try {
      let execed = false

      for (let attempt = 0; attempt < 40 && !execed; attempt += 1) {
        const command = (await exec(`ps -ww -o command= -p ${child.pid}`)).stdout

        execed = command.includes(entrypoint)

        if (!execed) {
          await new Promise(resolve => setTimeout(resolve, 25))
        }
      }

      assert.equal(execed, true, 'wrapper must exec into the fake installer entrypoint')

      const raw = await readFile(`/proc/${child.pid}/stat`, 'utf8')

      const creationTime = `linux:${
        raw
          .slice(raw.lastIndexOf(')') + 2)
          .trim()
          .split(/\s+/)[19]
      }`

      const lock = ownedLock({
        pid: child.pid,
        profile: 'serve',
        hermesPath: launcher,
        hermesHome: '/unrelated/hermes-home',
        creationTime
      })

      const ssh = {
        exec: async (command: string) => {
          if (/cat .*\.json/.test(command)) {
            return `${JSON.stringify(lock)}\n`
          }

          return (await exec(command, { shell: '/bin/bash' })).stdout
        }
      }

      const result = await terminateOwnedDashboardForUpdate(ssh, lock)

      assert.equal(result.terminated, true)
      await exited
      assert.equal(child.signalCode, 'SIGTERM')
    } finally {
      child.kill('SIGKILL')
      await rm(temp, { force: true, recursive: true })
    }
  }
)

test('disconnect reaps the backend recorded for this desktop ownership', async () => {
  const lock = ownedLock()

  const ssh = fakeSsh([
    [/cat .*backend\.lock\.json/, JSON.stringify(lock)],
    [/kill -0 333/, 'ALIVE\n'],
    [/print\("OWNED"/, 'OWNED\n']
  ])

  await disconnect(ssh, OWNERSHIP_ID)

  assert.ok(ssh.calls.some(command => /kill 333\b/.test(command)))
  assert.ok(ssh.calls.some(command => /rm -f .*backend\.lock\.json/.test(command)))
})

test('disconnect is a no-op when this desktop has no lockfile', async () => {
  const ssh = fakeSsh([[/cat .*backend\.lock\.json/, '']])

  await disconnect(ssh, OWNERSHIP_ID)

  assert.ok(!ssh.calls.some(command => /\bkill\b/.test(command)))
})

test('cleanupStale kills ONLY a provably-ours pid, always drops the lockfile', async () => {
  const notOurs = fakeSsh([[/print\("OWNED"/, 'FOREIGN\n']])
  await cleanupStale(notOurs, OWNERSHIP_ID, {
    pid: 5,
    spawnNonce: SPAWN_NONCE,
    hermesPath: '/x/hermes',
    logPath: spawnLogPath(OWNERSHIP_ID, SPAWN_NONCE)
  })
  assert.ok(
    notOurs.calls.some(c => /print\("OWNED"/.test(c)),
    'must perform an ownership preflight'
  )
  assert.ok(notOurs.calls.some(c => /rm -f/.test(c)))

  const ours = fakeSsh([
    [/print\("OWNED"/, 'OWNED\n'],
    [cmd => /printf TERMINATED/.test(cmd), 'TERMINATED\n']
  ])

  await cleanupStale(ours, OWNERSHIP_ID, {
    pid: 9,
    spawnNonce: SPAWN_NONCE,
    hermesPath: '/x/hermes',
    logPath: spawnLogPath(OWNERSHIP_ID, SPAWN_NONCE)
  })
  assert.ok(ours.calls.some(c => /kill 9\b/.test(c)))
  assert.ok(ours.calls.some(c => /rm -f/.test(c)))
})

test('buildSpawnCommand is headless serve, detached, token not in argv', () => {
  const cmd = buildSpawnCommand('/x/hermes', 'work', { logPath: spawnLogPath(OWNERSHIP_ID, SPAWN_NONCE) })
  assert.match(cmd, /serve --isolated/)
  assert.match(cmd, /--host 127\.0\.0\.1 --port 0/)
  assert.doesNotMatch(cmd, /--skip-build|--no-open/)
  assert.doesNotMatch(cmd, /\bdashboard\b/)
  assert.match(cmd, /--profile/)
  assert.match(cmd, /work/)
  assert.match(cmd, /setsid/)
  assert.match(cmd, /<\/dev\/null/)
  assert.match(cmd, /echo \$!/)
  assert.ok(!cmd.includes('tok_secret_value'), 'token must not appear in spawn command')
  assert.ok(!cmd.includes('HERMES_DASHBOARD_SESSION_TOKEN'), 'token env var must not appear')
})

test('buildSpawnCommand never pins a non-slug profile into the remote argv', () => {
  // The roster/SSH bridge hands the profile verbatim; a numeric id or display
  // label must never cross into the remote serve argv, where the CLI used to
  // str()-coerce it into a phantom profiles/0/ directory (#88842).
  const bad = buildSpawnCommand('/x/hermes', 0 as unknown as string, {
    logPath: spawnLogPath(OWNERSHIP_ID, SPAWN_NONCE)
  })

  assert.ok(!bad.includes('--profile'), 'a non-string profile must not be pinned')

  const empty = buildSpawnCommand('/x/hermes', '', { logPath: spawnLogPath(OWNERSHIP_ID, SPAWN_NONCE) })
  assert.ok(!empty.includes('--profile'), 'an empty profile must not be pinned')

  const label = buildSpawnCommand('/x/hermes', 'My Profile!', { logPath: spawnLogPath(OWNERSHIP_ID, SPAWN_NONCE) })
  assert.ok(!label.includes('--profile'), 'a non-slug label must not be pinned')

  const good = buildSpawnCommand('/x/hermes', 'Work', { logPath: spawnLogPath(OWNERSHIP_ID, SPAWN_NONCE) })
  assert.ok(good.includes('--profile'), 'a valid profile stays pinned')
  assert.ok(good.includes("'work'"), 'the profile is normalized like the CLI would')
})

test.skipIf(process.platform === 'win32')(
  'detached backend does not inherit the update mutex descriptor',
  async (): Promise<void> => {
    const shell: string = (await exec('command -v bash', { shell: 'bash' })).stdout.trim()
    const directory: string = await mkdtemp(path.join(os.tmpdir(), 'hermes-update-mutex-'))
    const hermesPath: string = path.join(directory, 'hermes')
    const reportPath: string = path.join(directory, 'descriptor-report')
    const logPath: string = path.join(directory, 'spawn.log')

    try {
      await writeFile(
        hermesPath,
        `#!${shell}
report=${expandRemotePath(reportPath)}
: > "$report.tmp"
for fd in /proc/$$/fd/*; do
  target=$(readlink "$fd" 2>/dev/null || true)
  case "$target" in
    *hermes-update-in-progress.lock) printf '%s\\n' "$target" >> "$report.tmp" ;;
  esac
done
mv "$report.tmp" "$report"
`,
        { encoding: 'utf8', mode: 0o700 }
      )

      const command: string = buildSpawnCommand(hermesPath, '', {
        hermesHome: path.join(directory, 'home'),
        logPath
      })

      await exec(command, { shell, env: { ...process.env, HOME: directory, HERMES_HOME: directory } })

      for (let attempt: number = 0; attempt < 100; attempt += 1) {
        try {
          const report: string = await readFile(reportPath, 'utf8')
          assert.equal(report, '', 'the backend process must not retain the update mutex descriptor')

          return
        } catch (error: unknown) {
          if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
            throw error
          }

          await new Promise(resolve => setTimeout(resolve, 25))
        }
      }

      assert.fail('the detached backend did not write its descriptor report')
    } finally {
      await rm(directory, { recursive: true, force: true })
    }
  }
)

test('spawnRemoteDashboard returns exact ownership artifacts', async () => {
  const ssh = fakeSsh([
    [/grep -q ssh-session-token-file/, 'YES\n'],
    [/python3 -c/, ''],
    [/printf '%s\\n'/, ''],
    [/setsid|nohup/, '4242\n']
  ])

  const { pid, spawnNonce, logPath } = await spawnRemoteDashboard(ssh, {
    hermesPath: '/x/hermes',
    profile: '',
    token: 'tk',
    ownershipId: OWNERSHIP_ID
  })

  assert.equal(pid, 4242)
  assert.match(spawnNonce, /^[0-9a-f]{16}$/)
  assert.equal(logPath, spawnLogPath(OWNERSHIP_ID, spawnNonce))
})

test('READY_RE accepts both serve and dashboard sentinels', () => {
  assert.equal(READY_RE.exec('HERMES_BACKEND_READY port=4321')?.[1], '4321')
  assert.equal(READY_RE.exec('HERMES_DASHBOARD_READY port=8765')?.[1], '8765')
  // The remote log is `>> log 2>&1`, so a stderr chunk without a newline can be spliced onto the sentinel.
  assert.equal(READY_RE.exec('INFO  Started server process [4711]HERMES_BACKEND_READY port=65238')?.[1], '65238')
})

test('spawnRemoteDashboard rejects when no pid is returned', async () => {
  const ssh = fakeSsh([
    [/grep -q ssh-session-token-file/, 'YES\n'],
    [/python3 -c/, ''],
    [/printf '%s\\n'/, ''],
    [/setsid|nohup/, 'not-a-pid']
  ])

  await assert.rejects(
    () => spawnRemoteDashboard(ssh, { hermesPath: '/x/hermes', profile: '', token: 't', ownershipId: OWNERSHIP_ID }),
    (err: any) => {
      assert.equal(err.kind, 'spawn-failed')

      return true
    }
  )
})

test('scrapeReadyPort reads only the named spawn log', async () => {
  const logPath = spawnLogPath(OWNERSHIP_ID, SPAWN_NONCE)
  const ssh = fakeSsh([[/cat/, 'some noise\nHERMES_DASHBOARD_READY port=51234\n']])
  const port = await scrapeReadyPort(ssh, logPath, { timeoutMs: 1000 })
  assert.equal(port, 51234)
  assert.ok(ssh.calls.every(call => !call.includes('desktop-ssh.log')))
})

test('scrapeReadyPort times out and reports a dead spawn', async () => {
  // never emits a READY line
  const ssh = fakeSsh([[/cat .*\.log/, 'still starting...']])
  await assert.rejects(
    () => scrapeReadyPort(ssh, spawnLogPath(OWNERSHIP_ID, SPAWN_NONCE), { timeoutMs: 60 }),
    (err: any) => {
      assert.equal(err.kind, 'ready-timeout')

      return true
    }
  )
  // dead process before announcement → spawn-failed
  await assert.rejects(
    () =>
      scrapeReadyPort(fakeSsh([[/cat/, '']]), spawnLogPath(OWNERSHIP_ID, SPAWN_NONCE), {
        timeoutMs: 1000,
        isAlive: async () => false
      }),
    (err: any) => {
      assert.equal(err.kind, 'spawn-failed')

      return true
    }
  )
})

function connectDeps(ssh, over: any = {}) {
  return {
    ssh,
    ownershipId: OWNERSHIP_ID,
    profile: '',
    forward: async () => {},
    cancelForward: async () => {},
    pickLocalPort: async () => 50001,
    waitForHermes: async () => {},
    probeReuseProof: async () => 'authenticated-ok',
    adoptServedToken: async (_baseUrl, spawn) => spawn || 'served-token',
    rememberLog: () => {},
    readyTimeoutMs: 2000,
    ...over
  }
}

test('connect() spawns fresh when there is no lockfile, adopts the served token', async () => {
  const ssh = fakeSsh([
    [/uname/, 'Linux\nx86_64'],
    [/\[ -x/, 'OK'],
    [/cat .*lock\.json/, ''], // no lockfile
    [/grep -q ssh-session-token-file/, 'YES\n'],
    [/python3 -c/, ''], // token file write
    [/printf '%s\\n'/, ''],
    [/setsid/, '777\n'],
    // The wrapper may exit before the detached daemon writes READY; startup
    // must rely on the bounded log wait rather than kill -0 on this pid.
    [/cat .*\.log/, 'HERMES_DASHBOARD_READY port=51999\n'],
    // The post-readiness served-token adoption still verifies the daemon.
    [/kill -0 777/, 'ALIVE']
  ])

  const result = await connect(
    connectDeps(ssh, {
      adoptServedToken: async () => 'the-served-token',
      platform: { os: 'Linux', arch: 'x86_64' }
    })
  )

  assert.equal(ssh.calls.filter(command => command === 'uname -s; uname -m').length, 0)
  assert.equal(result.reused, false)
  assert.equal(result.remotePort, 51999)
  assert.equal(result.localPort, 50001)
  assert.equal(result.pid, 777)
  assert.equal(result.token, 'the-served-token')
  assert.equal(result.baseUrl, 'http://127.0.0.1:50001')
  assert.equal(result.tokenFingerprint, fingerprintToken('the-served-token'))
})

test('managed SSH maps a local scope to a different non-default remote profile', async () => {
  const localScope = 'work'

  const sshConfig = profileSshOverride(
    {
      profiles: {
        [localScope]: {
          mode: 'ssh',
          host: 'remote-box',
          remoteProfile: 'writer_2'
        }
      }
    },
    localScope
  )

  assert.equal(sshConfig?.remoteProfile, 'writer_2')

  const ssh = fakeSsh([
    [/uname/, 'Linux\nx86_64'],
    [/\[ -x/, 'OK'],
    [/cat .*lock\.json/, ''],
    [/grep -q ssh-session-token-file/, 'YES\n'],
    [/python3 -c/, ''],
    [/printf '%s\\n'/, ''],
    [/setsid/, '778\n'],
    [/kill -0 778/, 'ALIVE'],
    [/cat .*\.log/, 'HERMES_BACKEND_READY port=52000\n']
  ])

  await connect(
    connectDeps(ssh, {
      profile: sshConfig?.remoteProfile,
      adoptServedToken: async () => 'mapped-profile-token'
    })
  )

  const spawn = ssh.calls.find(command => /setsid|nohup/.test(command)) || ''
  assert.match(spawn, /--profile\b/)
  assert.ok(spawn.includes('writer_2'))
  assert.match(spawn, /serve\s+--isolated/)
  assert.match(spawn, /\.hermes\/desktop-ssh\/[0-9a-f]{32}\/[0-9a-f]{16}\.token/)
  assert.ok(!spawn.includes(' work'), 'the local Desktop scope must not become the remote profile')
})

test('connect() reuses a healthy dashboard when fingerprint + probe pass', async () => {
  const reuseToken = 'stored-token'
  const lock = ownedLock({ tokenFingerprint: fingerprintToken(reuseToken) })

  const ssh = fakeSsh([
    [/uname/, 'Linux\nx86_64'],
    [/\[ -x/, 'OK'],
    [/cat .*lock\.json/, JSON.stringify(lock)],
    [/kill -0/, 'ALIVE'],
    [/print\("OWNED"/, 'OWNED\n']
  ])

  const result = await connect(connectDeps(ssh, { reuseToken, adoptServedToken: async (_b, t) => t }))
  assert.equal(result.reused, true)
  assert.equal(result.pid, 333)
  assert.equal(result.remotePort, 40000)
  // never spawned
  assert.ok(!ssh.calls.some(c => /setsid/.test(c)), 'reuse path must not spawn a new dashboard')
})

test('connect() respawns when the requested remote profile differs from the lockfile profile', async () => {
  const reuseToken = 'stored-token'
  const lock = ownedLock({ profile: 'desktop-work', tokenFingerprint: fingerprintToken(reuseToken) })

  const ssh = fakeSsh([
    [/uname/, 'Linux\nx86_64'],
    [/\[ -x/, 'OK'],
    [/cat .*lock\.json/, JSON.stringify(lock)],
    [/kill -0 333/, 'ALIVE'],
    [/print\("OWNED"/, 'OWNED\n'],
    [cmd => /pidfd_open/.test(cmd), 'TERMINATED\n'],
    [/kill 333/, ''],
    [/--version/, 'Hermes Agent v0.18.2\n'],
    [/grep -q ssh-session-token-file/, 'YES\n'],
    [/python3 -c/, ''],
    [/setsid/, '890\n'],
    [/kill -0 890/, 'ALIVE'],
    [/cat .*\.log/, 'HERMES_DASHBOARD_READY port=52050\n']
  ])

  const result = await connect(
    connectDeps(ssh, { profile: 'default', reuseToken, adoptServedToken: async () => 'fresh' })
  )

  assert.equal(result.reused, false)
  assert.ok(
    ssh.calls.some(c => /setsid/.test(c)),
    'profile mismatch must spawn a fresh dashboard'
  )
})

test('connect() respawns when the lockfile hermesPath differs from the resolved path', async () => {
  const reuseToken = 'stored-token'
  const lock = ownedLock({ hermesPath: '/old/stale/hermes', tokenFingerprint: fingerprintToken(reuseToken) })

  const ssh = fakeSsh([
    [/uname/, 'Linux\nx86_64'],
    [/\[ -x/, 'OK'],
    [/cat .*lock\.json/, JSON.stringify(lock)],
    [/kill -0/, 'ALIVE'],
    [/print\("OWNED"/, 'FOREIGN\n'],
    [/--version/, 'Hermes Agent v0.18.2\n'],
    [/grep -q ssh-session-token-file/, 'YES\n'],
    [/python3 -c/, ''],
    [/setsid/, '890\n'],
    [/cat .*\.log/, 'HERMES_DASHBOARD_READY port=52050\n']
  ])

  const result = await connect(
    connectDeps(ssh, { reuseToken, remoteHermesPath: '/new/hermes', adoptServedToken: async () => 'fresh' })
  )

  assert.equal(result.reused, false, 'must respawn, not reuse the old-path dashboard')
  assert.ok(
    ssh.calls.some(c => /setsid/.test(c)),
    'a fresh dashboard must be spawned'
  )
})

test('connect() respawns when the lockfile protocolVersion is incompatible', async () => {
  const reuseToken = 'stored-token'

  const lock = ownedLock({
    protocolVersion: PROTOCOL_VERSION + 99,
    tokenFingerprint: fingerprintToken(reuseToken)
  })

  const ssh = fakeSsh([
    [/uname/, 'Linux\nx86_64'],
    [/\[ -x/, 'OK'],
    [/cat .*lock\.json/, JSON.stringify(lock)],
    [/kill -0 333/, 'ALIVE'],
    [/print\("OWNED"/, 'FOREIGN\n'],
    [/grep -q ssh-session-token-file/, 'YES\n'],
    [/python3 -c/, ''],
    [/setsid/, '901\n'],
    [/kill -0 901/, 'ALIVE'],
    [/cat .*\.log/, 'HERMES_DASHBOARD_READY port=44100\n']
  ])

  const result = await connect(connectDeps(ssh, { reuseToken, adoptServedToken: async () => 'fresh' }))
  assert.equal(result.reused, false, 'incompatible protocol must force a fresh spawn, not a reattach')
  assert.equal(result.pid, 901)
})

test('connect() fresh spawn writes hermesHome + protocolVersion into the lockfile', async () => {
  const writes: string[] = []

  const ssh = fakeSsh([
    [/uname/, 'Linux\nx86_64'],
    [/\[ -x/, 'OK'],
    [/cat .*lock\.json/, ''], // no lockfile
    [/HERMES_HOME/, '/home/alice/.hermes\n'],
    [/grep -q ssh-session-token-file/, 'YES\n'],
    [/python3 -c/, ''],
    [/printf '%s\\n'/, ''],
    [/setsid/, '700\n'],
    [/kill -0 700/, 'ALIVE'],
    [/cat .*\.log/, 'HERMES_DASHBOARD_READY port=45500\n'],
    [
      /printf '%s' '/,
      c => {
        writes.push(c)

        return ''
      }
    ]
  ])

  await connect(connectDeps(ssh, { adoptServedToken: async () => 'fresh' }))
  const lockWrite = writes.find(c => c.includes('schemaVersion')) || ''
  assert.match(lockWrite, new RegExp(`"protocolVersion":${PROTOCOL_VERSION}`))
  assert.match(lockWrite, /"hermesHome":"\/home\/alice\/\.hermes"/)
})

test('connect() respawns when the lockfile pid is dead (killed dashboard)', async () => {
  const lock = ownedLock({ tokenFingerprint: fingerprintToken('t') })

  const ssh = fakeSsh([
    [/uname/, 'Linux\nx86_64'],
    [/\[ -x/, 'OK'],
    [/cat .*lock\.json/, JSON.stringify(lock)],
    [/kill -0 333/, 'DEAD'],
    [/print\("OWNED"/, 'FOREIGN\n'],
    [/grep -q ssh-session-token-file/, 'YES\n'],
    [/python3 -c/, ''],
    [/setsid/, '888\n'],
    [/kill -0 888/, 'ALIVE'],
    [/cat .*\.log/, 'HERMES_DASHBOARD_READY port=42000\n']
  ])

  const result = await connect(connectDeps(ssh, { reuseToken: 't', adoptServedToken: async () => 'fresh' }))
  assert.equal(result.reused, false)
  assert.equal(result.pid, 888)
  assert.equal(result.remotePort, 42000)
  assert.ok(
    !ssh.calls.some(command => command.includes('pid=333') && command.includes('print("OWNED"')),
    'a dead pid has no process identity to verify'
  )
})

test('managed update drain preserves a live foreign POSIX owner and its lock bytes', async () => {
  const lock = ownedLock()
  const rawLock = JSON.stringify(lock)

  const ssh = fakeSsh([
    [/cat .*lock\.json/, rawLock],
    [/kill -0 333/, 'ALIVE'],
    [/value="linux:"/, 'linux:123456\n'],
    [/print\("OWNED"/, 'FOREIGN\n']
  ])

  await assert.rejects(terminateOwnedDashboardForUpdate(ssh, lock), /ownership is unproven/)
  assert.equal(
    ssh.calls.some(command => /kill 333 &&/.test(command)),
    false,
    'foreign process is never signalled'
  )
  assert.equal(
    ssh.calls.some(command => /rm -f .*backend\.lock\.json/.test(command)),
    false,
    'foreign ownership bytes remain untouched'
  )
})

test('managed update drain rechecks the POSIX ownership record before signalling', async () => {
  const lock = ownedLock()
  const replacement = ownedLock({ pid: 334, spawnNonce: 'fedcba9876543210' })
  let reads = 0

  const ssh = fakeSsh([
    [
      /cat .*lock\.json/,
      () => {
        reads += 1

        return JSON.stringify(reads === 1 ? lock : replacement)
      }
    ],
    [/kill -0 333/, 'ALIVE'],
    [/value="linux:"/, 'linux:123456\n'],
    [/print\("OWNED"/, 'OWNED\n']
  ])

  await assert.rejects(terminateOwnedDashboardForUpdate(ssh, lock), /changed during process verification/)
  assert.equal(
    ssh.calls.some(command => /kill 333 &&/.test(command)),
    false
  )
})

test('managed update drain never falls back to a bare kill when the identity-bound signal is refused', async () => {
  const lock = ownedLock()
  const rawLock = JSON.stringify(lock)

  const ssh = fakeSsh([
    [/cat .*lock\.json/, rawLock],
    [/kill -0 333/, 'ALIVE'],
    [/value="linux:"/, 'linux:123456\n'],
    [/print\("OWNED"/, 'OWNED\n'],
    [/pidfd_open/, 'REFUSED\n']
  ])

  await assert.rejects(terminateOwnedDashboardForUpdate(ssh, lock), /identity changed at the signal boundary/)
  assert.equal(
    ssh.calls.some(command => /^kill 333\b/.test(command.trim())),
    false,
    'the final signal must stay inside the identity-checking helper'
  )
})

test.skipIf(process.platform === 'win32')(
  'managed update drain reports the real POSIX refusal, not a generic transport error',
  async () => {
    // Regression for #124617: the termination probe prints REFUSED (and, on
    // Darwin, DARWIN_UNAVAILABLE) but used to exit non-zero for it. ssh.exec()
    // throws on any non-zero remote exit, so the specific message built below
    // from the probe's stdout was dead code in production — every refusal
    // collapsed into the generic "Could not terminate the Desktop-owned
    // remote serve for update." Run the real probe (not a canned string)
    // against a live-but-foreign local process so its actual exit code
    // decides the outcome, the same way the real SSH transport does.
    const dummy = spawn('sleep', ['5'], { stdio: 'ignore' })

    try {
      const lock = ownedLock({ pid: dummy.pid })
      const rawLock = JSON.stringify(lock)

      const ssh: Pick<SshConnection, 'exec'> = {
        async exec(cmd: string): Promise<string> {
          if (/cat .*lock\.json/.test(cmd)) {
            return rawLock
          }

          if (/kill -0 /.test(cmd)) {
            return 'ALIVE'
          }

          if (/fields\[19\]/.test(cmd)) {
            return lock.creationTime
          }

          if (/print\("OWNED" if ok else "FOREIGN"\)/.test(cmd)) {
            return 'OWNED'
          }

          // The real termination probe: execute it for real so its actual
          // exit code — not a canned string — is what drives the caller.
          return (await exec(cmd)).stdout
        }
      }

      await assert.rejects(terminateOwnedDashboardForUpdate(ssh, lock), /identity changed at the signal boundary/)
    } finally {
      dummy.kill('SIGKILL')
    }
  }
)

test('connect() respawns when the dashboard is wedged (alive pid, probe fails)', async () => {
  const reuseToken = 'stored'
  const lock = ownedLock({ tokenFingerprint: fingerprintToken(reuseToken) })

  const ssh = fakeSsh([
    [/uname/, 'Linux\nx86_64'],
    [/\[ -x/, 'OK'],
    [/cat .*lock\.json/, JSON.stringify(lock)],
    [/kill -0/, 'ALIVE'],
    [/print\("OWNED"/, 'FOREIGN\n'],
    [/grep -q ssh-session-token-file/, 'YES\n'],
    [/python3 -c/, ''],
    [/setsid/, '999\n'],
    [/kill -0 999/, 'ALIVE'],
    [/cat .*\.log/, 'HERMES_DASHBOARD_READY port=43000\n']
  ])

  const result = await connect(
    connectDeps(ssh, {
      reuseToken,
      probeReuseProof: async () => 'authenticated-stale',
      adoptServedToken: async () => 'fresh'
    })
  )

  assert.equal(result.reused, false)
  assert.equal(result.pid, 999)
  assert.equal(result.remotePort, 43000)
})

test('connect() aborts on an unsupported remote platform before doing anything else', async () => {
  const ssh = fakeSsh([[/uname/, 'SunOS\nsun4v']])
  await assert.rejects(
    () => connect(connectDeps(ssh)),
    (err: any) => {
      assert.equal(err.kind, 'unsupported-platform')

      return true
    }
  )
  assert.ok(!ssh.calls.some(c => /setsid/.test(c)))
})

test('openForward retries bind collisions only', async () => {
  const ports = [41001, 41002]
  const calls: number[] = []

  const localPort = await openForward(
    {
      pickLocalPort: async () => ports.shift(),
      forward: async port => {
        calls.push(port)

        if (calls.length === 1) {
          throw new Error('bind: Address already in use')
        }
      }
    },
    9119
  )

  assert.equal(localPort, 41002)
  assert.deepEqual(calls, [41001, 41002])
  assert.equal(isForwardBindCollision(new Error('Permission denied')), false)
})

test('connect() preserves an owned backend when a reuse transport throws', async () => {
  const reuseToken = 'stored-token'
  const lock = ownedLock({ tokenFingerprint: fingerprintToken(reuseToken) })

  const ssh = fakeSsh([
    [/uname/, 'Linux\nx86_64'],
    [/\[ -x/, 'OK'],
    [/cat .*lock\.json/, JSON.stringify(lock)],
    [/kill -0/, 'ALIVE'],
    [/print\("OWNED"/, 'OWNED\n']
  ])

  await assert.rejects(
    () =>
      connect(
        connectDeps(ssh, {
          reuseToken,
          forward: async () => {
            throw new Error('network reset')
          }
        })
      ),
    /network reset/
  )
  assert.ok(!ssh.calls.some(cmd => /kill 333\b/.test(cmd)))
})

test('validateRemotePath accepts absolute POSIX paths', () => {
  assert.doesNotThrow(() => validateRemotePath('/usr/bin/hermes'))
  assert.doesNotThrow(() => validateRemotePath('/home/user/.hermes/hermes-agent/venv/bin/hermes'))
})

test('validateRemotePath accepts ~/ prefix paths', () => {
  assert.doesNotThrow(() => validateRemotePath('~/bin/hermes'))
  assert.doesNotThrow(() => validateRemotePath('~/.hermes/logs/desktop-ssh.log'))
  assert.doesNotThrow(() => validateRemotePath('~'))
})

test('validateRemotePath accepts paths with spaces and quotes', () => {
  assert.doesNotThrow(() => validateRemotePath('/home/user/my project/hermes'))
  assert.doesNotThrow(() => validateRemotePath("~/path with 'quotes'/file"))
  assert.doesNotThrow(() => validateRemotePath('/path with "double quotes"/file'))
})

test('validateRemotePath rejects relative paths', () => {
  assert.throws(() => validateRemotePath('hermes'), /absolute|relative/i)
  assert.throws(() => validateRemotePath('./bin/hermes'), /absolute|relative/i)
  assert.throws(() => validateRemotePath('../etc/passwd'), /absolute|relative/i)
})

test('validateRemotePath rejects NUL and newline', () => {
  assert.throws(() => validateRemotePath('/usr/bin/hermes\x00'), /unsafe/i)
  assert.throws(() => validateRemotePath('/usr/bin/hermes\n'), /unsafe/i)
  assert.throws(() => validateRemotePath('/usr/bin/hermes\r'), /unsafe/i)
})

test('validateRemotePath preserves shell metacharacters as path data', () => {
  for (const p of ['/usr/$(whoami)/hermes', '/usr/`id`/hermes', '/usr/a;b|c&d<e>f']) {
    assert.doesNotThrow(() => validateRemotePath(p))
    assert.match(expandRemotePath(p), /^'/)
  }
})

test('expandRemotePath expands ~/ to "$HOME"/', () => {
  const result = expandRemotePath('~/.hermes/logs/desktop-ssh.log')
  assert.match(result, /\$HOME/)
  assert.ok(!result.includes('eval'), 'must not use eval')
  assert.ok(!result.includes('echo'), 'must not use echo for expansion')
})

test('expandRemotePath returns quoted absolute paths unchanged', () => {
  const result = expandRemotePath('/usr/local/bin/hermes')
  assert.ok(result.includes('/usr/local/bin/hermes'))
  assert.ok(!result.includes('eval'))
})

test('expandRemotePath preserves spaces as data', () => {
  const result = expandRemotePath('/home/user/my project/hermes')
  assert.ok(result.includes('my project'), 'spaces must be preserved, not split')
})

test('buildSpawnCommand includes --ssh-session-token-file when tokenFilePath is provided', () => {
  const cmd = buildSpawnCommand('/x/hermes', 'work', {
    tokenFilePath: `~/.hermes/desktop-ssh/${OWNERSHIP_ID}/${SPAWN_NONCE}.token`,
    logPath: spawnLogPath(OWNERSHIP_ID, SPAWN_NONCE),
    spawnNonce: SPAWN_NONCE
  })

  assert.match(cmd, /--ssh-session-token-file/)
  assert.match(cmd, /\.hermes\/desktop-ssh\//)
})

test('spawnRemoteDashboard removes a token file when upload reporting fails', async () => {
  const failure = new Error('channel closed')

  const ssh = fakeSsh([
    [/grep -q ssh-session-token-file/, 'YES\n'],
    [command => /python3 -c/.test(command) && !/rm -f/.test(command), failure],
    [/rm -f/, '']
  ])

  await assert.rejects(
    () => spawnRemoteDashboard(ssh, { hermesPath: '/x/hermes', profile: '', token: 'tok', ownershipId: OWNERSHIP_ID }),
    /channel closed/
  )
  assert.ok(ssh.calls.some(command => /rm -f .*\.token/.test(command)))
})

test('spawnRemoteDashboard streams the token over stdin, not argv/env', async () => {
  const stdinCalls: string[] = []
  const calls: string[] = []

  const ssh = {
    calls,
    async exec(cmd, opts?) {
      calls.push(cmd)

      if (opts?.stdinData) {
        stdinCalls.push(opts.stdinData)
      }

      if (/grep -q ssh-session-token-file/.test(cmd)) {
        return 'YES\n'
      }

      if (/python3 -c/.test(cmd) && !/fcntl\.flock/.test(cmd)) {
        return ''
      }

      if (/setsid|nohup/.test(cmd)) {
        return '4242\n'
      }

      if (/printf '%s\\n'/.test(cmd)) {
        return ''
      }

      return ''
    }
  }

  const { pid } = await spawnRemoteDashboard(ssh as any, {
    hermesPath: '/x/hermes',
    profile: '',
    token: 'secret_token_val',
    ownershipId: OWNERSHIP_ID
  })

  assert.equal(pid, 4242)
  assert.ok(stdinCalls.length > 0, 'token must be sent via stdin')
  assert.ok(
    stdinCalls.some(d => d === 'secret_token_val'),
    'stdin must contain the token'
  )

  for (const cmd of calls) {
    assert.ok(!cmd.includes('secret_token_val'), `token leaked into command: ${cmd}`)
  }
})

test('spawnRemoteDashboard upload uses exclusive-create and O_NOFOLLOW', async () => {
  const calls: string[] = []

  const ssh = {
    calls,
    async exec(cmd, opts?) {
      calls.push(cmd)

      if (/grep -q ssh-session-token-file/.test(cmd)) {
        return 'YES\n'
      }

      if (/python3 -c/.test(cmd) && !/fcntl\.flock/.test(cmd)) {
        return ''
      }

      if (/setsid|nohup/.test(cmd)) {
        return '4242\n'
      }

      if (/printf '%s\\n'/.test(cmd)) {
        return ''
      }

      return ''
    }
  }

  await spawnRemoteDashboard(ssh as any, {
    hermesPath: '/x/hermes',
    profile: '',
    token: 'tk',
    ownershipId: OWNERSHIP_ID
  })
  const uploadCmd = calls.find(c => /python3 -c/.test(c) && !/fcntl\.flock/.test(c))
  assert.ok(uploadCmd, 'must use python3 -c for token upload')
  assert.match(uploadCmd, /O_EXCL/, 'upload must use O_EXCL to reject existing files')
  assert.match(uploadCmd, /O_NOFOLLOW/, 'upload must use O_NOFOLLOW to reject symlinks')
  assert.match(uploadCmd, /O_WRONLY/, 'upload must open write-only')
  assert.match(uploadCmd, /dir_fd=dd/, 'upload must create relative to the opened parent directory')
  assert.match(uploadCmd, /os\.fstat\(dd\)/, 'upload must validate the opened parent directory')
  assert.ok(!uploadCmd.includes('tk'), 'token must not appear in the upload command')
})

test('readLockfile treats a lock with non-integer pid as skew', async () => {
  const lock = { schemaVersion: LOCKFILE_SCHEMA_VERSION, pid: 'not-a-number', port: 8080 }
  assert.equal(isLockfileSkew(await readLockfile(fakeSsh([[/cat/, JSON.stringify(lock)]]), OWNERSHIP_ID)), true)
})

test('readLockfile treats a lock with pid <= 0 as skew', async () => {
  const lock = { schemaVersion: LOCKFILE_SCHEMA_VERSION, pid: -1, port: 8080 }
  assert.equal(isLockfileSkew(await readLockfile(fakeSsh([[/cat/, JSON.stringify(lock)]]), OWNERSHIP_ID)), true)
})

test('readLockfile treats a lock with port out of range as skew', async () => {
  const lock = { schemaVersion: LOCKFILE_SCHEMA_VERSION, pid: 100, port: 99999 }
  assert.equal(isLockfileSkew(await readLockfile(fakeSsh([[/cat/, JSON.stringify(lock)]]), OWNERSHIP_ID)), true)
  const lock2 = { schemaVersion: LOCKFILE_SCHEMA_VERSION, pid: 100, port: 0 }
  assert.equal(isLockfileSkew(await readLockfile(fakeSsh([[/cat/, JSON.stringify(lock2)]]), OWNERSHIP_ID)), true)
})

test('readLockfile accepts a complete owned lock', async () => {
  const lock = ownedLock({ pid: 42, port: 51234 })
  const result = await readLockfile(fakeSsh([[/cat/, JSON.stringify(lock)]]), OWNERSHIP_ID)
  assert.deepEqual(result, lock)
})

test('connect() reuse path does not write a token file', async () => {
  const reuseToken = 'stored-token'
  const lock = ownedLock({ tokenFingerprint: fingerprintToken(reuseToken) })

  const ssh = fakeSsh([
    [/uname/, 'Linux\nx86_64'],
    [/\[ -x/, 'OK'],
    [/cat .*lock\.json/, JSON.stringify(lock)],
    [/kill -0/, 'ALIVE'],
    [/print\("OWNED"/, 'OWNED\n']
  ])

  const result = await connect(connectDeps(ssh, { reuseToken, adoptServedToken: async (_b, t) => t }))
  assert.equal(result.reused, true)
  assert.ok(!ssh.calls.some(c => /sys\.stdin\.buffer\.read/.test(c)), 'reuse must not upload a token file')
})

test('spawnRemoteDashboard fails with update-required when remote lacks --ssh-session-token-file', async () => {
  const ssh = fakeSsh([[/--ssh-session-token-file/, 'NO\n']])

  await assert.rejects(
    () => spawnRemoteDashboard(ssh, { hermesPath: '/x/hermes', profile: '', token: 'tk', ownershipId: OWNERSHIP_ID }),
    (err: any) => {
      assert.match(err.message, /update|upgrade/i)
      assert.equal(err.kind, 'update-required')

      return true
    }
  )
})

test('readLockfile treats a log path outside the exact ownership and spawn path as skew', async () => {
  const lock = ownedLock({ logPath: '~/.hermes/desktop-ssh/other.log' })
  const ssh = fakeSsh([[/cat .*lock\.json/, JSON.stringify(lock)]])
  assert.equal(isLockfileSkew(await readLockfile(ssh, OWNERSHIP_ID)), true)
})

test('cleanupStale never deletes a lock-supplied unexpected log path', async () => {
  const ssh = fakeSsh([
    [/print\("OWNED"/, 'OWNED\n'],
    [cmd => /pidfd_open/.test(cmd), 'TERMINATED\n']
  ])

  await cleanupStale(ssh, OWNERSHIP_ID, ownedLock({ logPath: '~/.hermes/unrelated.log' }))
  assert.ok(!ssh.calls.some(command => command.includes('unrelated.log')))
})

test('pidIsOurDashboard requires an exact nonce option value', async () => {
  const prefix = `/x/hermes serve --isolated --ssh-owner-nonce ${SPAWN_NONCE}ff`
  const suffix = `/x/hermes serve --isolated --ssh-owner-nonce xx${SPAWN_NONCE}`
  assert.equal(await pidIsOurDashboard(fakeSsh([[/print\("OWNED"/, 'FOREIGN\n']]), 5, SPAWN_NONCE, '/x/hermes'), false)
  assert.equal(await pidIsOurDashboard(fakeSsh([[/print\("OWNED"/, 'FOREIGN\n']]), 5, SPAWN_NONCE, '/x/hermes'), false)
})

test('connect removes the token file when a fresh backend fails after returning a pid', async () => {
  const ssh = fakeSsh([
    [/uname/, 'Linux\nx86_64'],
    [/\[ -x/, 'OK'],
    [/cat .*lock\.json/, ''],
    [/grep -q ssh-session-token-file/, 'YES\n'],
    [/python3 -c/, ''],
    [/setsid/, '999\n'],
    [/kill -0 999/, 'DEAD']
  ])

  await assert.rejects(() => connect(connectDeps(ssh)), /Timed out waiting for the remote dashboard/i)
  assert.ok(ssh.calls.some(command => /rm -f .*\.token/.test(command)))
})

test('connect preserves an exact-owned backend when reuse proof transport fails', async () => {
  const reuseToken = 'stored-token'
  const lock = ownedLock({ tokenFingerprint: fingerprintToken(reuseToken) })

  const ssh = fakeSsh([
    [/uname/, 'Linux\nx86_64'],
    [/\[ -x/, 'OK'],
    [/cat .*lock\.json/, JSON.stringify(lock)],
    [/kill -0/, 'ALIVE'],
    [/print\("OWNED"/, 'OWNED\n']
  ])

  await assert.rejects(
    () =>
      connect(
        connectDeps(ssh, {
          reuseToken,
          probeReuseProof: async () => {
            throw new Error('connection reset')
          }
        })
      ),
    (error: any) => error.kind === 'transient-transport-error'
  )
  assert.ok(!ssh.calls.some(command => /kill 333\b/.test(command)))
  assert.ok(!ssh.calls.some(command => /rm -f .*backend\.lock\.json/.test(command)))
})

test('connect replaces an exact-owned backend only after authenticated stale proof', async () => {
  const reuseToken = 'stored-token'
  const lock = ownedLock({ tokenFingerprint: fingerprintToken(reuseToken) })

  const ssh = fakeSsh([
    [/uname/, 'Linux\nx86_64'],
    [/\[ -x/, 'OK'],
    [/cat .*lock\.json/, JSON.stringify(lock)],
    [/kill -0 333/, 'ALIVE'],
    [/print\("OWNED"/, 'OWNED\n'],
    [cmd => /pidfd_open/.test(cmd), 'TERMINATED\n'],
    [/grep -q ssh-session-token-file/, 'YES\n'],
    [/python3 -c/, ''],
    [/setsid/, '999\n'],
    [/kill -0 999/, 'ALIVE'],
    [/cat .*\.log/, 'HERMES_DASHBOARD_READY port=43000\n']
  ])

  const result = await connect(
    connectDeps(ssh, {
      reuseToken,
      probeReuseProof: async (_baseUrl, token, nonce) => {
        assert.equal(token, reuseToken)
        assert.equal(nonce, SPAWN_NONCE)

        return 'authenticated-stale'
      },
      adoptServedToken: async () => 'fresh'
    })
  )

  assert.equal(result.reused, false)
  // The kill goes through main's cleanupStale (ownership-proved SIGTERM with
  // SIGKILL escalation, #91668) — the PR's python re-proof command shape is
  // used by the managed-update path (terminateOwnedDashboardForUpdate), not
  // by connect's stale replacement. Assert the CONTRACT: the owned pid was
  // signalled and the record reclaimed.
  assert.ok(ssh.calls.some(command => /kill 333\b/.test(command)))
  assert.ok(ssh.calls.some(command => /rm -f .*backend\.lock\.json/.test(command)))
})

test('remote SSH ownership capability requires both secure bootstrap flags', async () => {
  let helpProbe = ''

  const supported = fakeSsh([
    [
      /serve --help/,
      command => {
        helpProbe = command

        return 'YES\n'
      }
    ]
  ])

  assert.equal(await remoteSupportsSshOwnership(supported, '/x/hermes'), true)
  assert.match(helpProbe, /ssh-session-token-file/)
  assert.match(helpProbe, /ssh-owner-nonce/)

  const unsupported = fakeSsh([[/serve --help/, 'NO\n']])
  assert.equal(await remoteSupportsSshOwnership(unsupported, '/x/hermes'), false)
})

test.skipIf(process.platform === 'win32')(
  'capability probe survives a zsh login shell on the remote (#111949)',
  async t => {
    // sshd runs the remote command under the account's LOGIN shell. A bare
    // `set -m` is fatal in a non-interactive zsh, so the watchdog-wrapped probe
    // used to return nothing and a current remote was reported as unsupported.
    const zsh = await exec('command -v zsh || true').then(r => r.stdout.trim())

    // CI installs zsh (js-tests.yml); locally a missing zsh must show as a
    // skip, not a pass, or a wrapper regression stays green unnoticed.
    if (!zsh) {
      t.skip('zsh not installed')

      return
    }

    const dir = await mkdtemp(path.join(os.tmpdir(), 'hermes-zsh-probe-'))

    try {
      const hermes = path.join(dir, 'hermes')
      await writeFile(hermes, '#!/bin/sh\necho "--ssh-session-token-file --ssh-owner-nonce"\n', { mode: 0o700 })

      const ssh = { exec: async (command: string) => (await exec(command, { shell: zsh })).stdout }

      assert.equal(await remoteSupportsSshOwnership(ssh, hermes), true)
    } finally {
      await rm(dir, { recursive: true, force: true })
    }
  }
)

test('probes run under the remote watchdog so a hung CLI cannot orphan (#110478)', async () => {
  let versionProbe = ''

  const versionSsh = fakeSsh([
    [
      /--version/,
      (cmd: string) => {
        versionProbe = cmd

        return 'Hermes Agent v0.18.2 (abc123)\n'
      }
    ]
  ])

  assert.equal(await probeHermesVersion(versionSsh, '/x/hermes'), 'Hermes Agent v0.18.2 (abc123)')
  assert.ok(versionProbe.includes('kill -9'), 'version probe wrapped in the remote watchdog')

  let helpProbe = ''

  const helpSsh = fakeSsh([
    [
      /serve --help/,
      (cmd: string) => {
        helpProbe = cmd

        return 'YES\n'
      }
    ]
  ])

  assert.equal(await remoteSupportsSshOwnership(helpSsh, '/x/hermes'), true)
  assert.ok(helpProbe.includes('kill -9'), 'ownership probe wrapped in the remote watchdog')
  assert.ok(
    /\$\(.*\(.*serve --help.*\) <\/dev\/null &/.test(helpProbe),
    'watchdog nested around the inner serve --help'
  )
})

test('cleanupStale escalates to SIGKILL when the backend survives the graceful wait (#91668 quit-during-active-turn)', async () => {
  // A serve mid-turn (in-flight LLM call, live MCP children) can ride out
  // SIGTERM well past the 5s graceful wait. Before-quit races the whole
  // teardown against 6s and then closes SSH — so a give-up here reparents
  // the still-running backend to pid 1: exactly the #91668 leak. The
  // graceful-wait failure must escalate to SIGKILL and still drop the lock.
  const ssh = fakeSsh([
    [/print\("OWNED"/, 'OWNED\n'],
    [(cmd: string) => /kill 9 &&/.test(cmd), new Error('exit 1: pid alive after graceful wait')]
  ])

  await cleanupStale(ssh, OWNERSHIP_ID, {
    pid: 9,
    spawnNonce: SPAWN_NONCE,
    hermesPath: '/x/hermes',
    logPath: spawnLogPath(OWNERSHIP_ID, SPAWN_NONCE)
  })
  assert.ok(
    ssh.calls.some(c => /kill -9 9\b/.test(c)),
    'must escalate to SIGKILL after the graceful wait fails'
  )
  assert.ok(
    ssh.calls.some(c => /rm -f .*backend\.lock\.json/.test(c)),
    'lockfile must still be dropped after the forced kill'
  )
})
test('cleanupStale keeps the lockfile when even SIGKILL cannot confirm the pid died', async () => {
  const ssh = fakeSsh([
    [/print\("OWNED"/, 'OWNED\n'],
    [(cmd: string) => /kill 9 &&/.test(cmd), new Error('exit 1: pid alive after graceful wait')],
    [(cmd: string) => /kill -9 9\b/.test(cmd), new Error('exit 1: unkillable (D-state)')]
  ])

  await assert.rejects(
    cleanupStale(ssh, OWNERSHIP_ID, {
      pid: 9,
      spawnNonce: SPAWN_NONCE,
      hermesPath: '/x/hermes',
      logPath: spawnLogPath(OWNERSHIP_ID, SPAWN_NONCE)
    }),
    /Could not terminate/
  )
  // The record must survive so the next connect's reap pass retries.
  assert.ok(!ssh.calls.some(c => /rm -f .*backend\.lock\.json/.test(c)))
})
test.skipIf(process.platform === 'win32')(
  'buildSpawnCommand quotes expandRemotePath fragments exactly once (real sh parse)',
  async () => {
    // expandRemotePath() output is pre-quoted; a second shq() ships literal quote
    // characters to the remote python. Parse the composed command with a real sh,
    // as the remote login shell does, and require every path to come out clean.
    const cmd = buildSpawnCommand('/x/hermes', 'work', {
      hermesHome: '~/.hermes',
      logPath: spawnLogPath(OWNERSHIP_ID, SPAWN_NONCE),
      ownershipId: OWNERSHIP_ID,
      reservationNonce: SPAWN_NONCE,
      spawnNonce: SPAWN_NONCE,
      tokenFilePath: spawnTokenPath(OWNERSHIP_ID, SPAWN_NONCE),
      lockMetadata: { ownershipId: OWNERSHIP_ID, spawnNonce: SPAWN_NONCE }
    })

    // Capture the argv a remote shell would hand to python3, via a shim on PATH.
    const shell: string = (await exec('command -v bash', { shell: 'bash' })).stdout.trim()
    const root: string = await mkdtemp(path.join(os.tmpdir(), 'hermes-argv-shim-'))

    try {
      const shimDir = path.join(root, 'shim')
      const fakeHome = path.join(root, 'home')
      await mkdir(shimDir)
      await mkdir(fakeHome)
      const argvFile = path.join(shimDir, 'argv')
      await writeFile(path.join(shimDir, 'python3'), `#!${shell}\nprintf '%s\\0' "$@" > '${argvFile}'\n`, {
        mode: 0o755
      })
      await exec(cmd, {
        shell: 'sh',
        env: { ...process.env, PATH: `${shimDir}:${process.env.PATH}`, HOME: fakeHome }
      })
      const argv = (await readFile(argvFile, 'utf8')).split('\0')

      // argv: ['-c', <marker gate>, <marker path>, <payload>]
      assert.equal(
        argv[2],
        `${fakeHome}/.hermes/.hermes-update-in-progress`,
        'marker path must reach python fully expanded, with no quote characters'
      )

      // The payload assigns reservation/lock/owner_file before its mkdir loop.
      // Evaluate only that prefix the way the remote sh does; never the loop itself.
      const payload = argv[3]
      const loopStart = payload.indexOf('i=0;')
      assert.ok(loopStart > 0, 'payload prefix sentinel missing')

      const { stdout } = await exec(
        `${payload.slice(0, loopStart)} printf '%s\\n' "$reservation" "$lock" "$owner_file"`,
        {
          shell: 'sh',
          env: { ...process.env, HOME: fakeHome }
        }
      )

      const [reservation, lock, ownerFile] = stdout.split('\n')
      const base = `${fakeHome}/.hermes/desktop-ssh/${OWNERSHIP_ID}`
      assert.equal(reservation, `${base}/.connect.lock`)
      assert.equal(lock, `${base}/backend.lock.json`)
      assert.equal(ownerFile, `${base}/.connect.lock/owner`)
    } finally {
      await rm(root, { recursive: true, force: true })
    }
  }
)

// The liveness and ownership probes answer over the same SSH channel that is
// often mid-teardown right after the served token resolved. An exec that
// returns neither sentinel is indeterminate (#111810): read as DEAD it tore
// down a live backend; read as FOREIGN it skipped the reap while removing the
// lockfile — one orphaned `serve --isolated` per failed attempt.
test('connect() does not declare a live dashboard dead when the liveness probe answers nothing once', async () => {
  let liveness = 0

  const ssh = fakeSsh([
    [/uname/, 'Linux\nx86_64'],
    [/\[ -x/, 'OK'],
    [/cat .*lock\.json/, ''],
    [/grep -q ssh-session-token-file/, 'YES\n'],
    [/python3 -c/, ''],
    [/printf '%s\\n'/, ''],
    [/setsid/, '777\n'],
    [(cmd: string) => /kill -0 777/.test(cmd) && !cmd.includes('while'), () => (liveness++ === 0 ? '' : 'ALIVE\n')],
    [/cat .*\.log/, 'HERMES_DASHBOARD_READY port=51999\n']
  ])

  const result = await connect(connectDeps(ssh, { platform: { os: 'Linux', arch: 'x86_64' } }))

  assert.equal(result.reused, false)
  assert.equal(result.pid, 777)
  assert.ok(
    !ssh.calls.some(c => /(^|[^-\d])kill(?: -\w+)? 777\b/.test(c) && !/kill -0/.test(c)),
    'must not reap a live backend'
  )
})

test('cleanupStale reaps after one lost ownership answer and keeps the lockfile when none ever settles', async () => {
  let ownership = 0

  const flaky = fakeSsh([
    [/print\("OWNED"/, () => (ownership++ === 0 ? '' : 'OWNED\n')],
    [/kill 777 &&/, 'TERMINATED\n']
  ])

  await cleanupStale(flaky, OWNERSHIP_ID, ownedLock({ pid: 777 }))
  assert.ok(
    flaky.calls.some(c => /kill 777 &&/.test(c)),
    'must reap the owned backend'
  )
  assert.ok(flaky.calls.some(c => /rm -f .*backend\.lock\.json/.test(c)))

  const silent = fakeSsh([[/print\("OWNED"/, '']])

  await assert.rejects(
    cleanupStale(silent, OWNERSHIP_ID, ownedLock({ pid: 777 })),
    (error: any) => error.kind === 'transient-transport-error'
  )

  assert.ok(
    !silent.calls.some(c => /(^|[^-\d])kill(?: -\w+)? 777\b/.test(c) && !/kill -0/.test(c)),
    'must not kill unproven'
  )
  assert.ok(
    !silent.calls.some(c => /rm -f .*backend\.lock\.json/.test(c)),
    'record must survive for the next connect to reap'
  )
})

test('connect() post-spawn cleanup that cannot prove ownership keeps the original boot error', async () => {
  const boot: any = new Error('dashboard never answered')
  boot.kind = 'boot-failed'

  const ssh = fakeSsh([
    [/uname/, 'Linux\nx86_64'],
    [/\[ -x/, 'OK'],
    [/cat .*lock\.json/, ''],
    [/grep -q ssh-session-token-file/, 'YES\n'],
    [/python3 -c/, ''],
    [/printf '%s\\n'/, ''],
    [/setsid/, '777\n'],
    [/kill -0 777/, 'ALIVE\n'],
    [/cat .*\.log/, 'HERMES_DASHBOARD_READY port=51999\n'],
    [/print\("OWNED"/, '']
  ])

  await assert.rejects(
    connect(
      connectDeps(ssh, {
        platform: { os: 'Linux', arch: 'x86_64' },
        waitForHermes: async () => {
          throw boot
        }
      })
    ),
    (error: any) => error === boot && error.cleanupCause?.kind === 'transient-transport-error'
  )

  assert.ok(
    !ssh.calls.some(c => /rm -f .*backend\.lock\.json/.test(c)),
    'record must survive for the next connect to reap'
  )
})

// ---------------------------------------------------------------------------
// resolveReadyTimeoutMs (issue #94642): cold-start-tolerant remote budgets
// ---------------------------------------------------------------------------
test('honors a valid HERMES_DESKTOP_REMOTE_READY_TIMEOUT_MS override', () => {
  const env = { HERMES_DESKTOP_REMOTE_READY_TIMEOUT_MS: '180000' }
  assert.equal(resolveReadyTimeoutMs(env), 180_000)
})
test('clamps an override below the floor up to the 45s minimum', () => {
  const env = { HERMES_DESKTOP_REMOTE_READY_TIMEOUT_MS: '1000' }
  assert.equal(resolveReadyTimeoutMs(env), MIN_READY_TIMEOUT_MS)
})
test('rounds a fractional override', () => {
  const env = { HERMES_DESKTOP_REMOTE_READY_TIMEOUT_MS: '60000.7' }
  assert.equal(resolveReadyTimeoutMs(env), 60_001)
})
test('falls back to the default for malformed / non-positive overrides', () => {
  for (const bad of ['', 'abc', '0', '-5', 'NaN', undefined]) {
    const env = bad === undefined ? {} : { HERMES_DESKTOP_REMOTE_READY_TIMEOUT_MS: bad }
    assert.equal(
      resolveReadyTimeoutMs(env),
      DEFAULT_READY_TIMEOUT_MS,
      `override ${JSON.stringify(bad)} should fall through to the default`
    )
  }
})