List an install ISO's contents WITHOUT mounting it (pure ISO9660/Joliet read).

Use this before any VM work: confirms the image is readable, shows the layout (I386/ legacy vs SOURCES/ modern), and surfaces version markers. Run fingerprint_windows for the full version verdict.

Create a registered sandbox VM (qcow2 disk + config) for the reference ISO.

Networking is OFF by default — enabling it needs the user's OK (RULES.md). Call vm_boot next. workspace: path of the universal-os workspace this VM belongs to.

Boot the VM headless (boot='d' = CD-ROM first, 'c' = disk). Waits, then reports status.

Take a screenshot afterwards to see the display. Under pure TCG (no /dev/kvm) a full Windows install can take 30-90+ minutes — snapshot right after setup milestones.

Report one VM's status, or every registered VM when name is empty.

Capture the VM display to a PNG and return its path.

Use it after boot, after each setup screen, and after app tests — it is the AI's eyes on the guest. Read the PNG with vision to decide the next step.

Save an internal qcow2 snapshot of the running VM (e.g. 'clean-install', 'pre-app-test').

Snapshot before risky operations: installing apps, changing components, registry edits. Restore with vm_restore. Tag naming: kebab-case, one milestone per tag.

Restore the running VM to a previously saved snapshot (revert experiments safely).

Run a command inside the guest via the QEMU guest agent (qemu-ga must be installed).

args: single string, split on whitespace, quotes respected, backslashes kept as-is (Windows guest paths like 'C:\uos-tests\app.exe' survive). Windows guests: use 'cmd.exe' with args like '/c dir C:'. If the agent is missing the error explains how to install it (virtio-win ISO for Windows guests).

Copy a file from the host into the guest (via qemu-ga). Guest paths are Windows-style for Windows guests (e.g. C:\uos-tests\app.exe). Size cap: ~2GB practical.

Pull a file out of the guest (e.g. an .etl trace, a crash dump, a test log).

Swap the CD-ROM medium in the running VM (e.g. insert virtio-win to install the guest agent, then swap back to the reference ISO).

Send a key combo to the VM display: 'ret', 'esc', 'f8', 'ctrl-alt-delete', 'shift-f10', 'spc', 'tab', 'up'/'down'/'left'/'right', single letters/digits.

This drives text-mode installers BEFORE the guest agent exists (the part vm_exec cannot reach). One combo per call; screenshot after each to see the installer's reaction.

Shut the VM down (ACPI powerdown; falls back to quit after a timeout; force=true kills immediately). Registry metadata is kept — vm_boot can start it again.

Tail the VM's serial console log and show the qemu command line (debugging boot).

Identify the Windows version/build inside an install ISO (any version): layout markers, version resources of setup binaries, cversion.ini — with confidence.

Run this first. It decides the API-surface strategy (NT 5.x vs 6.x differ a lot). Version facts are interface facts — fine to journal; media contents stay out of the repo.

Analyze one PE binary (headers, sections, imports, exports, version resource).

Works on a file extracted INSIDE the VM sandbox or copied out with vm_get_file. Reports interface facts only — no disassembly, nothing shippable from the binary.

Extract ONE file from an install ISO to the host inspect dir — no mounting (pure ISO9660/Joliet read), e.g. member='/I386/NTOSKRNL.EX_' dest='~/inspect/xp/'.

Inspection only: keep extracted copies OUTSIDE the rebuilt-OS repo and keep only interface facts (RULES.md). Pair with analyze_pe / dump_api_surface.

Dump the interface surface of a directory of reference DLLs: export names, ordinals, imports, versions -> JSON + MD. This is the rebuild's target contract.

IMPORTANT (moderate guardrails): keep the inspected copies OUTSIDE the repo (e.g. ~/inspect/); only the generated surface JSON/MD goes into workspace/api/.

Write a concrete NT-syscall/API tracing plan for this VM (ETW/WPR steps, KDNET setup, static-surface fallback) and optionally kick off in-guest prep via qemu-ga.

Dynamic tracing needs in-guest tooling; this tool gives the exact commands and can fetch the results with vm_get_file afterwards.

Diff two API-surface dumps (reference vs rebuilt build): per-module export coverage, missing/extra exports. THE key progress metric for compatibility.

Create a rebuild workspace: src/{boot,drivers,subsystems,dll,shell,include,apps}, spec/, api/, tests/, reports/, third-party/, plus WORKSPACE.md journal.

Everything the AI builds lands here. target examples: windows-xp, windows-7, windows-any (version decided after fingerprint_windows).

Scaffold a ReactOS-style component: CMakeLists.txt, .spec export table, .c with DllMain, README, and an API test file.

exports: comma-separated export names from the API surface. Implementation always comes from behavioral specs written in spec/ — never from decompiled bodies.

Generate .spec + stub .c for one DLL straight from an API-surface dump (stubs return E_NOTIMPL; implement from behavioral specs, highest-import first).

Scaffold a small compat shim for one module: records per-quirk workarounds that unblock specific apps (quirks: semicolon-separated; for_apps: comma-separated).

Clone a reference implementation into third-party/ (read-only reference): reactos, wine, qemu, virtio-win, or any git URL. Clone repos as needed when a component needs proven patterns or test suites.

Return the concrete build plan for the workspace and check which host toolchains are present (cmake/ninja/mingw/RosBE). The AI runs the steps in src/.

Full app-compat cycle on the rebuilt (or reference) OS: copy the app in, run install_cmd then the app, capture exit/output, screenshot, record PASS/FAIL.

install_cmd/run_cmd: single command lines (argv[0] + args). Results go to tests/results/ and tests/RESULTS.md in the workspace. Use reference apps the user owns (RULES.md).

Aggregate all recorded app tests into a dated compatibility report (pass rate, failing labels, next-step guidance).

Append a dated entry to tests/REGRESSIONS.md (status: pass|regressed|fixed|wip).

Search field notes from previous rebuild attempts (routes, gotchas, versions). Search BEFORE starting — prior art saves the whole session. Covers the repo knowledge base, the wheel's seed notes, and $UOS_HOME/knowledge.

Report which knowledge-base roots resolve and where new notes go (repo checkout / packaged seed / UOS_HOME). Use when kb_search comes back empty and you need to know why.

Create a field-note template for this rebuild. Fill it while working, then kb_check before sharing. One note per os+component milestone.

Lint a field note: required sections + prohibited-content scan (no binary dumps, no media links). Run before opening a PR.

Regenerate knowledge/INDEX.md from all notes' front matter.

Check the host environment: qemu, qemu-img, git, cmake, ninja, mingw, /dev/kvm. Run once at session start; the result decides what the AI can do right now.

Validate an install ISO before use. Checks that the media exists and contains a recognizable Windows boot/install structure with no host-side mounting.

Set the VM's network flag: OFF by default; enabling needs the user's OK (RULES.md). Only user-mode NAT is implemented (bridge raises honestly). Applies at the next vm_boot - a running VM keeps its old network until shutdown + boot. Check with vm_status.

Summarize the rebuild workspace: required dirs (src/spec/api/tests/reports/ third-party), the WORKSPACE.md journal state and its last line, api/ surface count and src/ components. Use to decide the next phase of the loop.

Find (and with confirm=true delete) regenerable junk in the workspace: pycache, .pytest_cache, build/, dist/, .pyc/.pyo/*.tmp. Dry run by default - the response lists what would go. Sources, WORKSPACE.md, reports/ and third-party/ are never touched; VMs live under UOS_HOME and are unaffected. Use before archiving or sharing the workspace.