windows-development-sandbox 1.5.0 → 1.9.0

package/dist/host/engines/types.d.ts

@@ -0,0 +1,58 @@
+import type { Config, ResolvedMapping } from '../../core/types.js';
+import type { StorageAttachment } from '../storage/providers/index.js';
+export type EngineId = Config['sandbox']['engine'];
+export interface EngineCapabilities {
+    readonly desktop: boolean;
+    readonly gpu: boolean;
+    readonly clipboard: boolean;
+    readonly audio: boolean;
+    readonly video: boolean;
+    readonly printers: boolean;
+    /** Folders can be added to a running sandbox. */
+    readonly liveFolderAdd: boolean;
+    readonly attachedDisks: boolean;
+    readonly multipleInstances: boolean;
+    readonly hvsocket: boolean;
+}
+export interface EngineCheck {
+    readonly available: boolean;
+    readonly reasons: readonly string[];
+    readonly fixes: readonly string[];
+}
+export interface LaunchDevices {
+    readonly gpu: boolean;
+    readonly clipboard: boolean;
+    readonly audioInput: boolean;
+    readonly videoInput: boolean;
+    readonly printers: boolean;
+    readonly protectedClient: boolean;
+}
+/** One launch, whatever runs it. Pure data: nothing in it is engine-specific. */
+export interface LaunchPlan {
+    /** The launch folder: where an engine writes its own files. */
+    readonly launchPath: string;
+    readonly memoryMb: number;
+    /** Percent of this PC's CPU, or 'none'. The guest applies it; an engine may use it as a hint. */
+    readonly cpuLimit: 'none' | number;
+    readonly networking: boolean;
+    readonly devices: LaunchDevices;
+    /** Every folder shared in, in order (the folder attachments of `storage` are among them). */
+    readonly mappings: readonly ResolvedMapping[];
+    /** The command the guest runs at logon. */
+    readonly logonCommand: string;
+    readonly storage: readonly StorageAttachment[];
+}
+/** What an engine made of a LaunchPlan: files to write and the one to start from. Callers do not look inside. */
+export interface EnginePlan {
+    readonly engine: EngineId;
+    readonly files: readonly {
+        readonly path: string;
+        readonly text: string;
+    }[];
+    readonly entry: string;
+}
+export interface RunningSandbox {
+    readonly id: string;
+    readonly engine: EngineId;
+    readonly started: number;
+}

package/dist/host/engines/types.js

@@ -0,0 +1 @@
+export {};

package/dist/host/engines/windows-sandbox/engine.d.ts

@@ -0,0 +1,16 @@
+import type { Config } from '../../../core/types.js';
+import type { SandboxEngine } from '../engine.js';
+import type { EngineCapabilities, EngineCheck, EnginePlan, LaunchPlan, RunningSandbox } from '../types.js';
+export declare class WindowsSandboxEngine implements SandboxEngine {
+    private readonly sandbox;
+    private readonly hasWsbCli;
+    readonly id = "windows-sandbox";
+    /** `hasWsbCli`: whether wsb.exe is on this PC (adding folders to a running sandbox needs it). */
+    constructor(sandbox: Config['sandbox'], hasWsbCli?: () => boolean);
+    capabilities(): EngineCapabilities;
+    check(): Promise<EngineCheck>;
+    plan(launch: LaunchPlan): EnginePlan;
+    start(plan: EnginePlan): Promise<RunningSandbox>;
+    running(): Promise<boolean>;
+    stop(): Promise<void>;
+}

package/dist/host/engines/windows-sandbox/engine.js

