@crewhaus/tool-proc 0.7.0

package/dist/lib/backoff.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Backoff schedules for Retry.
+ *
+ * Deliberately jitter-free: jitter is randomness, and a tool whose waits
+ * differ run to run is a tool whose transcript cannot be replayed. The
+ * caller declares the schedule up front and gets exactly that schedule.
+ */
+export type BackoffPolicy = {
+    readonly kind: "fixed";
+    readonly delayMs: number;
+} | {
+    readonly kind: "exponential";
+    readonly baseMs: number;
+    readonly factor?: number;
+    readonly maxDelayMs?: number;
+};
+/**
+ * The delay to wait BEFORE a 1-based attempt number. Attempt 1 never waits;
+ * attempt 2 waits `baseMs`, attempt 3 `baseMs * factor`, and so on.
+ */
+export declare function backoffDelayMs(policy: BackoffPolicy, attempt: number): number;
+/** The whole schedule for `maxAttempts` attempts, including the leading 0. */
+export declare function backoffSchedule(policy: BackoffPolicy, maxAttempts: number): number[];
+/** What the whole schedule costs in waiting alone — useful to reject a plan
+ *  that could not finish inside the caller's overall deadline. */
+export declare function totalBackoffMs(policy: BackoffPolicy, maxAttempts: number): number;

package/dist/lib/backoff.js

@@ -0,0 +1,34 @@
+/**
+ * Backoff schedules for Retry.
+ *
+ * Deliberately jitter-free: jitter is randomness, and a tool whose waits
+ * differ run to run is a tool whose transcript cannot be replayed. The
+ * caller declares the schedule up front and gets exactly that schedule.
+ */
+/**
+ * The delay to wait BEFORE a 1-based attempt number. Attempt 1 never waits;
+ * attempt 2 waits `baseMs`, attempt 3 `baseMs * factor`, and so on.
+ */
+export function backoffDelayMs(policy, attempt) {
+    if (attempt <= 1)
+        return 0;
+    if (policy.kind === "fixed")
+        return Math.max(0, Math.round(policy.delayMs));
+    const factor = policy.factor ?? 2;
+    const raw = policy.baseMs * factor ** (attempt - 2);
+    const capped = policy.maxDelayMs === undefined ? raw : Math.min(raw, policy.maxDelayMs);
+    return Math.max(0, Math.round(Number.isFinite(capped) ? capped : (policy.maxDelayMs ?? raw)));
+}
+/** The whole schedule for `maxAttempts` attempts, including the leading 0. */
+export function backoffSchedule(policy, maxAttempts) {
+    const out = [];
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        out.push(backoffDelayMs(policy, attempt));
+    }
+    return out;
+}
+/** What the whole schedule costs in waiting alone — useful to reject a plan
+ *  that could not finish inside the caller's overall deadline. */
+export function totalBackoffMs(policy, maxAttempts) {
+    return backoffSchedule(policy, maxAttempts).reduce((a, b) => a + b, 0);
+}

package/dist/lib/env.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Environment handling for spawned processes.
+ *
+ * Two rules drive everything here.
+ *
+ * 1. A spawned command does NOT inherit this process's environment. The
+ *    harness environment holds API keys, tokens and cloud credentials, and
+ *    handing all of them to every `ls` is an exfiltration channel nobody
+ *    asked for. The caller names what it wants forwarded.
+ * 2. What is left is pinned for determinism: `LC_ALL`/`LANG` fix collation
+ *    and message language, `TZ` fixes any timestamp the program prints.
+ *    Without those, the same command produces different bytes on two
+ *    machines that differ only in locale.
+ */
+export declare function isValidEnvName(name: string): boolean;
+/** PATH used when the parent has none — enough to find the system tools. */
+export declare const FALLBACK_PATH = "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+export type SpawnEnvResult = {
+    /** The environment to hand the child, key-sorted so it is stable. */
+    readonly env: Record<string, string>;
+    /** Names the caller asked to forward that the parent does not define. */
+    readonly missing: readonly string[];
+    /** Names rejected as not being environment-variable names at all. */
+    readonly invalid: readonly string[];
+};
+export declare function buildSpawnEnv(parent: Readonly<Record<string, string | undefined>>, options?: {
+    readonly forward?: readonly string[];
+    readonly set?: Readonly<Record<string, string>>;
+}): SpawnEnvResult;
+/** One variable as EnvInspect reports it. `value` is present only for names
+ *  the caller explicitly asked to reveal. */
+export type EnvView = {
+    readonly name: string;
+    readonly present: boolean;
+    readonly chars: number;
+    readonly value?: string;
+};
+/**
+ * Inspect named variables and nothing else. There is deliberately no way to
+ * enumerate the environment: a caller must know the name to learn anything,
+ * and learns only whether it is set and how long it is unless it names the
+ * variable in `reveal`.
+ */
+export declare function inspectEnv(parent: Readonly<Record<string, string | undefined>>, names: readonly string[], reveal?: readonly string[]): {
+    readonly views: EnvView[];
+    readonly invalid: readonly string[];
+};

