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.

95.3 KB
Raw Blame
#!/usr/bin/env python3
"""Boot and install the actual ISO in a disposable QEMU machine.

Uses a private qcow2 disk with a known serial. Never passes a host block device
to QEMU. Screenshots, serial logs, timings and checks survive every failure.
"""
from __future__ import annotations
import argparse
import base64
import csv
import hashlib
import io
import json
import os
from pathlib import Path
import re
import select
import shlex
import shutil
import socket
import subprocess
import sys
import tempfile
import tarfile
import time
import uuid


def control_point(words, word, width, height, scale, border):
    rows = [r for r in csv.DictReader(io.StringIO(words), delimiter='\t')
            if r.get('text', '').strip('[]').lower() == word.lower()]
    assert rows, f'The visible screen has no {word} control'
    row = max(rows, key=lambda r: int(r['top']))  # The dock is the lowest instance.
    x = (int(row['left']) + int(row['width']) / 2 - border) / scale
    y = (int(row['top']) + int(row['height']) / 2 - border) / scale
    assert 0 <= x < width and 0 <= y < height, 'OCR control lies outside the actual screen'
    return round(x * 32767 / (width - 1)), round(y * 32767 / (height - 1))


def check_live_media(vm, result, expected_mode=None):
    # Archiso reserves 2 GiB beyond the compressed payload before copying it.
    # A fixed guest RAM size therefore does not determine the boot mode.
    probe = '''import importlib.util, json
from pathlib import Path
s = importlib.util.spec_from_file_location('installer', '/usr/lib/harness-os/install.py')
i = importlib.util.module_from_spec(s)
s.loader.exec_module(i)
payload = i.live_payload()
ram = Path('/run/archiso/copytoram/airootfs.sfs')
media = Path('/run/archiso/bootmnt/arch/x86_64/airootfs.sfs')
bootmnt = Path('/run/archiso/bootmnt')
assert payload in (ram, media), str(payload)
mode = 'ram' if payload == ram else 'media'
if mode == 'ram':
    assert not bootmnt.exists(), 'RAM boot kept the USB mounted'
    assert ram.parent.is_mount(), 'RAM payload is not on its own mount'
    assert i.run('findmnt', '-nro', 'FSTYPE', '--mountpoint', str(ram.parent), capture=True).strip() == 'tmpfs'
else:
    assert bootmnt.is_mount(), 'USB payload is not on mounted media'
    assert not ram.exists(), 'Ambiguous live payload'
d = next(d for d in i.inventory() if d.get('serial') == 'HN_OS_LIVE')
assert not d['ro'] and d['size'] >= i.MIN_DISK_BYTES
try:
    i.validate_disk(d)
except ValueError as e:
    assert ('booted into RAM' if mode == 'ram' else 'mounted filesystems') in str(e), str(e)
else:
    raise AssertionError('The writable boot USB was offered as an installation target')
print('HN_LIVE_MEDIA=' + json.dumps(dict(mode=mode, payload=str(payload), payload_bytes=payload.stat().st_size, boot_usb_rejected=True)))
'''
    encoded = base64.b64encode(probe.encode()).decode()
    output, _ = vm.command('printf %s ' + encoded + ' | base64 -d | python3')
    match = re.search(r'HN_LIVE_MEDIA=(\{[^\r\n]+\})', output)
    assert match, 'The guest did not report its actual live media'
    media = json.loads(match.group(1))
    result['live_media'] = media
    if expected_mode and media['mode'] != expected_mode:
        raise AssertionError(f"Expected {expected_mode} boot, observed {media['mode']}")
    if media['mode'] == 'ram':
        result['checks'].append('Real USB boot automatically copies the payload into RAM and unmounts the boot medium')
        result['checks'].append('The unmounted writable Harness USB is rejected as an installation target in RAM mode')
    else:
        result['checks'].append('Real USB boot retains the mounted payload when automatic RAM copying is not selected')
        result['checks'].append('The mounted writable Harness USB is rejected as an installation target')


# Harness OS requires an account before its workspace opens (#1276). The fixture signs in the way a
# headless box does: a box ticket the account issues (backend issueBoxTicket), spent in the guest by
# `harness login --ticket`. The account is a review account with a fixed email code; both come from
# the repository's secrets (HARNESS_TEST_EMAIL, HARNESS_TEST_OTP), never from this public file.
ACCOUNT_API = 'https://apiv2.autonomous.ai'
HARNESS_API = 'https://harness-api.autonomous.ai'
# Real model replies (--model-calls): a free model's speed and wording are another service's, so an
# ordinary run checks only what the image does, and asks a model nothing.
MODEL_CALLS = False


def account_ticket():
    """A one-time, 30-minute sign-in ticket for the test account. Never logs a token."""
    import urllib.error
    import urllib.request
    email, code = os.environ.get('HARNESS_TEST_EMAIL'), os.environ.get('HARNESS_TEST_OTP')
    if not email or not code:
        raise RuntimeError('Harness OS requires an account: set HARNESS_TEST_EMAIL and HARNESS_TEST_OTP.')

    def post(url, body, token=None):
        headers = {'Content-Type': 'application/json', 'Accept': 'application/json', 'Location': 'en-US',
                   'User-Agent': 'Harness-OS-VM-Test/1'}  # the account API refuses a bare client
        if token:
            headers['Authorization'] = 'Bearer ' + token
        request = urllib.request.Request(url, data=json.dumps(body).encode(), headers=headers, method='POST')
        try:
            with urllib.request.urlopen(request, timeout=30) as response:
                return json.loads(response.read() or b'{}')
        except urllib.error.HTTPError as error:
            raise RuntimeError(f'{url} answered {error.code}') from None

    post(ACCOUNT_API + '/api/v1/customers/send-login-verification', {'email': email})
    signed = post(ACCOUNT_API + '/api/v1/customers/sign-in', {'email': email, 'otp': code, 'grant_type': 'otp'})
    token = (signed.get('data') or {}).get('access_token') if signed.get('status') == 1 else None
    if not token:
        raise RuntimeError('The test account did not sign in.')
    ticket = (post(HARNESS_API + '/api/auth/box/ticket', {}, token).get('data') or {}).get('ticket')
    if not ticket:
        raise RuntimeError('Harness issued no sign-in ticket for the test account.')
    return ticket


def form_text(path):
    """OCR an OS form or hn page as sign_in_vm.py reads them: both draw light text, hn on a shaded
    panel that global thresholding mistakes for ink, so the known dark palette is normalized first."""
    from PIL import Image, ImageOps
    readable = path.with_name(path.stem + '-ocr.png')
    with Image.open(path) as frame:
        ink = frame.convert('L').point(lambda value: 0 if value >= 96 else 255)
        ink = ink.resize((frame.width * 2, frame.height * 2), Image.Resampling.NEAREST)
        ImageOps.expand(ink, border=24, fill=255).save(readable)
    return subprocess.check_output(['tesseract', str(readable), 'stdout', '--psm', '6'],
                                   text=True, stderr=subprocess.DEVNULL, timeout=15)