@@ -0,0 +1,63 @@
+// Windows Sandbox behind the engine interface: the .wsb file, and the existing start / wait / running code.
+import path from 'node:path';
+import { fail, isWin } from '../../../core/util/index.js';
+import { confirmSandboxStarted, findWsb, isSandboxRunning, sandboxFeatureInstalled, startSandbox, } from '../../sandbox/index.js';
+import { wsbText } from './wsb-text.js';
+const WSB_FILE = 'agent.wsb';
+export class WindowsSandboxEngine {
+    sandbox;
+    hasWsbCli;
+    id = 'windows-sandbox';
+    /** `hasWsbCli`: whether wsb.exe is on this PC (adding folders to a running sandbox needs it). */
+    constructor(sandbox, hasWsbCli = () => findWsb() !== null) {
+        this.sandbox = sandbox;
+        this.hasWsbCli = hasWsbCli;
+    }
+    capabilities() {
+        return {
+            desktop: true,
+            gpu: this.sandbox.vGpu,
+            clipboard: this.sandbox.clipboard,
+            audio: this.sandbox.audioInput,
+            video: this.sandbox.videoInput,
+            printers: this.sandbox.printerRedirection,
+            liveFolderAdd: this.hasWsbCli(),
+            attachedDisks: false,
+            multipleInstances: false,
+            hvsocket: false,
+        };
+    }
+    check() {
+        if (!isWin)
+            return Promise.resolve({
+                available: false,
+                reasons: ['Windows Sandbox only runs on Windows.'],
+                fixes: ['Use sandbox generate to only write the files.'],
+            });
+        if (!sandboxFeatureInstalled())
+            return Promise.resolve({
+                available: false,
+                reasons: ['Windows Sandbox is not enabled on this PC.'],
+                fixes: [
+                    'Run in an admin PowerShell, then reboot: Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All  (needs Windows Pro, Enterprise or Education)',
+                ],
+            });
+        return Promise.resolve({ available: true, reasons: [], fixes: [] });
+    }
+    plan(launch) {
+        const entry = path.join(launch.launchPath, WSB_FILE);
+        return { engine: this.id, files: [{ path: entry, text: wsbText(launch) }], entry };
+    }
+    async start(plan) {
+        startSandbox(plan.entry);
+        await confirmSandboxStarted(plan.entry);
+        return { id: path.basename(path.dirname(plan.entry)), engine: this.id, started: Date.now() };
+    }
+    running() {
+        return Promise.resolve(isSandboxRunning());
+    }
+    stop() {
+        // Windows Sandbox shuts itself down from inside, through the session channel; it is never killed from outside.
+        return Promise.resolve().then(() => fail('Windows Sandbox is not stopped from outside.', 'Use sandbox stop (it shuts down from inside).'));
+    }
+}

package/dist/host/engines/windows-sandbox/wsb-text.d.ts

@@ -0,0 +1,2 @@
+import type { LaunchPlan } from '../types.js';
+export declare function wsbText(plan: LaunchPlan): string;

package/dist/host/engines/windows-sandbox/wsb-text.js

@@ -0,0 +1,29 @@
+// The .wsb file Windows Sandbox starts from: memory, devices and the folders mapped in, written from a LaunchPlan.
+import { xmlEscape } from '../../../core/util/index.js';
+import { sandboxFolder } from '../../../shared/paths/index.js';
+function element(name, value) {
+    return '<' + name + '>' + value + '</' + name + '>';
+}
+function toggle(value) {
+    return value ? 'Enable' : 'Disable';
+}
+export function wsbText(plan) {
+    const d = plan.devices;
+    // Guest paths on other drive letters (F:\x) really live under C:\Mirror\F; bootstrap.ps1 substs F: onto it at boot.
+    const folders = plan.mappings
+        .map((m) => element('MappedFolder', element('HostFolder', xmlEscape(m.host)) +
+        element('SandboxFolder', xmlEscape(sandboxFolder(m.guest))) +
+        element('ReadOnly', String(m.readOnly))))
+        .join('');
+    // The elements are in the order Windows Sandbox expects.
+    return element('Configuration', element('MemoryInMB', String(plan.memoryMb)) +
+        element('vGPU', toggle(d.gpu)) +
+        element('Networking', toggle(plan.networking)) +
+        element('ClipboardRedirection', toggle(d.clipboard)) +
+        element('AudioInput', toggle(d.audioInput)) +
+        element('VideoInput', toggle(d.videoInput)) +
+        element('PrinterRedirection', toggle(d.printers)) +
+        element('ProtectedClient', toggle(d.protectedClient)) +
+        element('MappedFolders', folders) +
+        element('LogonCommand', element('Command', xmlEscape(plan.logonCommand))));
+}