package/dist/lib/env.js

@@ -0,0 +1,89 @@
+/**
+ * Environment handling for spawned processes.
+ *
+ * Two rules drive everything here.
+ *
+ * 1. A spawned command does NOT inherit this process's environment. The
+ *    harness environment holds API keys, tokens and cloud credentials, and
+ *    handing all of them to every `ls` is an exfiltration channel nobody
+ *    asked for. The caller names what it wants forwarded.
+ * 2. What is left is pinned for determinism: `LC_ALL`/`LANG` fix collation
+ *    and message language, `TZ` fixes any timestamp the program prints.
+ *    Without those, the same command produces different bytes on two
+ *    machines that differ only in locale.
+ */
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export function isValidEnvName(name) {
+    return ENV_NAME.test(name);
+}
+/** PATH used when the parent has none — enough to find the system tools. */
+export const FALLBACK_PATH = "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+export function buildSpawnEnv(parent, options = {}) {
+    const out = new Map();
+    // The deterministic floor. PATH and HOME are forwarded because almost no
+    // real command works without them; everything else must be asked for.
+    out.set("PATH", parent["PATH"] ?? FALLBACK_PATH);
+    const home = parent["HOME"];
+    if (home !== undefined)
+        out.set("HOME", home);
+    out.set("LC_ALL", "C");
+    out.set("LANG", "C");
+    out.set("TZ", "UTC");
+    const missing = [];
+    const invalid = [];
+    for (const name of options.forward ?? []) {
+        if (!isValidEnvName(name)) {
+            invalid.push(name);
+            continue;
+        }
+        const value = parent[name];
+        if (value === undefined) {
+            missing.push(name);
+            continue;
+        }
+        out.set(name, value);
+    }
+    for (const [name, value] of Object.entries(options.set ?? {})) {
+        if (!isValidEnvName(name)) {
+            invalid.push(name);
+            continue;
+        }
+        out.set(name, value);
+    }
+    const env = {};
+    for (const name of [...out.keys()].sort())
+        env[name] = out.get(name);
+    return { env, missing, invalid };
+}
+/**
+ * Inspect named variables and nothing else. There is deliberately no way to
+ * enumerate the environment: a caller must know the name to learn anything,
+ * and learns only whether it is set and how long it is unless it names the
+ * variable in `reveal`.
+ */
+export function inspectEnv(parent, names, reveal = []) {
+    const revealSet = new Set(reveal);
+    const invalid = [];
+    const views = [];
+    const seen = new Set();
+    for (const name of names) {
+        if (!isValidEnvName(name)) {
+            invalid.push(name);
+            continue;
+        }
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        const value = parent[name];
+        const base = {
+            name,
+            present: value !== undefined,
+            chars: value === undefined ? 0 : value.length,
+        };
+        views.push(value !== undefined && revealSet.has(name) ? { ...base, value } : base);
+    }
+    // Sorted by name so two calls with the same names in a different order
+    // return the same bytes.
+    views.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return { views, invalid };
+}

