@tikoci/quickchr 0.3.0 → 0.4.0

package/DESIGN.md

@@ -19,7 +19,7 @@ Modules (src/lib/)      ← qemu, images, versions, network, state, ...
 ```
 
 - **CLI** — git-style subcommands + interactive wizard. Thin layer over the library.
-- **Library** — `QuickCHR` class with static methods: `start()`, `list()`, `get()`, `doctor()`. Returns `ChrInstance` handles with `stop()`, `remove()`, `rest()`, `monitor()`, etc.
+- **Library** — `QuickCHR` class with static methods: `start()`, `add()`, `list()`, `get()`, `doctor()`. Returns `ChrInstance` handles with `stop()`, `remove()`, `rest()`, `exec()`, `monitor()`, etc.
 - **Modules** — Pure functions for QEMU arg building, image download, port allocation, state persistence.
 
 ### Key Design Decisions
@@ -36,6 +36,16 @@ Modules (src/lib/)      ← qemu, images, versions, network, state, ...
 
 6. **Class-based API** — `QuickCHR` is a class with static methods for clean namespacing. `ChrInstance` is an interface implemented as a plain object with closures.
 
+7. **Running-only connection descriptors** — `ChrInstance.descriptor()`, `quickchr inspect`, and `quickchr env` are live connection handoff surfaces, not stale state readers. They intentionally fail with `MACHINE_STOPPED` when the VM is not running, because ports/auth/status are only safe to consume when the machine is active. Descriptor/env output includes auth material by design for subprocess handoff; callers must treat it as credential-bearing output.
+
+8. **Boot respawn-once on hardware accel** — When `QuickCHR.start()` boots a fresh machine in background mode and `waitForBoot` exhausts its budget under `kvm`/`hvf`, it stops the QEMU process, clears its `server=on` socket files, and respawns **once** before raising `BOOT_TIMEOUT` (see `start()` in `src/lib/quickchr.ts`, gated on `accel`). This targets an observed CI flake: on GitHub's nested-KVM runner a single boot among many occasionally never reaches REST while siblings boot in ~30-45s — a *wedged* process that a longer timeout would not rescue, only a fresh one. Gated to hardware accel because TCG boots are legitimately long and doubling buys nothing.
+
+   ⚠️ **Watch-item / scope caveat.** The root cause is **unconfirmed** — the respawn is a pragmatic mitigation that keeps CI green, not a proven diagnosis; the trigger could be something else (runner CPU-steal, a SLiRP stall, image-specific timing). Two deliberate limits to revisit if it recurs:
+   - **Not applied to `_launchExisting`** (the restart-existing-machine path) — that path also spawns + `waitForBoot`s but has never been observed to flake. Extend the same respawn there only with evidence.
+   - **Timeout factor left at 1.5×** (`accelTimeoutFactor`, `src/lib/platform.ts`) rather than inflated further — the respawn is the recovery mechanism, not a bigger ceiling.
+
+   How to tell it's firing: grep CI `qemu.log`/run logs for `respawning QEMU once`. A frequent occurrence, or a `BOOT_TIMEOUT` that *survives* the respawn (or appears on the `_launchExisting` path), is the signal to stop treating it as a flake and find the real cause. Tracked in `BACKLOG.md` (boot-respawn watch-item).
+
 ## Port Layout
 
 | Offset | Service    | Guest Port |
@@ -87,37 +97,41 @@ Modules (src/lib/)      ← qemu, images, versions, network, state, ...
 
 ## CI System
 
-**Workflow**: `.github/workflows/ci.yml`
+**Workflows**: `.github/workflows/{ci,verify-extended,publish}.yml`. Full artifact map and
+failure-diagnosis guide live in `.github/instructions/ci.instructions.md` — this section is
+the high-level rationale only.
 
-Three jobs — lint and unit-tests run in parallel; integration is gated on both:
+**`ci.yml`** — core quality gate on every push/PR to `main`:
 
+```text
+lint (ubuntu)  ──┐
+unit-tests (ubuntu, --coverage) ──┴→ integration-x86 (ubuntu) → windows-unit-tests (windows-latest)
 ```
-lint                    unit-tests                windows-unit-tests
-Biome + tsc --noEmit    bun test test/unit/       bun test test/unit/
-                        --coverage                (windows-latest, always)
-        ↘               ↙
-        integration (matrix)
-          linux/x86_64  (always)
-          linux/aarch64 (always)
-          macos/arm64   (workflow_dispatch: macos=true)
-          macos/x86_64  (workflow_dispatch: macos=true)
-```
 