class VM:
    def __init__(self, folder, iso, firmware, memory, live_transport='cdrom', cpu=None, video='virtio-vga', audio=False, apple_model=None):
        self.folder, self.iso, self.firmware, self.memory = folder, iso, firmware, memory
        self.live_transport = live_transport
        self.cpu = cpu
        if video not in ('virtio-vga', 'VGA'):
            raise ValueError('Unsupported test display: ' + video)
        self.video = video
        self.audio = audio
        if apple_model is not None and not re.fullmatch(r'(?:MacBook(?:Air|Pro)|Macmini|MacPro|iMac|iMacPro)[0-9]+,[0-9]+', apple_model):
            raise ValueError('Invalid synthetic Apple DMI model.')
        self.apple_model = apple_model
        self.unlock_count = 0
        self.boot_count = 0
        self.process = None
        self.serial = None
        self.qmp = None
        self.qmp_file = None
        self.shell_ready = False
        self.control = tempfile.TemporaryDirectory(prefix='hn-os-vm-', dir='/tmp')
        self.control_path = Path(self.control.name)
        self.log = (folder / 'serial.log').open('ab', buffering=0)
        self.stderr = (folder / 'qemu.log').open('ab', buffering=0)
        self.disk = folder / 'target.qcow2'
        subprocess.run(['qemu-img', 'create', '-f', 'qcow2', str(self.disk), '24G'], check=True)
        if live_transport == 'usb':
            self.usb = folder / 'live-usb.qcow2'
            subprocess.run(['qemu-img', 'create', '-f', 'qcow2', '-F', 'raw', '-b',
                            str(iso), str(self.usb)], check=True)
            subprocess.run(['qemu-img', 'resize', str(self.usb), '16G'], check=True)
        if firmware == 'uefi':
            self.code = Path('/usr/share/OVMF/OVMF_CODE_4M.fd')
            self.vars = folder / 'OVMF_VARS.fd'
            shutil.copyfile('/usr/share/OVMF/OVMF_VARS_4M.fd', self.vars)

    def start(self, live):
        self.shell_ready = False
        for name in ['serial.sock', 'qmp.sock']:
            (self.control_path / name).unlink(missing_ok=True)
        self.started = time.monotonic()
        self.boot_count += 1
        self.boot_event('start', live=live)
        acceleration = 'kvm' if os.access('/dev/kvm', os.R_OK | os.W_OK) else 'tcg'
        self.acceleration = acceleration
        args = ['qemu-system-x86_64', '-accel', acceleration, '-m', str(self.memory), '-smp', '2',
                '-cpu', self.cpu or ('host' if acceleration == 'kvm' else 'max'), '-device', self.video,
                '-device', 'virtio-tablet-pci',
                '-display', 'none', '-no-reboot',
                '-drive', f'file={self.disk},format=qcow2,if=none,id=target',
                '-device', f'virtio-blk-pci,drive=target,serial=HN_OS_TEST,bootindex={2 if live else 1}',
                '-device', 'virtio-net-pci,netdev=net,id=hnnet', '-netdev', 'user,id=net',
                '-serial', f'unix:{self.control_path / "serial.sock"},server=on,wait=off',
                '-qmp', f'unix:{self.control_path / "qmp.sock"},server=on,wait=off']
        if self.apple_model:
            # Explicit synthetic DMI for firmware selection tests. This does
            # not emulate the T2 bridge, physical input, radios or audio.
            args += ['-smbios', 'type=1,manufacturer=Apple Inc.,product=' + self.apple_model.replace(',', ',,')]
        if self.audio:
            args += ['-audiodev', f'wav,id=sound,path={self.folder / ("audio-" + str(self.boot_count) + ".wav")}',
                     '-device', 'intel-hda', '-device', 'hda-duplex,audiodev=sound']
        if live:
            # UEFI remembers the installed disk in NVRAM. Explicit device boot
            # indices are needed to select the recovery ISO again on later boots.
            if self.live_transport == 'usb':
                # A private overlay exposes a full-sized writable USB while
                # preserving the verified host ISO, including on test failure.
                args += ['-device', 'qemu-xhci,id=usb',
                         '-drive', f'file={self.usb},format=qcow2,if=none,id=live',
                         '-device', 'usb-storage,bus=usb.0,drive=live,serial=HN_OS_LIVE,removable=on,bootindex=1']
            else:
                args += ['-drive', f'file={self.iso},format=raw,media=cdrom,if=none,id=live',
                         '-device', 'ide-cd,drive=live,bootindex=1']
        if self.firmware == 'uefi':
            args += ['-drive', f'if=pflash,format=raw,readonly=on,file={self.code}',
                     '-drive', f'if=pflash,format=raw,file={self.vars}']
        self.process = subprocess.Popen(args, stdout=self.stderr, stderr=self.stderr)
        self.serial = self.connect('serial.sock')
        self.qmp = self.connect('qmp.sock')
        self.qmp.settimeout(10)
        self.qmp_file = self.qmp.makefile('rb')
        json.loads(self.qmp_file.readline())
        self.monitor('qmp_capabilities')

    def connect(self, name):
        deadline = time.monotonic() + 30
        while time.monotonic() < deadline:
            if self.process.poll() is not None:
                raise RuntimeError('QEMU exited before opening its control sockets: ' +
                                   (self.folder / 'qemu.log').read_text()[-2000:])
            sock = socket.socket(socket.AF_UNIX)
            try:
                sock.connect(str(self.control_path / name))
                return sock
            except (FileNotFoundError, ConnectionRefusedError):
                sock.close()
                time.sleep(0.1)
        raise TimeoutError(f'QEMU did not expose {name}')

    def monitor(self, command, /, **arguments):
        identity = uuid.uuid4().hex
        self.qmp.sendall((json.dumps({'execute': command, 'arguments': arguments, 'id': identity}) + '\n').encode())
        while True:
            result = json.loads(self.qmp_file.readline())
            if result.get('id') == identity:
                if 'error' in result:
                    raise RuntimeError(result['error'])
                return result.get('return')

    def wait(self, pattern, timeout=180):
        deadline = time.monotonic() + timeout
        output = b''
        regex = re.compile(pattern.encode(), re.S)
        while time.monotonic() < deadline:
            if self.process.poll() is not None:
                raise RuntimeError(f'QEMU exited while waiting for {pattern!r}')
            if select.select([self.serial], [], [], min(1, max(0, deadline - time.monotonic())))[0]:
                chunk = self.serial.recv(65536)
                if not chunk:
                    raise RuntimeError('Guest serial console disconnected.')
                self.log.write(chunk)
                output += chunk
                if regex.search(output):
                    return output.decode(errors='replace')
        raise TimeoutError(f'Guest did not produce {pattern!r}; see serial.log')

    def send(self, text):
        self.serial.sendall(text.encode())

    def boot_event(self, stage, **details):
        event = dict(boot=self.boot_count, stage=stage,
                     seconds=round(time.monotonic() - self.started, 3), **details)
        with (self.folder / 'boot-events.jsonl').open('a') as log:
            log.write(json.dumps(event) + '\n')
        return event

    def boot_diagnostics(self, config, name):
        # Keep the initrd journal as well as userspace timings. A single overall
        # boot duration cannot distinguish waiting for a person from an OS stall.
        output, _ = self.command('printf %s ' + shlex.quote(config['password'] + '\n') +
                                 ' | sudo -S journalctl -b -o short-monotonic --no-pager', timeout=60)
        (self.folder / (name + '-boot-journal.log')).write_text(output)
        output, _ = self.command('systemd-analyze --no-pager; systemd-analyze --no-pager blame; '
                                 'systemd-analyze --no-pager critical-chain; systemctl --failed --no-pager')
        (self.folder / (name + '-boot-analysis.txt')).write_text(output)

    def command(self, command, timeout=90, check=True):
        marker = 'HN_RESULT_' + uuid.uuid4().hex
        # A probe may use `exit` or `exec`. Keep it inside a subshell so the
        # serial login remains available to report its status and run diagnostics.
        self.send('(' + command + f"); hn_status=$?; printf '\\n{marker}:%s\\n' \"$hn_status\"\n")
        output = self.wait(r'\r?\n' + marker + r':\d+\r?\n', timeout)
        match = re.search(r'\r?\n' + marker + r':(\d+)\r?\n', output)
        status = int(match.group(1))
        if check and status:
            raise RuntimeError(f'Guest command failed ({status}): {command}\n{output[-2000:]}')
        return output[:match.start()], status

    def read_file(self, path, timeout=90):
        """Read exact guest bytes without serial prompt or shell-integration codes."""
        marker = 'HN_FILE_' + uuid.uuid4().hex
        output, _ = self.command(
            'hn_file_data=$(base64 < ' + shlex.quote(str(path)) + ') && '
            f"printf '\\n{marker}:begin\\n%s\\n{marker}:end\\n' \"$hn_file_data\"",
            timeout=timeout)
        match = re.search(r'\r?\n' + marker + r':begin\r?\n(.*?)\r?\n' + marker + r':end\r?\n', output, re.S)
        if not match:
            raise RuntimeError(f'Guest file transfer is incomplete: {path}')
        return base64.b64decode(''.join(match.group(1).splitlines()), validate=True)

    def login_installed(self, config, unlock_delay=0, wait_workspace=True):
        if config['encrypt']:
            self.unlock_count += 1
            self.wait_unlock()
            self.unlock_prompt_seconds = self.boot_event('unlock-prompt')['seconds']
            if unlock_delay:
                time.sleep(unlock_delay)
                self.screenshot('delayed-disk-unlock')
                # A wrong password must return to the prompt, without losing
                # the ability to unlock after the old device-timeout deadline.
                self.type_probe('wrong-password')
                self.keys('ret')
                time.sleep(8)
                self.wait_unlock()
                self.boot_event('unlock-retry-prompt')
                self.screenshot('disk-unlock-retry')
            self.type_probe(config['password'][:3])
            self.screenshot(f'disk-unlock-{self.unlock_count}-masked')
            self.type_probe(config['password'][3:])
            self.keys('ret')
            self.boot_event('password-submitted')
        self.wait(r'login:', timeout=180)
        self.boot_event('serial-login-prompt')
        self.send(config['username'] + '\n')
        self.wait(r'Password:')
        self.send(config['password'] + '\n')
        self.wait(r'\$ ')
        self.shell_ready = True
        self.command('stty -echo')
        if not config['encrypt']:
            # tty1 knows its one account and asks only its password (installer.py, password.conf).
            for char in config['password']:
                self.keys('minus' if char == '-' else char)
            self.keys('ret')
            time.sleep(2)
        if wait_workspace:
            self.command('for n in $(seq 1 90); do systemctl --user is-active --quiet hn-screen && pgrep -x "hn|harness-tui" >/dev/null && exit 0; sleep 1; done; exit 1', timeout=110)
        self.command('/usr/lib/harness-os/wait-runtime', timeout=160)
        self.boot_event('harness-ready')

    def form_shows(self, name, text, timeout=90):
        """Wait until the framebuffer shows `text`: the OS network form runs before hn, so no
        `hn capture-pane` can read it, and hn's sign-in page is a dialog over its panes."""
        deadline = time.monotonic() + timeout
        while True:
            self.screenshot(name)
            seen = form_text(self.folder / (name + '.png'))
            (self.folder / (name + '.txt')).write_text(seen)
            if text.lower() in seen.lower():
                return
            if time.monotonic() >= deadline:
                raise AssertionError(f'{text} was not visible; see {name}.png')
            time.sleep(1)

    def sign_in(self, name='sign-in'):
        """Sign the installed system in to the test account at hn's required sign-in page (#1276),
        as a headless box is signed in. Runs as the logged-in user; needs the network."""
        self.command('nm-online -q --timeout=60', timeout=70)
        # Concurrent test VMs share the test account, and signed in, hn shows the account's shared
        # tabs: another VM's windows would fill this screen. Keep this computer's tabs to itself.
        self.command('mkdir -p ~/.config/systemd/user/hn-screen.service.d && printf "[Service]\\n'
                     'Environment=HARNESS_TUI_DESK_SIGNED_IN=off\\n" > ~/.config/systemd/user/hn-screen.service.d/test-desk.conf && '
                     'systemctl --user daemon-reload && systemctl --user restart hn-screen && '
                     'for n in $(seq 1 60); do pgrep -u "$(id -u)" -x "hn|harness-tui" >/dev/null && '
                     'tr "\\0" "\\n" < /proc/$(pgrep -u "$(id -u)" -nx "hn|harness-tui")/environ | '
                     'grep -qx HARNESS_TUI_DESK_SIGNED_IN=off && exit 0; sleep 1; done; exit 1', timeout=75)
        self.form_shows(name + '-required', 'Sign in to Harness')
        output, status = self.command('harness login --json --ticket=' + shlex.quote(account_ticket()),
                                      timeout=120, check=False)
        # The result line shares the serial stream with shell-integration escapes and with the banner
        # of the daemon the sign-in restarts: find it anywhere, and let the daemon have the last word.
        results = []
        for found in re.finditer(r'\{"type":"result"[^\r\n]*\}', output):
            try:
                results.append(json.loads(found.group(0)))
            except json.JSONDecodeError:
                pass
        if status or any(result.get('status') == 'error' for result in results):
            raise RuntimeError('The test account sign-in failed: ' + json.dumps(results[-1:] or output[-300:]))
        # Asked over the daemon's own socket, as wait-runtime does: over the loopback port a caller
        # without the local credential is told only which daemon this is, never `signedIn`.
        self.command('for n in $(seq 1 60); do s=$(curl -s http://127.0.0.1:18473/api/status | jq -r ".localSocket // empty"); '
                     '[ -S "$s" ] && curl -s --unix-socket "$s" http://localhost/api/status | '
                     'grep -q \'"signedIn":true\' && exit 0; sleep 1; done; exit 1', timeout=75)
        # Signed in from outside hn (as a phone's setup does), hn learns it at its next account check,
        # at most a minute away: the page leaves once it has.
        deadline = time.monotonic() + 90
        while True:
            self.screenshot(name + '-signed-in')
            if 'sign in to harness' not in form_text(self.folder / (name + '-signed-in.png')).lower():
                break
            if time.monotonic() >= deadline:
                raise AssertionError('Required sign-in stayed on screen after the account signed in.')
            time.sleep(2)
        self.boot_event('signed-in')

    def wait_unlock(self):
        # OCR reads the actual framebuffer; a process or serial prompt alone
        # cannot prove the intended unlock screen was shown to the user.
        deadline = time.monotonic() + 180
        while time.monotonic() < deadline:
            name = f'disk-unlock-{self.unlock_count}'
            self.screenshot(name)
            text = subprocess.check_output(['tesseract', str(self.folder / (name + '.png')),
                                            'stdout', '--psm', '11'], text=True,
                                           stderr=subprocess.DEVNULL, timeout=10)
            if 'enter your password' in text.lower():
                (self.folder / (name + '.txt')).write_text(text)
                return
            time.sleep(2)
        raise TimeoutError('The Harness graphical unlock prompt was not rendered.')

    def screen_shows(self, name, text, timeout=20):
        """OCR the framebuffer until `text` is shown: hn's dialogs float over the panes, so
        `hn capture-pane`, which reads a pane, never contains them."""
        from PIL import Image, ImageOps
        deadline = time.monotonic() + timeout
        while True:
            self.screenshot(name)
            # Light text on hn's dark dialog reads as click_word reads controls: inverted, doubled.
            readable = self.folder / (name + '-ocr.png')
            with Image.open(self.folder / (name + '.png')) as image:
                inverted = ImageOps.invert(image.convert('L')).resize((image.width * 2, image.height * 2))
                ImageOps.expand(inverted, border=24, fill=255).save(readable)
            seen = subprocess.check_output(['tesseract', str(readable), 'stdout', '--psm', '11'],
                                           text=True, stderr=subprocess.DEVNULL, timeout=15)
            if text.lower() in seen.lower():
                return True
            if time.monotonic() >= deadline:
                (self.folder / (name + '.txt')).write_text(seen)
                return False
            time.sleep(1)

    def screenshot(self, name):
        ppm = self.folder / (name + '.ppm')
        self.monitor('screendump', filename=str(ppm))
        from PIL import Image
        Image.open(ppm).save(self.folder / (name + '.png'))
        ppm.unlink()

    def keys(self, *keys):
        self.monitor('send-key', keys=[{'type': 'qcode', 'data': key} for key in keys], **{'hold-time': 100})
        time.sleep(0.12)  # Release each key, including repeated password characters.

    def click_word(self, name, word):
        """Locate a visible control in a screenshot and send actual pointer input."""
        from PIL import Image, ImageOps
        self.screenshot(name)
        frame = self.folder / (name + '.png')
        # Small text against the screen edge needs a margin for OCR. Keep the
        # original framebuffer and the exact transform so clicks still target
        # the real control, never a hard-coded or inferred screen location.
        scale, border = 2, 24
        ocr_frame = self.folder / (name + '-ocr.png')
        with Image.open(frame) as image:
            width, height = image.size
            readable = ImageOps.invert(image.convert('L')).resize((width * scale, height * scale))
            ImageOps.expand(readable, border=border, fill=255).save(ocr_frame)
        words = subprocess.check_output(['tesseract', str(ocr_frame), 'stdout', '--psm', '11', 'tsv'],
                                        stderr=subprocess.DEVNULL, text=True, timeout=15)
        (self.folder / (name + '-ocr.txt')).write_text(words)
        x, y = control_point(words, word, width, height, scale, border)
        self.monitor('input-send-event', events=[
            {'type': 'abs', 'data': {'axis': 'x', 'value': x}},
            {'type': 'abs', 'data': {'axis': 'y', 'value': y}},
        ])
        # Move before pressing, as a person does. A QMP acknowledgement queues
        # input; it does not establish that the guest compositor has delivered
        # the pointer's enter/motion before the following button event.
        time.sleep(.2)
        for down in [True, False]:
            self.monitor('input-send-event', events=[{'type': 'btn', 'data': {'button': 'left', 'down': down}}])
            time.sleep(.15)

    def type_probe(self, text):
        # Send display keyboard events, not hn's CLI input path. Probe commands
        # use this bounded US-layout set, including browser URL punctuation.
        if not re.fullmatch(r'[a-z0-9 .:/-]+', text):
            raise ValueError('Keyboard probe contains unsupported characters.')
        for char in text:
            if char == ':':
                self.keys('shift', 'semicolon')
            else:
                self.keys({' ': 'spc', '-': 'minus', '.': 'dot', '/': 'slash'}.get(char, char))

    def stop(self):
        if self.process and self.process.poll() is None:
            try:
                self.monitor('quit')
            except (OSError, ValueError, RuntimeError):
                self.process.terminate()
            try:
                self.process.wait(timeout=15)
            except subprocess.TimeoutExpired:
                self.process.kill()
                self.process.wait()
        for handle in [self.serial, self.qmp_file, self.qmp]:
            if handle:
                handle.close()
        self.serial = self.qmp_file = self.qmp = None


