@wix/pathgrade 0.37.0 → 1.0.1

package/dist/plugin/lifecycle.js

@@ -1,146 +1 @@
-import { setRuntime } from '../sdk/eval-runtime.js';
-import { buildDiagnosticsReport } from '../reporters/diagnostics.js';
-// Agent tracking: each test creates its own agent(s) and calls evaluate() on them.
-// Results are keyed by agent reference, which is unique per test.
-const pendingAgents = new Set();
-const agentTaskIds = new WeakMap();
-const agentResults = new WeakMap();
-function currentTaskId() {
-    try {
-        return globalThis.__vitest_worker__?.current?.id ?? '';
-    }
-    catch {
-        return '';
-    }
-}
-function trackAgent(agent) {
-    pendingAgents.add(agent);
-    const taskId = currentTaskId();
-    if (taskId)
-        agentTaskIds.set(agent, taskId);
-}
-function untrackAgent(agent) {
-    pendingAgents.delete(agent);
-}
-/**
- * Flush results and dispose agents for the current test. Agents created in
- * this test's scope are disposed after flushing. Shared agents (created in a
- * different scope, e.g. module-level or beforeAll) have their pending results
- * flushed but are kept alive for subsequent tests.
- */
-async function flush(task) {
-    const results = [];
-    const toDispose = [];
-    for (const agent of pendingAgents) {
-        const storedId = agentTaskIds.get(agent);
-        const belongsToThisTest = !storedId || storedId === task.id;
-        const meta = agentResults.get(agent);
-        if (meta && meta.length > 0) {
-            // Always flush pending results, even for shared agents
-            results.push(...meta);
-            agentResults.delete(agent);
-        }
-        if (belongsToThisTest) {
-            if (!meta || meta.length === 0) {
-                // evaluate() was never called — synthesize a trial from agent data
-                // so the reporter still surfaces token usage and command counts.
-                const synthTrial = synthesizeTrialFromAgent(agent);
-                if (synthTrial) {
-                    results.push(synthTrial);
-                }
-            }
-            pendingAgents.delete(agent);
-            toDispose.push(agent);
-        }
-    }
-    if (results.length > 0) {
-        task.meta.pathgrade = results;
-    }
-    await Promise.all(toDispose.map((a) => a.dispose().catch(() => { })));
-}
-function onResult(result, agent) {
-    if (!agentResults.has(agent)) {
-        agentResults.set(agent, []);
-    }
-    const conversationEnd = [...agent.log].reverse().find((entry) => entry.type === 'conversation_end');
-    const completionReason = conversationEnd?.completion_reason ?? (agent.log.some((entry) => entry.type === 'agent_result') ? 'completed' : undefined);
-    agentResults.get(agent).push({
-        score: result.score,
-        scorers: result.scorers,
-        trial: result.trial,
-        diagnostics: buildDiagnosticsReport({
-            completionReason,
-            completionDetail: conversationEnd?.completion_detail,
-            turnDetails: conversationEnd?.turn_details,
-            reactionsFired: conversationEnd?.reactions_fired,
-            score: result.score,
-            scorers: result.scorers,
-            log: agent.log,
-        }),
-    });
-}
-/**
- * When evaluate() is never called, synthesize a minimal trial from the agent's
- * log so the reporter still surfaces command count and token usage.
- */
-function synthesizeTrialFromAgent(agent) {
-    // Only synthesize if the agent actually ran (has log entries)
-    if (agent.log.length === 0)
-        return null;
-    const nCommands = agent.log.filter((e) => e.type === 'command').length;
-    const tokenUsage = agent.llm.tokenUsage;
-    const conversationEnd = [...agent.log].reverse().find((entry) => entry.type === 'conversation_end');
-    const completionReason = conversationEnd?.completion_reason ?? (agent.log.some((entry) => entry.type === 'agent_result') ? 'completed' : undefined);
-    return {
-        score: 1, // Will be overridden by vitest pass/fail in the reporter
-        scorers: [],
-        trial: {
-            trial_id: 0,
-            reward: 1,
-            scorer_results: [],
-            duration_ms: 0,
-            n_commands: nCommands,
-            input_tokens: tokenUsage?.inputTokens ?? 0,
-            output_tokens: tokenUsage?.outputTokens ?? 0,
-            session_log: [...agent.log],
-        },
-        diagnostics: buildDiagnosticsReport({
-            completionReason,
-            completionDetail: conversationEnd?.completion_detail,
-            turnDetails: conversationEnd?.turn_details,
-            reactionsFired: conversationEnd?.reactions_fired,
-            score: 1,
-            scorers: [],
-            log: agent.log,
-        }),
-    };
-}
-/**
- * Dispose any agents still pending at end-of-file. Shared agents (created at
- * module scope or in beforeAll) have a stored task id that won't match any
- * per-test id in afterEach, so afterAll is their only disposal opportunity.
- * Without this, sandboxes leak and `debug: true` folders never get written.
- */
-async function flushAll() {
-    const toDispose = [...pendingAgents];
-    pendingAgents.clear();
-    await Promise.all(toDispose.map((a) => a.dispose().catch(() => { })));
-}
-function reset() {
-    pendingAgents.clear();
-}
-function install(afterEach, afterAll) {
-    setRuntime({ onResult });
-    afterEach(async ({ task }) => flush(task));
-    if (afterAll)
-        afterAll(async () => flushAll());
-}
-export const lifecycle = {
-    trackAgent,
-    untrackAgent,
-    flush,
-    flushAll,
-    onResult,
-    reset,
-    install,
-};
+export { lifecycle } from '../adapters/vitest/lifecycle.js';

