sidekick-shared 0.28.3 → 0.29.1

package/dist/esm/report/htmlReportGenerator.js

@@ -596,14 +596,51 @@ function renderContentBlock(block, includeThinking, includeToolDetail) {
             return '';
     }
 }
-function renderToolUse(block, includeDetail) {
+/** Prefix of the bookkeeping keys session parsers stash inside tool inputs. */
+const SIDEKICK_INPUT_KEY_PREFIX = '_sidekick';
+/**
+ * The tool's display identity and user-facing input. Entries built outside
+ * the canonical projection may still carry the parsers' `_sidekick*` keys in
+ * `toolInput`; those are hidden here and read as the raw identity.
+ */
+function toolDisplay(block) {
     const name = block.toolName || 'unknown';
+    const raw = block.toolInput;
+    let input = raw;
+    let rawToolName = block.rawToolName;
+    let mcpServerName = block.mcpServerName;
+    if (raw && Object.keys(raw).some((key) => key.startsWith(SIDEKICK_INPUT_KEY_PREFIX))) {
+        const clean = {};
+        for (const [key, value] of Object.entries(raw)) {
+            if (!key.startsWith(SIDEKICK_INPUT_KEY_PREFIX))
+                clean[key] = value;
+        }
+        input = clean;
+        if (!rawToolName && typeof raw._sidekickRawToolName === 'string') {
+            rawToolName = raw._sidekickRawToolName;
+        }
+        if (!mcpServerName && typeof raw._sidekickMcpServerName === 'string') {
+            mcpServerName = raw._sidekickMcpServerName;
+        }
+    }
+    const parts = [];
+    if (rawToolName && rawToolName.trim() && rawToolName !== name)
+        parts.push(rawToolName);
+    if (mcpServerName && mcpServerName.trim())
+        parts.push(`MCP: ${mcpServerName}`);
+    const hint = parts.length
+        ? ` <span class="tool-raw-name" style="color:var(--text-muted);font-size:11px">${escapeHtml(parts.join(' · '))}</span>`
+        : '';
+    return { name, hint, input };
+}
+function renderToolUse(block, includeDetail) {
+    const { name, hint, input } = toolDisplay(block);
     if (!includeDetail) {
-        return `<div class="tool-block" data-block-type="tool"><div style="padding:8px 12px;background:rgba(245,166,35,0.08);color:var(--accent-orange);font-family:monospace;font-size:13px;">${escapeHtml(name)}</div></div>`;
+        return `<div class="tool-block" data-block-type="tool"><div style="padding:8px 12px;background:rgba(245,166,35,0.08);color:var(--accent-orange);font-family:monospace;font-size:13px;">${escapeHtml(name)}${hint}</div></div>`;
     }
     let inputHtml = '';
-    if (block.toolInput && Object.keys(block.toolInput).length > 0) {
-        const inputJson = JSON.stringify(block.toolInput, null, 2);
+    if (input && Object.keys(input).length > 0) {
+        const inputJson = JSON.stringify(input, null, 2);
         const highlighted = highlightCodeBlock(inputJson, 'json');
         inputHtml = `<div class="tool-io">
     <div class="tool-label">Input</div>
@@ -611,7 +648,7 @@ function renderToolUse(block, includeDetail) {
   </div>`;
     }
     return `<details class="tool-block" data-block-type="tool">
-  <summary>${escapeHtml(name)}${block.toolUseId ? ` <span style="color:var(--text-muted);font-size:11px">${escapeHtml(block.toolUseId)}</span>` : ''}</summary>
+  <summary>${escapeHtml(name)}${hint}${block.toolUseId ? ` <span style="color:var(--text-muted);font-size:11px">${escapeHtml(block.toolUseId)}</span>` : ''}</summary>
   <div class="tool-content">
     ${inputHtml}
   </div>

package/dist/esm/report/transcriptParser.js

@@ -42,17 +42,19 @@ function toReportBlock(block) {
             return block.text ? [{ type: 'text', text: block.text }] : [];
         case 'thinking':
             return block.text ? [{ type: 'thinking', text: block.text }] : [];
-        case 'tool_use':
-            return [
-                {
-                    type: 'tool_use',
-                    toolName: block.toolName ?? 'unknown',
-                    toolInput: block.input && typeof block.input === 'object'
-                        ? block.input
-                        : {},
-                    toolUseId: block.toolUseId,
-                },
-            ];
+        case 'tool_use': {
+            const toolBlock = {
+                type: 'tool_use',
+                toolName: block.toolName ?? 'unknown',
+                toolInput: block.input && typeof block.input === 'object'
+                    ? block.input
+                    : {},
+                toolUseId: block.toolUseId,
+                ...(block.rawToolName ? { rawToolName: block.rawToolName } : {}),
+                ...(block.mcpServerName ? { mcpServerName: block.mcpServerName } : {}),
+            };
+            return [toolBlock];
+        }
         case 'tool_result':
             return [
                 {

package/dist/esm/schemas/providerFailure.js

@@ -9,7 +9,7 @@
  */
 import { z } from 'zod';
 import { ACCOUNT_PROVIDER_IDS } from '../providerIds';
-import { PROVIDER_AUTHENTICATION_SOURCES, PROVIDER_AUTHENTICATION_STATES, PROVIDER_CREDENTIAL_KINDS, PROVIDER_FAILURE_CODES, PROVIDER_FAILURE_EVIDENCE_SOURCES, PROVIDER_RECOVERY_ACTIONS, } from '../providerFailure';
+import { CODEX_ERROR_INFO_KINDS, PROVIDER_AUTHENTICATION_SOURCES, PROVIDER_AUTHENTICATION_STATES, PROVIDER_CREDENTIAL_KINDS, PROVIDER_FAILURE_CODES, PROVIDER_FAILURE_EVIDENCE_SOURCES, PROVIDER_RECOVERY_ACTIONS, } from '../providerFailure';
 export const providerAuthenticationEvidenceSchema = z.object({
     credentialKind: z.enum(PROVIDER_CREDENTIAL_KINDS),
     state: z.enum(PROVIDER_AUTHENTICATION_STATES),
@@ -20,6 +20,7 @@ export const providerFailureEvidenceSchema = z.object({
     source: z.enum(PROVIDER_FAILURE_EVIDENCE_SOURCES),
     rule: z.enum(PROVIDER_FAILURE_CODES),
     checkedAt: z.string().optional(),
+    codexErrorInfo: z.enum(CODEX_ERROR_INFO_KINDS).optional(),
 });
 export const providerRetryAfterSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('delay'), delayMs: z.number() }),
@@ -30,6 +31,7 @@ export const providerFailureDiagnosisSchema = z.object({
     credentialKind: z.enum(PROVIDER_CREDENTIAL_KINDS),
     diagnosis: z.enum(PROVIDER_FAILURE_CODES),
     recovery: z.enum(PROVIDER_RECOVERY_ACTIONS),
+    retryable: z.boolean().optional(),
     evidence: z.array(providerFailureEvidenceSchema),
     authentication: providerAuthenticationEvidenceSchema.optional(),
     httpStatus: z.number().optional(),

package/dist/esm/schemas/sessionEvent.js

@@ -8,6 +8,7 @@
  */
 import { z } from 'zod';
 import { normalizedUsageSchema } from './usageNormalization';
+import { taskNotificationPromptFromAttachment } from '../subagentSpawn';
 // ── MessageUsage ──
 export const messageUsageSchema = z.object({
     input_tokens: z.number(),
@@ -52,7 +53,9 @@ const eventBaseShape = {
     promptSource: z.string().optional(),
     cwd: z.string().optional(),
     gitBranch: z.string().optional(),
-    permissionMode: permissionModeSchema.optional(),
+    // A mode this release doesn't know (Claude Code added `auto`) is dropped
+    // rather than rejecting the whole line with its prompt or tool results.
+    permissionMode: permissionModeSchema.optional().catch(undefined),
     rateLimits: z
         .object({
         primary: z
@@ -169,22 +172,21 @@ export const sessionEventSchema = z.union([
 // ── Progress unwrapping ──
 /** Recursion bound for nested progress envelopes; real data nests 1 level. */
 const MAX_PROGRESS_DEPTH = 8;
-/**
- * Extracts canonical SessionEvents from a raw JSONL value.
- *
- * Claude Code wraps subagent/SDK events as
- * `{ type: 'progress', data: { message: <SessionEvent> } }`, which
- * `sessionEventSchema` alone rejects. This helper tries a direct parse,
- * then unwraps progress envelopes (recursively, in case of nesting).
- * Returns zero events for unrecognized input — never throws.
- */
-export function extractSessionEvents(raw, depth = 0) {
-    return extractSessionEventsWithProvenance(raw, depth, {});
+export function extractSessionEvents(raw, depthOrOptions = 0) {
+    if (typeof depthOrOptions === 'number') {
+        return extractSessionEventsWithProvenance(raw, depthOrOptions, {}, {});
+    }
+    return extractSessionEventsWithProvenance(raw, 0, {}, depthOrOptions ?? {});
 }
-function extractSessionEventsWithProvenance(raw, depth, inherited) {
+function extractSessionEventsWithProvenance(raw, depth, inherited, options) {
     const direct = sessionEventSchema.safeParse(raw);
     if (direct.success)
         return [{ ...inherited, ...direct.data }];
+    if (options.includeTaskNotifications) {
+        const notification = taskNotificationAttachmentEvent(raw);
+        if (notification)
+            return [{ ...inherited, ...notification }];
+    }
     if (depth >= MAX_PROGRESS_DEPTH)
         return [];
     if (typeof raw === 'object' && raw !== null && raw.type === 'progress') {
@@ -193,12 +195,31 @@ function extractSessionEventsWithProvenance(raw, depth, inherited) {
         if (typeof data === 'object' && data !== null) {
             const message = data.message;
             if (typeof message === 'object' && message !== null) {
-                return extractSessionEventsWithProvenance(message, depth + 1, provenance);
+                return extractSessionEventsWithProvenance(message, depth + 1, provenance, options);
             }
         }
     }
     return [];
 }
+/** The `system` event for a task-notification attachment line, or `null`. */
+function taskNotificationAttachmentEvent(raw) {
+    const prompt = taskNotificationPromptFromAttachment(raw);
+    if (prompt === null)
+        return null;
+    const line = raw;
+    const candidate = {
+        type: 'system',
+        timestamp: line.timestamp,
+        origin: { kind: 'task-notification' },
+        message: { role: 'user', sourceLabel: 'task notification', content: prompt },
+    };
+    for (const key of ['entrypoint', 'isSidechain', 'cwd', 'gitBranch']) {
+        if (line[key] !== undefined)
+            candidate[key] = line[key];
+    }
+    const parsed = systemSessionEventSchema.safeParse(candidate);
+    return parsed.success ? parsed.data : null;
+}
 function progressProvenance(raw) {
     const value = raw;
     const provenance = {};

package/dist/esm/schemas/transcript.js

@@ -17,6 +17,8 @@ export const canonicalTranscriptBlockSchema = z.object({
     type: z.enum(['text', 'thinking', 'tool_use', 'tool_result', 'image', 'unknown']),
     text: z.string().optional(),
     toolName: z.string().optional(),
+    rawToolName: z.string().optional(),
+    mcpServerName: z.string().optional(),
     toolUseId: z.string().optional(),
     input: z.unknown().optional(),
     output: z.unknown().optional(),
@@ -28,6 +30,8 @@ export const canonicalTranscriptBlockSchema = z.object({
 export const canonicalToolCallSchema = z.object({
     id: z.string().optional(),
     name: z.string(),
+    rawToolName: z.string().optional(),
+    mcpServerName: z.string().optional(),
     timestamp: z.string(),
     input: z.unknown().optional(),
     output: z.unknown().optional(),

package/dist/esm/sessionPromptHistory.js

@@ -14,13 +14,13 @@
  * and replies or signals that belong to an out-of-scope prompt are dropped.
  */
 import * as fs from 'fs';
-import { DEFAULT_BOUNDS, compareStrings, emptyStats, listCandidates, resolveRoots, scanFile, } from './promptHistory';
+import { DEFAULT_BOUNDS, PROMPT_HISTORY_ORDINAL_MAX_RECORD_BYTES, compareStrings, emptyStats, listCandidates, resolveRoots, scanFile, } from './promptHistory';
 import { createSessionRecordExtractor, } from './sessionPromptSignals';
 const DEFAULT_SESSION_BOUNDS = {
     maxSessions: 1000,
     maxSessionBytes: 256 * 1024 * 1024,
     maxTotalBytes: 256 * 1024 * 1024,
-    maxRecordBytes: DEFAULT_BOUNDS.maxRecordBytes,
+    maxRecordBytes: PROMPT_HISTORY_ORDINAL_MAX_RECORD_BYTES,
     deadlineMs: 60_000,
 };
 const MAX_EXCLUSIONS = 1000;

package/dist/esm/statusline/payload.js

@@ -0,0 +1,9 @@
+/**
+ * `sidekick-shared/statusline/payload` — the pure Claude Code status-line
+ * stdin parser on its own, for hosts with a tight bundle budget that render
+ * their own line. Loads no account, credential, quota-snapshot, or network
+ * code (the full `sidekick-shared/statusline` entry does).
+ *
+ * @module statusline/payload
+ */
+export { parseClaudeStatuslinePayload, quotaFromStatuslinePayload, } from './claudeStatuslinePayload';

package/dist/esm/subagentSpawn.js

@@ -0,0 +1,163 @@
+/**
+ * Recognizes Claude Code subagent spawns and background-task notifications.
+ *
+ * Claude Code's subagent tool is `Agent`; `Task` is its earlier name (and the
+ * name OpenCode's `task` tool is normalized to). A background agent's spawning
+ * tool call gets its result right away ("Async agent launched successfully.")
+ * and its completion arrives later as a `<task-notification>` block, delivered
+ * either as a user line or as a mid-turn `queued_command` attachment.
+ *
+ * Pure: no filesystem access, so it is safe for browser bundles.
+ *
+ * @module subagentSpawn
+ */
+/** Tool names that spawn a subagent: `Agent` (current) and `Task` (earlier name). */
+export const SUBAGENT_SPAWN_TOOL_NAMES = Object.freeze(['Agent', 'Task']);
+const SPAWN_TOOLS = new Set(SUBAGENT_SPAWN_TOOL_NAMES);
+/** Whether a tool name spawns a subagent (`Agent` or `Task`). */
+export function isSubagentSpawnTool(name) {
+    return typeof name === 'string' && SPAWN_TOOLS.has(name);
+}
+const ASYNC_LAUNCH_PREFIX = /^\s*Async agent launched successfully\b/;
+const AGENT_ID_LINE = /(?:^|\n)[ \t]*agentId:[ \t]*([A-Za-z0-9][\w.@-]*)/;
+/**
+ * Plain text of tool-result or message content: a string as-is, or the text
+ * blocks of a content array joined by newlines.
+ */
+export function contentText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== 'object')
+            continue;
+        const typed = block;
+        if (typed.type === 'text' && typeof typed.text === 'string')
+            parts.push(typed.text);
+    }
+    return parts.join('\n');
+}
+/**
+ * Recognizes the immediate result of a background spawn
+ * (`Async agent launched successfully.` … `agentId: <id> …`). Accepts the
+ * result text or the raw tool-result content. Returns `null` for anything
+ * else, including a finished foreground agent's result.
+ */
+export function parseAsyncAgentLaunch(result) {
+    const text = contentText(result);
+    if (!ASYNC_LAUNCH_PREFIX.test(text))
+        return null;
+    const match = AGENT_ID_LINE.exec(text);
+    return match ? { agentId: match[1] } : {};
+}
+const NOTIFICATION_OPEN = '<task-notification>';
+const NOTIFICATION_CLOSE = '</task-notification>';
+const NOTIFICATION_PREFIX = /^\s*<task-notification>/;
+const TAG_PATTERNS = {
+    taskId: /<task-id>\s*([\s\S]*?)\s*<\/task-id>/,
+    toolUseId: /<tool-use-id>\s*([\s\S]*?)\s*<\/tool-use-id>/,
+    status: /<status>\s*([\s\S]*?)\s*<\/status>/,
+    summary: /<summary>\s*([\s\S]*?)\s*<\/summary>/,
+    note: /<note>\s*([\s\S]*?)\s*<\/note>/,
+};
+const INTERIM_TEXT = /waiting on its own background work|background work of its own still running/i;
+function tagValue(body, pattern) {
+    const value = pattern.exec(body)?.[1]?.trim();
+    return value ? value : undefined;
+}
+/**
+ * Parses the first `<task-notification>` block in `text`. Whitespace and
+ * newlines between tags, missing fields, and unknown extra fields are
+ * tolerated; the block needs a `<task-id>`. Fields are read before the
+ * agent's own `<result>` output, which may quote anything.
+ */
+export function parseTaskNotification(text) {
+    if (typeof text !== 'string')
+        return null;
+    const start = text.indexOf(NOTIFICATION_OPEN);
+    if (start < 0)
+        return null;
+    let body = text.slice(start + NOTIFICATION_OPEN.length);
+    const resultAt = body.indexOf('<result>');
+    let header = resultAt >= 0 ? body.slice(0, resultAt) : body;
+    if (resultAt < 0) {
+        const end = body.indexOf(NOTIFICATION_CLOSE);
+        if (end >= 0)
+            header = body = body.slice(0, end);
+    }
+    if (!TAG_PATTERNS.taskId.test(header))
+        header = body;
+    const taskId = tagValue(header, TAG_PATTERNS.taskId);
+    if (!taskId)
+        return null;
+    const toolUseId = tagValue(header, TAG_PATTERNS.toolUseId);
+    const status = tagValue(header, TAG_PATTERNS.status);
+    const summary = tagValue(header, TAG_PATTERNS.summary);
+    const note = tagValue(header, TAG_PATTERNS.note);
+    return {
+        taskId,
+        ...(toolUseId ? { toolUseId } : {}),
+        ...(status ? { status } : {}),
+        ...(summary ? { summary } : {}),
+        interim: INTERIM_TEXT.test(summary ?? '') || INTERIM_TEXT.test(note ?? ''),
+    };
+}
+/**
+ * The `<task-notification>` prompt of a raw Claude Code attachment line
+ * (`{ type: 'attachment', attachment: { type: 'queued_command', commandMode:
+ * 'task-notification', prompt } }`), which is how a notification that lands
+ * mid-turn is recorded. `null` for any other value.
+ */
+export function taskNotificationPromptFromAttachment(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const line = raw;
+    if (line.type !== 'attachment' || !line.attachment || typeof line.attachment !== 'object') {
+        return null;
+    }
+    const attachment = line.attachment;
+    return attachment.type === 'queued_command' &&
+        attachment.commandMode === 'task-notification' &&
+        typeof attachment.prompt === 'string'
+        ? attachment.prompt
+        : null;
+}
+/**
+ * The synthetic `system` event `extractSessionEvents(raw, {
+ * includeTaskNotifications: true })` makes from a mid-turn task-notification
+ * attachment. It is bookkeeping, not a message or a prompt.
+ */
+export function isTaskNotificationSystemEvent(event) {
+    return event.type === 'system' && event.origin?.kind === 'task-notification';
+}
+/**
+ * The task notification an event carries: a user line with
+ * `origin.kind === 'task-notification'` or whose text starts with
+ * `<task-notification>`, or the opt-in synthetic system event. `null` otherwise.
+ */
+export function taskNotificationFromEvent(event) {
+    if (event.type !== 'user' && event.type !== 'system')
+        return null;
+    const flagged = event.origin?.kind === 'task-notification';
+    if (event.type === 'system' && !flagged)
+        return null;
+    const text = contentText(event.message?.content);
+    if (!flagged && !NOTIFICATION_PREFIX.test(text))
+        return null;
+    return parseTaskNotification(text);
+}
+/** Maps a notification `<status>` to an outcome; unknown or missing statuses read as `completed`. */
+export function taskNotificationOutcome(status) {
+    switch (status?.toLowerCase()) {
+        case 'failed':
+            return 'failed';
+        case 'killed':
+            return 'killed';
+        case 'stopped':
+            return 'stopped';
+        default:
+            return 'completed';
+    }
+}

package/dist/esm/testing/credentialGuard.js

@@ -10,7 +10,8 @@
  * - `HOME` (and the Windows equivalents) point at a per-process temp dir,
  *   removed on exit, and the home overrides (`CLAUDE_CONFIG_DIR`,
  *   `CLAUDE_SECURESTORAGE_CONFIG_DIR`, `CODEX_HOME`, `SIDEKICK_CONFIG_DIR`)
- *   are unset, so every `os.homedir()`-derived path is isolated structurally;
+ *   are unset (unless named in `preserveEnv` and pointed at a fixture), so
+ *   every `os.homedir()`-derived path is isolated structurally;
  * - the real `child_process` module object is patched, which reaches both ESM
  *   named imports (after `syncBuiltinESMExports`) and CommonJS code loaded
  *   through native `require`; per-file `vi.mock('child_process')` factories
@@ -28,6 +29,13 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 const GUARD_KEY = '__sidekickCredentialGuard';
 const DEFAULT_BLOCKED_BINARIES = ['security', 'claude', 'codex'];
+/** Home overrides the guard unsets; only these can be preserved. */
+const SCRUBBED_ENV = [
+    'CLAUDE_CONFIG_DIR',
+    'CLAUDE_SECURESTORAGE_CONFIG_DIR',
+    'CODEX_HOME',
+    'SIDEKICK_CONFIG_DIR',
+];
 const CHILD_PROCESS_FUNCTIONS = [
     'spawn',
     'spawnSync',
@@ -75,6 +83,8 @@ export function installCredentialGuard(options = {}) {
     // os.userInfo() reads the passwd entry, so it still names the real home
     // after HOME is redirected below.
     const realHome = os.userInfo().homedir;
+    // Validated before any side effect, so a refused install changes nothing.
+    const preserved = checkPreservedEnv(options, realHome, realFs);
     const testHome = realFs.mkdtempSync(path.join(os.tmpdir(), 'sidekick-test-home-'));
     const removeTestHome = realFs.rmSync.bind(realFs);
     process.once('exit', () => {
@@ -103,10 +113,9 @@ export function installCredentialGuard(options = {}) {
     process.env.USERPROFILE = testHome;
     process.env.APPDATA = path.join(testHome, 'AppData', 'Roaming');
     process.env.LOCALAPPDATA = path.join(testHome, 'AppData', 'Local');
-    delete process.env.CLAUDE_CONFIG_DIR;
-    delete process.env.CLAUDE_SECURESTORAGE_CONFIG_DIR;
-    delete process.env.CODEX_HOME;
-    delete process.env.SIDEKICK_CONFIG_DIR;
+    for (const name of SCRUBBED_ENV)
+        if (!preserved.has(name))
+            delete process.env[name];
     const protectedRoots = path.resolve(realHome) === path.resolve(testHome)
         ? []
         : [
@@ -208,6 +217,79 @@ export function installCredentialGuard(options = {}) {
     globalThis[GUARD_KEY] = state;
     return state;
 }
+/** The `preserveEnv` names, after refusing unknown names and unsafe values. */
+function checkPreservedEnv(options, realHome, realFs) {
+    const preserved = new Set();
+    for (const name of options.preserveEnv ?? []) {
+        if (!SCRUBBED_ENV.includes(name)) {
+            throw new Error(`installCredentialGuard: preserveEnv accepts only ${SCRUBBED_ENV.join(', ')}; got ${JSON.stringify(name)}.`);
+        }
+        preserved.add(name);
+    }
+    if (preserved.size === 0)
+        return preserved;
+    const roots = [
+        path.join(realHome, '.claude'),
+        path.join(realHome, '.claude.json'),
+        path.join(realHome, '.codex'),
+        path.join(realHome, '.config', 'sidekick'),
+        // The Windows default config dir, read before HOME and APPDATA move.
+        ...(process.platform === 'win32' && process.env.APPDATA
+            ? [path.join(process.env.APPDATA, 'sidekick')]
+            : []),
+        ...(options.protectedPaths ?? []),
+    ];
+    for (const name of preserved) {
+        const value = process.env[name]?.trim();
+        if (!value)
+            continue;
+        const hit = protectedLocation(value, roots, realFs);
+        if (hit) {
+            throw new Error(`installCredentialGuard: preserveEnv ${name}=${value} reaches the real protected location ${hit}. Point it at a temporary fixture instead.`);
+        }
+    }
+    return preserved;
+}
+/** The root `target` equals, contains, or lies inside, comparing plain and symlink-resolved paths. */
+function protectedLocation(target, roots, realFs) {
+    // Case-insensitive by default on macOS and Windows; folding can only over-refuse.
+    const fold = process.platform === 'darwin' || process.platform === 'win32';
+    const normal = (value) => {
+        const resolved = path.resolve(value);
+        return fold ? resolved.toLowerCase() : resolved;
+    };
+    const within = (parent, child) => child === parent || child.startsWith(parent.endsWith(path.sep) ? parent : parent + path.sep);
+    const related = (a, b) => within(a, b) || within(b, a);
+    // Plain paths first, so an obviously unsafe value never reaches the filesystem.
+    const plain = normal(target);
+    for (const root of roots)
+        if (related(normal(root), plain))
+            return root;
+    const real = normal(realpathOfNearest(target, realFs));
+    for (const root of roots) {
+        const realRoot = normal(realpathOfNearest(root, realFs));
+        if (related(realRoot, real) || related(normal(root), real) || related(realRoot, plain))
+            return root;
+    }
+    return null;
+}
+/** `realpath` of the nearest existing ancestor, with the missing tail re-appended. */
+function realpathOfNearest(target, realFs) {
+    let current = path.resolve(target);
+    let tail = [];
+    for (;;) {
+        try {
+            return path.join(realFs.realpathSync.native(current), ...tail);
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return path.resolve(target);
+            tail = [path.basename(current), ...tail];
+            current = parent;
+        }
+    }
+}
 /**
  * The real module object of a Node built-in: `process.getBuiltinModule`
  * (Node 20.16+), or `require` in CommonJS on older Node.