package/dist/lib/format.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure formatting helpers for the process tools. Nothing here spawns,
+ * reads the filesystem or looks at a clock, so the behaviour that these
+ * back can be unit-tested without a world.
+ */
+export type CappedText = {
+    readonly text: string;
+    readonly truncated: boolean;
+    readonly droppedChars: number;
+};
+/**
+ * Cap a captured stream to a character budget, keeping BOTH ends.
+ *
+ * A command's head says what it started doing and its tail says how it
+ * ended; dropping either one loses the half a caller usually needs. The
+ * elision marker states the exact number of dropped characters so the
+ * result is still a faithful description of what the process produced.
+ */
+export declare function capText(text: string, maxChars: number): CappedText;
+/**
+ * Render an argv array the way a person would type it, for log lines and
+ * error messages ONLY. This is never fed back to a shell — the tools spawn
+ * the argv array directly — so it quotes for readability, not for safety.
+ */
+export declare function formatArgv(argv: readonly string[]): string;
+/**
+ * Compile a caller-supplied regular expression, refusing the shapes behind
+ * catastrophic backtracking. The pattern reaches us from a model, and a
+ * waiting tool applies it repeatedly to a growing buffer, so an exponential
+ * pattern would pin a core for the whole deadline.
+ */
+export declare function compileSafePattern(source: string, flags: string): {
+    readonly ok: true;
+    readonly regex: RegExp;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};

package/dist/lib/format.js