package/dist/plugin/reporter.d.ts

@@ -1,37 +1 @@
-import type { Reporter, TestModule } from 'vitest/node';
-import type { PathgradePluginOptions } from '../sdk/types.js';
-/**
- * Custom vitest reporter that layers pathgrade aggregate statistics
- * on top of vitest's default output.
- */
-export declare class PathgradeReporter implements Reporter {
-    private opts;
-    constructor(opts?: PathgradePluginOptions);
-    onTestRunEnd(testModules: ReadonlyArray<TestModule>): Promise<void>;
-    private collectGroups;
-    /**
-     * Group key is the parent suite's full name (file + describe hierarchy).
-     * Tests without a describe wrapper are grouped by module path.
-     */
-    private getGroupKey;
-    private toTestEntry;
-    private isReportableEntry;
-    private printCliSummary;
-    private writeJsonResults;
-    private buildEvalReport;
-    private toTrialResult;
-    private slug;
-    private openBrowserViewer;
-    private computePassRate;
-    /**
-     * pass@k = 1 - (1 - p)^k
-     * Probability of at least 1 success in k trials.
-     */
-    private computePassAtK;
-    /**
-     * pass^k = p^k
-     * Probability of all k trials succeeding.
-     */
-    private computePassPowK;
-    private computeAvgDuration;
-}
+export { PathgradeReporter } from '../adapters/vitest/reporter.js';

package/dist/plugin/reporter.js

