@crewhaus/tool-desktop 0.7.0 → 0.8.0

package/dist/lib/open.js

@@ -265,7 +265,24 @@ export function classifyTarget(target, allowed) {
  *   - `.desktop`, `.lnk`, `.url` and `.webloc` are INDIRECTION. They contain a
  *     target, and opening one reaches a program or a URL that never passed
  *     the scheme allow-list at the top of this file. A `.url` file holding
- *     `URL=file:///etc/passwd` walks straight around the gate.
+ *     `URL=file:///etc/passwd` walks straight around the gate. The macOS
+ *     location files are the same family: `.fileloc` is `.webloc`'s file:
+ *     twin, and Launch Services resolves it straight to its target — an app
+ *     outside the workspace, or a workspace `.command` this list refuses by
+ *     name, laundered through one level of indirection (flag-truth-5#6,
+ *     security-10#4). `.afploc`/`.ftploc` are schemes refused above.
+ *
+ * The list also names what INSTALLS or RUNS on open without an execute bit:
+ * configuration profiles, Java Web Start, ClickOnce and MSIX installers,
+ * scripts an interpreter's launcher is registered for, Automator and
+ * Shortcuts documents, macOS plug-in bundles, every disk image type macOS's
+ * DiskImageMounter registers, System Settings extensions and network
+ * configurations, certificates and keychains Keychain Access imports, and
+ * Microsoft's Level-1 attachment list in full. A deny-list always trails the
+ * handler table on a real machine; this one is the union of what the 0.7.0
+ * reviews found and those handlers register (read from their Info.plist
+ * files on macOS 26), and an allow-list of document types for path opens is
+ * the structural fix still to be decided.
  */
 const DANGEROUS_EXTENSIONS = new Set([
     // runs directly
@@ -293,6 +310,9 @@ const DANGEROUS_EXTENSIONS = new Set([
     "bash",
     "zsh",
     "fish",
+    "ksh",
+    "csh",
+    "tcsh",
     "command",
     "tool",
     "run",
@@ -307,17 +327,217 @@ const DANGEROUS_EXTENSIONS = new Set([
     "scptd",
     "applescript",
     "terminal",
+    // a Terminal.app session file: Terminal is its registered handler and
+    // runs the command its ExecutionString names
+    "term",
+    // more macOS bundles, installers and automation
+    "mpkg",
+    "prefpane",
+    "saver",
+    "service",
+    "osax",
+    "qlgenerator",
+    "kext",
+    "plugin",
+    "bundle",
+    "appex",
+    "action",
+    "caction",
+    "wflow",
+    "shortcut",
+    "mobileconfig",
+    "configprofile",
+    "provisionprofile",
+    // interpreters whose launcher is registered to RUN the file on open
+    "py",
+    "pyw",
+    "pyz",
+    "pyzw",
+    "pyc",
+    "pyo",
+    "pl",
+    "rb",
+    "jnlp",
+    // Windows: installers, shell and management documents that act on open
+    "appref-ms",
+    "application",
+    "appx",
+    "appxbundle",
+    "msix",
+    "msixbundle",
+    "appinstaller",
+    "msc",
+    "chm",
+    "gadget",
+    "ws",
+    "wsc",
+    "sct",
+    "diagcab",
+    "xll",
+    "rdp",
+    "theme",
+    "themepack",
+    "deskthemepack",
+    // the rest of Microsoft's Level-1 (always blocked) attachment list, in
+    // full: each runs, installs, configures or redirects on open
+    "appcontent-ms",
+    "printerexport",
+    "osd",
+    "prf",
+    "xnk",
+    "udl",
+    "vsmacros",
+    "vsw",
+    "webpnp",
+    "asp",
+    "aspx",
+    "asx",
+    "bgi",
+    "cnt",
+    "fxp",
+    "hpj",
+    "htc",
+    "its",
+    "ops",
+    "pcd",
+    "plg",
+    "prg",
+    "pst",
+    "tmp",
+    "msu",
+    "mst",
+    "cab",
+    "ins",
+    "isp",
+    "hlp",
+    "grp",
+    "mcf",
+    "xbap",
+    "vb",
+    "vbp",
+    "bas",
+    "shb",
+    "shs",
+    "wsb",
+    "msh",
+    "msh1",
+    "msh2",
+    "mshxml",
+    "msh1xml",
+    "msh2xml",
+    "ps1xml",
+    "ps2",
+    "ps2xml",
+    "psc1",
+    "psc2",
+    "psd1",
+    "psdm1",
+    // Access databases and their shortcuts run an AutoExec macro on open
+    "ade",
+    "adp",
+    "accda",
+    "accdb",
+    "accde",
+    "accdr",
+    "accdt",
+    "mad",
+    "maf",
+    "mag",
+    "mam",
+    "maq",
+    "mar",
+    "mas",
+    "mat",
+    "mau",
+    "mav",
+    "maw",
+    "mda",
+    "mdb",
+    "mde",
+    "mdt",
+    "mdw",
+    "mdz",
+    // Linux packages and self-running images
+    "deb",
+    "rpm",
+    "flatpakref",
+    "appimage",
+    "snap",
+    // disk images that mount on open (and skip mark-of-the-web on Windows):
+    // on macOS, every type DiskImageMounter registers
+    "iso",
+    "img",
+    "vhd",
+    "vhdx",
+    "udif",
+    "toast",
+    "dvdr",
+    "cdr",
+    "dmgpart",
+    "sparseimage",
+    "asif",
+    "sparsebundle",
+    "backupbundle",
+    // macOS System Settings extensions and network configurations, which it
+    // installs on open
+    "sysprefex",
+    "internetconnect",
+    "networkconnect",
+    // certificates and keychains: Keychain Access imports them on open (and
+    // Windows' Level-1 list names cer, crt and der for the same reason)
+    "cer",
+    "cert",
+    "crt",
+    "der",
+    "pem",
+    "p7",
+    "p7b",
+    "p7c",
+    "p7m",
+    "p7r",
+    "p7s",
+    "p10",
+    "p12",
+    "pfx",
+    "pkcs12",
+    "keychain",
+    "keychain-db",
     // indirection — the target never passes the scheme gate
     "desktop",
     "lnk",
     "url",
     "webloc",
     "inetloc",
+    "fileloc",
+    "vncloc",
+    "afploc",
+    "ftploc",
+    "mailloc",
+    "newsloc",
+    "atloc",
+    "telnetloc",
+    "website",
+    "scf",
+    "searchconnector-ms",
+    "library-ms",
+    "search-ms",
+    "settingcontent-ms",
     "inf",
 ]);
-/** The lowercase extension, or `""`. */
+/**
+ * The lowercase extension, or `""`.
+ *
+ * Trailing dots and spaces are dropped first: Windows strips them when it
+ * opens a path, so `x.bat.` and `x.bat ` run `x.bat`, and reading them as
+ * "no extension" let a refused type through by spelling.
+ */
 export function extensionOf(path) {
-    const base = path.split(/[\\/]/).pop() ?? path;
+    const full = path.split(/[\\/]/).pop() ?? path;
+    // A loop, not /[. ]+$/, which rescans the run from every start (quadratic).
+    let end = full.length;
+    while (end > 0 && (full[end - 1] === "." || full[end - 1] === " "))
+        end--;
+    const base = full.slice(0, end);
     const dot = base.lastIndexOf(".");
     return dot <= 0 ? "" : base.slice(dot + 1).toLowerCase();
 }
@@ -333,7 +553,7 @@ export function refusePath(absolutePath, facts) {
     }
     const extension = extensionOf(absolutePath);
     if (DANGEROUS_EXTENSIONS.has(extension)) {
-        return `the path ends in ".${extension}", which a desktop either RUNS or follows to a target this tool never got to check — "open this" and "run this" are the same gesture to an operating system, so it is refused`;
+        return `the path ends in ".${extension}", which a desktop RUNS, installs, mounts or imports on open, or follows to a target this tool never got to check — "open this" and "run this" are the same gesture to an operating system, so it is refused`;
     }
     if (facts.isFile && isExecutable(facts)) {
         return "the path is an executable file, and asking a desktop to OPEN one is how it gets RUN — this tool refuses, whatever the registered handler would have done";

package/dist/lib/power.d.ts

@@ -17,10 +17,13 @@
  *    caller that cannot see when its own inhibitor lapses will hold another.
  * 2. **A PID IS NOT AN IDENTITY.** Pids are reused, and `release` reading a
  *    stale state file would otherwise send SIGTERM to whatever now owns that
- *    number. So the state file records the backend program, and `release` and
- *    `status` VERIFY the live process's command line before signalling
- *    anything. A mismatch is reported as `stale` and the file is cleared —
- *    nothing is killed.
+ *    number. So `release` and `status` VERIFY the live process's command line
+ *    against the holder THIS package starts on this platform
+ *    ({@link isHolderCommand}) before signalling anything — never against a
+ *    value the record itself carries, since the record also supplies the pid.
+ *    A mismatch is reported as `stale` and the file is cleared — nothing is
+ *    killed. The record lives in a per-user private directory outside the
+ *    workspace, where the agent's file tools cannot plant one.
  * 3. **WINDOWS CANNOT DO THIS IN A ONE-LINER.** `SetThreadExecutionState` is
  *    THREAD-scoped and its effect dies with the thread, so a PowerShell
  *    one-liner that sets the flag and exits does precisely nothing — the
@@ -39,8 +42,34 @@ export type AssertionScope = "system" | "display";
 /** The ceiling, and the reason there is one. Eight hours is a working day. */
 export declare const MAX_HOLD_MINUTES = 480;
 export declare const DEFAULT_HOLD_MINUTES = 30;
-/** Where the held assertion is remembered, relative to the workspace root. */
-export declare const STATE_RELATIVE_PATH = ".crewhaus/power-assertion.json";
+/**
+ * Where 0.7.0 remembered the held assertion, relative to the workspace root.
+ *
+ * NOT READ ANY MORE, only reported. A file in the workspace can be written by
+ * the agent the tool serves (Write, CopyPath, an extracted archive), and the
+ * record names the pid `release` signals: a planted record made `release`
+ * SIGTERM any process of the operator's (security-10#1). The record now lives
+ * in a private per-user directory — see `powerStateFile` in ../index.ts.
+ */
+export declare const LEGACY_STATE_RELATIVE_PATH = ".crewhaus/power-assertion.json";
+/**
+ * The program this package's holder runs on `platform` — the ONE source for
+ * both `planHold` and the identity check `release` makes before signalling.
+ * The check used to compare against the `marker` field of the state record,
+ * which is the same record that supplies the pid, so whoever wrote the record
+ * chose what the live process was checked against (security-10#1).
+ */
+export declare function holderMarker(platform: HostPlatform): string | undefined;
+/**
+ * Is `commandLine` a holder THIS package starts on `platform`?
+ *
+ * The program must be the platform's holder, and the arguments must carry
+ * what `planHold` always gives it: `-t <seconds>` for caffeinate,
+ * `--who=crewhaus` for systemd-inhibit, and the generated type name inside a
+ * powershell host. An operator's own `caffeinate -d` is therefore never
+ * taken for ours.
+ */
+export declare function isHolderCommand(platform: HostPlatform, commandLine: string): boolean;
 export declare const WINDOWS_INHIBIT: import("./escape").PowerShellScript;
 export declare const WINDOWS_PROCESS_PROBE: import("./escape").PowerShellScript;
 /**
@@ -134,7 +163,9 @@ export type Liveness = "alive" | "gone" | "reused" | "unknown";
  * test is kept for that case alone, narrowed to a powershell host.
  */
 export declare function commandMatchesMarker(commandLine: string, marker: string): boolean;
-export declare function classifyLiveness(marker: string, result: {
+export declare function classifyLiveness(
+/** The holder's program name, or a predicate over the live command line. */
+holder: string | ((commandLine: string) => boolean), result: {
     readonly code: number;
     readonly stdout: string;
     readonly stderr: string;

package/dist/lib/power.js

@@ -3,8 +3,62 @@ import { unsupportedPlatform } from "./outcome";
 /** The ceiling, and the reason there is one. Eight hours is a working day. */
 export const MAX_HOLD_MINUTES = 480;
 export const DEFAULT_HOLD_MINUTES = 30;
-/** Where the held assertion is remembered, relative to the workspace root. */
-export const STATE_RELATIVE_PATH = ".crewhaus/power-assertion.json";
+/**
+ * Where 0.7.0 remembered the held assertion, relative to the workspace root.
+ *
+ * NOT READ ANY MORE, only reported. A file in the workspace can be written by
+ * the agent the tool serves (Write, CopyPath, an extracted archive), and the
+ * record names the pid `release` signals: a planted record made `release`
+ * SIGTERM any process of the operator's (security-10#1). The record now lives
+ * in a private per-user directory — see `powerStateFile` in ../index.ts.
+ */
+export const LEGACY_STATE_RELATIVE_PATH = ".crewhaus/power-assertion.json";
+/**
+ * The program this package's holder runs on `platform` — the ONE source for
+ * both `planHold` and the identity check `release` makes before signalling.
+ * The check used to compare against the `marker` field of the state record,
+ * which is the same record that supplies the pid, so whoever wrote the record
+ * chose what the live process was checked against (security-10#1).
+ */
+export function holderMarker(platform) {
+    switch (platform) {
+        case "darwin":
+            return DARWIN_HOLDER;
+        case "linux":
+            return LINUX_HOLDER;
+        case "win32":
+            return WINDOWS_HOLDER_TYPE;
+        default:
+            return undefined;
+    }
+}
+const DARWIN_HOLDER = "caffeinate";
+const LINUX_HOLDER = "systemd-inhibit";
+/** The type name the Windows holder script defines; see WINDOWS_INHIBIT. */
+const WINDOWS_HOLDER_TYPE = "CHPwr";
+/**
+ * Is `commandLine` a holder THIS package starts on `platform`?
+ *
+ * The program must be the platform's holder, and the arguments must carry
+ * what `planHold` always gives it: `-t <seconds>` for caffeinate,
+ * `--who=crewhaus` for systemd-inhibit, and the generated type name inside a
+ * powershell host. An operator's own `caffeinate -d` is therefore never
+ * taken for ours.
+ */
+export function isHolderCommand(platform, commandLine) {
+    const marker = holderMarker(platform);
+    if (marker === undefined || !commandMatchesMarker(commandLine, marker))
+        return false;
+    const tokens = commandLine.trim().split(/\s+/);
+    switch (platform) {
+        case "darwin":
+            return tokens.includes("-t");
+        case "linux":
+            return tokens.includes("--who=crewhaus");
+        default:
+            return true;
+    }
+}
 export const WINDOWS_INHIBIT = registerPowerShellScript({
     name: "power-inhibit",
     // DOCUMENTED, NOT RECORDED. The flags are ES_CONTINUOUS (0x80000000) |
@@ -83,7 +137,7 @@ export function planHold(platform, scope, seconds, reason) {
             if (scope === "display")
                 argv.push("-d");
             argv.push("-t", String(seconds));
-            return { ok: true, backend: "caffeinate", marker: "caffeinate", request: { argv } };
+            return { ok: true, backend: "caffeinate", marker: DARWIN_HOLDER, request: { argv } };
         }
         case "linux": {
             const what = scope === "display" ? "idle:sleep:handle-lid-switch" : "idle:sleep";
@@ -101,7 +155,7 @@ export function planHold(platform, scope, seconds, reason) {
             return {
                 ok: true,
                 backend: "systemd-inhibit",
-                marker: "systemd-inhibit",
+                marker: LINUX_HOLDER,
                 request: { argv },
             };
         }
@@ -114,7 +168,7 @@ export function planHold(platform, scope, seconds, reason) {
             return {
                 ok: true,
                 backend: "powershell SetThreadExecutionState",
-                marker: "CHPwr",
+                marker: WINDOWS_HOLDER_TYPE,
                 request: { argv: built.argv, env: built.env },
             };
         }
@@ -184,7 +238,9 @@ export function commandMatchesMarker(commandLine, marker) {
         return true;
     return /^powershell$/i.test(base) && commandLine.includes(marker);
 }
-export function classifyLiveness(marker, result) {
+export function classifyLiveness(
+/** The holder's program name, or a predicate over the live command line. */
+holder, result) {
     if (result.refused === true || result.missing || result.timedOut)
         return "unknown";
     // `ps -p <pid>` exits 1 with no output when nothing has that pid. That is a
@@ -208,7 +264,8 @@ export function classifyLiveness(marker, result) {
     const line = result.stdout.trim();
     if (line === "")
         return "gone";
-    return commandMatchesMarker(line, marker) ? "alive" : "reused";
+    const ours = typeof holder === "string" ? commandMatchesMarker(line, holder) : holder(line);
+    return ours ? "alive" : "reused";
 }
 /** Minutes to a bounded second count, or a refusal naming the ceiling. */
 export function boundedSeconds(minutes) {

package/dist/lib/presence.js

@@ -76,7 +76,12 @@ export const WINDOWS_PRESENCE = registerPowerShellScript({
     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",
+        // THIS session's LogonUI only: Get-Process lists every session's, so on
+        // a host with another signed-in (or RDP) user, their lock screen read as
+        // this user being locked out — the direction that sends a workflow off
+        // to act unattended.
+        "$sid = [System.Diagnostics.Process]::GetCurrentProcess().SessionId",
+        "$lock = @(Get-Process -Name LogonUI -ErrorAction SilentlyContinue | Where-Object { $_.SessionId -eq $sid }).Count",
         "[Console]::Out.WriteLine('locked=' + $(if ($lock -gt 0) { 'yes' } else { 'no' }))",
     ].join("; "),
     reads: [],
@@ -218,6 +223,8 @@ export function parseLoginctl(stdout) {
 }
 /** Parse the two lines the Windows script prints. */
 export function parseWindowsPresence(stdout) {
+    // `[Console]::Out.WriteLine` ends each line with CRLF on Windows; `$`
+    // under `m` matches before `\r` as well as `\n`, so both parse.
     const idle = /^idleMs=(\d+)$/m.exec(stdout);
     const locked = /^locked=(yes|no)$/m.exec(stdout);
     return {

package/dist/lib/print.d.ts

@@ -71,6 +71,14 @@ export type QueueFacts = {
  * parser that breaks on the next one.
  */
 export declare function parseQueues(stdout: string, stderr: string): QueueFacts;
+/**
+ * Parse the Windows printer probe's JSON: `{"printers":[{"name","status"}],
+ * "default":<name>|null}`. Anything else — no stdout, a PowerShell error, a
+ * shape this parser does not know — is UNREADABLE, never "no printers".
+ * A name is taken whole, spaces, commas and a `\\server\queue` share
+ * included.
+ */
+export declare function parseWindowsQueues(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 = {

package/dist/lib/print.js

@@ -20,9 +20,17 @@ export function planPrinterProbe(platform) {
 }
 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) }",
+    // DOCUMENTED, NOT RECORDED on a desktop — `Get-Printer` is in the
+    // PrintManagement module, present on client Windows since 8.1; the
+    // windows-tools CI job logs what a Windows runner prints (see
+    // windows-recording.test.ts). JSON, not prose: the 0.7.0 script printed
+    // `printer <Name> is <Status>` into the lpstat parser, whose `\S+` cut every
+    // Windows name with a space at the first one — every Windows box ships
+    // "Microsoft Print to PDF" (reliability#7). Names and statuses are cast to
+    // strings (an enum would serialise as a number), the list is forced to an
+    // array (ConvertTo-Json unwraps a one-element pipeline), and a failure goes
+    // to stderr with nothing on stdout, so it can never read as "no printers".
+    script: "try { $rows = @(Get-Printer -ErrorAction Stop | ForEach-Object { [pscustomobject]@{ name = [string]$_.Name; status = [string]$_.PrinterStatus } }); $def = $null; try { $def = [string](Get-CimInstance -ClassName Win32_Printer -Filter 'Default=TRUE' -ErrorAction Stop | Select-Object -First 1 -ExpandProperty Name) } catch { $def = $null }; [Console]::Out.Write((ConvertTo-Json -InputObject ([pscustomobject]@{ printers = $rows; default = $def }) -Compress -Depth 3)) } catch { [Console]::Error.WriteLine($_.Exception.Message) }",
     reads: [],
 });
 export const WINDOWS_PRINT_TEXT = registerPowerShellScript({
@@ -75,6 +83,58 @@ export function parseQueues(stdout, stderr) {
     }
     return { printers, defaultPrinter, schedulerDown: false, unreadable: null };
 }
+/**
+ * Parse the Windows printer probe's JSON: `{"printers":[{"name","status"}],
+ * "default":<name>|null}`. Anything else — no stdout, a PowerShell error, a
+ * shape this parser does not know — is UNREADABLE, never "no printers".
+ * A name is taken whole, spaces, commas and a `\\server\queue` share
+ * included.
+ */
+export function parseWindowsQueues(stdout, stderr) {
+    const text = stdout.trim();
+    const why = stderr.trim();
+    const unreadable = (detail) => unreadableQueues(`the Windows printer probe ${detail}${why === "" ? "" : `: ${why.slice(0, 300)}`}, so whether this host has printers is unknown — it is NOT that it has none`);
+    if (text === "")
+        return unreadable("printed nothing");
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return unreadable("did not print the JSON it was written to print");
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return unreadable("printed an unknown shape");
+    const record = parsed;
+    const rawList = record["printers"];
+    // ConvertTo-Json unwraps a one-element array under some hosts; accept both.
+    const list = Array.isArray(rawList)
+        ? rawList
+        : typeof rawList === "object" && rawList !== null
+            ? [rawList]
+            : rawList === null || rawList === undefined
+                ? []
+                : undefined;
+    if (list === undefined)
+        return unreadable("printed an unknown shape");
+    const printers = [];
+    for (const row of list) {
+        if (typeof row !== "object" || row === null)
+            return unreadable("printed an unknown row");
+        const name = row["name"];
+        const status = row["status"];
+        if (typeof name !== "string" || name === "")
+            return unreadable("printed a row with no name");
+        printers.push({ name, state: typeof status === "string" ? status : "" });
+    }
+    const dflt = record["default"];
+    return {
+        printers,
+        defaultPrinter: typeof dflt === "string" && dflt !== "" ? dflt : null,
+        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 };

package/dist/lib/windows.js

@@ -95,8 +95,11 @@ export const WINDOWS_WINDOW_LIST = registerPowerShellScript({
     // 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) }",
+    // as UNKNOWN rather than as zeros, and say why. Focus too: the 0.7.0 script
+    // printed a literal `false` for every window, a definite "nothing has
+    // focus" from a probe that never asked (GetForegroundWindow is the same
+    // P/Invoke step), so focused is `?` → null like the bounds.
+    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 + '?' + $fs + '?' + $rs) }",
     reads: [],
 });
 export function planWindowList(platform, env) {

package/dist/paths.d.ts

@@ -1,10 +1,29 @@
 import { CrewhausError } from "@crewhaus/errors";
-/** Raised when a caller-supplied path resolves outside the workspace root. */
+/**
+ * The longest path this resolves, in UTF-16 code units; a longer one is
+ * refused before it is walked. Nothing that long can be opened or created:
+ * PATH_MAX is 1,024 bytes on macOS and 4,096 on Linux, Windows stops at
+ * 32,767 UTF-16 units, and a path's UTF-8 form is never shorter than its
+ * UTF-16 one. The limit is twice that because the part of a path that exists
+ * is itself under PATH_MAX, so the part that does not is over PATH_MAX on its
+ * own: no spelling of the place reaches it, not even one through a symlink
+ * that shortens the part that exists.
+ */
+export declare const MAX_PATH_CHARS: number;
+/**
+ * Raised when a caller-supplied path resolves outside the workspace root, or
+ * is longer than any path can be.
+ */
 export declare class ToolPermissionError extends CrewhausError {
     readonly name = "ToolPermissionError";
     readonly toolName: string;
     readonly path: string;
-    constructor(toolName: string, attemptedPath: string);
+    /**
+     * Why, when it is not that the location escapes the workspace root: a path
+     * longer than any path can be. A caller that rewords the refusal says this.
+     */
+    readonly reason: string | undefined;
+    constructor(toolName: string, attemptedPath: string, reason?: string);
 }
 /**
  * A validated path, in both forms the tools need.