def workspace_text_visible(text, *, allow_welcome=False):
    compact = re.sub(r'\s+', '', text).lower()
    return 'me@harness' in compact or (allow_welcome and all(
        label in compact for label in ('startopencode', 'newterminal', 'connecttowi-fi')))


def check_graphical_keyboard(vm, name, *, allow_welcome=False):
    """Prove the installed graphical surface accepts input and renders output."""
    started = time.monotonic()
    vm.command('pgrep -x labwc >/dev/null && pgrep -x foot >/dev/null')
    # A running renderer or the daemon's discovery endpoint can precede the
    # first graphical frame. The saved workspace must actually be visible
    # before sending its shortcut; otherwise early keystrokes can be lost.
    deadline = time.monotonic() + 30
    dismissed = False
    while time.monotonic() < deadline:
        vm.screenshot(name + '-ready')
        visible = subprocess.check_output(
            ['tesseract', str(vm.folder / (name + '-ready.png')), 'stdout', '--psm', '11'],
            text=True, stderr=subprocess.DEVNULL, timeout=10)
        if workspace_text_visible(visible, allow_welcome=allow_welcome):
            break
        # Offline for 10 s, a signed-in hn brings the Wi-Fi form forward as a tab (os_welcome
        # offer_wifi). Escape closes it, as a person who means to work offline does, once.
        if not dismissed and 'connecttowi-fi' in re.sub(r'\s+', '', visible).lower():
            vm.screenshot(name + '-offline-wifi-offered')
            vm.keys('esc')
            dismissed = True
            deadline = max(deadline, time.monotonic() + 15)
        time.sleep(.25)
    else:
        raise RuntimeError('The graphical workspace did not render before keyboard input.')
    previous, _ = vm.command('hn display-message -p "HN_PREVIOUS_PANE=#{pane_id}"')
    previous_pane = re.search(r'HN_PREVIOUS_PANE=(%\d+)', previous)
    if not previous_pane:
        raise RuntimeError('Keyboard probe could not identify the original pane.')
    vm.keys('ctrl', 'b')
    vm.keys('shift', 't')
    # New terminal is asynchronous. Require both a newly focused pane and its
    # empty shell prompt before typing, rather than sleeping for a guessed time.
    vm.command('for n in $(seq 1 60); do '
               'current=$(hn display-message -p "#{pane_id}"); '
               'if test "$current" != ' + shlex.quote(previous_pane[1]) +
               ' && hn capture-pane -p | grep -Eq ' + shlex.quote(r'^\[me@harness [^]]*\]\$$') +
               '; then exit 0; fi; sleep .25; done; exit 1', timeout=25)
    marker = 'keyboard-' + name + '-ready'
    vm.type_probe('echo ' + marker)
    vm.keys('ret')
    output, _ = vm.command(
        'for n in $(seq 1 60); do hn capture-pane -p 2>/dev/null | '
        'grep -Fx ' + shlex.quote(marker) +
        ' >/dev/null && break; sleep 0.25; done; '
        'hn capture-pane -p | grep -Fx ' + shlex.quote(marker) +
        '; hn display-message -p "HN_KEYBOARD_PANE=#{pane_id}"; hn capture-pane -p')
    pane = re.search(r'HN_KEYBOARD_PANE=(%\d+)', output)
    if not pane:
        raise RuntimeError('Keyboard probe did not identify its actual hn pane.')
    # Require the standalone response, not merely the echoed command text.
    if not re.search(r'(?m)^' + re.escape(marker) + r'\r?$', output):
        raise RuntimeError('Graphical keyboard input did not produce shell output.')
    confirmed = time.monotonic()
    (vm.folder / (name + '-keyboard.txt')).write_text(output)
    vm.screenshot(name + '-keyboard')
    vm.keys('ctrl', 'd')
    vm.command('for n in $(seq 1 60); do '
               'if ! hn list-panes -a -F "#{pane_id}" | grep -Fx ' +
               shlex.quote(pane.group(1)) + '; then exit 0; fi; '
               'sleep 0.25; done; exit 1')
    vm.command('systemctl --user is-active --quiet hn-screen && pgrep -x "hn|harness-tui" >/dev/null')
    time.sleep(0.25)  # Let the frame following the pane-close event paint.
    return {'confirmed_seconds_since_boot': round(confirmed - vm.started, 3),
            'probe_seconds_including_automated_typing': round(confirmed - started, 3)}


def check_console_fallback(vm, user, folder):
    """Break graphics in the live overlay, then type through hn on a real VT."""
    # The payload and session launcher remain unchanged. An invalid wlroots
    # backend forces the compositor to fail through its normal startup path.
    override = '/etc/profile.d/00-hn-test-broken-graphics.sh'
    vm.command('printf %s ' + shlex.quote('export WLR_BACKENDS=hn-test-missing\n') +
               ' > ' + override + '; systemctl restart [email protected]')
    try:
        vm.command('for n in $(seq 1 60); do '
                   'for p in $(pgrep -u 1000 -x "hn|harness-tui"); do '
                   'if test "$(readlink /proc/$p/fd/0)" = /dev/tty1; then '
                   'printf "HN_CONSOLE_PID=%s\\n" "$p"; exit 0; fi; done; '
                   'sleep 1; done; exit 1', timeout=75)
        vm.command('! pgrep -u 1000 -x labwc && ! pgrep -u 1000 -x foot')
        vm.command(user('/usr/lib/harness-os/wait-runtime'), timeout=160)
        # A process attached to tty1 is not yet its command endpoint. During
        # takeover the named socket can still belong to the departing renderer.
        # Wait for a reply from this VT's actual client before creating a pane.
        vm.command(user('sh -c ' + shlex.quote(
            'for n in $(seq 1 60); do '
            'p=$(hn display-message -p "#{client_pid}") || p=; '
            'case "$p" in ""|*[!0-9]*) ;; *) '
            'if test "$(readlink /proc/$p/fd/0)" = /dev/tty1; then '
            'printf "HN_CONSOLE_READY=%s\\n" "$p"; exit 0; fi ;; esac; '
            'sleep .25; done; exit 1')), timeout=75)
        vm.command('kill -0 "$(cat /tmp/hn-survivor.pid)"')
        probe = ('printf "Console input ready\\n"; touch /tmp/hn-console-input-ready; '
                 'read -r answer; test "$answer" = ready && '
                 'touch /tmp/hn-console-input-passed; exec sleep 1800')
        vm.command(user('hn new-window -n console-input ' + shlex.quote(probe)))
        vm.command('for n in $(seq 1 15); do test -e /tmp/hn-console-input-ready && '
                   'exit 0; sleep 1; done; exit 1', timeout=20)
        for key in ['r', 'e', 'a', 'd', 'y', 'ret']:
            vm.keys(key)
        vm.command('for n in $(seq 1 15); do test -e /tmp/hn-console-input-passed && '
                   'exit 0; sleep 1; done; exit 1', timeout=20)
        vm.screenshot('03a-console-fallback')
    finally:
        output, _ = vm.command('cat /home/me/.local/state/harness-os/display.log; '
                               'ps -u 1000 -o pid,ppid,tty,comm; cat /dev/vcs1', check=False)
        (folder / 'console-fallback.log').write_text(output)
        output, _ = vm.command(user('sh -c ' + shlex.quote('hn hn-list-clients; hn show-messages')), check=False)
        (folder / 'console-client.log').write_text(output)
        vm.command('rm -f ' + override + '; systemctl restart [email protected]')
    vm.command(user("sh -c 'for n in $(seq 1 60); do systemctl --user is-active --quiet hn-screen && "
                    "pgrep -x labwc >/dev/null && pgrep -x foot >/dev/null && exit 0; "
                    "sleep 1; done; exit 1'"), timeout=75)
    vm.command('kill -0 "$(cat /tmp/hn-survivor.pid)"')
    vm.command(user('/usr/lib/harness-os/wait-runtime'), timeout=160)
    vm.screenshot('03b-graphics-restored')