@@ -1,280 +1 @@
-import * as path from 'path';
-import { execSync } from 'child_process';
-import { extractSkillsFromLog } from '../tool-events.js';
-import { fmt } from '../utils/cli.js';
-import { getPathgradeDir } from '../reporters/results-path.js';
-import fs from 'fs-extra';
-import { formatDiagnostics, formatDiagnosticsSummary } from '../reporters/diagnostics.js';
-import { readSidecar } from '../affected/sidecar.js';
-/**
- * Custom vitest reporter that layers pathgrade aggregate statistics
- * on top of vitest's default output.
- */
-export class PathgradeReporter {
-    opts;
-    constructor(opts) {
-        this.opts = opts ?? {};
-    }
-    async onTestRunEnd(testModules) {
-        const groups = this.collectGroups(testModules);
-        if (groups.length === 0)
-            return;
-        const mode = this.opts.reporter ?? 'cli';
-        if (mode === 'cli' || mode === 'browser') {
-            this.printCliSummary(groups);
-        }
-        await this.writeJsonResults(groups);
-        if (mode === 'browser') {
-            this.openBrowserViewer(groups);
-        }
-        // CI threshold check
-        if (this.opts.ci?.threshold != null) {
-            const allScores = groups.flatMap((g) => g.tests.map((t) => t.score));
-            if (allScores.length > 0) {
-                const avg = allScores.reduce((a, b) => a + b, 0) / allScores.length;
-                if (avg < this.opts.ci.threshold) {
-                    console.log(`\n  ${fmt.fail('CI THRESHOLD FAILED')}  avg score ${fmt.bold(avg.toFixed(3))} < threshold ${fmt.bold(String(this.opts.ci.threshold))}\n`);
-                    process.exitCode = 1;
-                }
-            }
-        }
-    }
-    collectGroups(testModules) {
-        const groupMap = new Map();
-        for (const mod of testModules) {
-            for (const testCase of mod.children.allTests()) {
-                const groupKey = this.getGroupKey(testCase);
-                const entry = this.toTestEntry(testCase);
-                if (!this.isReportableEntry(entry))
-                    continue;
-                if (!groupMap.has(groupKey)) {
-                    groupMap.set(groupKey, []);
-                }
-                groupMap.get(groupKey).push(entry);
-            }
-        }
-        return Array.from(groupMap.entries()).map(([groupName, tests]) => ({
-            groupName,
-            tests,
-        }));
-    }
-    /**
-     * Group key is the parent suite's full name (file + describe hierarchy).
-     * Tests without a describe wrapper are grouped by module path.
-     */
-    getGroupKey(testCase) {
-        const parent = testCase.parent;
-        const modulePath = testCase.module.relativeModuleId;
-        if (parent.type === 'suite') {
-            return `${modulePath} > ${parent.fullName}`;
-        }
-        return modulePath;
-    }
-    toTestEntry(testCase) {
-        const meta = testCase.meta();
-        const pathgradeMeta = meta.pathgrade;
-        const diag = testCase.diagnostic();
-        const result = testCase.result();
-        let score = 0;
-        let trial;
-        let diagnostics;
-        if (pathgradeMeta === undefined) {
-            // Test didn't use pathgrade — infer from test pass/fail
-            score = result.state === 'passed' ? 1 : 0;
-        }
-        else if (pathgradeMeta.length === 0) {
-            // Anomaly: pathgrade was set up but evaluate() was never called
-            console.warn(`  [pathgrade] warning: empty results for "${testCase.name}" — evaluate() may not have been called`);
-            score = result.state === 'passed' ? 1 : 0;
-        }
-        else {
-            // Use the last eval result's score
-            score = pathgradeMeta[pathgradeMeta.length - 1].score;
-            trial = pathgradeMeta[pathgradeMeta.length - 1].trial;
-            diagnostics = pathgradeMeta[pathgradeMeta.length - 1].diagnostics;
-        }
-        return {
-            name: testCase.name,
-            score,
-            durationMs: diag?.duration ?? 0,
-            state: result.state === 'pending' ? 'pending' : result.state,
-            trial,
-            diagnostics,
-        };
-    }
-    isReportableEntry(entry) {
-        return entry.state !== 'skipped' && entry.state !== 'pending';
-    }
-    printCliSummary(groups) {
-        console.log(`\n${fmt.bold('── pathgrade summary ')}${fmt.dim('─'.repeat(40))}\n`);
-        const forceVerbose = this.opts.diagnostics === true || process.env.PATHGRADE_DIAGNOSTICS === '1';
-        const currentTimeoutMs = this.opts.timeout != null ? this.opts.timeout * 1000 : undefined;
-        for (const group of groups) {
-            const k = group.tests.length;
-            const passRate = this.computePassRate(group.tests);
-            const passAtK = this.computePassAtK(passRate, k);
-            const passPowK = this.computePassPowK(passRate, k);
-            const avgDuration = this.computeAvgDuration(group.tests);
-            const prColor = passRate >= 0.5 ? fmt.green : fmt.red;
-            console.log(`  ${fmt.bold(group.groupName)}`);
-            console.log(`    ${fmt.dim('pass rate'.padEnd(12))} ${prColor((passRate * 100).toFixed(1) + '%')}`);
-            console.log(`    ${fmt.dim(`pass@${k}`.padEnd(12))} ${(passAtK * 100).toFixed(1)}%`);
-            console.log(`    ${fmt.dim(`pass^${k}`.padEnd(12))} ${(passPowK * 100).toFixed(1)}%`);
-            console.log(`    ${fmt.dim('avg time'.padEnd(12))} ${(avgDuration / 1000).toFixed(1)}s`);
-            console.log(`    ${fmt.dim('trials'.padEnd(12))} ${k}`);
-            console.log();
-            for (const test of group.tests) {
-                if (!test.diagnostics)
-                    continue;
-                const shouldPrintFull = forceVerbose || test.state !== 'passed' || test.diagnostics.completionReason === 'timeout' || test.diagnostics.completionReason === 'agent_crashed';
-                console.log(`    ${fmt.bold(test.name)}`);
-                const formatted = shouldPrintFull
-                    ? formatDiagnostics(test.diagnostics, { verbose: true, currentTimeoutMs })
-                    : formatDiagnosticsSummary(test.diagnostics);
-                for (const line of formatted.split('\n')) {
-                    console.log(`      ${line}`);
-                }
-                console.log();
-            }
-        }
-    }
-    async writeJsonResults(groups) {
-        const outputDir = getPathgradeDir(process.cwd());
-        const tracesDir = path.join(outputDir, 'traces');
-        await fs.ensureDir(tracesDir);
-        // Auto-create .gitignore if it doesn't exist
-        const gitignorePath = path.join(outputDir, '.gitignore');
-        if (!(await fs.pathExists(gitignorePath))) {
-            await fs.writeFile(gitignorePath, '*\n');
-        }
-        const allScores = groups.flatMap((g) => g.tests.map((t) => t.score));
-        const overallPassRate = allScores.length > 0
-            ? allScores.reduce((a, b) => a + b, 0) / allScores.length
-            : 0;
-        const threshold = this.opts.ci?.threshold;
-        const status = threshold != null
-            ? (overallPassRate >= threshold ? 'pass' : 'fail')
-            : (groups.every(g => g.tests.every(t => t.state === 'passed')) ? 'pass' : 'fail');
-        const consolidatedGroups = [];
-        for (const group of groups) {
-            const report = this.buildEvalReport(group);
-            const slug = this.slug(group.groupName);
-            const traceFile = `traces/${slug}.json`;
-            // Write full trace data (with session_log and conversation)
-            await fs.writeJson(path.join(outputDir, traceFile), report.trials, { spaces: 2 });
-            // Strip session_log and conversation from trials in consolidated report
-            const strippedTrials = report.trials.map(t => {
-                const { session_log, conversation, ...rest } = t;
-                return rest;
-            });
-            const { trials: _omitted, ...rest } = report;
-            consolidatedGroups.push({
-                ...rest,
-                trials: strippedTrials,
-                trace_file: traceFile,
-            });
-        }
-        // Merge selection metadata from the CLI-written sidecar, if any.
-        // Missing sidecar → plain run; malformed → warn and proceed without it.
-        const selection = await readSidecar(process.cwd(), msg => {
-            console.warn(`[pathgrade] ${msg}`);
-        });
-        const consolidated = {
-            version: 1,
-            timestamp: new Date().toISOString(),
-            ...(threshold != null ? { threshold } : {}),
-            overall_pass_rate: overallPassRate,
-            status,
-            groups: consolidatedGroups,
-            ...(selection ? { selection } : {}),
-        };
-        await fs.writeJson(path.join(outputDir, 'results.json'), consolidated, { spaces: 2 });
-        console.log(`\n  ${fmt.dim('Results written to')} ${outputDir}\n`);
-    }
-    buildEvalReport(group) {
-        const trials = group.tests.map((test, index) => this.toTrialResult(test, index));
-        const passRate = this.computePassRate(group.tests);
-        // Aggregate skills_used across all trials (deduplicated)
-        const allSkills = new Set();
-        for (const trial of trials) {
-            for (const skill of trial.skills_used ?? []) {
-                allSkills.add(skill);
-            }
-        }
-        return {
-            task: group.groupName,
-            pass_rate: passRate,
-            pass_at_k: this.computePassAtK(passRate, trials.length),
-            pass_pow_k: this.computePassPowK(passRate, trials.length),
-            trials,
-            skills_used: [...allSkills],
-        };
-    }
-    toTrialResult(test, index) {
-        const base = test.trial ?? {
-            trial_id: index + 1,
-            reward: test.score,
-            scorer_results: [],
-            duration_ms: test.durationMs,
-            n_commands: 0,
-            input_tokens: 0,
-            output_tokens: 0,
-            session_log: [],
-        };
-        // Extract skills_used from session_log tool events if not already present
-        const skills = base.skills_used ?? extractSkillsFromLog(base.session_log);
-        return {
-            ...base,
-            trial_id: index + 1,
-            name: test.name,
-            duration_ms: base.duration_ms || test.durationMs,
-            diagnostics: test.diagnostics ?? base.diagnostics,
-            ...(skills.length > 0 ? { skills_used: skills } : {}),
-        };
-    }
-    slug(value) {
-        return value
-            .toLowerCase()
-            .replace(/[^a-z0-9]+/g, '-')
-            .replace(/^-+|-+$/g, '') || 'report';
-    }
-    openBrowserViewer(_groups) {
-        // Write results JSON first, then open the viewer
-        const viewerPath = path.resolve(import.meta.dirname, '..', 'viewer.html');
-        try {
-            const openCmd = process.platform === 'darwin' ? 'open'
-                : process.platform === 'win32' ? 'start'
-                    : 'xdg-open';
-            execSync(`${openCmd} "${viewerPath}"`, { stdio: 'ignore' });
-            console.log(`\n  ${fmt.dim('Opened viewer in browser')}\n`);
-        }
-        catch {
-            console.log(`\n  ${fmt.dim('Open manually:')} ${viewerPath}\n`);
-        }
-    }
-    computePassRate(tests) {
-        if (tests.length === 0)
-            return 0;
-        const passed = tests.filter((t) => t.state === 'passed').length;
-        return passed / tests.length;
-    }
-    /**
-     * pass@k = 1 - (1 - p)^k
-     * Probability of at least 1 success in k trials.
-     */
-    computePassAtK(passRate, k) {
-        return 1 - Math.pow(1 - passRate, k);
-    }
-    /**
-     * pass^k = p^k
-     * Probability of all k trials succeeding.
-     */
-    computePassPowK(passRate, k) {
-        return Math.pow(passRate, k);
-    }
-    computeAvgDuration(tests) {
-        if (tests.length === 0)
-            return 0;
-        return tests.reduce((sum, t) => sum + t.durationMs, 0) / tests.length;
-    }
-}
+export { PathgradeReporter } from '../adapters/vitest/reporter.js';

