windows-development-sandbox 1.5.0 → 1.7.0

package/dist/host/channel/channel.js

@@ -7,8 +7,18 @@ import { isWithin } from '../../shared/paths/index.js';
 import { now, RunDir } from '../../shared/channel/index.js';
 import { safeRemove, writeJsonAtomic } from '../../shared/io/index.js';
 import { isSandboxRunning } from '../sandbox/index.js';
+import { withoutSecrets, writeSecrets } from '../secrets/index.js';
 import { assertTestWritable, refuseInSelfTest } from '../test-guard.js';
 const BOOT_TIMEOUT_MS = 30 * 60 * 1000;
+/**
+ * The boot script writes its first status once Windows has booted the sandbox and logged on (a minute or two, longer on
+ * a slow PC or the very first start); none after this long means it never got going.
+ */
+export const FIRST_STATUS_MS = 8 * 60 * 1000;
+/** True when a boot is silent: no status of this launch yet, and the sandbox had its time to write one. */
+export function bootSilent(elapsedMs, seenStatus, limitMs = FIRST_STATUS_MS) {
+    return !seenStatus && elapsedMs > limitMs;
+}
 /** Most sessions the host will ever contact for one listing: a sandbox can write as many session files as it likes. */
 export const MAX_QUERIED_SESSIONS = 32;
 const printLine = (line) => console.log(line);