@@ -0,0 +1,124 @@
+/**
+ * Pure formatting helpers for the process tools. Nothing here spawns,
+ * reads the filesystem or looks at a clock, so the behaviour that these
+ * back can be unit-tested without a world.
+ */
+/**
+ * Cap a captured stream to a character budget, keeping BOTH ends.
+ *
+ * A command's head says what it started doing and its tail says how it
+ * ended; dropping either one loses the half a caller usually needs. The
+ * elision marker states the exact number of dropped characters so the
+ * result is still a faithful description of what the process produced.
+ */
+export function capText(text, maxChars) {
+    if (maxChars <= 0) {
+        return { text: "", truncated: text.length > 0, droppedChars: text.length };
+    }
+    if (text.length <= maxChars) {
+        return { text, truncated: false, droppedChars: 0 };
+    }
+    const head = Math.floor(maxChars / 2);
+    const tail = maxChars - head;
+    const dropped = text.length - maxChars;
+    const kept = `${text.slice(0, head)}\n...[${dropped} chars dropped]...\n${text.slice(text.length - tail)}`;
+    return { text: kept, truncated: true, droppedChars: dropped };
+}
+/**
+ * Render an argv array the way a person would type it, for log lines and
+ * error messages ONLY. This is never fed back to a shell — the tools spawn
+ * the argv array directly — so it quotes for readability, not for safety.
+ */
+export function formatArgv(argv) {
+    return argv
+        .map((arg) => arg === "" || /[\s"'\\$`*?|&;<>()[\]{}#~!]/.test(arg) ? JSON.stringify(arg) : arg)
+        .join(" ");
+}
+/**
+ * Compile a caller-supplied regular expression, refusing the shapes behind
+ * catastrophic backtracking. The pattern reaches us from a model, and a
+ * waiting tool applies it repeatedly to a growing buffer, so an exponential
+ * pattern would pin a core for the whole deadline.
+ */
+export function compileSafePattern(source, flags) {
+    if (source.length > 1_000) {
+        return { ok: false, message: `pattern is ${source.length} characters, over the 1000 limit` };
+    }
+    const risk = backtrackingRisk(source);
+    if (risk === "nested-quantifier") {
+        return {
+            ok: false,
+            message: "pattern nests one quantifier inside another, which can backtrack exponentially",
+        };
+    }
+    if (risk === "quantified-alternation") {
+        return {
+            ok: false,
+            message: "pattern quantifies a group containing an alternation, e.g. (a|a)*, which can backtrack exponentially — quantify a character class instead",
+        };
+    }
+    try {
+        return { ok: true, regex: new RegExp(source, flags) };
+    }
+    catch (err) {
+        return { ok: false, message: `invalid regex: ${err.message}` };
+    }
+}
+function backtrackingRisk(source) {
+    let depth = 0;
+    let nested = false;
+    let quantifiedAlternation = false;
+    const quantifiedAt = [];
+    const alternationAt = [];
+    for (let i = 0; i < source.length; i++) {
+        const ch = source[i];
+        if (ch === "\\") {
+            i++;
+            continue;
+        }
+        if (ch === "[") {
+            while (i < source.length && source[i] !== "]") {
+                if (source[i] === "\\")
+                    i++;
+                i++;
+            }
+            continue;
+        }
+        if (ch === "(") {
+            depth++;
+            quantifiedAt[depth] = false;
+            alternationAt[depth] = false;
+            continue;
+        }
+        if (ch === "|") {
+            if (depth > 0)
+                alternationAt[depth] = true;
+            continue;
+        }
+        if (ch === ")") {
+            const next = source[i + 1];
+            if (next === "*" || next === "+" || next === "{" || next === "?") {
+                // This group is itself quantified. `?` cannot repeat, so it only
+                // carries an inner quantifier outward; `*`, `+` and `{n,}` repeat,
+                // which is what turns an overlapping alternation catastrophic.
+                if (quantifiedAt[depth] === true && next !== "?")
+                    nested = true;
+                if (alternationAt[depth] === true && next !== "?")
+                    quantifiedAlternation = true;
+                if (depth > 1)
+                    quantifiedAt[depth - 1] = true;
+            }
+            depth = Math.max(0, depth - 1);
+            continue;
+        }
+        if (ch === "*" || ch === "+") {
+            if (depth > 0)
+                quantifiedAt[depth] = true;
+        }
+    }
+    if (nested)
+        return "nested-quantifier";
+    if (quantifiedAlternation)
+        return "quantified-alternation";
+    return "none";
+}

package/dist/registry.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The background-process registry: the processes THIS harness started, and
+ * nothing else. No tool here can see or touch a process the harness did not
+ * start, which is what keeps `ProcessList` a description of the harness's
+ * own work rather than a view of the machine.
+ *
+ * Ids are a plain counter (`proc_1`, `proc_2`, ...) rather than random hex:
+ * the same sequence of calls produces the same ids, so a transcript replays
+ * identically and a test can assert on them.
+ *
+ * Reap policy. An exited process is KEPT, so its final output can still be
+ * read after it is gone — the common case of "it died, what did it say?".
+ * Entries leave the registry in exactly three ways: the caller reaps one
+ * with `ProcessStop({ reap: true })`, a new start evicts the oldest
+ * finished entries once the table is full, or the host process exits (at
+ * which point any survivor is SIGKILLed so a session never leaks children).
+ */
+/** How many entries the table holds before evicting finished ones. */
+export declare const MAX_RETAINED_PROCS = 64;
+export type BgStatus = "running" | "exited" | "killed";
+export type BgProc = {
+    readonly id: string;
+    readonly argv: readonly string[];
+    readonly cwd: string;
+    readonly label: string | undefined;
+    readonly proc: ReturnType<typeof Bun.spawn>;
+    stdout: string;
+    stderr: string;
+    /** Characters already handed back by a previous ProcessOutput poll. */
+    stdoutReturned: number;
+    stderrReturned: number;
+    status: BgStatus;
+    exitCode: number | null;
+    readonly startedAt: number;
+    exitedAt: number | null;
+    truncated: boolean;
+};
+export type StartResult = {
+    readonly ok: true;
+    readonly proc: BgProc;
+    readonly evicted: number;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+export declare function startBackground(argv: readonly string[], options: {
+    readonly cwd: string;
+    readonly env: Record<string, string>;
+    readonly stdin?: string;
+    readonly label?: string;
+}): StartResult;
+export declare function getProc(id: string): BgProc | undefined;
+/** Every entry, in start order — a stable order, unlike Map iteration on
+ *  a table that has had entries evicted. */
+export declare function listProcs(): BgProc[];
+export declare function reapProc(id: string): boolean;
+export declare function markKilled(bg: BgProc): void;
+/** Test-only: kill every live process and empty the table, including the id
+ *  counter, so each test file starts from the same state. */
+export declare function __resetRegistryForTest(): void;

package/dist/registry.js

@@ -0,0 +1,173 @@
+/**
+ * The background-process registry: the processes THIS harness started, and
+ * nothing else. No tool here can see or touch a process the harness did not
+ * start, which is what keeps `ProcessList` a description of the harness's
+ * own work rather than a view of the machine.
+ *
+ * Ids are a plain counter (`proc_1`, `proc_2`, ...) rather than random hex:
+ * the same sequence of calls produces the same ids, so a transcript replays
+ * identically and a test can assert on them.
+ *
+ * Reap policy. An exited process is KEPT, so its final output can still be
+ * read after it is gone — the common case of "it died, what did it say?".
+ * Entries leave the registry in exactly three ways: the caller reaps one
+ * with `ProcessStop({ reap: true })`, a new start evicts the oldest
+ * finished entries once the table is full, or the host process exits (at
+ * which point any survivor is SIGKILLed so a session never leaks children).
+ */
+/** Per-stream retained output for one background process. */
+const MAX_STREAM_CHARS = 256_000;
+/** How many entries the table holds before evicting finished ones. */
+export const MAX_RETAINED_PROCS = 64;
+const procs = new Map();
+let nextId = 1;
+let cleanupInstalled = false;
+function ensureCleanup() {
+    if (cleanupInstalled)
+        return;
+    cleanupInstalled = true;
+    // Synchronous, and therefore safe in an exit handler: never leave a live
+    // child behind when the session ends.
+    process.on("exit", () => {
+        for (const bg of procs.values()) {
+            if (bg.status === "running") {
+                try {
+                    bg.proc.kill("SIGKILL");
+                }
+                catch {
+                    // Already gone.
+                }
+            }
+        }
+    });
+}
+function append(bg, stream, chunk) {
+    const next = bg[stream] + chunk;
+    if (next.length <= MAX_STREAM_CHARS) {
+        bg[stream] = next;
+        return;
+    }
+    // Keep the tail: for a long-running process the recent output is the
+    // interesting one, and the cursor moves with the window so a poll never
+    // re-reads text it already returned.
+    const drop = next.length - MAX_STREAM_CHARS;
+    bg[stream] = next.slice(drop);
+    const cursor = stream === "stdout" ? "stdoutReturned" : "stderrReturned";
+    bg[cursor] = Math.max(0, bg[cursor] - drop);
+    bg.truncated = true;
+}
+async function pump(stream, onChunk) {
+    if (stream === null || stream === undefined)
+        return;
+    const decoder = new TextDecoder();
+    try {
+        for await (const chunk of stream)
+            onChunk(decoder.decode(chunk, { stream: true }));
+        const tail = decoder.decode();
+        if (tail.length > 0)
+            onChunk(tail);
+    }
+    catch {
+        // Stream torn down because the process was killed — stop draining.
+    }
+}
+/** Evict finished entries, oldest first, until the table has room. */
+function evictFinished() {
+    let evicted = 0;
+    while (procs.size >= MAX_RETAINED_PROCS) {
+        const victim = [...procs.values()].find((p) => p.status !== "running");
+        if (victim === undefined)
+            break; // every entry is live: keep them all.
+        procs.delete(victim.id);
+        evicted++;
+    }
+    return evicted;
+}
+export function startBackground(argv, options) {
+    ensureCleanup();
+    const evicted = evictFinished();
+    if (procs.size >= MAX_RETAINED_PROCS) {
+        return {
+            ok: false,
+            message: `the background table is full (${MAX_RETAINED_PROCS} live processes) — stop one first`,
+        };
+    }
+    const id = `proc_${nextId++}`;
+    let spawned;
+    try {
+        spawned = Bun.spawn([...argv], {
+            cwd: options.cwd,
+            env: options.env,
+            stdin: options.stdin === undefined ? "ignore" : new TextEncoder().encode(options.stdin),
+            stdout: "pipe",
+            stderr: "pipe",
+        });
+    }
+    catch (err) {
+        return { ok: false, message: err instanceof Error ? err.message : String(err) };
+    }
+    const bg = {
+        id,
+        argv: [...argv],
+        cwd: options.cwd,
+        label: options.label,
+        proc: spawned,
+        stdout: "",
+        stderr: "",
+        stdoutReturned: 0,
+        stderrReturned: 0,
+        status: "running",
+        exitCode: null,
+        startedAt: Date.now(),
+        exitedAt: null,
+        truncated: false,
+    };
+    procs.set(id, bg);
+    // Fire and forget: the tool returns while the process keeps running.
+    void pump(spawned.stdout, (t) => append(bg, "stdout", t));
+    void pump(spawned.stderr, (t) => append(bg, "stderr", t));
+    void spawned.exited.then((code) => {
+        if (bg.status === "running")
+            bg.status = "exited";
+        bg.exitCode = code;
+        bg.exitedAt = Date.now();
+    });
+    return { ok: true, proc: bg, evicted };
+}
+export function getProc(id) {
+    return procs.get(id);
+}
+/** Every entry, in start order — a stable order, unlike Map iteration on
+ *  a table that has had entries evicted. */
+export function listProcs() {
+    return [...procs.values()].sort((a, b) => idNumber(a.id) - idNumber(b.id));
+}
+function idNumber(id) {
+    const n = Number.parseInt(id.slice("proc_".length), 10);
+    return Number.isNaN(n) ? 0 : n;
+}
+export function reapProc(id) {
+    return procs.delete(id);
+}
+export function markKilled(bg) {
+    if (bg.status === "running") {
+        bg.status = "killed";
+        bg.exitedAt = Date.now();
+    }
+}
+/** Test-only: kill every live process and empty the table, including the id
+ *  counter, so each test file starts from the same state. */
+export function __resetRegistryForTest() {
+    for (const bg of procs.values()) {
+        if (bg.status === "running") {
+            try {
+                bg.proc.kill("SIGKILL");
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    procs.clear();
+    nextId = 1;
+}

package/dist/safe-path.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Workspace containment for every path a caller supplies — the working
+ * directory a command runs in, and the file a wait watches.
+ *
+ * The algorithm is the one `@crewhaus/tool-fs` uses, reproduced here rather
+ * than imported because this package does not depend on that one: resolve
+ * lexically first (cheap, catches `..` and absolute escapes), then resolve
+ * the real path of the deepest ancestor that EXISTS AS A NAME so an
+ * in-workspace symlink pointing outside is caught too (CWE-59). A tool that
+ * can be pointed at `/etc` is a defect, so this fails closed: anything it
+ * cannot prove is inside the root is refused.
+ *
+ * It returns a result rather than throwing, because the tools report a
+ * caller's mistake as a readable string instead of an exception.
+ */
+export type SafePath = {
+    readonly ok: true;
+    readonly path: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Is `candidate` the root itself, or something beneath it? Both arguments
+ * must already be REAL paths — this is a string containment test, and it is
+ * only sound once the symlinks are out of the way.
+ */
+export declare function isInsideRoot(candidate: string, root: string): boolean;
+/**
+ * Re-check, at the moment of use, that a path resolved earlier still lives
+ * inside the root.
+ *
+ * `resolveSafe` can only resolve the symlinks that exist when it is called.
+ * A path that does not exist at all is admitted on the strength of its
+ * parent, and a link planted or swapped AFTER that call was never seen. A
+ * tool that polls a path for seconds or minutes — `WaitForFile` does exactly
+ * that — would happily report on the target once somebody creates it outside
+ * the root, so every poll asks again.
+ *
+ * (An outward DANGLING link is refused up front now, because `resolveSafe`
+ * follows it by hand rather than mistaking it for a missing file. This
+ * remains the guard for everything that only becomes a symlink later.)
+ *
+ * Returns `"absent"` when nothing is there yet (which is not an escape — it
+ * is the condition `WaitForFile` may be waiting for), `"inside"` when the
+ * real path is contained, and `"escaped"` when it is not.
+ */
+export declare function recheckContainment(target: string, root?: string): "inside" | "absent" | "escaped";
+export declare function resolveSafe(toolName: string, rel: string, root?: string): SafePath;
+/**
+ * Containment for a directory that must already exist (a command's cwd).
+ *
+ * `existsSync` is the right probe HERE, unlike in the walk above: a cwd has
+ * to be a directory the OS can actually chdir into, so a name that leads
+ * nowhere is useless and following the link is exactly what is wanted.
+ */
+export declare function resolveSafeDir(toolName: string, rel: string, root?: string): SafePath;