def check_first_use(vm, user, folder, installed=False):
    """Operate the installed first-use page or a historical USB trial."""
    version, _ = vm.command(user('/usr/bin/opencode --version'))
    (folder / 'bundled-opencode-version.txt').write_text(version)
    defaults = json.loads(vm.read_file('/home/me/.config/opencode/opencode.json'))
    assert 'model' not in defaults, 'The image must start on upstream\'s own free model'
    assert not set(defaults) & {'provider', 'providers'}, 'The image must retain upstream provider defaults'
    assert defaults.get('update') == 'disable', 'The packaged agent must remain managed by system updates'
    if installed:
        vm.command('test ! -e /etc/harness-live && test "$(id -un)" = me')
        # 0.1.4 (#1276): the OS network form owns first setup, before hn and before any agent,
        # and neither Escape nor a workspace shortcut gets past it while offline.
        vm.form_shows('installed-network-first', 'Connect to Wi-Fi')
        vm.command('! pgrep -u 1000 -f "^/usr/lib/harness/hn$" && ! pgrep -u 1000 -x opencode')
        vm.keys('esc')
        vm.keys('meta_l', 't')
        vm.form_shows('installed-network-still-required', 'Connect to Wi-Fi')
        vm.command('! pgrep -u 1000 -x opencode')
        # Connected, hn opens on required sign-in; the account signs in, and only then does the
        # workspace (welcome, its terminals and the agent) begin.
        vm.monitor('set_link', name='hnnet', up=True)
        vm.sign_in('installed')
        vm.screenshot('installed-signed-in')
    else:
        vm.command('test "$(uname -n)" = harness && test "$(id -nu 1000)" = me && test -f /etc/harness-live')
        vm.command('nmcli networking off')
        vm.command(user('sh -c ' + shlex.quote('for n in $(seq 1 30); do hn capture-pane -p | grep -q "Connect to Wi-Fi to get started" && exit 0; sleep 1; done; exit 1')), timeout=40)
        vm.screenshot('01a-network-first')
        vm.command('! pgrep -u 1000 -x opencode')
        # Escape cannot leave a first-use dead end. Offline install is in this page.
        vm.keys('esc')
        vm.command(user('hn capture-pane -p') + ' | grep -q "Install without connecting"')
        vm.keys('i')
        vm.command(user('sh -c ' + shlex.quote('for n in $(seq 1 30); do hn capture-pane -p | grep -q "Repeat password" && exit 0; sleep 1; done; exit 1')), timeout=40)
        vm.screenshot('01a-offline-install')
        vm.keys('esc')
        # The OS shortcut needs neither a prefix nor Shift, and works offline.
        vm.keys('meta_l', 'i')
        vm.command(user('sh -c ' + shlex.quote('for n in $(seq 1 30); do hn capture-pane -p | grep -q "Repeat password" && exit 0; sleep 1; done; exit 1')), timeout=40)
        vm.screenshot('01b-direct-install-offline')
        vm.keys('esc')
        vm.command('sleep 1; test "$(lsblk -n -o TYPE /dev/vda | wc -l)" -eq 1')
        # A preflight error must remain visible in a command-owned pane until read.
        vm.command(user('hn new-window -n install-error ' + shlex.quote('sudo /usr/bin/harness install --source /run/hn-missing-image')))
        vm.command(user('sh -c ' + shlex.quote('for n in $(seq 1 15); do hn capture-pane -p | grep -q "Press Enter to return to Harness" && exit 0; sleep 1; done; exit 1')), timeout=20)
        installer_process = '^/usr/bin/python3 /usr/lib/harness-os/install[.]py --source /run/hn-missing-image$'
        vm.command('pgrep -f ' + shlex.quote(installer_process))
        vm.screenshot('01b-install-error')
        vm.keys('ret')
        vm.command('for n in $(seq 1 15); do ! pgrep -f ' + shlex.quote(installer_process) + ' && exit 0; sleep 1; done; exit 1', timeout=20)
        # New terminal is a shell immediately, without agent/project/task fields.
        vm.keys('meta_l', 't')
        vm.type_probe('echo terminal-ready')
        vm.keys('ret')
        vm.command(user('sh -c ' + shlex.quote('for n in $(seq 1 20); do hn capture-pane -p | grep -qx terminal-ready && exit 0; sleep 1; done; exit 1')), timeout=30)
        vm.screenshot('01c-direct-terminal')
        # Allow a full discovery cycle, then ensure a live-overlay shell or
        # installer has not been promoted to an agent by rounded file identities.
        vm.command('sleep 6')
        identity_probe = '''const fs = require('node:fs');
    for (const path of ['/usr/bin/opencode', '/usr/bin/bash', '/usr/bin/python3', '/usr/bin/nmtui', '/usr/bin/sudo']) {
        const numeric = fs.statSync(path), exact = fs.statSync(path, {bigint: true});
        console.log(JSON.stringify({path, numberKey: `${numeric.dev}:${numeric.ino}`, exactKey: `${exact.dev}:${exact.ino}`}));
    }
    const rows = JSON.parse(fs.readFileSync('/home/me/.harness/cli/data/registry.json', 'utf8'));
    for (const row of rows) console.log(JSON.stringify({agentId: row.agentId, engine: row.engine, active: row.active, processIdentity: row.processIdentity}));
    if (rows.some(row => row.engine !== 'terminal')) throw new Error('A plain shell or installer was misidentified as an agent');
    '''
        output, identity_status = vm.command(user('node -e ' + shlex.quote(identity_probe)), check=False)
        (folder / 'live-process-identities.txt').write_text(output)
        assert identity_status == 0, 'Live USB executable discovery must distinguish shells and installers from agents'
        output, _ = vm.command(user('hn display-message -p "HN_FIRST_TERMINAL=#{pane_id}"'))
        pane = re.search(r'HN_FIRST_TERMINAL=(%\d+)', output)
        assert pane, 'New terminal must identify its actual pane'
        vm.keys('ctrl', 'd')
        vm.command(user('sh -c ' + shlex.quote('for n in $(seq 1 30); do '
            'hn list-panes -a -F "#{pane_id}" | grep -Fx ' + shlex.quote(pane.group(1)) +
            ' >/dev/null || exit 0; sleep .25; done; exit 1')), timeout=15)
        # The OS opts into hn's existing shell-tab setting; test real prefix keys,
        # since invoking new-window through the CLI already opened a shell before.
        vm.keys('ctrl', 'b')
        vm.keys('c')
        time.sleep(1)
        vm.type_probe('echo prefix-tab-ready')
        vm.keys('ret')
        vm.command(user('sh -c ' + shlex.quote('for n in $(seq 1 20); do hn capture-pane -p | grep -qx prefix-tab-ready && exit 0; sleep .5; done; exit 1')), timeout=15)
        vm.screenshot('01c-prefix-terminal-tab')
        vm.keys('ctrl', 'd')
        time.sleep(.5)
    vm.monitor('set_link', name='hnnet', up=True)
    if not installed:
        vm.command('nmcli networking on')
    vm.command('for n in $(seq 1 30); do test "$(nmcli -t -f STATE general)" = connected && exit 0; sleep 1; done; exit 1', timeout=40)
    vm.command('for n in $(seq 1 90); do pgrep -u 1000 -x opencode >/dev/null && exit 0; sleep 1; done; exit 1', timeout=100)
    time.sleep(5)
    vm.screenshot('01d-bundled-opencode')
    vm.command(user('sh -c ' + shlex.quote('for n in $(seq 1 30); do test "$(hn list-panes -F "#{pane_id}" | wc -l)" -eq 3 && break; sleep .5; done; hn list-panes -F "#{pane_id}|#{pane_left}|#{pane_top}|#{pane_width}|#{pane_height}" > /tmp/hn-first-panes.txt')))
    # Serial shell-integration escapes precede the first output line. Read exact
    # file bytes so the first pane is not silently discarded by an anchored regex.
    pane_data = vm.read_file('/tmp/hn-first-panes.txt')
    (folder / 'first-use-panes.txt').write_bytes(pane_data)
    pane_rows = [line.split('|') for line in pane_data.decode().splitlines() if re.match(r'^%\d+\|', line)]
    assert len(pane_rows) == 3, 'First use must contain three real terminal panes'
    left = min(pane_rows, key=lambda row: int(row[1]))
    right = sorted((row for row in pane_rows if row != left), key=lambda row: int(row[2]))
    # Coordinates describe the terminal cells inside hn's one-cell pane border.
    assert int(left[1]) == 1 and right[0][1] == right[1][1] and int(right[1][2]) > int(right[0][2])
    assert abs(int(left[3]) - int(right[0][3])) <= 2, 'First-use columns must be balanced'
    assert abs(int(right[0][4]) - int(right[1][4])) <= 2, 'Right terminals must split their column equally'
    # hn's pane_pid describes remote panes; these local panes are backed by
    # tmux. Ask that actual backend for the agent PID, then inspect /proc.
    # The session's original shell path can lag discovery after exec.
    vm.command(user('tmux list-panes -a -F "#{pane_pid}|#{pane_current_command}"') + ' > /tmp/hn-first-processes.txt')
    process_data = vm.read_file('/tmp/hn-first-processes.txt')
    (folder / 'first-use-processes.txt').write_bytes(process_data)
    agent_pids = [line.split('|')[0] for line in process_data.decode().splitlines()
                  if re.fullmatch(r'\d+\|opencode', line)]
    assert len(agent_pids) == 1, 'The trial must have exactly one visible OpenCode process'
    vm.command('readlink /proc/' + agent_pids[0] + '/cwd > /tmp/hn-first-agent-path.txt')
    agent_path = vm.read_file('/tmp/hn-first-agent-path.txt').decode().strip()
    assert re.fullmatch(r'/home/me/projects/opencode-\d{4}-\d{2}-\d{2}-\d{2}-\d{2}(?:-\d+)*', agent_path), agent_path
    vm.command(user('hn display-message -p "#{E:status-right}"') + ' > /tmp/hn-first-footer.txt')
    footer = vm.read_file('/tmp/hn-first-footer.txt').decode()
    if installed:
        assert 'Install Harness' not in footer, footer
    else:
        assert 'Make Harness your OS.' in footer and '[ Install Harness ]' in footer, footer
        vm.command(user('hn show-options -gv status-style') + ' > /tmp/hn-first-footer-style.txt')
        assert vm.read_file('/tmp/hn-first-footer-style.txt').strip() == b'fg=black,bg=green'
    vm.command("! pgrep -f '[/]usr/lib/harness-os/network[.]py'")
    for index, row in enumerate(right):
        vm.command(user('hn select-pane -t ' + row[0]))
        vm.type_probe('echo starter-terminal-' + str(index))
        vm.keys('ret')
        vm.command(user('sh -c ' + shlex.quote('for n in $(seq 1 30); do hn capture-pane -p | grep -Fx starter-terminal-' + str(index) + ' && exit 0; sleep .2; done; exit 1')))
    vm.command(user('hn select-pane -t ' + left[0]))
    vm.screenshot('01d-three-real-panes')
    # runuser changes the account but retains the serial root shell's cwd.
    # OpenCode 2 resolves a project through its service; /root is inaccessible
    # to me. Inspect the same project as the visible agent instead.
    vm.command(user('sh -c ' + shlex.quote('cd "$HOME/projects" && /usr/bin/opencode debug config > /tmp/hn-opencode-config.json')), timeout=60)
    config_sources = vm.read_file('/tmp/hn-opencode-config.json')
    (folder / 'opencode-config-sources.json').write_bytes(config_sources)
    # V2 reports configuration sources, not the resolved V1 object. Its
    # documented global AGENTS.md carries instructions; the real conversation
    # below independently checks that the agent knows the Harness shortcuts.
    agent_config = json.loads(config_sources)
    assert isinstance(agent_config, list) and any(row.get('path') == '/home/me/.config/opencode' for row in agent_config), 'OpenCode did not discover its global configuration'
    instructions = vm.read_file('/home/me/.config/opencode/AGENTS.md')
    assert instructions == vm.read_file('/etc/skel/.config/opencode/AGENTS.md'), 'OpenCode global instructions differ from the packaged entry point'
    assert b'/usr/share/harness-os/guide.md' in instructions, 'OpenCode must discover the current packaged guide'
    vm.command('test ! -e /home/me/.config/opencode/plugin/launcher-register.js && test -s /home/me/.config/opencode/plugins/launcher-register/tui.js')
    screen, _ = vm.command(user('hn capture-pane -p'))
    (folder / 'bundled-opencode-screen.txt').write_text(screen)
    assert 'Plugin failed:' not in screen and 'plugin failed /plugins' not in screen, 'Bundled OpenCode must open without a plugin error'
    output, _ = vm.command(user('hn display-message -p "HN_FIRST_AGENT=#{pane_id}"'))
    agent_pane = re.search(r'HN_FIRST_AGENT=(%\d+)', output)
    assert agent_pane, 'The visible OpenCode must identify its actual pane'
    vm.keys('meta_l', 'n')
    time.sleep(1)
    vm.screenshot('01d-new-harness')
    vm.keys('esc')
    vm.keys('meta_l', 'm')
    time.sleep(1)
    vm.screenshot('01d-connect-computer')
    if installed:
        # Signed in already (required since #1276): the account page's third row is Sign out, so the
        # signed-out walk below would end this session. Leave the connection panel as it opened.
        vm.keys('esc')
        time.sleep(1)
    else:
        # Fresh USB users are signed out. The connection panel must lead to the
        # normal local sign-in flow, with a cancellable return to the trial.
        vm.type_probe('sign in')
        vm.keys('ret')
        # Sign in opens hn's own account page (#897): Google, Apple, the phone, or keep using locally.
        # The phone needs no browser in the VM. Its `harness login` is hn's child, and Esc cancels it.
        assert vm.screen_shows('01d-account', 'with your phone'), 'Sign in must open the account page'
        vm.keys('down')
        vm.keys('down')
        vm.keys('ret')
        login_process = '[/]usr/lib/harness/cli.mjs login'
        vm.command('for n in $(seq 1 20); do pgrep -u 1000 -f ' + shlex.quote(login_process) +
                   ' >/dev/null && exit 0; sleep 1; done; exit 1', timeout=30)
        time.sleep(2)
        vm.screenshot('01d-connect-sign-in')
        vm.keys('esc')
        vm.command('for n in $(seq 1 20); do ! pgrep -u 1000 -f ' + shlex.quote(login_process) +
                   ' >/dev/null && exit 0; sleep 1; done; exit 1', timeout=30)
        # Back to the work it was opened over, whether Esc closed the page or only stopped sign-in.
        if vm.screen_shows('01d-account-cancelled', 'harness account', timeout=2):
            vm.keys('esc')
        time.sleep(1)
    if not installed:
        # F10 reaches the dock without consuming the agent's ordinary Tab key.
        vm.keys('f10')
        vm.keys('ret')
        vm.command(user('sh -c ' + shlex.quote('for n in $(seq 1 30); do hn capture-pane -p | grep -q "Repeat password" && exit 0; sleep 1; done; exit 1')), timeout=40)
        vm.screenshot('01d-dock-install')
        vm.keys('esc')
        time.sleep(1)
        vm.click_word('01d-mouse-install', 'Install')
        vm.command(user('sh -c ' + shlex.quote('for n in $(seq 1 30); do hn capture-pane -p | grep -q "Repeat password" && exit 0; sleep 1; done; exit 1')), timeout=40)
        vm.command('test "$(lsblk -n -o TYPE /dev/vda | wc -l)" -eq 1')
        vm.keys('esc')
    project_name = 'first-project' if installed else 'usb-trial'
    trial_project = agent_path + '/' + project_name + '/index.html'
    if not MODEL_CALLS:
        # The visible agent takes keyboard input; the project a person would have it make is written
        # here instead, so the installation that follows still has trial work to preserve.
        draft = 'hello harness keyboard check'
        vm.type_probe(draft)
        _, typed_status = vm.command(user('sh -c ' + shlex.quote(
            'for n in $(seq 1 30); do hn capture-pane -p | grep -Fq ' + shlex.quote(draft) + ' && exit 0; '
            'sleep 1; done; exit 1')), timeout=40, check=False)
        vm.screenshot('01e-first-agent-input')
        assert typed_status == 0, 'The visible bundled agent must accept keyboard input'
        for _ in draft:
            vm.keys('backspace')
        vm.command(user('sh -c ' + shlex.quote(
            'mkdir -p ' + shlex.quote(str(Path(trial_project).parent)) +
            ' && printf "<h1>hello harness</h1>\\n" > ' + shlex.quote(trial_project))))
        (folder / 'trial-project.html').write_bytes(vm.read_file(trial_project))
        if installed:
            return trial_project
        vm.keys('ctrl', 'c')
        time.sleep(.3)
        vm.keys('ctrl', 'c')
        vm.command(user('sh -c ' + shlex.quote('for n in $(seq 1 60); do '
            'hn list-panes -a -F "#{pane_id}" | grep -Fx ' + shlex.quote(agent_pane.group(1)) +
            ' >/dev/null || exit 0; sleep .25; done; exit 1')), timeout=20)
        return trial_project
    # Exercise what a first-time user actually does after choosing Try: type
    # into the visible agent and receive its answer, without a CLI/API shortcut.
    vm.type_probe('what is six times seven reply with digits only')
    vm.keys('ret')
    _, interactive_status = vm.command(user('sh -c ' + shlex.quote(
        'for n in $(seq 1 120); do hn capture-pane -p > /tmp/hn-first-tui.txt; '
        "grep -Eq '^[^[:alnum:]]*42[^[:alnum:]]*$' /tmp/hn-first-tui.txt && exit 0; "
        'sleep 1; done; exit 1')), timeout=140, check=False)
    screen, _ = vm.command('cat /tmp/hn-first-tui.txt')
    (folder / 'first-opencode-interactive.txt').write_text(screen)
    vm.screenshot('01e-first-agent-reply')
    assert interactive_status == 0, 'The visible bundled agent must accept keyboard input and display its reply'
    # The real agent receives the local guide, knows both shortcut layers, and
    # creates work that the later offline installation must preserve.
    # Short on purpose: the check reads the agent's visible screen, and a long answer scrolls the
    # Super shortcuts off it (run 38380548451 answered correctly, only the Ctrl+b lines still shown).
    vm.type_probe('in three short lines what are the os shortcuts for a new harness and connecting a computer and does ctrl b still work')
    vm.keys('ret')
    _, guide_status = vm.command(user('sh -c ' + shlex.quote(
        'for n in $(seq 1 120); do hn capture-pane -p > /tmp/hn-first-guide.txt; '
        "grep -Eiq 'super[[:space:]]*\\+[[:space:]]*n' /tmp/hn-first-guide.txt && "
        "grep -Eiq 'super[[:space:]]*\\+[[:space:]]*m' /tmp/hn-first-guide.txt && exit 0; "
        'sleep 1; done; exit 1')), timeout=140, check=False)
    (folder / 'first-agent-guide.txt').write_bytes(vm.read_file('/tmp/hn-first-guide.txt'))
    vm.screenshot('01f-agent-explains-harness')
    assert guide_status == 0, 'Bundled OpenCode must explain the actual OS shortcuts from its local guide'
    # Build inside the actual per-agent project, as a person does. A sibling
    # directory would instead exercise OpenCode's external-directory permission.
    vm.type_probe('create the folder ' + project_name + ' in this project and an index html page inside it saying hello harness')
    vm.keys('ret')
    vm.command('for n in $(seq 1 120); do test -s ' + shlex.quote(trial_project) + ' && '
               'grep -iq "hello harness" ' + shlex.quote(trial_project) + ' && exit 0; sleep 1; done; exit 1', timeout=140)
    (folder / 'trial-project.html').write_bytes(vm.read_file(trial_project))
    vm.screenshot('01g-agent-created-trial-project')
    if not installed:
        # Test the agent-led install entry too. It may open the form; it must never
        # choose a disk or perform the destructive action from the conversation.
        vm.type_probe('open the harness installer for me but do not choose a disk or start installation')
        vm.keys('ret')
        vm.command(user('sh -c ' + shlex.quote('for n in $(seq 1 90); do hn capture-pane -p | grep -q "Repeat password" && exit 0; sleep 1; done; exit 1')), timeout=100)
        vm.command('test "$(lsblk -n -o TYPE /dev/vda | wc -l)" -eq 1')
        vm.screenshot('01h-agent-opened-installer')
        vm.keys('esc')
    # No model flag/config, API key, account, or installer. Validate a real
    # upstream-default reply; preserve all events rather than just the exit code.
    prompt = 'What is six times seven? Reply with only the decimal number. Do not use tools.'
    command = 'cd "$HOME/projects" && timeout 120 /usr/bin/opencode run --format json ' + shlex.quote(prompt) + ' > /tmp/hn-first-chat.jsonl 2>/tmp/hn-first-chat.err'
    _, status = vm.command(user('sh -c ' + shlex.quote(command)), timeout=140, check=False)
    raw = vm.read_file('/tmp/hn-first-chat.jsonl')
    errors = vm.read_file('/tmp/hn-first-chat.err')
    (folder / 'first-opencode-chat.jsonl').write_bytes(raw)
    (folder / 'first-opencode-chat.stderr.txt').write_bytes(errors)
    output = raw.decode('utf-8')
    events = []
    for line in output.splitlines():
        try:
            event = json.loads(line)
        except json.JSONDecodeError:
            continue
        if isinstance(event, dict):
            events.append(event)
    reply = ''.join(e.get('part', {}).get('text', '') for e in events if e.get('type') == 'text').strip()
    assert status == 0 and reply == '42', f'Bundled OpenCode default conversation failed: exit={status}, reply={reply!r}'
    if installed:
        return trial_project
    vm.keys('ctrl', 'c')
    time.sleep(.3)
    vm.keys('ctrl', 'c')
    # OpenCode 2 keeps `opencode serve --service` alive after its TUI exits.
    # The user's pane must close; the vendor's shared service is not a window.
    vm.command(user('sh -c ' + shlex.quote('for n in $(seq 1 60); do '
        'hn list-panes -a -F "#{pane_id}" | grep -Fx ' + shlex.quote(agent_pane.group(1)) +
        ' >/dev/null || exit 0; sleep .25; done; exit 1')), timeout=20)
    return trial_project