-**Integration matrix**: Each runner boots a CHR matching its native arch.  `detectAccel()`
-selects KVM/HVF/TCG automatically — no per-runner overrides needed.
+`lint` and `unit-tests` run in parallel. `integration-x86` boots an x86 CHR (KVM if
+available, else TCG) and gates on both. `windows-unit-tests` runs last — if the core is
+broken, Windows runner minutes add no signal. Only x86 integration runs on every push;
+cross-arch and macOS are too slow/fragile for the per-push gate.
+
+**`verify-extended.yml`** — `workflow_dispatch` only. Independent jobs (no cross-`needs:`)
+for the platforms kept out of the per-push gate: linux/aarch64, macOS (arm64 + x86), and
+Windows. Dispatch inputs `arm64` / `macos` / `windows` select platforms; `test-filter`
+narrows to specific test files for fast iteration. Each runner boots a CHR matching its
+native arch — `detectAccel()` selects KVM/HVF/TCG automatically, no per-runner overrides.
+
+**`publish.yml`** — triggers on `v*` tags (or dispatch). Runs lint + unit + x86 integration +
+windows-unit before `npm publish` (`--tag next` for odd/pre-release minors, `--tag latest`
+for even/stable). See "Release Process" in `ci.instructions.md`.
 
-**Coverage**: `bun test test/unit/ --coverage` output is parsed and compared against
-thresholds (default 75% functions, 60% lines).  Failures emit `::warning::` annotations
-but do NOT block merges (`continue-on-error: true`).  Thresholds are overridable via
-dispatch inputs `min-funcs` / `min-lines`.
+**Coverage**: `unit-tests` parses `bun test --coverage` output and compares against thresholds
+(default 75% functions, 60% lines). Failures emit `::warning::` annotations but do NOT block
+merges (`continue-on-error: true`). Thresholds are overridable via dispatch inputs
+`min-funcs` / `min-lines`.
 
-**Artifacts** (details in `.github/instructions/ci.instructions.md`):
+**Artifacts**:
 - `coverage-report` — full per-file coverage table (14 days)
 - `integration-logs-{platform}` — bun test output + machine.json + qemu.log (7 days)
 
-**Publish workflow** (`.github/workflows/publish.yml`): triggers on `v*` tags;
-runs lint + typecheck + unit tests before npm publish.
-
 ## Design Principles
 
 ### Scope Boundary — QEMU Expert, Not Orchestrator
@@ -144,6 +158,23 @@ The `default-route-distance=2` ensures the shared route is backup — SLiRP ethe
 
 **TCG hazard:** SLiRP half-open connections (TCP connect succeeds, data never flows) burn the full per-probe HTTP timeout in `waitForBoot`. Under cross-arch TCG where TCP round-trips are slow, this compounds badly. Lab: `test/lab/slirp-hostfwd/`.
 
+#### Host-Side L2 Capture (MNDP, MAC-Telnet)
+
+A caller can receive the guest's raw Layer-2 frames — RouterOS MNDP (UDP/5678
+broadcast) being the first use case — without root or a native helper, using the
+TCP `socket` netdev: the host runs a TCP server, the CHR gets a `socket-connect`
+NIC, and QEMU streams every guest frame to the host length-prefixed (4-byte BE
+length + raw Ethernet). Loopback-only, cross-platform. Writing a frame back over
+the same connection injects L2 into the guest (the MAC-Telnet primitive). Recipe:
+`docs/mndp.md`; example: `examples/mndp/`.
+
+**Discovered constraint (2026-06-06):** the `socket-mcast` netdev — the documented
+multi-VM L2 path — is **broken on macOS**. QEMU's mcast socket sets only
+`SO_REUSEADDR`, while macOS/BSD need `SO_REUSEPORT` on every socket sharing a
+multicast port; two CHRs on one group don't discover each other and host capture
+gets nothing. mcast still works on Linux/CI. Prefer `socket-connect` for host
+capture on any platform. Evidence: `test/lab/mndp/REPORT.md`.
+
 ### Platform Priority
 
 macOS → Linux → Windows. Mac and Linux share most code paths with minor `#ifdef`-style branches. Windows is tracked but lower priority — larger RouterOS admin audience there, but fewer recipes and harder to test. Windows CI runner planned after the existing macOS/Linux matrix is stable.