package/dist/plugin/setup.d.ts

@@ -1 +1 @@
-export {};
+import '../adapters/vitest/setup.js';

package/dist/plugin/setup.js

@@ -1,3 +1 @@
-import { afterAll, afterEach } from 'vitest';
-import { lifecycle } from './lifecycle.js';
-lifecycle.install(afterEach, afterAll);
+import '../adapters/vitest/setup.js';

package/dist/providers/copy-filter.d.ts

@@ -16,3 +16,8 @@ export declare const DEFAULT_COPY_IGNORE: readonly string[];
  *   Pass `[]` to disable filtering. Invalid glob patterns are silently ignored.
  */
 export declare function createCopyFilter(ignorePatterns: readonly string[]): (src: string) => boolean;
+/**
+ * fs-extra cannot copy sockets, FIFOs, or device files. Host config caches can
+ * contain transient sockets, so filter them out before copy() reaches them.
+ */
+export declare function isPortableCopyEntry(src: string): boolean;

package/dist/providers/copy-filter.js

@@ -5,6 +5,7 @@
  * when copying workspace/skill directories into the sandbox.
  */
 import * as path from 'path';
+import * as fs from 'fs';
 import picomatch from 'picomatch';
 /**
  * Default ignore patterns applied when copying workspace and skill directories.
@@ -64,3 +65,11 @@ export function createCopyFilter(ignorePatterns) {
         return true;
     };
 }
+/**
+ * fs-extra cannot copy sockets, FIFOs, or device files. Host config caches can
+ * contain transient sockets, so filter them out before copy() reaches them.
+ */
+export function isPortableCopyEntry(src) {
+    const stat = fs.lstatSync(src);
+    return stat.isFile() || stat.isDirectory() || stat.isSymbolicLink();
+}