def install_interactively(vm, config, folder, direct=False):
    # Drive the actual graphical form. The sole installer addition is serial boot
    # output so the following installed boot remains observable to this fixture.
    bootstrap = f'''import importlib.util, traceback
from pathlib import Path
spec = importlib.util.spec_from_file_location('installer', '/usr/lib/harness-os/install.py')
installer = importlib.util.module_from_spec(spec)
spec.loader.exec_module(installer)
expected = {config!r}
installer.selected_disk(expected)
original_install = installer.install
def observed_install(actual, source, target, **kwargs):
    assert actual == {{k: v for k, v in expected.items() if k != 'serial_console'}}, 'Interactive installation choices differ from test input'
    actual['serial_console'] = True
    return original_install(actual, source, target, **kwargs)
installer.install = observed_install
original_run = installer.run
def observed_run(*args, **kwargs):
    if args == ('systemctl', 'poweroff'):
        Path('/run/hn-shutdown-requested').touch()
        return
    return original_run(*args, **kwargs)
installer.run = observed_run
status = 0
try:
    installer.main()
except BaseException:
    traceback.print_exc()
    status = 1
finally:
    Path('/run/hn-interactive-status').write_text(str(status))
if status:
    input('Installation test failed. Press Enter to close.')
'''
    encoded = base64.b64encode(bootstrap.encode()).decode()
    assert len(encoded) < 3000, 'Keep serial-console commands below the line discipline limit.'
    vm.command(f"printf %s {shlex.quote(encoded)} | base64 -d > /run/hn-interactive-test.py; chmod 600 /run/hn-interactive-test.py")
    user = lambda command: 'runuser -u me -- env XDG_RUNTIME_DIR=/run/user/1000 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus ' + command
    _, progress_status = vm.command("grep -q '^def install_with_progress(' /usr/lib/harness-os/install.py", check=False)
    if direct:
        command = '/usr/bin/foot --config=/usr/share/harness-os/foot.ini /usr/bin/sudo /usr/bin/python3 /run/hn-interactive-test.py --boot'
        override = '[Service]\nExecStart=\nExecStart=' + command + '\n'
        encoded = base64.b64encode(override.encode()).decode()
        vm.command('mkdir -p /run/user/1000/systemd/user/harness-install.service.d; printf %s ' + encoded + ' | base64 -d > /run/user/1000/systemd/user/harness-install.service.d/fixture.conf; chown -R me:me /run/user/1000/systemd')
        vm.command(user('systemctl --user daemon-reload'))
        vm.command(user('systemctl --user restart harness-install.service'))
    else:
        vm.command(user('sh -c ' + shlex.quote('hn new-window -P -F "#{pane_id}" -n Install '
                   + shlex.quote('sudo python3 /run/hn-interactive-test.py') + ' > /tmp/hn-install-pane')))
    transcript = []

    def wait_screen(pattern, timeout=30):
        if direct:
            from install_first import wait_installer_screen
            output = wait_installer_screen(vm, pattern, 'installer-current', timeout)
            transcript.append(output)
            return output
        command = ('for n in $(seq 1 ' + str(timeout * 2) + '); do '
                   'hn capture-pane -p -t "$(cat /tmp/hn-install-pane)" > /tmp/hn-install-screen || exit 1; '
                   'grep -Eq ' + shlex.quote(pattern) + ' /tmp/hn-install-screen && exit 0; '
                   'test ! -e /run/hn-interactive-status || exit 1; sleep .5; done; exit 1')
        _, status = vm.command(user('sh -c ' + shlex.quote(command)), timeout=timeout + 15, check=False)
        output, _ = vm.command('cat /tmp/hn-install-screen')
        transcript.append(output)
        assert status == 0, 'Graphical installer did not show ' + pattern + '; see installer-ui.log'
        return output

    try:
        wait_screen('Repeat password')
        vm.screenshot('install-01-form')
        # A first typed character must go straight into the masked password.
        vm.type_probe('x')
        entered = wait_screen('Repeat password')
        if not direct:
            assert '[*' in entered, 'Installer did not initially focus Password'
        vm.keys('ctrl', 'u')
        vm.keys('shift', 'tab')
        vm.keys('shift', 'tab')
        vm.keys('ret')
        wait_screen('Select disk')
        vm.screenshot('install-02-disks')
        vm.keys('esc')
        wait_screen('Repeat password')
        vm.keys('ret')
        wait_screen('Select disk')
        vm.keys('ret')
        wait_screen('Repeat password')
        vm.keys('tab')
        if not config['encrypt']:
            vm.keys('spc')
        vm.keys('tab')
        vm.type_probe(config['password'])
        vm.keys('ret')
        vm.type_probe(config['password'])
        vm.keys('ret')
        output = wait_screen('Repeat password')
        assert config['password'] not in output, 'Password fields must be masked'
        if not direct:
            assert '*' * len(config['password']) in output, 'Password fields must be masked'
        vm.screenshot('install-03-ready')
        # Finishing password entry only focuses Install. No disk has changed yet.
        vm.command('test "$(lsblk -n -o TYPE /dev/vda | wc -l)" -eq 1')
        install_started = time.monotonic()
        vm.keys('ret')
        if progress_status == 0:
            progress = wait_screen('Preparing the disk|Setting up encryption|Copying Harness|Setting up your account', timeout=30)
            assert 'Keep this computer powered on' not in progress and 'Installing Harness' not in progress
            vm.screenshot('install-04-progress')
        output = wait_screen('Harness is installed', timeout=900)
        install_seconds = round(time.monotonic() - install_started, 3)
        vm.screenshot('install-05-complete')
        if direct:
            assert 'Back to Harness' not in output
        vm.keys('ret' if direct else 'esc')
        vm.command('for n in $(seq 1 30); do test -s /run/hn-interactive-status && break; sleep .25; done; test "$(cat /run/hn-interactive-status)" = 0')
    finally:
        (folder / 'installer-ui.log').write_text('\n'.join(transcript))
        output, _ = vm.command('cat /var/log/harness-install.log 2>/dev/null', check=False)
        (folder / 'installer-commands.log').write_text(output)
        assert config['password'] not in output, 'Installation diagnostics must not contain the password'
    # This includes input delivery and success-screen observation, not form entry.
    return install_seconds