package/README.md

@@ -93,6 +93,11 @@ quickchr list
 # Detailed status for one instance
 quickchr status my-chr
 
+# Stable connection descriptor/env for a running instance
+quickchr inspect my-chr
+quickchr env my-chr
+quickchr env my-chr --json
+
 # Stop an instance
 quickchr stop my-chr
 
@@ -157,6 +162,7 @@ quickchr doctor
 | `--boot-disk-format <f>` | Boot disk format: qcow2\|raw | qcow2 |
 | `--boot-size <size>` | Resize boot disk (e.g., 512M, 2G). Requires `qemu-img`. | |
 | `--add-disk <size>` | Attach an extra blank qcow2 disk. Repeatable. Requires `qemu-img`. | |
+| `--forward <spec>` | Add or pin a QEMU SLiRP hostfwd mapping. Repeatable. | |
 | `--bg` / `--background` | Run in background (default) | true |
 | `--fg` / `--foreground` | Run in foreground — serial console on stdio | |
 | `--add-package <pkg>` | Extra package to install (repeatable) | |
@@ -261,6 +267,39 @@ Each instance gets a block of 10 ports. With the default base of 9100, the first
 
 The second instance gets 9110–9119, and so on.
 
+### Custom Port Forwards and Fixed WinBox
+
+Use `--forward <spec>` on `add` or create-and-start `start` commands to add
+extra QEMU SLiRP `hostfwd` mappings. The shorthand uses the built-in service
+registry when it knows the guest port:
+
+```bash
+quickchr add lab --forward smb                  # auto host port → guest 445/tcp
+quickchr add dude-lab --forward winbox:8291     # host 8291 → guest WinBox 8291/tcp
+quickchr add app-lab --forward myapp:9200:7777/udp
+```
+
+Reusing a built-in service name such as `winbox` pins/replaces that service's
+host port for the machine. Existing machines keep the mapping stored in
+`machine.json`; recreate the machine to change fixed service ports cleanly.
+
+### Machine Descriptors and Subprocess Environments
+
+`quickchr inspect <name> [--json]` emits a stable JSON descriptor for a
+**running** machine: status, ports, URLs, auth, env vars, and the machine
+directory. `--json` is accepted for parity; inspect output is always JSON.
+
+`quickchr env <name> [--json]` prints the same subprocess environment as
+`ChrInstance.subprocessEnv()`: shell `KEY=value` lines by default, or a JSON
+map with `--json`.
+
+> **Credential caveat:** descriptor/env output includes connection secrets
+> (`auth.password`, `auth.basic`, `auth.header`, `QUICKCHR_AUTH`, `BASICAUTH`)
+> so child processes can connect without reading quickchr's secret store. Treat
+> it like a password: do not commit it, paste it into public issues, or leave it
+> in CI logs. Stopped machines fail with `MACHINE_STOPPED`; start the machine
+> before requesting a descriptor or env map.
+
 ### Library Usage
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/quickchr",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU",
   "module": "src/index.ts",
   "main": "src/index.ts",
