@crewhaus/tool-desktop 0.7.0

package/dist/lib/presence.js

@@ -0,0 +1,249 @@
+/**
+ * `UserPresence` — is there a human at this machine, and should a workflow
+ * interrupt them.
+ *
+ * THIS IS THE TOOL RULE 6 WAS WRITTEN FOR. Every field here has a tempting
+ * fallback that inverts the tool's purpose:
+ *
+ *   - "no idle signal, assume active" tells a workflow the operator is at the
+ *     keyboard when the truth is that nothing could be asked.
+ *   - "the probe failed, so idle" tells it the opposite, and a workflow that
+ *     acts on `idle: true` does things unattended.
+ *   - "screen-lock has no CLI, so not locked" claims the screen is unlocked
+ *     on every machine in the world.
+ *
+ * So every field is `number | null` or `boolean | null`, `null` always
+ * carries an entry in `unknown` naming the probe and the reason, and the
+ * derived `idle` boolean is `null` whenever `idleSeconds` is.
+ *
+ * ── WHAT EACH PLATFORM CAN ACTUALLY ANSWER ────────────────────────────────
+ *
+ * macOS     Idle comes out of an `ioreg` text dump, in NANOSECONDS. The unit
+ *           is the trap: reading it as milliseconds makes every host look
+ *           permanently active, and nothing about the number's shape gives
+ *           that away. The incantation matters too — the survey sketch's
+ *           `ioreg -c IOHIDSystem -d 1` prints NOTHING on macOS 26.6.2
+ *           (verified); `-r` is required, because `-d 1` without it bounds
+ *           the depth from the root rather than from the matched object:
+ *
+ *             $ ioreg -c IOHIDSystem -d 1 | grep HIDIdleTime      # empty
+ *             $ ioreg -r -c IOHIDSystem -d 1 | grep HIDIdleTime
+ *                   "HIDIdleTime" = 3254341351000
+ *
+ *           Lock state has no supported CLI, and the framework call
+ *           (CGSessionCopyCurrentDictionary) is a C API. But the same
+ *           registry carries it, recorded on the same machine with the screen
+ *           locked:
+ *
+ *             $ ioreg -n Root -d1
+ *                   "IOConsoleLocked" = Yes
+ *                   "IOConsoleUsers" = ({...,"CGSSessionScreenIsLocked"=Yes,...})
+ *
+ *           Both keys are read, `IOConsoleLocked` first. A dump with neither
+ *           is reported as unknown rather than as unlocked.
+ * Linux     `xprintidle` is the only idle source and is usually NOT
+ *           installed; under Wayland there is no idle query at all. Lock
+ *           state comes from logind's `LockedHint`, which is a HINT — it is
+ *           set by a screen locker that bothers to call `SetLockedHint`, and
+ *           a locker that does not leaves it `no` on a locked screen. It is
+ *           reported with that caveat attached rather than as a fact.
+ * Windows   `GetLastInputInfo` through a registered PowerShell script, and
+ *           the presence of `LogonUI` as the lock signal — that process runs
+ *           only while the lock or login screen is up.
+ *
+ * And over all of it: an SSH session. Idle time on a machine you are talking
+ * to over a wire says nothing about whether a person is sitting at it, so a
+ * remote shell reports `sessionKind: "ssh"` and does not pretend otherwise.
+ */
+import { isRemoteShell, linuxSession } from "../host";
+import { powershellArgv, registerPowerShellScript } from "./escape";
+/** The C# `GetLastInputInfo` shim, as one fixed string no caller value touches. */
+const WINDOWS_IDLE_SOURCE = [
+    "using System;using System.Runtime.InteropServices;",
+    "public class CHIdle{",
+    '[DllImport("user32.dll")]static extern bool GetLastInputInfo(ref LASTINPUTINFO p);',
+    "[StructLayout(LayoutKind.Sequential)]struct LASTINPUTINFO{public uint cbSize;public uint dwTime;}",
+    "public static long Ms(){LASTINPUTINFO i=new LASTINPUTINFO();i.cbSize=(uint)Marshal.SizeOf(i);",
+    "if(!GetLastInputInfo(ref i))return -1;return (long)((uint)Environment.TickCount - i.dwTime);}}",
+].join("");
+export const WINDOWS_PRESENCE = registerPowerShellScript({
+    name: "presence",
+    // DOCUMENTED, NOT RECORDED. Two facts on two lines: idle milliseconds from
+    // GetLastInputInfo, then whether LogonUI is running. Both are printed with
+    // a `key=value` prefix so a partial answer is still parseable — an idle
+    // probe that throws prints `idleMs=?` and leaves the lock line intact,
+    // rather than taking the whole result down with it.
+    script: [
+        `$src = '${WINDOWS_IDLE_SOURCE}'`,
+        "try { Add-Type -TypeDefinition $src -ErrorAction Stop; [Console]::Out.WriteLine('idleMs=' + [CHIdle]::Ms()) } catch { [Console]::Out.WriteLine('idleMs=?') }",
+        "$lock = @(Get-Process -Name LogonUI -ErrorAction SilentlyContinue).Count",
+        "[Console]::Out.WriteLine('locked=' + $(if ($lock -gt 0) { 'yes' } else { 'no' }))",
+    ].join("; "),
+    reads: [],
+});
+/**
+ * Which probes to run, plus the fields this platform cannot probe at all.
+ *
+ * A platform with no probe for a field is not an error — it is a field that
+ * comes back `null` with its reason, which is the whole contract here.
+ */
+export function planPresence(platform, env) {
+    const notes = [];
+    switch (platform) {
+        case "darwin":
+            return {
+                probes: [
+                    // `-r` is load-bearing; see the header.
+                    {
+                        field: "idleSeconds",
+                        request: { argv: ["ioreg", "-r", "-c", "IOHIDSystem", "-d", "1"] },
+                    },
+                    { field: "screenLocked", request: { argv: ["ioreg", "-n", "Root", "-d1"] } },
+                ],
+                notes,
+            };
+        case "linux": {
+            const session = linuxSession(env);
+            const probes = [];
+            if (session.kind === "x11") {
+                probes.push({
+                    field: "idleSeconds",
+                    request: { argv: ["xprintidle"], env: { DISPLAY: session.display } },
+                });
+            }
+            else {
+                notes.push([
+                    "idleSeconds",
+                    session.kind === "wayland"
+                        ? "this is a Wayland session, and Wayland exposes no idle-time query to a client — there is no program to install that would answer this"
+                        : session.reason,
+                ]);
+            }
+            probes.push({
+                field: "screenLocked",
+                request: {
+                    argv: [
+                        "loginctl",
+                        "show-session",
+                        "self",
+                        "-p",
+                        "LockedHint",
+                        "-p",
+                        "Type",
+                        "-p",
+                        "Active",
+                    ],
+                },
+            });
+            return { probes, notes };
+        }
+        case "win32":
+            return {
+                probes: [
+                    { field: "idleSeconds", request: { argv: powershellArgv(WINDOWS_PRESENCE, {}).argv } },
+                ],
+                notes,
+            };
+        default:
+            return {
+                probes: [],
+                notes: [
+                    ["idleSeconds", `this package has no presence backend for platform "${platform}"`],
+                    ["screenLocked", `this package has no presence backend for platform "${platform}"`],
+                ],
+            };
+    }
+}
+/**
+ * Parse `HIDIdleTime` out of an ioreg dump.
+ *
+ * NANOSECONDS. Recorded: `"HIDIdleTime" = 3254341351000` is 3254 seconds —
+ * about 54 minutes, which is what the machine had been idle for. Reading it
+ * as milliseconds would have reported 3254 SECONDS as 3.2 seconds and made a
+ * locked, untouched machine look freshly used.
+ *
+ * The value passes 2^53 on a host idle for more than about 104 days, so it is
+ * divided as a BigInt. A float round there is only seconds of error, but it
+ * is error with no reason to exist.
+ */
+export function parseIoregIdleSeconds(stdout) {
+    const match = /"HIDIdleTime"\s*=\s*(\d+)/.exec(stdout);
+    if (match?.[1] === undefined)
+        return null;
+    try {
+        return Number(BigInt(match[1]) / 1000000000n);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse macOS lock state out of an `ioreg -n Root -d1` dump.
+ *
+ * `null` when neither key is present — that is a macOS version this parser
+ * has not seen, and guessing "unlocked" for it would claim every such machine
+ * has a human looking at it.
+ */
+export function parseIoregLocked(stdout) {
+    // Recorded shape: `"IOConsoleLocked" = Yes`. The nested key inside
+    // IOConsoleUsers has NO spaces around the `=`, so both are matched.
+    const direct = /"IOConsoleLocked"\s*=\s*(Yes|No|true|false)/i.exec(stdout);
+    if (direct?.[1] !== undefined)
+        return /^(yes|true)$/i.test(direct[1]);
+    const session = /"CGSSessionScreenIsLocked"\s*=\s*(Yes|No|true|false)/i.exec(stdout);
+    if (session?.[1] !== undefined)
+        return /^(yes|true)$/i.test(session[1]);
+    return null;
+}
+/** `xprintidle` prints milliseconds and nothing else. */
+export function parseXprintidleSeconds(stdout) {
+    const trimmed = stdout.trim();
+    if (!/^\d+$/.test(trimmed))
+        return null;
+    return Math.floor(Number(trimmed) / 1000);
+}
+/** Parse `loginctl show-session -p …` key=value output. */
+export function parseLoginctl(stdout) {
+    const read = (key) => {
+        const match = new RegExp(`^${key}=(.*)$`, "m").exec(stdout);
+        return match?.[1]?.trim() ?? null;
+    };
+    const hint = read("LockedHint");
+    const active = read("Active");
+    return {
+        locked: hint === null ? null : /^(yes|true)$/i.test(hint),
+        type: read("Type"),
+        active: active === null ? null : /^(yes|true)$/i.test(active),
+    };
+}
+/** Parse the two lines the Windows script prints. */
+export function parseWindowsPresence(stdout) {
+    const idle = /^idleMs=(\d+)$/m.exec(stdout);
+    const locked = /^locked=(yes|no)$/m.exec(stdout);
+    return {
+        idleSeconds: idle?.[1] === undefined ? null : Math.floor(Number(idle[1]) / 1000),
+        locked: locked?.[1] === undefined ? null : locked[1] === "yes",
+    };
+}
+/**
+ * What kind of session this is.
+ *
+ * `ssh` wins over everything: a forwarded `DISPLAY` on an ssh connection is
+ * still a wire, and the idle time it would report belongs to the machine at
+ * the far end rather than to the person typing.
+ */
+export function sessionKind(platform, env) {
+    if (isRemoteShell(env))
+        return "ssh";
+    switch (platform) {
+        case "darwin":
+        case "win32":
+            return "console";
+        case "linux": {
+            const session = linuxSession(env);
+            return session.kind === "x11" || session.kind === "wayland" ? "console" : "headless";
+        }
+        default:
+            return "unknown";
+    }
+}

package/dist/lib/print.d.ts

@@ -0,0 +1,120 @@
+/**
+ * `PrintDocument` — the one tool here whose effect is physical.
+ *
+ * Three things shape this file.
+ *
+ * 1. **`lp` AND `lpstat` HAVE NO `--`.** CUPS documents no end-of-options
+ *    separator for either, so a destination or a page range that begins with
+ *    `-` cannot be defended downstream — it is REFUSED here, against a closed
+ *    pattern, before an argv exists. (`escape.ts` holds the patterns and the
+ *    story of the `git branch -D` injection this repo already shipped once.)
+ *    The document path needs no such defence for a different reason: it comes
+ *    out of `../paths.ts` containment already absolute, so it begins with `/`.
+ *
+ * 2. **THE QUEUE IS PROBED FIRST, ON BOTH PATHS.** `lpstat -p -d` runs before
+ *    `lp` on a real print AND is the whole of a `dryRun`. That is not a
+ *    courtesy: it is what makes rule 9 true here. The dry run is a PREFIX of
+ *    the real run rather than a parallel preview that predicts a destination
+ *    the real call never uses — the drift that happened in tool-hostfs's
+ *    TrashPath. It also buys the rule-6 distinction: a host whose scheduler
+ *    is down prints "Scheduler is not running." and lists nothing, which
+ *    reads exactly like a host with zero queues, and the two are different
+ *    answers.
+ *
+ * 3. **WINDOWS IS A NAMED GAP, NOT A PAPERED-OVER ONE.** `Out-Printer` sends
+ *    TEXT to a queue. It cannot rasterise a PDF, a PNG or anything else, and
+ *    there is no PDF renderer in the Windows base image to pipe one through.
+ *    So a `.txt` prints and everything else comes back `unavailable` saying
+ *    exactly that, rather than silently spooling a page of mojibake. CUPS
+ *    options (copies beyond one, duplex, page ranges) have no Out-Printer
+ *    equivalent either, so asking for one on Windows is refused by name
+ *    instead of being dropped.
+ */
+import type { HostPlatform } from "../host";
+import type { RunRequest } from "../run";
+import { type Unavailable } from "./outcome";
+export type Duplex = "one-sided" | "two-sided-long-edge" | "two-sided-short-edge";
+export declare const DUPLEX_VALUES: readonly Duplex[];
+export declare const MAX_COPIES = 100;
+/** The queue probe. No caller value reaches it, on any platform. */
+export declare function planPrinterProbe(platform: HostPlatform): Omit<RunRequest, "timeoutMs"> | undefined;
+export declare const WINDOWS_PRINTER_LIST: import("./escape").PowerShellScript;
+export declare const WINDOWS_PRINT_TEXT: import("./escape").PowerShellScript;
+/** What `lpstat -p -d` said. Every field is separately unknown-able. */
+export type QueueFacts = {
+    readonly printers: ReadonlyArray<{
+        readonly name: string;
+        readonly state: string;
+    }>;
+    /** `null` when the output named no default — NOT "there is no default". */
+    readonly defaultPrinter: string | null;
+    /** Set when the scheduler is down, which is not "no printers". */
+    readonly schedulerDown: boolean;
+    /** Set when the probe could not answer at all. */
+    readonly unreadable: string | null;
+};
+/**
+ * Parse `lpstat -p -d`.
+ *
+ * Recorded on macOS 26.6.2 (CUPS 2.4), verbatim:
+ *
+ *   printer Canon_MX490_series is idle.  enabled since Sun Jul 26 10:59:45 2026
+ *   printer Canon_TS5300_series now printing Canon_TS5300_series-33.  enabled since Sat Sep 12 00:00:20 2026
+ *           Looking for printer.
+ *   system default destination: Canon_MX490_series
+ *
+ * Two shapes in two adjacent lines — `is idle.` and `now printing <job>.` —
+ * plus an indented continuation that belongs to the line above and must not
+ * be read as a printer. The state is taken as the words between the name and
+ * the first `.`, which is deliberately tolerant: the sketch was right that
+ * this is prose, and a strict grammar over a CUPS version's wording is a
+ * parser that breaks on the next one.
+ */
+export declare function parseQueues(stdout: string, stderr: string): QueueFacts;
+/** The probe could not answer. Distinct from "it answered, there are none". */
+export declare function unreadableQueues(reason: string): QueueFacts;
+export type PrintOptions = {
+    readonly absolutePath: string;
+    readonly printer?: string;
+    readonly copies: number;
+    readonly pageRanges?: string;
+    readonly duplex?: Duplex;
+};
+export type PrintPlan = {
+    readonly ok: true;
+    readonly backend: string;
+    readonly request: Omit<RunRequest, "timeoutMs">;
+} | {
+    readonly ok: false;
+    readonly unavailable: Unavailable;
+};
+/** A refusal string, or `undefined` when every caller value fits its pattern. */
+export declare function refusePrintOptions(platform: HostPlatform, options: PrintOptions): string | undefined;
+/** Build the print argv. `refusePrintOptions` must have passed first. */
+export declare function planPrint(platform: HostPlatform, options: PrintOptions): PrintPlan;
+export type PrintOutcome = {
+    readonly outcome: "queued";
+    readonly jobId: string | null;
+    readonly note: string;
+} | Unavailable | {
+    readonly outcome: "failed";
+    readonly reason: string;
+};
+/**
+ * Pull the job id out of `lp`'s prose.
+ *
+ * `lp` answers `request id is Canon_MX490_series-33 (1 file(s))`. There is no
+ * machine-readable alternative, so this is a regex over a sentence and it
+ * degrades to `null` — never to a guess, and never to the raw line dressed up
+ * as an id. A caller that gets `null` still knows the job was accepted; it
+ * just cannot name it to `lpstat`.
+ */
+export declare function parseJobId(stdout: string): string | null;
+export declare function classifyPrint(result: {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+    readonly missing: boolean;
+    readonly refused?: boolean;
+}): PrintOutcome;

package/dist/lib/print.js

@@ -0,0 +1,188 @@
+import { SAFE_DESTINATION, SAFE_PAGE_RANGES, powershellArgv, registerPowerShellScript, } from "./escape";
+import { firstLine, unavailable, unsupportedPlatform } from "./outcome";
+export const DUPLEX_VALUES = [
+    "one-sided",
+    "two-sided-long-edge",
+    "two-sided-short-edge",
+];
+export const MAX_COPIES = 100;
+/** The queue probe. No caller value reaches it, on any platform. */
+export function planPrinterProbe(platform) {
+    switch (platform) {
+        case "darwin":
+        case "linux":
+            return { argv: ["lpstat", "-p", "-d"] };
+        case "win32":
+            return { argv: powershellArgv(WINDOWS_PRINTER_LIST, {}).argv };
+        default:
+            return undefined;
+    }
+}
+export const WINDOWS_PRINTER_LIST = registerPowerShellScript({
+    name: "printer-list",
+    // DOCUMENTED, NOT RECORDED — nobody here has a Windows box. `Get-Printer`
+    // is in the PrintManagement module, present on client Windows since 8.1.
+    script: "try { Get-Printer | ForEach-Object { [Console]::Out.WriteLine('printer ' + $_.Name + ' is ' + $_.PrinterStatus) } } catch { [Console]::Error.WriteLine($_.Exception.Message) }",
+    reads: [],
+});
+export const WINDOWS_PRINT_TEXT = registerPowerShellScript({
+    name: "print-text",
+    script: "Get-Content -Raw -LiteralPath $env:CREWHAUS_PRINT_PATH | Out-Printer -Name $env:CREWHAUS_PRINT_DEST",
+    reads: ["CREWHAUS_PRINT_PATH", "CREWHAUS_PRINT_DEST"],
+});
+/**
+ * Parse `lpstat -p -d`.
+ *
+ * Recorded on macOS 26.6.2 (CUPS 2.4), verbatim:
+ *
+ *   printer Canon_MX490_series is idle.  enabled since Sun Jul 26 10:59:45 2026
+ *   printer Canon_TS5300_series now printing Canon_TS5300_series-33.  enabled since Sat Sep 12 00:00:20 2026
+ *           Looking for printer.
+ *   system default destination: Canon_MX490_series
+ *
+ * Two shapes in two adjacent lines — `is idle.` and `now printing <job>.` —
+ * plus an indented continuation that belongs to the line above and must not
+ * be read as a printer. The state is taken as the words between the name and
+ * the first `.`, which is deliberately tolerant: the sketch was right that
+ * this is prose, and a strict grammar over a CUPS version's wording is a
+ * parser that breaks on the next one.
+ */
+export function parseQueues(stdout, stderr) {
+    const both = `${stdout}\n${stderr}`;
+    if (/Scheduler is not running/i.test(both)) {
+        return { printers: [], defaultPrinter: null, schedulerDown: true, unreadable: null };
+    }
+    const printers = [];
+    let defaultPrinter = null;
+    for (const raw of stdout.split("\n")) {
+        // An indented line continues the one above it (`Looking for printer.`),
+        // and is not a record of its own.
+        if (raw.startsWith(" ") || raw.startsWith("\t"))
+            continue;
+        const line = raw.trim();
+        if (line === "")
+            continue;
+        const printer = /^printer\s+(\S+)\s+(.*?)\.?(?:\s{2,}.*)?$/.exec(line);
+        if (printer?.[1] !== undefined) {
+            printers.push({ name: printer[1], state: (printer[2] ?? "").replace(/\.$/, "").trim() });
+            continue;
+        }
+        const dflt = /^system default destination:\s*(\S+)/.exec(line);
+        if (dflt?.[1] !== undefined)
+            defaultPrinter = dflt[1];
+        // "no system default destination" is a real CUPS line and leaves the
+        // field null, which is correct: there is genuinely none.
+    }
+    return { printers, defaultPrinter, schedulerDown: false, unreadable: null };
+}
+/** The probe could not answer. Distinct from "it answered, there are none". */
+export function unreadableQueues(reason) {
+    return { printers: [], defaultPrinter: null, schedulerDown: false, unreadable: reason };
+}
+/** A refusal string, or `undefined` when every caller value fits its pattern. */
+export function refusePrintOptions(platform, options) {
+    if (options.printer !== undefined && !SAFE_DESTINATION.test(options.printer)) {
+        return `the printer name ${JSON.stringify(options.printer)} is not a CUPS destination name (letters, digits, "_", "." and "-", not starting with "-"); lp documents no "--", so a name that could be read as an option is refused rather than escaped`;
+    }
+    if (options.pageRanges !== undefined && !SAFE_PAGE_RANGES.test(options.pageRanges)) {
+        return `the page range ${JSON.stringify(options.pageRanges)} is not of the form "1", "1-4" or "1,3,5-9"`;
+    }
+    if (!Number.isInteger(options.copies) || options.copies < 1 || options.copies > MAX_COPIES) {
+        return `copies must be a whole number between 1 and ${MAX_COPIES}`;
+    }
+    if (platform === "win32") {
+        // Named, not dropped. See the header.
+        if (options.copies !== 1) {
+            return "Out-Printer has no copies option; print once or use a CUPS host";
+        }
+        if (options.pageRanges !== undefined) {
+            return "Out-Printer has no page-range option; it prints the whole document or nothing";
+        }
+        if (options.duplex !== undefined) {
+            return "Out-Printer has no duplex option; the queue's own default decides";
+        }
+        if (!/\.txt$/i.test(options.absolutePath)) {
+            return "Out-Printer sends TEXT to a queue and cannot rasterise a PDF, an image or an office document — on Windows this tool prints .txt only, and spooling anything else would put a page of mojibake on the operator's printer";
+        }
+    }
+    return undefined;
+}
+/** Build the print argv. `refusePrintOptions` must have passed first. */
+export function planPrint(platform, options) {
+    switch (platform) {
+        case "darwin":
+        case "linux": {
+            const argv = ["lp"];
+            if (options.printer !== undefined)
+                argv.push("-d", options.printer);
+            if (options.copies !== 1)
+                argv.push("-n", String(options.copies));
+            if (options.pageRanges !== undefined)
+                argv.push("-o", `page-ranges=${options.pageRanges}`);
+            if (options.duplex !== undefined)
+                argv.push("-o", `sides=${options.duplex}`);
+            // The path last, and absolute because containment resolved it. `lp`
+            // reads a leading "-" as an option, which is why nothing that could
+            // start with one reaches this array.
+            argv.push(options.absolutePath);
+            return { ok: true, backend: "lp", request: { argv } };
+        }
+        case "win32": {
+            const built = powershellArgv(WINDOWS_PRINT_TEXT, {
+                CREWHAUS_PRINT_PATH: options.absolutePath,
+                // An empty name means "the default queue" to Out-Printer, and keeping
+                // the key present keeps the script's `reads` contract exact.
+                CREWHAUS_PRINT_DEST: options.printer ?? "",
+            });
+            return {
+                ok: true,
+                backend: "powershell Out-Printer",
+                request: { argv: built.argv, env: built.env },
+            };
+        }
+        default:
+            return { ok: false, unavailable: unsupportedPlatform(platform, "printing") };
+    }
+}
+/**
+ * Pull the job id out of `lp`'s prose.
+ *
+ * `lp` answers `request id is Canon_MX490_series-33 (1 file(s))`. There is no
+ * machine-readable alternative, so this is a regex over a sentence and it
+ * degrades to `null` — never to a guess, and never to the raw line dressed up
+ * as an id. A caller that gets `null` still knows the job was accepted; it
+ * just cannot name it to `lpstat`.
+ */
+export function parseJobId(stdout) {
+    const match = /request id is\s+(\S+)/i.exec(stdout);
+    return match?.[1] ?? null;
+}
+export function classifyPrint(result) {
+    if (result.refused === true)
+        return { outcome: "failed", reason: result.stderr };
+    if (result.missing) {
+        return unavailable("program", "the print command is not installed on this host (lp, from CUPS)", "lp");
+    }
+    if (result.timedOut) {
+        // The rule-14 shape: the reason says what is unknown, so an assertion on
+        // it cannot also be satisfied by an unrelated failure.
+        return {
+            outcome: "failed",
+            reason: "lp did not finish within its timeout and was killed — whether the job reached the queue is unknown, so do not resend without checking the queue first",
+        };
+    }
+    if (result.code === 0) {
+        return {
+            outcome: "queued",
+            jobId: parseJobId(result.stdout),
+            // Said plainly: the queue accepted it. Paper is a separate question and
+            // this tool cannot see the answer.
+            note: "the job was accepted by the queue; whether it printed depends on the printer and is not observable from here",
+        };
+    }
+    const detail = firstLine(result.stderr) || firstLine(result.stdout);
+    return {
+        outcome: "failed",
+        reason: detail === "" ? `lp exited ${result.code}` : `lp exited ${result.code}: ${detail}`,
+    };
+}

package/dist/lib/windows.d.ts

@@ -0,0 +1,100 @@
+/**
+ * `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 { type HostPlatform, type SessionEnv } from "../host";
+import type { RunRequest } from "../run";
+import { type Unavailable } from "./outcome";
+export declare const WINDOW_LIST_SCRIPT: import("./escape").AppleScript;
+export declare const WINDOWS_WINDOW_LIST: import("./escape").PowerShellScript;
+/**
+ * One window.
+ *
+ * Every field that a backend may fail to read is `null`, never a zero and
+ * never a `false`. `minimized: null` means "this backend could not ask",
+ * which is a different thing from a window that is not minimized.
+ */
+export type WindowRecord = {
+    readonly app: string;
+    readonly title: string | null;
+    readonly x: number | null;
+    readonly y: number | null;
+    readonly width: number | null;
+    readonly height: number | null;
+    readonly focused: boolean | null;
+    readonly minimized: boolean | null;
+    /** Present on backends that expose one (wmctrl, Windows handles). */
+    readonly id?: string;
+    readonly pid?: number;
+};
+export type WindowPlan = {
+    readonly ok: true;
+    readonly backend: string;
+    readonly request: Omit<RunRequest, "timeoutMs">;
+} | {
+    readonly ok: false;
+    readonly unavailable: Unavailable;
+};
+export declare function planWindowList(platform: HostPlatform, env: SessionEnv): WindowPlan;
+/** Parse the separator-delimited output the macOS and Windows scripts emit. */
+export declare function parseDelimitedWindows(stdout: string): WindowRecord[];
+/**
+ * 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 declare function parseWmctrl(stdout: string): WindowRecord[];
+export type WindowOutcome = {
+    readonly outcome: "listed";
+    readonly windows: ReadonlyArray<WindowRecord>;
+    /** The stream was cut; the list is a PREFIX, not the whole desktop. */
+    readonly truncated: boolean;
+} | Unavailable | {
+    readonly outcome: "failed";
+    readonly reason: string;
+};
+export declare function classifyWindowList(backend: string, result: {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+    readonly missing: boolean;
+    readonly refused?: boolean;
+    readonly stdoutTruncated?: boolean;
+}): WindowOutcome;