def check_installer_cleanup(vm, folder):
    """Exercise the actual packaged cleanup against a real temporary dm device."""
    encoded = base64.b64encode(Path(__file__).with_name('installer-cleanup-native.py').read_bytes()).decode()
    vm.command('install -m 600 /dev/null /run/hn-cleanup-native.b64')
    for offset in range(0, len(encoded), 3000):
        vm.command('printf %s ' + encoded[offset:offset + 3000] + ' >> /run/hn-cleanup-native.b64')
    vm.command('base64 -d /run/hn-cleanup-native.b64 > /run/hn-cleanup-native.py')
    try:
        output, _ = vm.command('python3 /run/hn-cleanup-native.py --installer /usr/lib/harness-os/install.py '
                               '--output /run/hn-cleanup-result', timeout=90)
        (folder / 'cleanup-native.log').write_text(output)
    finally:
        failure = sys.exception()
        for name in ['receipt.json', 'baseline-close.txt', 'transient-close.log', 'persistent-close.log', 'timeout-close.log', 'stalled-udev-close.log']:
            try:
                (folder / ('cleanup-' + name)).write_bytes(vm.read_file('/run/hn-cleanup-result/' + name, timeout=10))
            except Exception as error:
                if failure is None:
                    raise
                failure.add_note(f'Could not retain cleanup {name}: {error}')
    receipt = json.loads((folder / 'cleanup-receipt.json').read_text())
    assert receipt['status'] == 'passed'
    expected = hashlib.sha256(Path(__file__).resolve().parents[1].joinpath('installer.py').read_bytes()).hexdigest()
    assert receipt['installer_sha256'] == expected, 'Cleanup evidence must exercise this exact installer'
    return receipt


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('--iso', required=True, type=Path)
    parser.add_argument('--firmware', choices=['bios', 'uefi'], default='bios')
    parser.add_argument('--encrypt', action='store_true')
    parser.add_argument('--memory', type=int, default=2048)
    parser.add_argument('--live-transport', choices=['cdrom', 'usb'], default='cdrom')
    parser.add_argument('--expect-live-mode', choices=['media', 'ram'], help='Require a specific USB boot path; otherwise validate and record the observed path')
    parser.add_argument('--cpu', help='Optional QEMU CPU model, for an older instruction-set baseline')
    parser.add_argument('--output', type=Path)
    parser.add_argument('--agents', action='store_true', help='Install and start real agent executables after recovery; no accounts/API calls')
    parser.add_argument('--workloads', action='store_true', help='Opt in to real free-model project builds and browser acceptance after --agents')
    parser.add_argument('--dsh', action='store_true', help='Exercise three real DSH agents and shared viewers after --agents')
    parser.add_argument('--workload-seed', type=Path, help='Previous workload artifact: preserve its generated projects and rerun acceptance')
    parser.add_argument('--workload-repair-game', action='store_true', help='With a seed, explicitly ask the agent to repair game layout before rechecking')
    parser.add_argument('--live-only', action='store_true', help='Development probe: stop after the live-session checks, without installing')
    parser.add_argument('--model-calls', action='store_true', help='Also ask the bundled agent real questions (a free model) on first use')
    args = parser.parse_args()
    global MODEL_CALLS
    MODEL_CALLS = args.model_calls or args.workloads or args.dsh
    if args.expect_live_mode and args.live_transport != 'usb':
        parser.error('--expect-live-mode requires --live-transport usb')
    if args.workloads and not args.agents:
        parser.error('--workloads requires --agents')
    if args.dsh and not args.agents:
        parser.error('--dsh requires --agents')
    if args.workloads and args.dsh:
        parser.error('Run the two long model suites separately.')
    if args.workload_seed and not args.workloads:
        parser.error('--workload-seed requires --workloads')
    if args.workload_repair_game and not args.workload_seed:
        parser.error('--workload-repair-game requires --workload-seed')
    folder = (args.output or Path(__file__).resolve().parents[1] / 'test-results' / (args.firmware + ('-encrypted' if args.encrypt else '-plain'))).resolve()
    folder.mkdir(parents=True, exist_ok=False)
    result = {'firmware': args.firmware, 'encrypted': args.encrypt, 'memory_mib': args.memory,
              'live_transport': args.live_transport, 'cpu': args.cpu or 'native/default',
              'scope': 'live session only' if args.live_only else 'live session, offline installation and recovery',
              'started_at_unix': time.time(), 'checks': [], 'status': 'running'}
    manifest = json.loads((args.iso.parent / 'manifest.json').read_text())
    with args.iso.open('rb') as handle:
        digest = hashlib.file_digest(handle, 'sha256').hexdigest()
    if digest != manifest['iso']['sha256']:
        raise RuntimeError('ISO does not match its build manifest.')
    result['iso_sha256'] = digest
    result['image_source_commit'] = manifest['source_commit']
    result['test_source_commit'] = subprocess.check_output(['git', 'rev-parse', 'HEAD'], text=True).strip()
    result['test_script_sha256'] = hashlib.sha256(Path(__file__).read_bytes()).hexdigest()
    direct = 'install-first' in manifest.get('capabilities', [])
    vm = VM(folder, args.iso.resolve(), args.firmware, args.memory, args.live_transport, args.cpu)
    user = lambda cmd: 'runuser -u "$(id -nu 1000)" -- env XDG_RUNTIME_DIR=/run/user/1000 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus ' + cmd
    try:
        vm.start(live=True)
        vm.monitor('set_link', name='hnnet', up=False)
        vm.wait(r'root@[^\r\n]*[#] ')
        vm.shell_ready = True
        vm.command('stty -echo')
        if args.live_transport == 'usb':
            check_live_media(vm, result, args.expect_live_mode)
        vm.command('foot --check-config --config=/usr/share/harness-os/foot.ini')
        if direct:
            from install_first import check_usb_installer
            result['live_installer_ready_seconds'] = check_usb_installer(vm, user, folder)
            result['checks'].append('USB opens the installer directly with no trial, network page, hn runtime or agent')
        else:
            vm.command(user("sh -c 'for n in $(seq 1 90); do systemctl --user is-active --quiet hn-screen && pgrep -u 1000 -x \"hn|harness-tui\" >/dev/null && exit 0; sleep 1; done; systemctl --user --no-pager status hn-screen harness-daemon; exit 1'"), timeout=110)
            vm.command(user('/usr/lib/harness-os/wait-runtime'), timeout=160)
            result['live_hn_ready_seconds'] = round(time.monotonic() - vm.started, 3)
            result['checks'].append('Harness runtime reports discovery ready before hn startup is measured')
            output, _ = vm.command("printf 'HN_SCRATCH=%s\\n' \"$(df -B1 --output=size /run/archiso/cowspace | tail -1)\"")
            scratch_bytes = int(re.search(r'HN_SCRATCH=\s*(\d+)', output).group(1))
            if scratch_bytes < args.memory * 1024 ** 2 * 0.45:
                raise RuntimeError('Live writable space is too small for on-demand agent installation.')
            result['live_scratch_mib'] = round(scratch_bytes / 1024 ** 2, 1)
            vm.command('! pgrep -x chromium')
            result['checks'].append('Live hn ready; browser absent at boot')
            vm.command('systemctl start harness-keyring; pacman -Si git chromium >/dev/null', timeout=180)
            result['checks'].append('Dated package repositories are queryable before the first download')
            vm.command(user('systemd-run --user --quiet --wait --pipe --collect /bin/sh -c ' +
                            shlex.quote('printf hn-clipboard-check | wl-copy; test "$(wl-paste --no-newline)" = hn-clipboard-check')))
            result['checks'].append('Wayland clipboard round trip')
            vm.screenshot('01-live-hn')
            output, _ = vm.command(user('hn-os measure'))
            (folder / 'live-measurement.txt').write_text(output)
            trial_project = check_first_use(vm, user, folder)
            result['checks'].append('USB opens network setup; Super+i opens Install offline; Super+t opens a terminal without a setup form')
            result['checks'].append('Installer errors remain visible until acknowledged; exiting a direct terminal removes its pane')
            result['checks'].append('USB first agent conversation accepts physical keyboard input and displays the expected reply')
            result['checks'].append('Bundled OpenCode loads the local TUI guide, explains Super+n/m, creates a trial project, and opens the native installer on request')
            result['checks'].append('Super+n/m open the agent and machine controls; F10/Enter and an actual pointer click open the install dock action')
            result['checks'].append('Bundled OpenCode starts offline and its upstream-default clean-profile conversation returns the independently checked answer')
            vm.keys('meta_l', 'b')
            vm.command("for n in $(seq 1 45); do pgrep -x chromium >/dev/null && break; sleep 1; done; pgrep -x chromium", timeout=60)
            time.sleep(3)
            vm.screenshot('02-browser')
            vm.keys('meta_l', 'b')
            time.sleep(1)
            vm.screenshot('03-return-to-hn')
            result['checks'].append('Browser starts only on shortcut; toggle screenshots recorded')
            # hn has its own tmux-style settings; the underlying tmux server needs
            # its separate system configuration so a short-lived last pane cannot
            # restart the server and reuse a still-registered terminal identity.
            for index in range(3):
                vm.command(user('hn new-window -n quick-exit ' + shlex.quote(f'touch /tmp/hn-quick-exit-{index}')))
                vm.command(f'for n in $(seq 1 10); do test -e /tmp/hn-quick-exit-{index} && exit 0; sleep 1; done; exit 1', timeout=15)
            result['checks'].append('Closing the last terminal and immediately opening another works repeatedly')
            # A long-lived terminal process proves a screen restart does not kill the work.
            survivor = "echo $$ > /tmp/hn-survivor.pid; exec sleep 1800"
            vm.command(user("hn new-window -n persistence " + shlex.quote(survivor)))
            vm.command('for n in $(seq 1 15); do test -s /tmp/hn-survivor.pid && exit 0; sleep 1; done; exit 1', timeout=20)
            clipboard_probe = 'printf hn-pane-clipboard | wl-copy; test "$(wl-paste --no-newline)" = hn-pane-clipboard && touch /tmp/hn-pane-clipboard-passed'
            vm.command(user('hn new-window -n clipboard ' + shlex.quote(clipboard_probe)))
            vm.command('for n in $(seq 1 15); do test -e /tmp/hn-pane-clipboard-passed && exit 0; sleep 1; done; exit 1', timeout=20)
            result['checks'].append('An hn terminal pane inherits the working Wayland clipboard environment')
            vm.command('! ' + user('hn detach'))
            vm.command('! ' + user('hn suspend-client'))
            vm.command('kill -0 "$(cat /tmp/hn-survivor.pid)"')
            result['checks'].append('OS surface refuses detach and suspend while work stays alive')
            vm.command(user('systemctl --user restart hn-screen'))
            vm.command('sleep 3; kill -0 "$(cat /tmp/hn-survivor.pid)"')
            result['checks'].append('Terminal process survives screen restart')
            check_console_fallback(vm, user, folder)
            result['checks'].append('Graphics startup failure falls back to hn on tty1; physical-keyboard input reaches a terminal pane and existing work survives')
            result['checks'].append('Restoring graphics returns to the fullscreen hn service without losing the terminal process')
        if args.live_only:
            result['status'] = 'passed'
            return
        if args.encrypt:
            result['installer_cleanup'] = check_installer_cleanup(vm, folder)
            result['checks'].append('Packaged installer safely defers transient/persistent encrypted-device readers, recovers a close timeout and preserves the filesystem')
        config = dict(disk='/dev/vda', expected_serial='HN_OS_TEST', confirm_erase='/dev/vda',
                      username='me', hostname='harness', password='test-password-123',
                      encrypt=args.encrypt, serial_console=True)
        # Installation must work with the NIC down, using the ISO's immutable payload.
        if not direct:
            (folder / 'trial-project.html').write_bytes(vm.read_file(trial_project))
        vm.command(user('sh -c ' + shlex.quote('mkdir -p "$HOME/.config"; printf trial-only > "$HOME/.config/hn-trial-credential"')))
        vm.command('nmcli networking off')
        result['install_action_to_success_seconds'] = install_interactively(vm, config, folder, direct=direct)
        result['checks'].append('Keyboard disk selection, encryption checkbox, masked password entry and a single Install action work on the guest terminal')
        result['checks'].append('Offline installer completed on disposable disk')
        if config['encrypt']:
            # Retain costs, not keyslot salts/digests or the full encrypted header.
            script = ('import json,sys; d=json.load(sys.stdin); k=d["keyslots"]["0"]["kdf"]; '
                      'print(json.dumps({key:k[key] for key in ["type","time","memory","cpus"]}))')
            vm.command('cryptsetup luksDump --dump-json-metadata /dev/vda3 | python3 -c '
                       + shlex.quote(script) + ' > /tmp/hn-install-pbkdf.json')
            result['installed_pbkdf'] = json.loads(vm.read_file('/tmp/hn-install-pbkdf.json'))
            assert result['installed_pbkdf']['type'] == 'argon2id', 'Encryption must retain Argon2id'
            assert result['installed_pbkdf']['time'] >= 4, 'Encryption must retain benchmarked iterations'
        vm.command('sync')
        vm.stop()
        vm.start(live=False)
        if direct:
            vm.monitor('set_link', name='hnnet', up=False)
        unlock_delay = 100 if config['encrypt'] else 0
        vm.login_installed(config, unlock_delay=unlock_delay)
        # First-use network setup and model turns are not OS boot time.
        result['installed_hn_ready_seconds_including_test_login'] = round(time.monotonic() - vm.started, 3)
        if direct:
            trial_project = check_first_use(vm, lambda command: command, folder, installed=True)
            result['checks'].append('Installed Wi-Fi first use advances into three real panes and the bundled default agent answers keyboard input')
            result['checks'].append('Bundled OpenCode loads the local TUI guide, explains Super+n/m and creates a project on the installed disk')
            result['checks'].append("Bundled OpenCode's upstream-default clean-profile conversation returns the independently checked answer")
        vm.command('for n in $(seq 1 60); do test -f ~/.local/state/harness-os/onboarded && '
                   'test "$(hn list-panes -F "#{pane_id}" | wc -l)" -eq 3 && exit 0; sleep .5; done; exit 1', timeout=40)
        vm.screenshot('installed-first-workspace')
        vm.command('hn capture-pane -p | grep -qv "Enter.*Start OpenCode"; test -d ~/projects')
        vm.command('hn show-options -gv status-right > /tmp/hn-installed-status.txt')
        installed_bar = vm.read_file('/tmp/hn-installed-status.txt').decode()
        assert 'local_machine' in installed_bar and '%H:%M' in installed_bar and 'Install Harness' not in installed_bar, installed_bar
        vm.command("! pgrep -f '[/]usr/lib/harness-os/network[.]py'")
        result['checks'].append('Fresh installed first boot opens the same three real panes and records onboarding only once')
        result['checks'].append('Installed first use preserves hn’s full status bar and never reopens networking after the connection succeeds')
        if not direct:
            saved_trial = vm.read_file(trial_project)
            assert saved_trial == (folder / 'trial-project.html').read_bytes(), 'The installed home lost or changed the agent-created trial project'
            vm.command('test ! -e /home/me/.config/hn-trial-credential && test "$(stat -c %u ' + shlex.quote(trial_project) + ')" -eq 1000')
            transfer = json.loads(vm.read_file('/home/me/.local/state/harness-os/trial-projects.json'))
            relative_trial = str(Path(trial_project).relative_to('/home/me/projects'))
            assert transfer['entries'][relative_trial]['sha256'] == hashlib.sha256(saved_trial).hexdigest()
            result['checks'].append('Agent-created USB trial project survives offline installation and installed boot byte-for-byte')
        result['deliberate_unlock_delay_seconds'] = unlock_delay
        if unlock_delay:
            result['installed_unlock_prompt_seconds'] = vm.unlock_prompt_seconds
            result['checks'].append('Harness unlock screen renders, masks input, accepts a retry after a wrong password, and unlocks after the deliberate 100-second wait')
        result['installed_keyboard_readiness'] = check_graphical_keyboard(vm, 'installed')
        result['checks'].append('Installed graphical hn accepts physical-keyboard shell input, returns output and returns home after closing the pane')
        from connections_vm import exercise as check_connections
        result['connections'] = check_connections(vm)
        result['checks'].append('Installed Connections opens in the browser and shares local credentials between command processes without device registration')
        if config['encrypt']:
            installed = json.loads(vm.read_file('/var/lib/harness-os/install.json'))
            budget = installed['pbkdf_memory_limit_kib']
            assert 64 * 1024 <= result['installed_pbkdf']['memory'] <= budget <= 1024 * 1024
            result['pbkdf_memory_limit_kib'] = budget
            result['checks'].append('Encrypted installation retains benchmarked Argon2id within its RAM budget and unlocks after reboot')
        vm.command('test "$(id -un)" = ' + shlex.quote(config['username']) +
                   ' && test "$HOME" = ' + shlex.quote('/home/' + config['username']) +
                   ' && test "$(uname -n)" = ' + shlex.quote(config['hostname']))
        vm.command('test ! -e /etc/sudoers.d/10-live && test ! -e /etc/harness-live && ! sudo -n true')
        if 'broadcom-offline' in manifest.get('capabilities', []):
            vm.command('test ! -e /usr/share/harness-os/hardware/broadcom && '
                       'for name in gcc dkms broadcom-wl-dkms linux-lts-headers; '
                       'do if pacman -Q "$name"; then exit 1; fi; done')
            vm.command('python3 -c ' + shlex.quote('import json; assert json.load(open('
                       '"/var/lib/harness-os/hardware.json")) == {"drivers": [], "devices": []}'))
            result['checks'].append('Unrelated hardware receives no optional Wi-Fi packages and retains no USB driver cache')
        if 'nvidia-offline' in manifest.get('capabilities', []):
            vm.command('test ! -e /usr/share/harness-os/hardware/nvidia && '
                       'test ! -e /etc/mkinitcpio.conf.d/30-harness-nvidia.conf && '
                       '! pacman -Q nvidia-open-lts && ! pacman -Q nvidia-utils')
            result['checks'].append('Unrelated hardware receives no NVIDIA packages, boot configuration or USB GPU cache')
        vm.command('! pgrep -x chromium')
        vm.command('test "$(npm prefix -g)" = "$HOME/.local"')
        vm.command('findmnt -n -o FSTYPE / | grep -qx btrfs')
        vm.command('findmnt -n -o FSTYPE /boot | grep -qx vfat')
        if direct:
            from install_first import check_installed_controls
            check_installed_controls(vm, result, folder)
        output, _ = vm.command('cat /var/lib/harness-os/install.json; hn-os measure')
        (folder / 'installed-measurement.txt').write_text(output)
        vm.screenshot('04-installed-hn')
        result['checks'].append('Installed disk boots to hn with intended account permissions and no browser')
        # Let boot jobs settle before calling a sample "idle". Keep all three
        # measurements, including CPU, rather than selecting the smallest one.
        output, _ = vm.command('sleep 45; for n in 1 2 3; do hn-os measure; done', timeout=65)
        (folder / 'installed-idle-measurements.txt').write_text(output)
        vm.boot_diagnostics(config, 'installed')
        if config['encrypt'] and vm.acceleration == 'kvm':
            assert vm.unlock_prompt_seconds < 30, 'Unlock prompt exceeded 30 seconds; see boot-events.jsonl and installed-boot-journal.log'
            result['checks'].append('Encrypted unlock prompt appears within 30 seconds on the native x86 VM')
        # A disposable failure exercises actual root + boot restoration, including
        # an encrypted root in the UEFI row. The project's separate subvolume survives.
        vm.command('printf %s ' + shlex.quote(config['password'] + '\n') + ' | sudo -S -v')
        update_script = base64.b64encode(Path(__file__).with_name('updates.sh').read_bytes()).decode()
        vm.command(': > /tmp/hn-os-updates.b64')
        for offset in range(0, len(update_script), 2000):
            vm.command('printf %s ' + update_script[offset:offset + 2000] + ' >> /tmp/hn-os-updates.b64')
        vm.command('base64 -d /tmp/hn-os-updates.b64 > /tmp/hn-os-updates.sh')
        output, status = vm.command('sudo bash /tmp/hn-os-updates.sh', timeout=300, check=False)
        (folder / 'update-retry.log').write_text(output)
        assert status == 0, 'Full-update failure/retry check failed; see update-retry.log'
        result['checks'].append('Failed full update blocks package changes; successful retry upgrades a local fixture and retains the original recovery checkpoint')
        # A local package exercises the actual pacman PreTransaction hook while
        # networking is unavailable. Its checkpoint includes the active db.lck.
        package_script = '''set -eu
mkdir -p /tmp/hn-recovery-package/etc
printf 'pkgname = hn-os-recovery-probe\npkgver = 1-1\npkgdesc = Disposable VM rollback probe\narch = any\nsize = 7\n' > /tmp/hn-recovery-package/.PKGINFO
printf changed > /tmp/hn-recovery-package/etc/hn-os-recovery-probe
bsdtar --zstd -cf /tmp/hn-os-recovery-probe-1-1-any.pkg.tar.zst -C /tmp/hn-recovery-package .PKGINFO etc
pacman --noconfirm -U /tmp/hn-os-recovery-probe-1-1-any.pkg.tar.zst
'''
        encoded = base64.b64encode(package_script.encode()).decode()
        output, _ = vm.command('printf %s ' + encoded + ' | base64 -d | sudo bash', timeout=180)
        checkpoint = re.search(r'Checkpoint ([A-Za-z0-9_-]+)', output).group(1)
        vm.command('pacman -Q hn-os-recovery-probe && test -f /etc/hn-os-recovery-probe')
        result['checks'].append('A real offline package transaction creates its pre-update checkpoint')
        vm.command('printf keep-my-project > ~/projects/recovery-probe.txt')
        vm.command("sudo sh -c 'printf broken > /etc/hn-os-recovery-probe; chmod 000 /usr/lib/harness/harness-tui'")
        vm.command('sync')
        vm.stop()
        vm.start(live=True)
        vm.wait(r'root@[^\r\n]*[#] ')
        vm.shell_ready = True
        vm.command('stty -echo')
        root_device = '/dev/vda3'
        if config['encrypt']:
            vm.command('printf %s ' + shlex.quote(config['password']) + ' | cryptsetup open --key-file=- /dev/vda3 hn-recovery')
            root_device = '/dev/mapper/hn-recovery'
        vm.command('hn-os recover ' + root_device + ' ' + checkpoint, timeout=180)
        if config['encrypt']:
            vm.command('cryptsetup close hn-recovery')
        result['checks'].append('Offline checkpoint restored root and verified matching boot files')
        vm.stop()
        vm.start(live=False)
        vm.login_installed(config)
        vm.boot_diagnostics(config, 'recovered')
        if config['encrypt']:
            result['recovered_unlock_prompt_seconds'] = vm.unlock_prompt_seconds
            if vm.acceleration == 'kvm':
                assert vm.unlock_prompt_seconds < 30, 'Recovered unlock prompt exceeded 30 seconds; see recovered-boot-journal.log'
        vm.command('test ! -e /etc/hn-os-recovery-probe && test -x /usr/lib/harness/harness-tui && test "$(cat ~/projects/recovery-probe.txt)" = keep-my-project')
        vm.command('test ! -e /var/lib/pacman/db.lck && ! pacman -Q hn-os-recovery-probe')
        result['recovered_keyboard_readiness'] = check_graphical_keyboard(vm, 'recovered')
        result['checks'].append('Recovered graphical hn accepts physical-keyboard shell input, returns output and returns home after closing the pane')
        vm.screenshot('05-recovered-hn')
        result['checks'].append('Recovered disk boots to hn; system and package database reverted, stale lock cleared and project preserved')
        if args.agents:
            # A real development toolchain must install from the shipped package
            # indexes, compile a project, and serve its preview in another hn pane.
            vm.command('printf %s ' + shlex.quote(config['password'] + '\n') + ' | sudo -S pacman --noconfirm -S --needed gcc make', timeout=300)
            development = base64.b64encode(Path(__file__).with_name('development.sh').read_bytes()).decode()
            vm.command(f'printf %s {development} | base64 -d > /tmp/hn-os-development.sh')
            vm.command('hn new-window -n development ' + shlex.quote('bash /tmp/hn-os-development.sh > "$HOME/.local/state/harness-os/development.log" 2>&1'))
            output, _ = vm.command('for n in $(seq 1 60); do test -s ~/.local/state/harness-os/development-check/status && break; sleep 1; done; cat ~/.local/state/harness-os/development.log; test "$(cat ~/.local/state/harness-os/development-check/status)" = 0', timeout=75)
            (folder / 'development.log').write_text(output)
            vm.command('hn new-window -n local-preview ' + shlex.quote('node "$HOME/projects/os-validation/server.mjs"'))
            vm.command('curl --fail --retry 15 --retry-connrefused --retry-delay 1 http://127.0.0.1:18781 | grep -F "Local development works."', timeout=30)
            vm.command('hn-browser http://127.0.0.1:18781')
            time.sleep(5)
            vm.screenshot('06-local-development-preview')
            vm.keys('meta_l', 'ret')
            vm.command('pkill -x chromium', check=False)
            result['checks'].append('On-demand gcc/make installation, C compilation, Git diff and Node preview in an hn pane passed')
            script = Path(__file__).with_name('agents.sh').read_bytes()
            encoded = base64.b64encode(script).decode()
            vm.command(f'printf %s {shlex.quote(encoded)} | base64 -d > /tmp/hn-os-agents.sh')
            vm.command('hn new-window -n agent-compatibility ' + shlex.quote('bash /tmp/hn-os-agents.sh > "$HOME/.local/state/harness-os/agent-check.log" 2>&1'))
            output, _ = vm.command('for n in $(seq 1 600); do test -s ~/.local/state/harness-os/agent-check/status && break; sleep 1; done; cat ~/.local/state/harness-os/agent-check.log; test "$(cat ~/.local/state/harness-os/agent-check/status)" = 0', timeout=630)
            (folder / 'agent-installation.log').write_text(output)
            output, _ = vm.command('cat ~/.local/state/harness-os/agent-check/packages.json')
            (folder / 'agent-versions.txt').write_text(output)
            result['checks'].append('Claude Code, Codex and pi install on demand; bundled OpenCode and all four agents report versions inside an hn terminal')
        if args.workloads:
            # Public fictional tasks only, in the disposable guest. No host keys,
            # accounts or workspaces are made available to the model.
            package = io.BytesIO()
            with tarfile.open(fileobj=package, mode='w:gz') as archive:
                archive.add(Path(__file__).with_name('workloads'), arcname='workloads')
                if args.workload_seed:
                    seeds = list(args.workload_seed.rglob('projects/os-workloads'))
                    if len(seeds) != 1:
                        raise RuntimeError('Need exactly one prior generated project tree.')
                    for name in ['terminal-tool', 'website', 'game', 'fullstack']:
                        archive.add(seeds[0] / name, arcname='workloads/seed/' + name)
                    result['workload_project_source_run_id'] = os.environ.get('OS_WORKLOAD_SOURCE_RUN')
                    if args.workload_repair_game:
                        marker = tarfile.TarInfo('workloads/repair-game')
                        marker.size = 0
                        archive.addfile(marker, io.BytesIO())
                    result['workload_game_repair_requested'] = args.workload_repair_game
            encoded = base64.b64encode(package.getvalue()).decode()
            vm.command(': > /tmp/hn-workloads.b64')
            for offset in range(0, len(encoded), 2000):
                vm.command('printf %s ' + encoded[offset:offset + 2000] + ' >> /tmp/hn-workloads.b64')
            vm.command('base64 -d /tmp/hn-workloads.b64 | tar -xz -C /tmp; rm /tmp/hn-workloads.b64')
            vm.command('hn new-window -n programmer-workloads ' + shlex.quote('bash /tmp/workloads/run.sh > "$HOME/.local/state/harness-os/workloads.log" 2>&1'))
            output, _ = vm.command('for n in $(seq 1 3300); do test -s ~/.local/state/harness-os/workloads/status && break; sleep 1; done; cat ~/.local/state/harness-os/workloads.log', timeout=3320)
            (folder / 'workloads.log').write_text(output)
            # Keep both successful and failed model output for review; exclude
            # install caches and dependencies from the small source archive.
            vm.command('tar --exclude=node_modules --exclude=.git --exclude=__pycache__ -czf /tmp/hn-workloads-results.tgz -C "$HOME" projects/os-workloads .local/state/harness-os/workloads', timeout=60)
            output, _ = vm.command("printf 'HN_WORKLOAD_ARCHIVE='; base64 -w0 /tmp/hn-workloads-results.tgz; printf '\\n'", timeout=120)
            packed = base64.b64decode(re.search(r'HN_WORKLOAD_ARCHIVE=([A-Za-z0-9+/=]+)', output).group(1), validate=True)
            destination = folder / 'workloads'
            destination.mkdir()
            with tarfile.open(fileobj=io.BytesIO(packed), mode='r:gz') as archive:
                archive.extractall(destination, filter='data')
            (destination / '.local/state/harness-os/workloads').rename(destination / 'reports')
            vm.command('test "$(cat ~/.local/state/harness-os/workloads/status)" = 0')
            # Validate what the player sees, including canvas-rendered labels.
            # Tesseract is on the test host; no OCR package enters the guest/ISO.
            for size in ['1024x768', '1280x800']:
                frame = destination / 'reports' / f'game-{size}.png'
                visible = subprocess.check_output(['tesseract', str(frame), 'stdout', '--psm', '11'],
                    text=True, stderr=subprocess.DEVNULL, timeout=15)
                frame.with_suffix('.txt').write_text(visible)
                words = visible.lower()
                required = ['move', 'space', 'pause', 'restart', 'enter', 'start']
                missing = [word for word in required if not re.search(r'\b' + word + r'\b', words)]
                if missing:
                    raise RuntimeError(f'Game controls are not readable at {size}: {missing}; inspect {frame}')
            result['checks'].append('Free OpenCode built four projects; independent CLI, keyboard browser, game and persistent API checks passed')
        if args.dsh:
            package = io.BytesIO()
            with tarfile.open(fileobj=package, mode='w:gz') as archive:
                archive.add(Path(__file__).with_name('dsh'), arcname='dsh')
                store = Path(__file__).resolve().parents[2] / 'store'
                for component in ['viewers/web-viewer', 'viewers/game-viewer', 'examples/hello-world']:
                    archive.add(store / component, arcname='dsh/components/' + component)
            encoded = base64.b64encode(package.getvalue()).decode()
            vm.command(': > /tmp/hn-dsh.b64')
            for offset in range(0, len(encoded), 2000):
                vm.command('printf %s ' + encoded[offset:offset + 2000] + ' >> /tmp/hn-dsh.b64')
            vm.command('base64 -d /tmp/hn-dsh.b64 | tar -xz -C /tmp; rm /tmp/hn-dsh.b64')
            vm.command('hn new-window -n dsh-acceptance ' + shlex.quote('bash /tmp/dsh/run.sh > "$HOME/.local/state/harness-os/dsh-check.log" 2>&1'))
            output, _ = vm.command('for n in $(seq 1 2700); do test -s ~/.local/state/harness-os/dsh-check/status && break; sleep 1; done; cat ~/.local/state/harness-os/dsh-check.log', timeout=2720)
            (folder / 'dsh-check.log').write_text(output)
            vm.command('tar --exclude=node_modules --exclude=.git --exclude=__pycache__ -czf /tmp/hn-dsh-results.tgz -C "$HOME" projects/os-dsh .local/state/harness-os/dsh-check', timeout=60)
            output, _ = vm.command("printf 'HN_DSH_ARCHIVE='; base64 -w0 /tmp/hn-dsh-results.tgz; printf '\\n'", timeout=120)
            packed = base64.b64decode(re.search(r'HN_DSH_ARCHIVE=([A-Za-z0-9+/=]+)', output).group(1), validate=True)
            destination = folder / 'dsh'
            destination.mkdir()
            with tarfile.open(fileobj=io.BytesIO(packed), mode='r:gz') as archive:
                archive.extractall(destination, filter='data')
            (destination / '.local/state/harness-os/dsh-check').rename(destination / 'reports')
            vm.command('test "$(cat ~/.local/state/harness-os/dsh-check/status)" = 0')
            result['checks'].append('Three managed DSH agents, terminal output, shared Web Viewer reload and Game Viewer keyboard play/export passed')
        result['status'] = 'passed'
    except Exception as error:
        result['status'] = 'failed'
        result['error'] = str(error)
        if vm.shell_ready:
            try:
                diagnostics, _ = vm.command('journalctl -b --no-pager -n 350; systemctl --failed --no-pager; cat /home/*/.local/state/harness-os/display.log; ps -efww', timeout=20, check=False)
                (folder / 'guest-diagnostics.log').write_text(diagnostics)
            except Exception:
                pass
        try:
            vm.screenshot('failure')
        except Exception:
            pass
        raise
    finally:
        vm.stop()
        vm.control.cleanup()
        result['finished_at_unix'] = time.time()
        (folder / 'receipt.json').write_text(json.dumps(result, indent=2) + '\n')
        # Large disposable disks are never uploaded with the small evidence set.
        vm.disk.unlink(missing_ok=True)


if __name__ == '__main__':
    main()