package/dist/providers/credentials.js

@@ -95,7 +95,7 @@ async function resolveClaude(userEnv, ports) {
             return {
                 env: { PATHGRADE_CLAUDE_LOCAL_OAUTH: '1' },
                 setupCommands: [],
-                copyFromHome: ['.claude.json'],
+                copyFromHome: [],
                 linkFromHome: ['Library/Keychains'],
             };
         }

package/dist/providers/sandbox-lifecycle.d.ts

@@ -0,0 +1,22 @@
+export declare const SANDBOX_PREFIX = "pathgrade-";
+export declare const SANDBOX_MARKER = ".pathgrade-sandbox.json";
+export declare const STALE_SANDBOX_AGE_MS: number;
+interface RemoveSandboxRootOptions {
+    remove?: (target: string) => Promise<void>;
+    sleep?: (ms: number) => Promise<void>;
+    retryDelaysMs?: readonly number[];
+}
+export declare function removeSandboxRoot(rootDir: string, opts?: RemoveSandboxRootOptions): Promise<void>;
+export interface StaleSandboxCleanupOptions extends RemoveSandboxRootOptions {
+    tempDir?: string;
+    now?: () => number;
+    isProcessAlive?: (pid: number) => boolean;
+}
+/**
+ * Removes old, crashed PathGrade sandboxes without examining anything outside
+ * the resolved operating-system temp directory. Every filesystem failure is
+ * intentionally ignored so a cleanup race never prevents a new trial.
+ */
+export declare function cleanupStaleSandboxes(opts?: StaleSandboxCleanupOptions): Promise<void>;
+export declare function createSandboxRoot(): Promise<string>;
+export {};