package/dist/host/health/acl-read.d.ts

@@ -0,0 +1,17 @@
+/** The Windows group of the users who may use a shared sandbox. */
+export declare const SHARING_GROUP = "Agent Sandbox Users";
+export interface AclEntry {
+    readonly principal: string;
+    /** The flags in order, e.g. "(OI)(CI)(F)". */
+    readonly flags: string;
+    readonly inherited: boolean;
+    readonly deny: boolean;
+}
+/** Entries of `icacls` output for `dir` (the first line starts with the folder's path). */
+export declare function parseIcacls(text: string, dir: string): AclEntry[];
+/** The entries that make a folder readable by more than you, SYSTEM and Administrators (empty: it is private). */
+export declare function privacyProblems(entries: readonly AclEntry[], groupName: string): string[];
+/** Entries of the sharing group (the folders it may enter only while a shared sandbox runs). */
+export declare function groupEntries(entries: readonly AclEntry[], groupName: string): AclEntry[];
+/** The folders a sharing plan touches for one user's data set: the storage folder, data folder, data set and run. */
+export declare function sharedFolders(storageUserDir: string, dataPath: string): string[];

package/dist/host/health/acl-read.js

@@ -0,0 +1,45 @@
+// Reading a folder's permissions from `icacls <folder>` (read only): who has an entry, and is it inherited. Used to
+// tell whether a user's data folder is private and whether the sharing group still has entries on folders it should
+// not.
+import path from 'node:path';
+/** The Windows group of the users who may use a shared sandbox. */
+export const SHARING_GROUP = 'Agent Sandbox Users';
+/** Entries of `icacls` output for `dir` (the first line starts with the folder's path). */
+export function parseIcacls(text, dir) {
+    const entries = [];
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        let line = lines[i];
+        if (/^\s*(Successfully processed|Failed processing)/i.test(line))
+            break;
+        if (i === 0 && line.toLowerCase().startsWith(dir.toLowerCase()))
+            line = line.slice(dir.length);
+        const m = /^\s*(\S.*?):((?:\([A-Za-z0-9,]+\))+)\s*$/.exec(line);
+        if (!m)
+            continue;
+        entries.push({
+            principal: m[1].trim(),
+            flags: m[2],
+            inherited: m[2].includes('(I)'),
+            deny: m[2].includes('(DENY)'),
+        });
+    }
+    return entries;
+}
+const BROAD = /(^|\\)(Everyone|Users|Authenticated Users)$/i;
+/** The entries that make a folder readable by more than you, SYSTEM and Administrators (empty: it is private). */
+export function privacyProblems(entries, groupName) {
+    const group = new RegExp('(^|\\\\)' + groupName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '$', 'i');
+    return entries
+        .filter((e) => !e.deny && (BROAD.test(e.principal) || group.test(e.principal) || e.inherited))
+        .map((e) => e.principal + (e.inherited ? ' (inherited)' : ''));
+}
+/** Entries of the sharing group (the folders it may enter only while a shared sandbox runs). */
+export function groupEntries(entries, groupName) {
+    const group = new RegExp('(^|\\\\)' + groupName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '$', 'i');
+    return entries.filter((e) => group.test(e.principal));
+}
+/** The folders a sharing plan touches for one user's data set: the storage folder, data folder, data set and run. */
+export function sharedFolders(storageUserDir, dataPath) {
+    return [storageUserDir, path.dirname(dataPath), dataPath, path.join(dataPath, 'run')];
+}