@@ -57,10 +67,20 @@ export class SandboxChannel {
      */
     waitForReady(launchId, progress = (m) => printLine('  [sandbox] ' + m), onStatus) {
         let last = '';
+        let seen = false;
+        const started = Date.now();
         return this.until(BOOT_TIMEOUT_MS, () => {
             const status = this.run.readSandboxStatus();
-            if (!status || (launchId !== null && status.launchId !== launchId))
+            if (!status || (launchId !== null && status.launchId !== launchId)) {
+                if (bootSilent(Date.now() - started, seen))
+                    fail('The sandbox has not reported anything for ' + Math.round(FIRST_STATUS_MS / 60000) + ' minutes.', 'It may still be starting, or it cannot reach its folders. Look at its window (sbx-show), the run folder ' +
+                        this.run.root +
+                        ' and the data folder ' +
+                        this.dataPath +
+                        ', and check that you can write to both. sandbox logs shows what happened.');
                 return null;
+            }
+            seen = true;
             onStatus?.(status);
             if (status.message !== last) {
                 progress(safeText(status.message).slice(0, 300));
@@ -77,7 +97,11 @@ export class SandboxChannel {
         if (request.kind === 'exec' && /shutdown/i.test(request.command[0] ?? ''))
             refuseInSelfTest('shut down Windows Sandbox');
         assertNoLinks(this.dataPath, this.run.requestsDir);
-        writeJsonAtomic(this.run.requestFile(request.id), request);
+        // Agent environment values (they may be API keys) never go into run: they travel in a one-shot file next to it.
+        const { request: plain, secrets } = withoutSecrets(request);
+        if (secrets)
+            writeSecrets(this.dataPath, request.id, secrets);
+        writeJsonAtomic(this.run.requestFile(request.id), plain);
     }
     waitForResponse(requestId, timeoutMs) {
         return this.until(timeoutMs, () => {

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;

package/dist/host/health/stale.js

@@ -0,0 +1,120 @@
+// What a closed or crashed sandbox leaves behind, and how to tell it from what is in use: records of sandboxes that are
+// gone, run files, old launch folders, background watchers with nothing to watch. These only look; the repair checks
+// remove through the safe helpers. Everything takes its folders as arguments, so tests use temp folders.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { dirExists, isLink } from '../../core/util/index.js';
+import { RunDir } from '../../shared/channel/index.js';
+const DAY = 24 * 60 * 60 * 1000;
+const SANDBOX_IMAGES = ['windowssandboxclient.exe', 'windowssandboxremotesession.exe', 'windowssandbox.exe'];
+/** A watcher this old, with its log quiet and no sandbox, is left over (a finishing one is done within minutes). */
+export const WATCHER_MIN_AGE_MS = 10 * 60 * 1000;
+export const WATCHER_LOG_QUIET_MS = 5 * 60 * 1000;
+/** Windows sessions that have a sandbox running (empty: none runs). */
+export function sandboxSessions(rows) {
+    const found = rows.filter((r) => SANDBOX_IMAGES.includes(r.image.toLowerCase()));
+    return [...new Set(found.map((r) => r.session))];
+}
+/** Sharing records whose Windows session has no sandbox running (nothing else removes them after a crash). */
+export function staleActiveRecords(records, rows) {
+    const sessions = sandboxSessions(rows);
+    return records.filter((r) => !sessions.includes(r.windowsSession));
+}
+/** What is left in <data>\run by a sandbox that is no longer running. */
+export function runStateProblems(dataPath) {
+    const run = new RunDir(dataPath);
+    const sessions = run.listSessions().filter((s) => s.phase === 'running' || s.phase === 'starting').length;
+    const found = run.scanRequests();
+    const requests = found.valid.length + found.invalid.length;
+    const phase = run.readSandboxStatus()?.phase;
+    const unfinishedBoot = phase && phase !== 'ready' ? phase : null;
+    return { sessions, requests, unfinishedBoot, any: sessions > 0 || requests > 0 || unfinishedBoot !== null };
+}
+/** Launch folders under <storage>\launches that nothing has touched for `days` days (each is a finished start). */
+export function staleLaunchFolders(storageRoot, days, now, keep = []) {
+    const dir = path.join(storageRoot, 'launches');
+    if (!dirExists(dir) || isLink(dir))
+        return [];
+    const found = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (keep.includes(name))
+            continue;
+        const full = path.join(dir, name);
+        try {
+            const age = now - fs.lstatSync(full).mtimeMs;
+            if (age > days * DAY)
+                found.push({ path: full, ageDays: Math.floor(age / DAY) });
+        }
+        catch {
+            // gone while we looked
+        }
+    }
+    return found;
+}
+const PidSchema = z.coerce.number().int().positive();
+/** The history-sync watcher records in <storage>\run (watcher-<data set>.pid) with the age of each and of its log. */
+export function watcherRecords(storageRoot, now) {
+    const dir = path.join(storageRoot, 'run');
+    if (!dirExists(dir) || isLink(dir))
+        return [];
+    const age = (p) => {
+        try {
+            return now - fs.statSync(p).mtimeMs;
+        }
+        catch {
+            return null;
+        }
+    };
+    return fs
+        .readdirSync(dir)
+        .map((name) => ({ name, m: /^watcher-(.+)\.pid$/i.exec(name) }))
+        .flatMap(({ name, m }) => {
+        if (!m)
+            return [];
+        const file = path.join(dir, name);
+        let pid = null;
+        try {
+            const parsed = PidSchema.safeParse(fs.readFileSync(file, 'utf8').trim());
+            pid = parsed.success ? parsed.data : null;
+        }
+        catch {
+            return [];
+        }
+        return [
+            {
+                file,
+                pid,
+                ageMs: age(file) ?? 0,
+                logAgeMs: age(path.join(storageRoot, 'logs', 'host-sync-' + m[1] + '.log')),
+            },
+        ];
+    });
+}
+/**
+ * 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 function orphanWatchers(infos, o) {
+    if (o.running)
+        return [];
+    return infos.filter((w) => w.pid !== null &&
+        o.alive(w.pid) &&
+        o.image(w.pid)?.toLowerCase() === 'node.exe' &&
+        w.ageMs > WATCHER_MIN_AGE_MS &&
+        (w.logAgeMs === null || w.logAgeMs > WATCHER_LOG_QUIET_MS));
+}
+/** null when a small file can be created in the folder, else the reason (the file is removed again). */
+export function writeProblem(dir) {
+    const probe = path.join(dir, '.write-test-' + process.pid);
+    try {
+        fs.writeFileSync(probe, '');
+        return null;
+    }
+    catch (e) {
+        return e.code ?? String(e);
+    }
+    finally {
+        fs.rmSync(probe, { force: true });
+    }
+}