package/dist/providers/sandbox-lifecycle.js

@@ -0,0 +1,133 @@
+import fs from 'fs-extra';
+import * as os from 'os';
+import * as path from 'path';
+export const SANDBOX_PREFIX = 'pathgrade-';
+export const SANDBOX_MARKER = '.pathgrade-sandbox.json';
+export const STALE_SANDBOX_AGE_MS = 24 * 60 * 60 * 1_000;
+let startupCleanup;
+const SANDBOX_REMOVE_RETRY_DELAYS_MS = [
+    50,
+    100,
+    250,
+    500,
+    1_000,
+    2_000,
+    3_000,
+    5_000,
+];
+function isRetryableRemoveError(error) {
+    const code = error.code;
+    return code === 'ENOTEMPTY' || code === 'EBUSY' || code === 'EPERM';
+}
+export async function removeSandboxRoot(rootDir, opts = {}) {
+    const remove = opts.remove ?? ((target) => fs.remove(target));
+    const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const retryDelaysMs = opts.retryDelaysMs ?? SANDBOX_REMOVE_RETRY_DELAYS_MS;
+    for (let attempt = 0;; attempt++) {
+        try {
+            await remove(rootDir);
+            return;
+        }
+        catch (error) {
+            if (!isRetryableRemoveError(error) || attempt >= retryDelaysMs.length) {
+                throw error;
+            }
+            await sleep(retryDelaysMs[attempt]);
+        }
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // A process we cannot signal is still live. Unknown failures are also
+        // preserved: cleanup must fail safe rather than delete a live trial.
+        return error.code !== 'ESRCH';
+    }
+}
+async function readOwnedSandboxMarker(rootDir) {
+    const rootStat = await fs.lstat(rootDir);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        return undefined;
+    const markerPath = path.join(rootDir, SANDBOX_MARKER);
+    const markerStat = await fs.lstat(markerPath);
+    if (!markerStat.isFile() || markerStat.isSymbolicLink())
+        return undefined;
+    const marker = JSON.parse(await fs.readFile(markerPath, 'utf8'));
+    const pid = marker.pid;
+    if (marker.version !== 1 || typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid <= 0)
+        return undefined;
+    return { version: 1, pid };
+}
+async function isStaleOwnedSandbox(rootDir, now, staleAfterMs, processIsAlive) {
+    const marker = await readOwnedSandboxMarker(rootDir);
+    if (!marker)
+        return false;
+    const markerStat = await fs.lstat(path.join(rootDir, SANDBOX_MARKER));
+    if (now - markerStat.mtimeMs < staleAfterMs)
+        return false;
+    return !processIsAlive(marker.pid);
+}
+/**
+ * Removes old, crashed PathGrade sandboxes without examining anything outside
+ * the resolved operating-system temp directory. Every filesystem failure is
+ * intentionally ignored so a cleanup race never prevents a new trial.
+ */
+export async function cleanupStaleSandboxes(opts = {}) {
+    let tempDir;
+    try {
+        tempDir = await fs.realpath(opts.tempDir ?? os.tmpdir());
+    }
+    catch {
+        return;
+    }
+    const now = opts.now ?? Date.now;
+    const processIsAlive = opts.isProcessAlive ?? isProcessAlive;
+    let entries;
+    try {
+        entries = await fs.readdir(tempDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.isSymbolicLink() || !entry.name.startsWith(SANDBOX_PREFIX))
+            continue;
+        const rootDir = path.resolve(tempDir, entry.name);
+        if (path.dirname(rootDir) !== tempDir)
+            continue;
+        try {
+            if (!await isStaleOwnedSandbox(rootDir, now(), STALE_SANDBOX_AGE_MS, processIsAlive))
+                continue;
+            // Re-check ownership and liveness immediately before removal. This
+            // narrows the window where another process can replace a candidate.
+            if (!await isStaleOwnedSandbox(rootDir, now(), STALE_SANDBOX_AGE_MS, processIsAlive))
+                continue;
+            await removeSandboxRoot(rootDir, opts);
+        }
+        catch {
+            // A disappeared directory, a permission change, or a deletion race
+            // must never make trial creation fail.
+        }
+    }
+}
+export async function createSandboxRoot() {
+    // A process may create many trial sandboxes. Scan only once at startup so
+    // repeated trials do not pay to enumerate the entire operating-system temp
+    // directory, while concurrent creators share the same best-effort sweep.
+    startupCleanup ??= cleanupStaleSandboxes();
+    await startupCleanup;
+    const tempDir = await fs.realpath(os.tmpdir());
+    const rootDir = await fs.mkdtemp(path.join(tempDir, SANDBOX_PREFIX));
+    const marker = { version: 1, pid: process.pid };
+    try {
+        await fs.writeFile(path.join(rootDir, SANDBOX_MARKER), JSON.stringify(marker), 'utf8');
+        return rootDir;
+    }
+    catch (error) {
+        await fs.remove(rootDir).catch(() => { });
+        throw error;
+    }
+}