package/dist/host/health/config-backup.d.ts

@@ -0,0 +1,11 @@
+export interface ConfigBackup {
+    readonly folder: string;
+    /** The saved copy of the settings file. */
+    readonly copy: string;
+    /** From the folder name: "1.4.0 to 1.5.0 at 2026-10-14 09:30:12". */
+    readonly label: string;
+}
+/** Saved copies of `configFile`, newest first. A backup with no readable manifest or no such copy is skipped. */
+export declare function configBackups(storageRoot: string, configFile: string): ConfigBackup[];
+/** A short line difference: "- line" only in `current`, "+ line" only in `backup`; at most `max` lines. */
+export declare function lineDiff(current: string, backup: string, max?: number): string[];

package/dist/host/health/config-backup.js

@@ -0,0 +1,73 @@
+// The copies of config.json that an update saved before it changed anything (<storage>\backups\migrate-*\), so a
+// settings file that no longer loads can be put back. Read only; the caller shows the difference first and keeps the
+// broken file.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { assertNoLinks, dirExists } from '../../core/util/index.js';
+import { readValid } from '../../shared/io/index.js';
+const ManifestSchema = z.object({
+    entries: z.array(z.object({ original: z.string(), copy: z.string(), existed: z.boolean() })),
+});
+const MAX_CONFIG_BYTES = 1024 * 1024;
+/** The stamp in migrate-<from>-<to>-<yyyymmddhhmmss>[-n] folder names. */
+function stampOf(name) {
+    return /-(\d{14})(?:-\d+)?$/.exec(name)?.[1] ?? '';
+}
+function labelOf(name) {
+    const m = /^migrate-(.+?)-(.+?)-(\d{4})(\d\d)(\d\d)(\d\d)(\d\d)(\d\d)(?:-\d+)?$/.exec(name);
+    return m
+        ? m[1] + ' to ' + m[2] + ' at ' + m[3] + '-' + m[4] + '-' + m[5] + ' ' + m[6] + ':' + m[7] + ':' + m[8]
+        : name;
+}
+/** Saved copies of `configFile`, newest first. A backup with no readable manifest or no such copy is skipped. */
+export function configBackups(storageRoot, configFile) {
+    const dir = path.join(storageRoot, 'backups');
+    if (!dirExists(dir))
+        return [];
+    assertNoLinks(storageRoot, dir);
+    const found = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.startsWith('migrate-'))
+            continue;
+        const folder = path.join(dir, name);
+        const manifest = readValid(ManifestSchema, path.join(folder, 'manifest.json'));
+        const entry = manifest?.entries.find((e) => e.existed && path.resolve(e.original).toLowerCase() === path.resolve(configFile).toLowerCase());
+        if (!entry)
+            continue;
+        // The manifest is data on disk: the copy must be a file inside this backup folder, and small.
+        const copy = path.resolve(entry.copy);
+        if (!copy.toLowerCase().startsWith(path.resolve(folder).toLowerCase() + path.sep))
+            continue;
+        try {
+            assertNoLinks(storageRoot, copy);
+            const stat = fs.statSync(copy);
+            if (!stat.isFile() || stat.size > MAX_CONFIG_BYTES)
+                continue;
+        }
+        catch {
+            continue;
+        }
+        found.push({ folder, copy, label: labelOf(name) });
+    }
+    return found.sort((a, b) => stampOf(path.basename(b.folder)).localeCompare(stampOf(path.basename(a.folder))));
+}
+/** A short line difference: "- line" only in `current`, "+ line" only in `backup`; at most `max` lines. */
+export function lineDiff(current, backup, max = 12) {
+    const split = (t) => t
+        .replace(/\r\n/g, '\n')
+        .split('\n')
+        .map((l) => l.trimEnd())
+        .filter((l) => l.trim() !== '');
+    const a = split(current);
+    const b = split(backup);
+    const inB = new Set(b);
+    const inA = new Set(a);
+    const lines = [
+        ...a.filter((l) => !inB.has(l)).map((l) => '- ' + l.trim()),
+        ...b.filter((l) => !inA.has(l)).map((l) => '+ ' + l.trim()),
+    ];
+    return lines.length > max
+        ? [...lines.slice(0, max), '... and ' + (lines.length - max) + ' more changed lines']
+        : lines;
+}

