@crewhaus/tool-desktop 0.7.0

package/dist/lib/windows.js

@@ -0,0 +1,258 @@
+/**
+ * `WindowList` — enumerating what is on the operator's screen, and the one
+ * answer this tool must never give.
+ *
+ * AN EMPTY LIST IS A CLAIM. It says "this desktop has no windows open", and a
+ * workflow that reads it will conclude the operator is looking at nothing.
+ * Every failure mode here produces that same empty list unless it is caught:
+ * a macOS box that has not granted Accessibility, a Wayland session where
+ * enumeration is not permitted at all, a Linux box with no `wmctrl`
+ * installed, a truncated stream. So none of them return a list. They return
+ * `unavailable` with the reason, and the reason names the grant to give or
+ * the package to install.
+ *
+ * ── THE macOS BACKEND, AND WHY IT IS THE SLOW ONE ─────────────────────────
+ *
+ * There are two, and the survey sketch was right that it is a real fork:
+ *
+ *   CGWindowListCopyWindowInfo   one call, stable CGWindowIDs, bounds, layer
+ *                                and on-screen state. It is a C API with no
+ *                                JS binding, so using it means shipping and
+ *                                code-signing a per-arch native helper.
+ *   osascript / System Events    no build step, an order of magnitude slower,
+ *                                no CGWindowID, and it needs the
+ *                                Accessibility grant.
+ *
+ * House rule 8 settles it: no new runtime dependency, and a signed native
+ * helper is a large one. So this is the System Events backend, and on a
+ * machine that has not granted Accessibility the honest answer is
+ * `unavailable` naming that grant — NOT an empty list, and not a list with
+ * blank titles. (The blank-title failure the sketch describes belongs to the
+ * CGWindowList backend, where a missing Screen Recording grant strips titles
+ * while still returning every window. That trap is not reachable from here;
+ * the System Events path fails loudly instead, which is the better failure.)
+ *
+ * The script is a frozen constant with arity 0 — no caller value reaches it —
+ * and it reports each field separately, so a window whose position cannot be
+ * read is a window with unknown bounds rather than a window at 0,0.
+ */
+import { linuxDisplayEnv, linuxSession } from "../host";
+import { osascriptArgv, osascriptPermissionReason, powershellArgv, registerAppleScript, registerPowerShellScript, } from "./escape";
+import { firstLine, unavailable, unsupportedPlatform } from "./outcome";
+/**
+ * The field and record separators, ASCII 31 and 30.
+ *
+ * They are built INSIDE each script (`character id 31`, `[char]31`) rather
+ * than written into this file, so no control byte travels through argv and no
+ * source file in this package holds one (house rule 13's neighbourhood). They
+ * are also the two characters a window title cannot plausibly contain, which
+ * a printable sentinel like `<|f|>` cannot promise.
+ */
+const FS = "\u001F";
+const RS = "\u001E";
+export const WINDOW_LIST_SCRIPT = registerAppleScript({
+    name: "window-list",
+    lines: [
+        "set fs to (character id 31)",
+        "set rs to (character id 30)",
+        'set out to ""',
+        'tell application "System Events"',
+        "repeat with p in (application processes whose visible is true)",
+        "set pname to name of p",
+        "set isFront to frontmost of p",
+        "repeat with w in (windows of p)",
+        'set wname to ""',
+        "try",
+        "set wname to name of w",
+        "end try",
+        'set wx to "?"',
+        'set wy to "?"',
+        'set ww to "?"',
+        'set wh to "?"',
+        "try",
+        "set {px, py} to position of w",
+        "set {sw, sh} to size of w",
+        "set wx to px as string",
+        "set wy to py as string",
+        "set ww to sw as string",
+        "set wh to sh as string",
+        "end try",
+        'set wmin to "?"',
+        "try",
+        'set wmin to (value of attribute "AXMinimized" of w) as string',
+        "end try",
+        "set out to out & pname & fs & wname & fs & wx & fs & wy & fs & ww & fs & wh & fs & (isFront as string) & fs & wmin & rs",
+        "end repeat",
+        "end repeat",
+        "end tell",
+        "return out",
+    ],
+    arity: 0,
+});
+export const WINDOWS_WINDOW_LIST = registerPowerShellScript({
+    name: "window-list",
+    // DOCUMENTED, NOT RECORDED. `MainWindowHandle`/`MainWindowTitle` give one
+    // window per process and no geometry; real bounds need EnumWindows +
+    // GetWindowRect through a P/Invoke shim, which is a compile step this
+    // package will not take (house rule 8). So the Windows rows report bounds
+    // as UNKNOWN rather than as zeros, and say why.
+    script: "$fs = [char]31; $rs = [char]30; Get-Process | Where-Object { $_.MainWindowHandle -ne 0 } | ForEach-Object { [Console]::Out.Write($_.ProcessName + $fs + $_.MainWindowTitle + $fs + '?' + $fs + '?' + $fs + '?' + $fs + '?' + $fs + 'false' + $fs + '?' + $rs) }",
+    reads: [],
+});
+export function planWindowList(platform, env) {
+    switch (platform) {
+        case "darwin":
+            return {
+                ok: true,
+                backend: "osascript System Events",
+                request: { argv: osascriptArgv(WINDOW_LIST_SCRIPT) },
+            };
+        case "linux": {
+            const session = linuxSession(env);
+            if (session.kind === "none" || session.kind === "wayland-unreachable") {
+                return { ok: false, unavailable: unavailable("session", session.reason) };
+            }
+            if (session.kind === "wayland") {
+                // Not a missing program and not an empty desktop. Wayland has no
+                // protocol by which one client may enumerate another's windows; the
+                // compositor-specific extensions that do (wlr-foreign-toplevel, the
+                // GNOME Shell eval endpoint) are per-compositor and, in GNOME's case,
+                // removed. There is nothing to install that would fix this, and the
+                // reason says so rather than suggesting a package.
+                return {
+                    ok: false,
+                    unavailable: unavailable("session", "this is a Wayland session, and Wayland deliberately provides no protocol for one client to enumerate another client's windows — there is no program to install that would change this; an X11 session or a compositor-specific extension is the only way"),
+                };
+            }
+            return {
+                ok: true,
+                backend: "wmctrl",
+                // `-l` list, `-G` geometry, `-p` pid, `-x` WM_CLASS. No caller value.
+                request: { argv: ["wmctrl", "-l", "-G", "-p", "-x"], env: linuxDisplayEnv(env) },
+            };
+        }
+        case "win32":
+            return {
+                ok: true,
+                backend: "powershell Get-Process",
+                request: { argv: powershellArgv(WINDOWS_WINDOW_LIST, {}).argv },
+            };
+        default:
+            return { ok: false, unavailable: unsupportedPlatform(platform, "window") };
+    }
+}
+/** `"?"` is the scripts' unknown marker; everything else must parse. */
+function num(value) {
+    if (value === undefined || value === "?" || value.trim() === "")
+        return null;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function bool(value) {
+    if (value === undefined || value === "?")
+        return null;
+    const lowered = value.trim().toLowerCase();
+    if (lowered === "true" || lowered === "yes")
+        return true;
+    if (lowered === "false" || lowered === "no")
+        return false;
+    return null;
+}
+/** Parse the separator-delimited output the macOS and Windows scripts emit. */
+export function parseDelimitedWindows(stdout) {
+    const out = [];
+    for (const record of stdout.split(RS)) {
+        if (record.trim() === "")
+            continue;
+        const f = record.split(FS);
+        if (f.length < 8)
+            continue;
+        out.push({
+            app: (f[0] ?? "").trim(),
+            // An empty title is a real state (a palette, a sheet), so it stays an
+            // empty string; only a field the script could not read becomes null.
+            title: f[1] ?? null,
+            x: num(f[2]),
+            y: num(f[3]),
+            width: num(f[4]),
+            height: num(f[5]),
+            focused: bool(f[6]),
+            minimized: bool(f[7]),
+        });
+    }
+    return out;
+}
+/**
+ * Parse `wmctrl -l -G -p -x`.
+ *
+ * Columns: id, desktop, pid, x, y, width, height, WM_CLASS, client machine,
+ * then the title — which contains spaces and is therefore everything left.
+ * A desktop of `-1` means "sticky / on all desktops", not an error.
+ */
+export function parseWmctrl(stdout) {
+    const out = [];
+    for (const raw of stdout.split("\n")) {
+        const line = raw.trimEnd();
+        if (line.trim() === "")
+            continue;
+        const parts = line.trim().split(/\s+/);
+        if (parts.length < 9)
+            continue;
+        const [id, , pid, x, y, w, h, wmClass] = parts;
+        // Nine fixed columns, then the title. The cursor walks the ORIGINAL line
+        // rather than re-joining the split, so a title with runs of spaces, or
+        // one that repeats a column's text, survives intact.
+        let cursor = 0;
+        for (let i = 0; i < 9; i += 1) {
+            const field = parts[i];
+            const next = line.indexOf(field, cursor);
+            if (next < 0)
+                break;
+            cursor = next + field.length;
+        }
+        const title = line.slice(cursor).trim();
+        const parsedPid = num(pid);
+        out.push({
+            app: (wmClass ?? "").split(".").pop() ?? "",
+            title,
+            x: num(x),
+            y: num(y),
+            width: num(w),
+            height: num(h),
+            // wmctrl does not report focus or minimisation. Unknown, not false —
+            // reporting `focused: false` for every window says "nothing has focus",
+            // which is never true of a running X session.
+            focused: null,
+            minimized: null,
+            ...(id === undefined ? {} : { id }),
+            ...(parsedPid === null ? {} : { pid: parsedPid }),
+        });
+    }
+    return out;
+}
+export function classifyWindowList(backend, result) {
+    if (result.refused === true)
+        return { outcome: "failed", reason: result.stderr };
+    if (result.missing) {
+        return unavailable("program", `the window enumerator for this platform is not installed on this host (${backend}; on X11 that is wmctrl)`, backend);
+    }
+    if (result.timedOut) {
+        return unavailable("unknown", "the window enumerator did not finish within its timeout and was killed — the window list could not be read, which is not the same as there being no windows", backend);
+    }
+    // Checked BEFORE the exit code: System Events reports a missing grant as an
+    // ordinary script error, and treating it as one would hand a caller "the
+    // script failed" when the actionable fact is "grant Accessibility".
+    const permission = osascriptPermissionReason(result.stderr);
+    if (permission !== undefined) {
+        return unavailable("permission", permission, backend);
+    }
+    if (result.code !== 0) {
+        const detail = firstLine(result.stderr);
+        return {
+            outcome: "failed",
+            reason: detail === "" ? `${backend} exited ${result.code}` : `${backend}: ${detail}`,
+        };
+    }
+    const windows = backend === "wmctrl" ? parseWmctrl(result.stdout) : parseDelimitedWindows(result.stdout);
+    return { outcome: "listed", windows, truncated: result.stdoutTruncated === true };
+}

package/dist/paths.d.ts

@@ -0,0 +1,42 @@
+import { CrewhausError } from "@crewhaus/errors";
+/** Raised when a caller-supplied path resolves outside the workspace root. */
+export declare class ToolPermissionError extends CrewhausError {
+    readonly name = "ToolPermissionError";
+    readonly toolName: string;
+    readonly path: string;
+    constructor(toolName: string, attemptedPath: string);
+}
+/**
+ * A validated path, in both forms the tools need.
+ *
+ * `real` has every in-workspace symlink already resolved and is what I/O
+ * should use — operating on it closes most of the check-to-use window.
+ * `abs` is the lexical resolution, which is what a tool must use when the
+ * question is about the link ITSELF (`Stat` reporting a symlink target,
+ * `RemovePath` deleting a link rather than its destination).
+ */
+export type SafePath = {
+    readonly abs: string;
+    readonly real: string;
+    /** The path as the caller wrote it, for echoing back in results. */
+    readonly given: string;
+    /** Slash-separated path relative to the workspace root. */
+    readonly rel: string;
+};
+/** The workspace root, resolved. Every path is contained within it. */
+export declare function workspaceRoot(): string;
+export declare function resolveSafe(toolName: string, rel: string, root?: string): SafePath;
+/** A path relative to the workspace root, with `/` separators on every OS. */
+export declare function toPosix(p: string): string;
+/**
+ * True when `candidate` is `parent` or lives underneath it. Both must already
+ * be absolute. Used to keep an archive entry, or a symlink inside an
+ * extracted tree, from reaching outside its destination.
+ */
+export declare function isInside(parent: string, candidate: string): boolean;
+/**
+ * Reject an archive member name that would escape its destination: an
+ * absolute path, a Windows drive prefix, or any `..` segment. Checked on the
+ * NAME, before extraction, because after extraction the damage is done.
+ */
+export declare function archiveEntryEscapes(name: string): boolean;

package/dist/paths.js

@@ -0,0 +1,158 @@
+/**
+ * Path containment — the gate every caller-supplied path in this package
+ * passes through before any syscall touches it.
+ *
+ * The approach is the one `@crewhaus/tool-fs` uses, and for the same reasons:
+ * a lexical check alone is fooled by a symlink that lives inside the
+ * workspace and points outside it (CWE-59), so the real path is checked too.
+ * The workspace root is `process.cwd()`, matching tool-fs, so a harness that
+ * trusts one tool's boundary gets the same boundary here.
+ */
+import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import * as path from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+/** Raised when a caller-supplied path resolves outside the workspace root. */
+export class ToolPermissionError extends CrewhausError {
+    name = "ToolPermissionError";
+    toolName;
+    path;
+    constructor(toolName, attemptedPath) {
+        super("tool", `tool "${toolName}" rejected path "${attemptedPath}": resolved location escapes the workspace root`);
+        this.toolName = toolName;
+        this.path = attemptedPath;
+    }
+}
+/** The workspace root, resolved. Every path is contained within it. */
+export function workspaceRoot() {
+    return path.resolve(process.cwd());
+}
+/**
+ * Resolve `rel` inside the workspace, or throw `ToolPermissionError`.
+ *
+ * The leaf is allowed not to exist — every tool here that creates something
+ * needs to validate a destination before it is made — so the deepest
+ * EXISTING ancestor is realpath'd and the missing tail re-appended. Any
+ * failure other than that walk fails closed.
+ */
+/**
+ * True when the NAME exists, whether or not it leads anywhere.
+ *
+ * `existsSync` FOLLOWS symlinks, so it answers false for a link whose target
+ * is missing — and that is exactly the case that matters: a dangling link is
+ * still a door, because `open(…, "w")` through `evil -> /outside/x` CREATES
+ * `/outside/x`. Probing with `lstat` keeps the link's name in the part of the
+ * path that gets resolved, rather than in the "does not exist yet" tail that
+ * is re-appended to the root verbatim and so passes the containment check.
+ */
+function nameExists(p) {
+    try {
+        lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where `target` would actually land, with every symlink on the way already
+ * followed — including one whose own target does not exist yet.
+ *
+ * `realpathSync` gives up with ENOENT on a dangling link, which would leave
+ * that link unresolved and let it stand in for a plain missing file. So the
+ * deepest ancestor that exists as a NAME is resolved, a dangling one is
+ * followed a hop by hand, and the components that do not exist are appended.
+ * The result is the path an `open` would create, which is the only path worth
+ * checking containment against.
+ */
+function resolveLocation(target, depth = 0) {
+    if (depth > 40)
+        throw new Error(`symlink chain at "${target}" is too long to resolve`);
+    let probe = target;
+    const tail = [];
+    while (!nameExists(probe)) {
+        tail.unshift(path.basename(probe));
+        const parent = path.dirname(probe);
+        if (parent === probe)
+            break; // reached the filesystem root
+        probe = parent;
+    }
+    let probeReal;
+    try {
+        probeReal = realpathSync(probe);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        // The name is there but `realpath` cannot finish it: a symlink with a
+        // missing target. `readlinkSync` throws EINVAL on anything else, which
+        // fails closed.
+        const link = readlinkSync(probe);
+        // A RELATIVE target resolves against the directory that actually CONTAINS
+        // the link, which is not the link's lexical parent when that parent is
+        // itself reached through a symlink. `<root>/dirlink/x -> ../y` with
+        // `dirlink` pointing out of the root really lands at `<elsewhere>/y`, but
+        // measured from the lexical parent it reads as `<root>/y` — an in-root
+        // path the caller's path does not lead to. So the parent is made real
+        // first. An absolute target ignores the base.
+        const base = realpathSync(path.dirname(probe));
+        probeReal = resolveLocation(path.resolve(base, link), depth + 1);
+    }
+    return tail.length > 0 ? path.join(probeReal, ...tail) : probeReal;
+}
+export function resolveSafe(toolName, rel, root = workspaceRoot()) {
+    const rootResolved = path.resolve(root);
+    const abs = path.resolve(rootResolved, rel);
+    // 1) Lexical containment — rejects `..` and absolute escapes. The trailing
+    //    separator avoids the `/root` vs `/root-sibling` prefix pitfall.
+    if (abs !== rootResolved && !abs.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new ToolPermissionError(toolName, rel);
+    }
+    let real;
+    try {
+        const rootReal = realpathSync(rootResolved);
+        real = resolveLocation(abs);
+        // 2) Symlink-aware containment. The real path must land inside the real
+        //    root, so an in-workspace symlink pointing at /etc is refused here.
+        if (real !== rootReal && !real.startsWith(`${rootReal}${path.sep}`)) {
+            throw new ToolPermissionError(toolName, rel);
+        }
+    }
+    catch (err) {
+        if (err instanceof ToolPermissionError)
+            throw err;
+        throw new ToolPermissionError(toolName, rel);
+    }
+    return {
+        abs,
+        real,
+        given: rel,
+        rel: toPosix(path.relative(rootResolved, abs)),
+    };
+}
+/** A path relative to the workspace root, with `/` separators on every OS. */
+export function toPosix(p) {
+    return path.sep === "/" ? p : p.split(path.sep).join("/");
+}
+/**
+ * True when `candidate` is `parent` or lives underneath it. Both must already
+ * be absolute. Used to keep an archive entry, or a symlink inside an
+ * extracted tree, from reaching outside its destination.
+ */
+export function isInside(parent, candidate) {
+    const p = path.resolve(parent);
+    const c = path.resolve(candidate);
+    return c === p || c.startsWith(`${p}${path.sep}`);
+}
+/**
+ * Reject an archive member name that would escape its destination: an
+ * absolute path, a Windows drive prefix, or any `..` segment. Checked on the
+ * NAME, before extraction, because after extraction the damage is done.
+ */
+export function archiveEntryEscapes(name) {
+    const normalized = name.replace(/\\/g, "/");
+    if (normalized.startsWith("/"))
+        return true;
+    if (/^[A-Za-z]:/.test(normalized))
+        return true;
+    return normalized.split("/").some((segment) => segment === "..");
+}

package/dist/run.d.ts

@@ -0,0 +1,187 @@
+/**
+ * The one place this package starts a child process, and the seam every test
+ * drives instead of the machine.
+ *
+ * The conventions are `@crewhaus/tool-proc`'s (`src/spawn.ts`) and
+ * `@crewhaus/tool-pkgmgr`'s (`src/run.ts`), copied rather than re-invented:
+ *
+ *   - ARGV IS AN ARRAY. There is no shell in this package: no `sh -c`, no
+ *     `cmd /c`, no interpolated command line. A caller's value is an ELEMENT
+ *     of an argv array or it does not reach a command at all. `assertArgv`
+ *     refuses anything that would make that untrue BEFORE a process exists.
+ *   - EVERY RUN HAS A DEADLINE. SIGTERM at the deadline, SIGKILL after a
+ *     grace period, and a bounded drain. The drain bound is load-bearing
+ *     here, not defensive: `xclip -i` and `wl-copy` DELIBERATELY fork a
+ *     resident holder (under X11 and Wayland the writing process owns the
+ *     selection, so it must outlive the tool call), and that holder inherits
+ *     the stdout pipe. Reading to EOF would block until the operator copies
+ *     something else — possibly for hours.
+ *   - THE ENVIRONMENT IS PINNED. `PATH` plus a C locale, plus whatever the
+ *     backend explicitly adds. Nothing else is inherited, so the harness's
+ *     secrets are not in `pbpaste`'s environment.
+ *
+ * TWO DELIBERATE EXCEPTIONS, BOTH SECURITY MEASURES RATHER THAN CONVENIENCES.
+ *
+ * 1. `RunRequest.env` exists so a value can reach a PowerShell script WITHOUT
+ *    being in the script's source. `powershell.exe -Command <script> a b c`
+ *    CONCATENATES the trailing arguments onto the command string — argv is
+ *    not a safe channel there the way it is for `notify-send`. So the Windows
+ *    backends put caller values in the child's environment and the script
+ *    reads `$env:CREWHAUS_*`. See ./lib/escape.ts, where that decision lives.
+ * 2. `RunRequest.stdin` is the channel for a PAYLOAD. `ClipboardWrite` pipes
+ *    its text in rather than passing it as an argument, because argv is
+ *    world-readable through `ps` on both macOS and Linux and a clipboard
+ *    payload is exactly the kind of thing an operator would not want in a
+ *    process listing.
+ *
+ * ── WHY THE "REAL HOST" GATE LIVES HERE AND NOT IN host.ts ────────────────
+ *
+ * `host.ts` imports from this file; this file imports from nothing in the
+ * package. The gate that decides whether an un-injected seam may consult the
+ * real machine is read by BOTH (`hostPlatform()` and `sessionEnv()` need it
+ * as much as `runHostCommand` does), so it is defined in the file at the
+ * bottom of the dependency order. An earlier draft had it in `host.ts` and
+ * `run.ts` importing it back, which is an ESM cycle: it happens to work while
+ * every use is inside a function body, and breaks the first time either file
+ * grows a module-scope constant that reads the other.
+ */
+/** `PATH` for a child, with a floor so a stripped harness env still spawns. */
+export declare const FALLBACK_PATH = "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+export type RunRequest = {
+    readonly argv: readonly string[];
+    readonly timeoutMs: number;
+    /** Piped to the child. `undefined` ⇒ stdin is closed, so a program that
+     *  would read a terminal gets EOF instead of blocking to its deadline. */
+    readonly stdin?: string;
+    /** Extra environment for the child — see the header. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Cap on each captured stream; hitting it is reported, never silent. */
+    readonly maxOutputChars?: number;
+    readonly signal?: AbortSignal;
+};
+export type RunResult = {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+    /** True when the program itself is not installed (ENOENT on spawn). */
+    readonly missing: boolean;
+    /**
+     * The stream was cut at the cap. It matters: a truncated window listing
+     * looks exactly like a complete short one, and a caller reads the missing
+     * tail as "there is nothing else".
+     */
+    readonly stdoutTruncated?: boolean;
+    readonly stderrTruncated?: boolean;
+    /** Set when no runner was installed and the real host was not allowed. */
+    readonly refused?: boolean;
+};
+/**
+ * A process this package started and deliberately did not wait for.
+ *
+ * Only `PowerAssertion` uses it: a sleep inhibitor IS the lifetime of a child
+ * process, so the tool has to return while the child keeps running.
+ */
+export type DetachResult = {
+    readonly ok: true;
+    readonly pid: number;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly missing: boolean;
+};
+export type Runner = (request: RunRequest) => Promise<RunResult>;
+export type Detacher = (request: RunRequest) => Promise<DetachResult>;
+export declare const DEFAULT_COMMAND_TIMEOUT_MS = 10000;
+export declare const MAX_COMMAND_TIMEOUT_MS = 120000;
+/**
+ * Per-stream cap.
+ *
+ * A clipboard can legitimately hold a whole file, and `ClipboardRead` applies
+ * its OWN, much smaller cap on top of this one — this is only the ceiling
+ * past which the process pipe stops being drained.
+ */
+export declare const DEFAULT_MAX_OUTPUT_CHARS = 4000000;
+/**
+ * Opt in to (or out of) the real machine for an un-injected seam.
+ *
+ * Exactly one test in this package calls it with `true`, and restores it in
+ * the same `finally`. Everything else drives a fixture.
+ */
+export declare function _allowRealHost(allowed: boolean): void;
+export declare function _realHostAllowed(): boolean;
+/**
+ * True when a runner is installed.
+ *
+ * Read by `host.ts` to decide the platform default: a test that has installed
+ * a recorded runner has already declared "I am not talking to this host", so
+ * if it then forgets to declare which host it is PRETENDING to be it gets a
+ * platform no backend serves — identically on macOS and on Linux CI. That
+ * exact bug (a test inheriting the ambient `process.platform`) cost this
+ * project a CI round in tool-hostfs.
+ */
+export declare function _runnerInstalled(): boolean;
+export declare function assertArgv(argv: readonly string[]): string | undefined;
+/**
+ * A child's environment: `PATH` so the program can be found, a C locale so a
+ * parsed message is the same string on every machine, and the backend's
+ * explicit additions (a display, a D-Bus address, a `CREWHAUS_*` payload).
+ *
+ * Nothing else. `process.env` is NOT copied in: `pbpaste` has no business
+ * seeing an API key, and neither does a PowerShell one-liner. The session
+ * variables a Linux backend needs arrive through `extra`, put there by a
+ * backend reading the INJECTED `sessionEnv()` — so a test controls them like
+ * everything else rather than inheriting whether the maintainer happened to
+ * be in an SSH session.
+ */
+export declare function childEnv(extra?: Readonly<Record<string, string>>): Record<string, string>;
+/** Cut a captured stream at the cap, saying whether it was cut. */
+export declare function capText(text: string, max: number): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * The refusal an un-injected runner produces under test.
+ *
+ * Shaped like a real failure so every caller's existing "the command did not
+ * work" branch handles it, and worded so the test author sees immediately
+ * what they forgot.
+ */
+export declare const NO_RUNNER_REASON = "no runner is installed and this process is not allowed to touch the real host (see _setRunner / _allowRealHost)";
+/**
+ * Turn a `Bun.spawn` throw into the right kind of "it did not run".
+ *
+ * ADVERSARIAL REVIEW: the first version set `missing: true` for EVERY spawn
+ * error, so a program that is installed but not executable by this user
+ * (`EACCES`), a name that resolves to a directory (`EISDIR`/`ENOTDIR`) or an
+ * argv over the kernel's limit (`E2BIG`) all came back as "the program is not
+ * installed on this host" — and `WindowList` then told an operator to install
+ * the `wmctrl` they already have. That is rule 6 one level below the tools:
+ * "could not start it" is not "it is not there".
+ *
+ * Only the two errnos that genuinely mean the NAME does not resolve set
+ * `missing`. Everything else is a failure carrying the errno, so the caller's
+ * reason names what actually happened.
+ *
+ * Exported because it is the only part of the real-spawn path a test can
+ * reach without spawning (house rule 4 allows exactly one real-host test, and
+ * it spawns nothing).
+ */
+export declare function classifySpawnError(err: unknown): RunResult;
+export declare function runHostCommand(request: RunRequest): Promise<RunResult>;
+/**
+ * Start a child and return its pid without waiting for it.
+ *
+ * `stdio` is all `ignore`: a detached holder that inherited this process's
+ * pipes would keep them open after the harness exits, and a holder whose
+ * stdout nobody reads eventually blocks on a full pipe — an inhibitor that
+ * stops inhibiting halfway through the job it was held for.
+ */
+export declare function detachHostCommand(request: RunRequest): Promise<DetachResult>;
+/**
+ * Test seam. Pass a function to answer every command from recorded output;
+ * pass `undefined` to go back to the (refused, under test) real spawn.
+ */
+export declare function _setRunner(runner: Runner | undefined): void;
+export declare function _setDetacher(detacher: Detacher | undefined): void;
+export declare function _resetRunSeams(): void;