@@ -20,11 +20,12 @@
     "DESIGN.md"
   ],
   "scripts": {
-    "check": "bun run lint:biome && bun run lint:typecheck && bun run lint:markdown",
+    "check": "bun run lint:biome && bun run lint:typecheck && bun run lint:markdown && bun run lint:cspell",
     "lint": "biome check . && tsc --noEmit",
     "lint:biome": "biome check .",
     "lint:typecheck": "tsc --noEmit",
     "lint:markdown": "bunx markdownlint-cli2 '**/*.md'",
+    "lint:cspell": "cspell lint . --no-progress",
     "test": "bun test test/unit/",
     "test:examples": "bun test examples/",
     "test:integration": "QUICKCHR_INTEGRATION=1 bun test test/integration/",
@@ -36,6 +37,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
     "@types/bun": "^1.3.11",
+    "cspell": "^10.0.0",
     "markdownlint-cli2": "^0.21.0"
   },
   "dependencies": {

package/src/cli/index.ts

@@ -152,6 +152,12 @@ async function main() {
 			case "get":
 				await cmdGet(args.slice(1));
 				break;
+			case "inspect":
+				await cmdInspect(args.slice(1));
+				break;
+			case "env":
+				await cmdEnv(args.slice(1));
+				break;
 			case "license":
 				console.error("Note: 'quickchr license' is deprecated. Use 'quickchr set <name> --license' instead.");
 				await cmdLicense(args.slice(1));
@@ -1432,6 +1438,50 @@ async function cmdList(argv: string[] = []) {
 	console.log(table(headers, rows));
 }
 
+function shellQuoteEnv(value: string): string {
+	if (/^[A-Za-z0-9_./:@+-]*$/.test(value)) return value;
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+async function getRunningDescriptor(name: string) {
+	const { QuickCHR } = await import("../lib/quickchr.ts");
+	const { machineNotFoundMessage } = await import("./format.ts");
+	const instance = QuickCHR.get(name);
+	if (!instance) {
+		console.error(machineNotFoundMessage(name));
+		process.exit(1);
+	}
+	return instance.descriptor();
+}
+
+async function cmdInspect(argv: string[] = []) {
+	const { positional } = parseFlags(argv);
+	const name = positional[0];
+	if (!name) {
+		console.error("Usage: quickchr inspect <name> [--json]");
+		process.exit(1);
+	}
+	const descriptor = await getRunningDescriptor(name);
+	console.log(JSON.stringify(descriptor, null, 2));
+}
+
+async function cmdEnv(argv: string[] = []) {
+	const { flags, positional } = parseFlags(argv);
+	const name = positional[0];
+	const asJson = flagBool(flags, "json");
+	if (!name) {
+		console.error("Usage: quickchr env <name> [--json]");
+		process.exit(1);
+	}
+	const descriptor = await getRunningDescriptor(name);
+	if (asJson) {
+		console.log(JSON.stringify(descriptor.env, null, 2));
+		return;
+	}
+	for (const [key, value] of Object.entries(descriptor.env)) {
+		console.log(`${key}=${shellQuoteEnv(value)}`);
+	}
+}
 
 async function cmdGet(argv: string[]) {
 	const { flags, positional } = parseFlags(argv);
@@ -2457,6 +2507,8 @@ Commands:
   stop [<name>|--all]     Stop instance(s) — print list if no name
   list [<name>] [--json]  List all instances, or detail for one
   status                  Alias for list
+  inspect <name> [--json] Print running machine descriptor as JSON
+  env <name> [--json]     Print subprocess environment for a running machine
   console <name>          Attach to serial console of a running instance
   exec <name> <command>   Run a RouterOS CLI command on a running instance
   remove [<name>|--all]   Remove instance(s) and disk
@@ -2637,6 +2689,23 @@ List all CHR instances or show detailed info for one.
 
 'quickchr status' is an alias for this command.`);
 			break;
+		case "inspect":
+			console.log(`quickchr inspect <name> [--json]
+
+Print a stable JSON descriptor for a running CHR instance: ports, URLs,
+credentials, status, and subprocess env vars.
+
+  <name>      Name of a running CHR instance.
+  --json      Accepted for parity; output is always JSON.`);
+			break;
+		case "env":
+			console.log(`quickchr env <name> [--json]
+
+Print environment variables for subprocesses that connect to a running CHR.
+
+  <name>      Name of a running CHR instance.
+  --json      Output the env map as JSON instead of KEY=value lines.`);
+			break;
 		case "doctor":
 			console.log(`quickchr doctor
 

package/src/index.ts

@@ -17,7 +17,7 @@
  * - {@link QuickCHR} — Main class with static methods: `start()`, `add()`, `list()`, `get()`, `doctor()`
  * - {@link ChrInstance} — Runtime handle returned by `start()`: `stop()`, `remove()`, `rest()`, `exec()`, `upload()`, `download()`, `snapshot`, etc.
  * - {@link StartOptions} — All options for creating/starting a CHR instance
- * - {@link QuickCHRError} — Typed errors with codes like `MISSING_QEMU`, `TIMEOUT`, `EXEC_FAILED`
+ * - {@link QuickCHRError} — Typed errors with codes like `MISSING_QEMU`, `BOOT_TIMEOUT`, `EXEC_FAILED` (full list: {@link ErrorCode})
  *
  * @packageDocumentation
  */
@@ -44,6 +44,7 @@ export type {
 	LicenseLevel,
 	LicenseOptions,
 	MachineConfig,
+	MachineDescriptor,
 	MachineState,
 	NetworkConfig,
 	NetworkMode,

package/src/lib/auth.ts

@@ -8,7 +8,7 @@
  */
 
 import type { MachineState } from "./types.ts";
-import { getInstanceCredentials } from "./credentials.ts";
+import { getInstanceCredentials, STORED_IN_SECRETS_PASSWORD } from "./credentials.ts";
 
 export interface ResolvedAuth {
 	/** HTTP Basic Authorization header value. */
@@ -48,9 +48,16 @@ export function resolveAuth(
 		};
 	}
 
-	// state.user is the canonical provisioned user written to machine.json.
-	// Check this first — no I/O, no keychain, no blocking.
 	if (state.user) {
+		if (state.user.password === STORED_IN_SECRETS_PASSWORD) {
+			const stored = getInstanceCredentials(state.name);
+			if (stored) {
+				return {
+					header: `Basic ${btoa(`${stored.user}:${stored.password}`)}`,
+					user: stored.user,
+				};
+			}
+		}
 		return {
 			header: `Basic ${btoa(`${state.user.name}:${state.user.password}`)}`,
 			user: state.user.name,
@@ -82,7 +89,13 @@ export function resolveCreds(
 	password?: string,
 ): ResolvedCreds {
 	if (user !== undefined) return { user, password: password ?? "" };
-	if (state.user) return { user: state.user.name, password: state.user.password };
+	if (state.user) {
+		if (state.user.password === STORED_IN_SECRETS_PASSWORD) {
+			const stored = getInstanceCredentials(state.name);
+			if (stored) return { user: stored.user, password: stored.password };
+		}
+		return { user: state.user.name, password: state.user.password };
+	}
 	const stored = getInstanceCredentials(state.name);
 	if (stored) return { user: stored.user, password: stored.password };
 	return { user: "admin", password: "" };

package/src/lib/channels.ts

@@ -1,7 +1,9 @@
 /**
  * Communication channels — QEMU monitor, serial console, QGA (QEMU Guest Agent).
  *
- * Uses Unix domain sockets stored in the machine directory.
+ * Uses Unix domain sockets stored in the machine directory on POSIX. On Windows,
+ * launched machines use TCP localhost endpoints derived from portBase; named pipes
+ * remain only as the no-portBase fallback path.
  * QGA protocol implementation lives in qga.ts — this module provides
  * the high-level qgaCommand() wrapper with arch guards and path resolution.
  */

package/src/lib/completions.ts

@@ -328,7 +328,7 @@ _quickchr() {
         cword=${D}COMP_CWORD
     }
 
-    local commands="add start stop list ls status remove rm clean console exec qga license disk snapshot snap networks net doctor setup completions version help"
+    local commands="add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net doctor setup completions version help"
 
     if [[ ${D}cword -eq 1 ]]; then
         COMPREPLY=( $(compgen -W "${D}commands" -- "${D}cur") )
@@ -337,7 +337,7 @@ _quickchr() {
 
     local cmd="${D}{words[1]}"
     case "${D}cmd" in
-        start|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status)
+        start|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status|inspect|env)
             local machines
             machines=$(quickchr completions --machines 2>/dev/null)
             COMPREPLY=( $(compgen -W "${D}machines" -- "${D}cur") )
@@ -387,6 +387,8 @@ _quickchr() {
                 'list:List all instances'
                 'ls:List all instances (alias)'
                 'status:Detailed status'
+                'inspect:Print running machine descriptor'
+                'env:Print subprocess environment'
                 'remove:Remove instance(s) and disk'
                 'rm:Remove instance(s) (alias)'
                 'clean:Reset instance disk to fresh image'
@@ -410,7 +412,7 @@ _quickchr() {
         args)
             local cmd="${D}{words[2]}"
             case ${D}cmd in
-                start|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status)
+                start|remove|rm|clean|console|exec|qga|license|disk|snapshot|snap|status|inspect|env)
                     local machines
                     machines=(${D}{(f)"${D}(quickchr completions --machines 2>/dev/null)"})
                     _describe 'machine' machines
@@ -432,7 +434,7 @@ _quickchr() {
                     _describe 'option' opts
                     ;;
                 help)
-                    local commands=(add start stop list status remove clean console exec qga license disk snapshot networks doctor setup completions version)
+                    local commands=(add start stop list status inspect env remove clean console exec qga license disk snapshot networks doctor setup completions version)
                     _describe 'command' commands
                     ;;
             esac
@@ -448,7 +450,7 @@ function generateFishCompletion(): string {
 	return `# quickchr fish completion
 # Generated by quickchr. Fish auto-loads files from ~/.config/fish/completions/.
 
-set -l quickchr_commands add start stop list ls status remove rm clean console exec qga license disk snapshot snap networks net doctor setup completions version help
+set -l quickchr_commands add start stop list ls status inspect env remove rm clean console exec qga license disk snapshot snap networks net doctor setup completions version help
 
 # Disable file completions globally for quickchr
 complete -c quickchr -f
@@ -464,6 +466,10 @@ complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "list ls"     -d "List all instances"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "status"      -d "Detailed status"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
+    -a "inspect"     -d "Print running machine descriptor"
+complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
+    -a "env"         -d "Print subprocess environment"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
     -a "remove rm"   -d "Remove instance(s) and disk"
 complete -c quickchr -n "not __fish_seen_subcommand_from $quickchr_commands" \\
@@ -499,7 +505,7 @@ complete -c quickchr -n "__fish_seen_subcommand_from stop" \\
     -d "machine"
 
 # Machine name completions for commands that take any machine
-complete -c quickchr -n "__fish_seen_subcommand_from start remove rm clean console exec qga license disk snapshot snap status" \\
+complete -c quickchr -n "__fish_seen_subcommand_from start remove rm clean console exec qga license disk snapshot snap status inspect env" \\
     -a "(quickchr completions --machines 2>/dev/null)" \\
     -d "machine"
 

package/src/lib/credentials.ts

@@ -26,6 +26,8 @@ export interface InstanceCredentials {
 	password: string;
 }
 
+export const STORED_IN_SECRETS_PASSWORD = "(stored in secrets)";
+
 const WEB_SERVICE = "com.quickchr.mikrotik-web";
 const INSTANCE_SERVICE = "com.quickchr.instance";
 

package/src/lib/qemu.ts

@@ -437,23 +437,23 @@ export async function stopQemu(pid: number): Promise<boolean> {
 	return true;
 }
 
-/** Stop a machine by name. */
-export async function stopMachineByName(_name: string, state: MachineState): Promise<boolean> {
-	if (!state.pid) return false;
-	const stopped = await stopQemu(state.pid);
-
-	// Clean up socket files
-	const machineDir = state.machineDir;
+/** Remove the listening unix-socket files QEMU binds (monitor/serial/qga).
+ *  A SIGKILLed QEMU leaves these behind; a respawn with `server=on` then fails
+ *  to bind ("Address already in use"). Call before re-spawning into the same dir. */
+export function cleanupQemuSockets(machineDir: string): void {
 	for (const sock of ["monitor.sock", "serial.sock", "qga.sock"]) {
 		const path = join(machineDir, sock);
 		try {
-			if (existsSync(path)) {
-				const { unlinkSync } = await import("node:fs");
-				unlinkSync(path);
-			}
+			if (existsSync(path)) unlinkSync(path);
 		} catch { /* ignore */ }
 	}
+}
 
+/** Stop a machine by name. */
+export async function stopMachineByName(_name: string, state: MachineState): Promise<boolean> {
+	if (!state.pid) return false;
+	const stopped = await stopQemu(state.pid);
+	cleanupQemuSockets(state.machineDir);
 	return stopped;
 }
 

package/src/lib/quickchr.ts

@@ -13,6 +13,7 @@ import type {
 	ExecResult,
 	LicenseInput,
 	LicenseLevel,
+	MachineDescriptor,
 	MachineState,
 	QgaCommand,
 	SnapshotInfo,
@@ -45,7 +46,7 @@ import {
 } from "./state.ts";
 import { ensureCachedImage, copyImageToMachine, listCachedImages } from "./images.ts";
 import { autoPruneIfOverCap } from "./cache.ts";
-import { buildQemuArgs, spawnQemu, stopQemu, waitForBoot, extractWrapper, type QemuLaunchConfig } from "./qemu.ts";
+import { buildQemuArgs, spawnQemu, stopQemu, cleanupQemuSockets, waitForBoot, extractWrapper, type QemuLaunchConfig } from "./qemu.ts";
 import { cleanDiskFiles, ensureConfiguredDisks, normalizeDiskOptions, parseSnapshotList, listSnapshots, formatDiskSize } from "./disk.ts";
 import { monitorCommand, serialStreams, qgaCommand, channelEndpoint } from "./channels.ts";
 import { installPackages, installAllPackages, downloadAndListPackages, downloadPackages, findPackageFile, uploadPackages } from "./packages.ts";
@@ -53,7 +54,7 @@ import { provision } from "./provision.ts";
 import { renewLicense, getLicenseInfo } from "./license.ts";
 import { resolveAuth, resolveCreds } from "./auth.ts";
 import { scpPush, scpPull } from "./scp.ts";
-import { deleteInstanceCredentials, credentialStorageLabel, getStoredCredentials } from "./credentials.ts";
+import { deleteInstanceCredentials, credentialStorageLabel, getStoredCredentials, STORED_IN_SECRETS_PASSWORD } from "./credentials.ts";
 import { restExecute } from "./exec.ts";
 import { qgaExec } from "./qga.ts";
 import { consoleExec } from "./console.ts";
@@ -224,6 +225,63 @@ async function resolveLicenseInput(input: LicenseInput): Promise<LicenseOptions
 function createInstance(state: MachineState): ChrInstance {
 	const ports = toChrPorts(state.ports);
 	const restUrl = `http://127.0.0.1:${ports.http}`;
+	const buildEnv = (): Record<string, string> => {
+		const creds = resolveCreds(state);
+		const rawCreds = `${creds.user}:${creds.password}`;
+		const restBase = `${restUrl}/rest`;
+		return {
+			QUICKCHR_NAME: state.name,
+			QUICKCHR_REST_URL: restUrl,
+			QUICKCHR_REST_BASE: restBase,
+			QUICKCHR_SSH_PORT: String(ports.ssh),
+			QUICKCHR_AUTH: rawCreds,
+			// Legacy compat keys used by restraml and similar consumers.
+			URLBASE: restBase,
+			BASICAUTH: rawCreds,
+		};
+	};
+	const buildDescriptor = (): MachineDescriptor => {
+		if (state.status !== "running") {
+			throw new QuickCHRError(
+				"MACHINE_STOPPED",
+				`Machine "${state.name}" must be running to inspect its connection environment (current status: ${state.status}).`,
+			);
+		}
+		const auth = resolveAuth(state);
+		const env = buildEnv();
+		const basic = env.QUICKCHR_AUTH ?? `${auth.user}:`;
+		return {
+			name: state.name,
+			status: "running",
+			version: state.version,
+			arch: state.arch,
+			cpu: state.cpu,
+			mem: state.mem,
+			pid: state.pid ?? null,
+			ports,
+			portMappings: state.ports,
+			urls: {
+				http: restUrl,
+				rest: `${restUrl}/rest`,
+				restBase: `${restUrl}/rest`,
+				https: ports.https ? `https://127.0.0.1:${ports.https}` : undefined,
+				ssh: ports.ssh ? `ssh://${auth.user}@127.0.0.1:${ports.ssh}` : undefined,
+				api: ports.api ? `tcp://127.0.0.1:${ports.api}` : undefined,
+				apiSsl: ports.apiSsl ? `tls://127.0.0.1:${ports.apiSsl}` : undefined,
+				winbox: ports.winbox ? `tcp://127.0.0.1:${ports.winbox}` : undefined,
+			},
+			auth: {
+				user: auth.user,
+				password: basic.slice(auth.user.length + 1),
+				basic,
+				header: auth.header,
+			},
+			env,
+			machineDir: state.machineDir,
+			createdAt: state.createdAt,
+			lastStartedAt: state.lastStartedAt ?? null,
+		};
+	};
 
 	return {
 		name: state.name,
@@ -571,22 +629,11 @@ function createInstance(state: MachineState): ChrInstance {
 		},
 
 		async subprocessEnv(): Promise<Record<string, string>> {
-			const auth = resolveAuth(state);
-			// auth.header is "Basic <base64>" — extract the raw user:pass.
-			const rawCreds = auth.header.startsWith("Basic ")
-				? Buffer.from(auth.header.slice(6), "base64").toString()
-				: `${auth.user}:`;
-			const restBase = `${restUrl}/rest`;
-			return {
-				QUICKCHR_NAME: state.name,
-				QUICKCHR_REST_URL: restUrl,
-				QUICKCHR_REST_BASE: restBase,
-				QUICKCHR_SSH_PORT: String(ports.ssh),
-				QUICKCHR_AUTH: rawCreds,
-				// Legacy compat keys used by restraml and similar consumers.
-				URLBASE: restBase,
-				BASICAUTH: rawCreds,
-			};
+			return buildEnv();
+		},
+
+		async descriptor(): Promise<MachineDescriptor> {
+			return buildDescriptor();
 		},
 
 		async queryLoad(): Promise<ChrLoadSample | null> {
@@ -1355,7 +1402,7 @@ export class QuickCHR {
 
 		const qemuArgs = await buildQemuArgs(launchConfig);
 		const wrapper = extractWrapper(resolvedNetworks);
-		const { pid } = await spawnQemu(qemuArgs, machineDir, spawnInBackground, wrapper);
+		let { pid } = await spawnQemu(qemuArgs, machineDir, spawnInBackground, wrapper);
 
 		// Foreground (no provisioning): spawnQemu blocks until QEMU exits
 		if (!background && !hasProvisioning) {
@@ -1375,7 +1422,26 @@ export class QuickCHR {
 		const bootTimeout = defaultBootTimeout(arch, opts.installAllPackages, accel) + (opts.timeoutExtra ?? 0);
 
 		// Always wait for boot in background mode — the JSDoc promises "REST-ready".
-		const booted = await instance.waitForBoot(bootTimeout);
+		let booted = await instance.waitForBoot(bootTimeout);
+
+		// Hardware-accelerated runners (nested-KVM on CI, HVF on virtualized macOS
+		// runners) occasionally produce a single QEMU process that boots but never
+		// reaches REST, while sibling boots on the same host succeed in ~30-45s. The
+		// process is wedged, not merely slow — so a fresh respawn recovers reliably
+		// where a longer timeout would only stretch the failure. Retry once, gated to
+		// hardware accel (TCG boots are legitimately long; doubling buys nothing there).
+		if (!booted && (accel === "kvm" || accel === "hvf")) {
+			logger.warn(
+				`CHR "${name}" did not reach REST within ${bootTimeout / 1000}s (accel=${accel}) — respawning QEMU once.`,
+			);
+			try { await stopQemu(pid); } catch { /* ignore */ }
+			cleanupQemuSockets(machineDir);
+			({ pid } = await spawnQemu(qemuArgs, machineDir, spawnInBackground, wrapper));
+			state.pid = pid;
+			saveMachine(state);
+			booted = await instance.waitForBoot(bootTimeout);
+		}
+
 		if (!booted) {
 			let qemuLogTail = "";
 			try {
@@ -1536,7 +1602,7 @@ export class QuickCHR {
 				// Persist user info in state (password placeholder — real password in secret store)
 				const current = loadMachine(machineState.name);
 				if (current) {
-					current.user = { name: result.user.name, password: "(stored in secrets)" };
+					current.user = { name: result.user.name, password: STORED_IN_SECRETS_PASSWORD };
 					saveMachine(current);
 				}
 				machineState.user = { name: result.user.name, password: result.user.password };

package/src/lib/types.ts

@@ -290,6 +290,38 @@ export interface ChrPorts {
 	[key: string]: number;
 }
 
+export interface MachineDescriptor {
+	name: string;
+	status: "running";
+	version: string;
+	arch: Arch;
+	cpu: number;
+	mem: number;
+	pid: number | null;
+	ports: ChrPorts;
+	portMappings: Record<string, PortMapping>;
+	urls: {
+		http: string;
+		rest: string;
+		restBase: string;
+		https?: string;
+		ssh?: string;
+		api?: string;
+		apiSsl?: string;
+		winbox?: string;
+	};
+	auth: {
+		user: string;
+		password: string;
+		basic: string;
+		header: string;
+	};
+	env: Record<string, string>;
+	machineDir: string;
+	createdAt: string;
+	lastStartedAt: string | null;
+}
+
 /** Return value of ChrInstance.queryLoad(). */
 export interface ChrLoadSample {
 	/** Host CPU percent across all virtual CPUs (0–100 × vCPU count). */
@@ -437,6 +469,8 @@ export interface ChrInstance {
 	 *  Bun.spawn(["bun", "my-script.ts"], { env: { ...process.env, ...await chr.subprocessEnv() } })
 	 */
 	subprocessEnv(): Promise<Record<string, string>>;
+	/** Build a stable machine-readable connection descriptor for a running instance. */
+	descriptor(): Promise<MachineDescriptor>;
 
 	/** Sample QEMU guest load from the monitor. Returns null when the monitor is
 	 *  unavailable (machine stopped or running in foreground mode). */