package/dist/host/health/index.d.ts

@@ -0,0 +1,6 @@
+export * from './system.js';
+export * from './install-state.js';
+export * from './acl-read.js';
+export * from './stale.js';
+export * from './config-backup.js';
+export * from './path-copies.js';

package/dist/host/health/index.js

@@ -0,0 +1,7 @@
+// Looking at the install, the data folders and what a closed sandbox leaves behind: the host side of doctor and repair.
+export * from './system.js';
+export * from './install-state.js';
+export * from './acl-read.js';
+export * from './stale.js';
+export * from './config-backup.js';
+export * from './path-copies.js';

package/dist/host/health/install-state.d.ts

@@ -0,0 +1,33 @@
+import { type InstallLayout } from '../install/index.js';
+export interface PointerState {
+    readonly activeVersion: string | null;
+    readonly activeNode: string | null;
+    /** Versions that have a package.json, oldest first. */
+    readonly versions: readonly string[];
+    /** Node folders that have node.exe, oldest first. */
+    readonly nodes: readonly string[];
+    readonly problems: readonly string[];
+    /** Where the pointers should point to be whole again, or null when nothing usable is installed. */
+    readonly want: {
+        readonly version: string;
+        readonly node: string;
+    } | null;
+}
+/** Node versions under <root>\node that really hold node.exe, oldest first. */
+export declare function installedNodes(layout: InstallLayout): string[];
+/** Versions that are really there (a package.json in their package folder), oldest first. */
+export declare function completeVersions(layout: InstallLayout): string[];
+/** Looks at active-version and active-node. */
+export declare function inspectPointers(layout: InstallLayout): PointerState;
+/** Moves the pointers to what is installed (the newest version and Node that are whole). Returns what changed. */
+export declare function repairPointers(layout: InstallLayout, state?: PointerState): string;
+/** The commands a package folder declares (name -> program path), or null when its package.json cannot be read. */
+export declare function binsOfPackage(packageDir: string): Record<string, string> | null;
+export interface ShimProblems {
+    readonly missing: readonly string[];
+    readonly different: readonly string[];
+}
+/** Shim files (both the .cmd and the shell one) that are missing or not what shimText() writes now. */
+export declare function shimProblems(layout: InstallLayout, bins: Record<string, string>): ShimProblems;
+/** Is `dir` one of the entries of a PATH value (variables expanded, case and a trailing slash ignored)? */
+export declare function pathHas(value: string | null, dir: string): boolean;

package/dist/host/health/install-state.js

@@ -0,0 +1,110 @@
+// Is a managed install (versions side by side, a private Node, shims in bin) in one piece: do the two pointer files
+// name installed folders, do the shims say what they should, is bin on PATH. These look; the fixes move a pointer or
+// rewrite shims, and never delete a version.
+import fs from 'node:fs';
+import path from 'node:path';
+import { expandVariables } from '../../core/util/index.js';
+import { NODE_PATTERN, compareVersions, readBins, shimText } from '../install/index.js';
+/** Node versions under <root>\node that really hold node.exe, oldest first. */
+export function installedNodes(layout) {
+    const dir = path.join(layout.root, 'node');
+    try {
+        return fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((d) => d.isDirectory() && NODE_PATTERN.test(d.name) && fs.existsSync(layout.nodeExe(d.name)))
+            .map((d) => d.name)
+            .sort((a, b) => compareVersions(a.slice(1), b.slice(1)));
+    }
+    catch {
+        return [];
+    }
+}
+/** Versions that are really there (a package.json in their package folder), oldest first. */
+export function completeVersions(layout) {
+    return layout.installedVersions().filter((v) => fs.existsSync(path.join(layout.packageDir(v), 'package.json')));
+}
+function rawPointer(layout, name) {
+    try {
+        return fs.readFileSync(path.join(layout.root, name), 'utf8').trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** Looks at active-version and active-node. */
+export function inspectPointers(layout) {
+    const versions = completeVersions(layout);
+    const nodes = installedNodes(layout);
+    const activeVersion = layout.activeVersion();
+    const activeNode = layout.activeNode();
+    const problems = [];
+    const raw = (name) => {
+        const text = rawPointer(layout, name);
+        return text === null ? 'is missing' : text === '' ? 'is empty' : 'says "' + text.slice(0, 40) + '"';
+    };
+    if (!activeVersion)
+        problems.push('active-version ' + raw('active-version') + ' (it must name a version like 1.5.0)');
+    else if (!versions.includes(activeVersion))
+        problems.push('active-version points at ' + activeVersion + ', which is not installed');
+    if (!activeNode)
+        problems.push('active-node ' + raw('active-node') + ' (it must name a Node like v22.11.0)');
+    else if (!nodes.includes(activeNode))
+        problems.push('active-node points at ' + activeNode + ', which is not installed');
+    const version = activeVersion && versions.includes(activeVersion) ? activeVersion : versions[versions.length - 1];
+    const node = activeNode && nodes.includes(activeNode) ? activeNode : nodes[nodes.length - 1];
+    return { activeVersion, activeNode, versions, nodes, problems, want: version && node ? { version, node } : null };
+}
+/** Moves the pointers to what is installed (the newest version and Node that are whole). Returns what changed. */
+export function repairPointers(layout, state = inspectPointers(layout)) {
+    if (!state.want)
+        throw new Error('No complete version or Node is installed in ' + layout.root + '.');
+    layout.setActive(state.want.version, state.want.node);
+    return 'active-version ' + state.want.version + ', active-node ' + state.want.node;
+}
+/** The commands a package folder declares (name -> program path), or null when its package.json cannot be read. */
+export function binsOfPackage(packageDir) {
+    try {
+        return readBins(JSON.parse(fs.readFileSync(path.join(packageDir, 'package.json'), 'utf8')));
+    }
+    catch {
+        return null;
+    }
+}
+const sameText = (a, b) => a.replace(/\r\n/g, '\n') === b.replace(/\r\n/g, '\n');
+/** Shim files (both the .cmd and the shell one) that are missing or not what shimText() writes now. */
+export function shimProblems(layout, bins) {
+    const missing = [];
+    const different = [];
+    for (const [name, target] of Object.entries(bins)) {
+        for (const [file, kind] of [
+            [name + '.cmd', 'cmd'],
+            [name, 'sh'],
+        ]) {
+            let text;
+            try {
+                text = fs.readFileSync(path.join(layout.binDir, file), 'utf8');
+            }
+            catch {
+                missing.push(file);
+                continue;
+            }
+            if (!sameText(text, shimText(name, kind, target)))
+                different.push(file);
+        }
+    }
+    return { missing, different };
+}
+const normal = (p) => path
+    .normalize(expandVariables(p.trim().replace(/^"|"$/g, '')))
+    .replace(/[\\/]+$/, '')
+    .toLowerCase();
+/** Is `dir` one of the entries of a PATH value (variables expanded, case and a trailing slash ignored)? */
+export function pathHas(value, dir) {
+    if (!value)
+        return false;
+    const want = normal(dir);
+    return value
+        .split(';')
+        .filter((p) => p.trim() !== '')
+        .some((p) => normal(p) === want);
+}

package/dist/host/health/path-copies.d.ts

@@ -0,0 +1,32 @@
+export declare const COMMAND_NAMES: readonly ["sandbox", "agent-sandbox", "claude-sbx"];
+export type CopyKind = 'managed-machine' | 'managed-user' | 'npm' | 'old-scripts' | 'other';
+/** One folder on the PATH that holds the commands. */
+export interface CommandCopy {
+    readonly dir: string;
+    /** The commands found in it, as the file Windows would run for each (sandbox.cmd, ...). */
+    readonly files: readonly string[];
+    readonly kind: CopyKind;
+    /** Position among the PATH folders that hold a copy (0 = the first one, the one that runs). */
+    readonly order: number;
+}
+export interface PathCopyEnv {
+    /** Machine PATH, then user PATH (raw registry values; null when unreadable). */
+    readonly machinePath: string | null;
+    readonly userPath: string | null;
+    /** PATHEXT, e.g. ".COM;.EXE;.BAT;.CMD". */
+    readonly pathext: string;
+    /** %ProgramFiles% and %LOCALAPPDATA% (where the managed installs live). */
+    readonly programFiles: string | null;
+    readonly localAppData: string | null;
+    readonly exists: (file: string) => boolean;
+}
+/** The PATH folders in the order Windows searches them (machine, then user), each once, variables expanded. */
+export declare function pathFolders(machinePath: string | null, userPath: string | null): string[];
+/** The folders that hold at least one of the commands, in search order. */
+export declare function findCommandCopies(env: PathCopyEnv): CommandCopy[];
+/** The folder a program runs from as a bin folder: the managed bin, or the npm global folder holding the package. */
+export declare function ownBinDir(packageRoot: string, managedBin: string | null): string | null;
+export declare const sameFolder: (a: string, b: string) => boolean;
+/** PATHEXT from the process, or the Windows default. */
+export declare function currentPathext(): string;
+export declare const fileOnDisk: (file: string) => boolean;

package/dist/host/health/path-copies.js

@@ -0,0 +1,82 @@
+// Every copy of the sandbox commands on the PATH (sandbox, agent-sandbox, claude-sbx), in the order Windows finds them:
+// the machine PATH, then yours, and in each folder PATHEXT order. Read only: nothing is run, and a file is only checked
+// for existing. Used by doctor to say which copy runs and how to remove each of the others.
+import fs from 'node:fs';
+import path from 'node:path';
+import { expandVariables } from '../../core/util/index.js';
+export const COMMAND_NAMES = ['sandbox', 'agent-sandbox', 'claude-sbx'];
+const normal = (p) => path
+    .normalize(expandVariables(p.trim().replace(/^"|"$/g, '')))
+    .replace(/[\\/]+$/, '')
+    .toLowerCase();
+/** The PATH folders in the order Windows searches them (machine, then user), each once, variables expanded. */
+export function pathFolders(machinePath, userPath) {
+    const seen = new Set();
+    const out = [];
+    for (const value of [machinePath, userPath])
+        for (const raw of (value ?? '').split(';')) {
+            if (raw.trim() === '')
+                continue;
+            const dir = path.normalize(expandVariables(raw.trim().replace(/^"|"$/g, '')));
+            const key = normal(raw);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push(dir);
+        }
+    return out;
+}
+function classify(dir, env) {
+    const here = normal(dir);
+    const managed = (base) => base ? normal(path.join(base, 'WindowsDevelopmentSandbox', 'bin')) : null;
+    if (here === managed(env.programFiles))
+        return 'managed-machine';
+    if (here === managed(env.localAppData))
+        return 'managed-user';
+    for (const pkg of ['windows-development-sandbox', 'agent-sandbox'])
+        if (env.exists(path.join(dir, 'node_modules', pkg, 'package.json')))
+            return 'npm';
+    if (/[\\/]scripts[\\/]agent-sandbox([\\/]bin)?$/i.test(here))
+        return 'old-scripts';
+    return 'other';
+}
+/** The folders that hold at least one of the commands, in search order. */
+export function findCommandCopies(env) {
+    const exts = env.pathext
+        .split(';')
+        .map((e) => e.trim().toLowerCase())
+        .filter((e) => e.startsWith('.'));
+    const copies = [];
+    for (const dir of pathFolders(env.machinePath, env.userPath)) {
+        const files = [];
+        for (const name of COMMAND_NAMES) {
+            const hit = exts.map((ext) => name + ext).find((file) => env.exists(path.join(dir, file)));
+            if (hit)
+                files.push(hit);
+        }
+        if (files.length)
+            copies.push({ dir, files, kind: classify(dir, env), order: copies.length });
+    }
+    return copies;
+}
+/** The folder a program runs from as a bin folder: the managed bin, or the npm global folder holding the package. */
+export function ownBinDir(packageRoot, managedBin) {
+    if (managedBin)
+        return managedBin;
+    const resolved = path.resolve(packageRoot);
+    const nodeModules = path.dirname(resolved);
+    return path.basename(nodeModules).toLowerCase() === 'node_modules' ? path.dirname(nodeModules) : null;
+}
+export const sameFolder = (a, b) => normal(a) === normal(b);
+/** PATHEXT from the process, or the Windows default. */
+export function currentPathext() {
+    return process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC';
+}
+export const fileOnDisk = (file) => {
+    try {
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+};

package/dist/host/health/stale.d.ts

@@ -0,0 +1,45 @@
+import type { ActiveSandbox, TaskRow } from '../sharing/index.js';
+/** A watcher this old, with its log quiet and no sandbox, is left over (a finishing one is done within minutes). */
+export declare const WATCHER_MIN_AGE_MS: number;
+export declare const WATCHER_LOG_QUIET_MS: number;
+/** Windows sessions that have a sandbox running (empty: none runs). */
+export declare function sandboxSessions(rows: readonly TaskRow[]): number[];
+/** Sharing records whose Windows session has no sandbox running (nothing else removes them after a crash). */
+export declare function staleActiveRecords(records: readonly ActiveSandbox[], rows: readonly TaskRow[]): ActiveSandbox[];
+export interface RunStateProblems {
+    /** Sessions still marked running or starting. */
+    readonly sessions: number;
+    /** Requests nobody answered (valid or not). */
+    readonly requests: number;
+    /** The sandbox status file says the boot never finished (booting, provisioning, failed). */
+    readonly unfinishedBoot: string | null;
+    readonly any: boolean;
+}
+/** What is left in <data>\run by a sandbox that is no longer running. */
+export declare function runStateProblems(dataPath: string): RunStateProblems;
+export interface OldLaunch {
+    readonly path: string;
+    readonly ageDays: number;
+}
+/** Launch folders under <storage>\launches that nothing has touched for `days` days (each is a finished start). */
+export declare function staleLaunchFolders(storageRoot: string, days: number, now: number, keep?: readonly string[]): OldLaunch[];
+export interface WatcherInfo {
+    readonly file: string;
+    readonly pid: number | null;
+    readonly ageMs: number;
+    /** How long ago the watcher's log was written; null when there is none. */
+    readonly logAgeMs: number | null;
+}
+/** The history-sync watcher records in <storage>\run (watcher-<data set>.pid) with the age of each and of its log. */
+export declare function watcherRecords(storageRoot: string, now: number): WatcherInfo[];
+/**
+ * Watchers that run with no sandbox to watch: the process is alive and is a Node program (a recycled pid is somebody
+ * else's), no sandbox runs, and neither its record nor its log has changed for a while (a finishing watcher is spared).
+ */
+export declare function orphanWatchers(infos: readonly WatcherInfo[], o: {
+    running: boolean;
+    alive: (pid: number) => boolean;
+    image: (pid: number) => string | null;
+}): WatcherInfo[];
+/** null when a small file can be created in the folder, else the reason (the file is removed again). */
+export declare function writeProblem(dir: string): string | null;