windows-development-sandbox 1.18.3 → 1.20.0

package/dist/host/agent-commands/reconcile.js

@@ -5,7 +5,7 @@ import { writeFileAtomic } from '../../shared/io/index.js';
 import { safeRemove } from '../../shared/io/index.js';
 import { MARKER, forwardingCmd, forwardingSh } from './forwarders.js';
 import { commandsDir, cmdSafe, agentCommands } from './commands.js';
-import { editUserPath } from './user-path.js';
+import { editUserPath, userPathHas } from './user-path.js';
 const ownFiles = (dir) => fs.existsSync(dir)
     ? fs
         .readdirSync(dir)
@@ -23,7 +23,7 @@ const ownFiles = (dir) => fs.existsSync(dir)
  * Makes this PC match agentCommands: on = a forwarding file per installed agent and the folder first on your PATH;
  * off = no files, no PATH entry. Only touches files it wrote and its own PATH entry; does nothing when already right.
  */
-export function reconcileAgentCommands(config, storageRoot, node, entry) {
+export function reconcileAgentCommands(config, storageRoot, target) {
     const dir = commandsDir(storageRoot);
     if (!config.agentCommands.enabled) {
         if (!fs.existsSync(dir))
@@ -35,14 +35,14 @@ export function reconcileAgentCommands(config, storageRoot, node, entry) {
             safeRemove(dir, storageRoot);
         return { on: false, commands: [], changed: true };
     }
-    if (!cmdSafe(node) || !cmdSafe(entry))
+    if (![target.node, target.entry, target.launcher ?? ''].every(cmdSafe))
         throw new Error('This tool is installed in a folder whose path has % " or ^, which cannot go into a command file safely.');
     const commands = agentCommands(config, storageRoot);
     ensureDir(dir);
     const wanted = new Map();
     for (const a of commands) {
-        wanted.set(path.join(dir, a.command + '.cmd'), forwardingCmd(a, node, entry));
-        wanted.set(path.join(dir, a.command), forwardingSh(a, node, entry));
+        wanted.set(path.join(dir, a.command + '.cmd'), forwardingCmd(a, target));
+        wanted.set(path.join(dir, a.command), forwardingSh(a, target));
     }
     let changed = false;
     for (const f of ownFiles(dir))
@@ -60,9 +60,8 @@ export function reconcileAgentCommands(config, storageRoot, node, entry) {
             changed = true;
         }
     }
-    const onPath = (process.env.PATH ?? '')
-        .split(path.delimiter)
-        .some((d) => path.resolve(d).toLowerCase() === path.resolve(dir).toLowerCase());
+    // Your PATH as stored (not this process's copy of it, which an older terminal keeps): the registry says if it is on.
+    const onPath = !changed && userPathHas(dir, storageRoot);
     if (changed || !onPath)
         editUserPath(dir, true, storageRoot);
     return { on: true, commands, changed: changed || !onPath };

package/dist/host/agent-commands/user-path.d.ts

@@ -3,3 +3,8 @@
  * <storageRoot>\bin), else native\scripts\edit-user-path.ps1.
  */
 export declare function editUserPath(dir: string, add: boolean, storageRoot: string): void;
+/**
+ * Whether dir is on YOUR PATH as stored in the registry (not this process's copy, which an older terminal keeps stale).
+ * False when it cannot be told: the caller then edits the PATH again, which is harmless.
+ */
+export declare function userPathHas(dir: string, storageRoot: string): boolean;

package/dist/host/agent-commands/user-path.js

@@ -23,3 +23,16 @@ export function editUserPath(dir, add, storageRoot) {
             ' your PATH: ' +
             (result.stderr || result.error?.message || 'exit ' + result.status).trim());
 }
+/**
+ * Whether dir is on YOUR PATH as stored in the registry (not this process's copy, which an older terminal keeps stale).
+ * False when it cannot be told: the caller then edits the PATH again, which is harmless.
+ */
+export function userPathHas(dir, storageRoot) {
+    refuseInSelfTest('read your PATH');
+    const tools = hostToolsExe(storageRoot);
+    const options = { encoding: 'utf8', windowsHide: true };
+    const result = tools
+        ? spawnSync(tools, ['user-path', '--has', dir], options)
+        : spawnSync(SYSTEM.powershell(), nativeScript('edit-user-path.ps1', ['-Dir', dir, '-Query']), options);
+    return result.status === 0;
+}

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

@@ -4,3 +4,4 @@ export * from './acl-read.js';
 export * from './stale.js';
 export * from './config-backup.js';
 export * from './path-copies.js';
+export * from './leftovers.js';

package/dist/host/health/index.js

@@ -5,3 +5,4 @@ export * from './acl-read.js';
 export * from './stale.js';
 export * from './config-backup.js';
 export * from './path-copies.js';
+export * from './leftovers.js';

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

@@ -0,0 +1,3 @@
+import { type SandboxFacts } from './stale.js';
+/** The facts for judgeSandbox, from the process list, our heartbeat and our life record. `ping`: ask the daemon too. */
+export declare function readSandboxFacts(storageRoot: string, dataPath: string, ping: boolean): Promise<SandboxFacts>;

package/dist/host/health/leftovers.js

@@ -0,0 +1,40 @@
+// Reads what is needed to judge "are the Windows Sandbox programs ours, alive, or left over?" (see judgeSandbox).
+import { LifeRecord, readHeartbeat } from '../life/index.js';
+import { SandboxChannel } from '../channel/index.js';
+import { listProcesses, sessionOf } from '../sharing/index.js';
+import { judgeSandbox } from './stale.js';
+const PING_WAIT_MS = 5000;
+/** The facts for judgeSandbox, from the process list, our heartbeat and our life record. `ping`: ask the daemon too. */
+export async function readSandboxFacts(storageRoot, dataPath, ping) {
+    const rows = listProcesses();
+    const life = new LifeRecord(storageRoot, dataPath).read();
+    const heartbeat = readHeartbeat(dataPath);
+    const nowMs = Date.now();
+    // A heartbeat from before this launch belongs to an earlier sandbox.
+    const mine = heartbeat && (!life || Date.parse(heartbeat.at) >= Date.parse(life.started) - 60000) ? heartbeat : null;
+    const base = {
+        rows,
+        mySession: sessionOf(rows),
+        heartbeatAgeMs: mine ? Math.max(0, nowMs - Date.parse(mine.at)) : null,
+        lifeEnded: Boolean(life?.ended),
+        startedAgeMs: life ? Math.max(0, nowMs - Date.parse(life.started)) : null,
+        answers: null,
+    };
+    if (!ping || judgeSandbox(base).state !== 'leftover')
+        return base;
+    return { ...base, answers: await answers(dataPath) };
+}
+/** Does the sandbox's daemon answer a ping within a few seconds? */
+async function answers(dataPath) {
+    try {
+        const reply = await Promise.race([
+            new SandboxChannel(dataPath).ping().then((r) => r.ok),
+            new Promise((resolve) => setTimeout(() => resolve(false), PING_WAIT_MS).unref()),
+        ]);
+        return reply;
+    }
+    catch {
+        // No answer, or a channel that cannot be used: it does not answer.
+        return false;
+    }
+}

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

@@ -43,3 +43,51 @@ export declare function orphanWatchers(infos: readonly WatcherInfo[], o: {
 }): 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;
+/** The Windows Sandbox programs of the user that a dead sandbox leaves behind (never the VM's own vmwp.exe). */
+export declare const LEFTOVER_IMAGES: readonly ["windowssandbox.exe", "windowssandboxclient.exe", "windowssandboxremotesession.exe", "windowssandboxserver.exe"];
+/** A heartbeat this recent means the sandbox is alive (the sandbox writes one every 10 seconds). */
+export declare const ALIVE_MS: number;
+/** A heartbeat older than this, with the sandbox's programs still there, means the sandbox is gone. */
+export declare const GONE_MS: number;
+/** A sandbox started this recently may not have written a heartbeat yet (a first boot takes minutes). */
+export declare const STARTING_MS: number;
+/** What is known about the Windows Sandbox programs on this PC and our sandbox (read by the caller). */
+export interface SandboxFacts {
+    /** Every process of every session (tasklist). */
+    readonly rows: readonly TaskRow[];
+    /** The Windows session this program runs in; null when unknown (then nothing is ever ended). */
+    readonly mySession: number | null;
+    /** Age of our sandbox's last heartbeat from this run; null when there is none. */
+    readonly heartbeatAgeMs: number | null;
+    /** Our life record says the last sandbox ended (the watcher saw it go). */
+    readonly lifeEnded: boolean;
+    /** Age of our last launch; null when unknown. */
+    readonly startedAgeMs: number | null;
+    /** Did the sandbox answer a ping just now? null: not asked. */
+    readonly answers: boolean | null;
+}
+export type SandboxState = 
+/** No Windows Sandbox program runs. */
+'none'
+/** Ours, and alive (or not known to be gone). */
+ | 'running'
+/** Ours, started a moment ago. */
+ | 'starting'
+/** Programs of a sandbox that is gone: safe to end after asking. */
+ | 'leftover'
+/** Another Windows session's sandbox: never touched. */
+ | 'foreign';
+export interface SandboxJudgement {
+    readonly state: SandboxState;
+    /** The programs of this user's session that cleaning up would end. */
+    readonly pids: readonly number[];
+    readonly images: readonly string[];
+    /** Why, in plain words (for the question). */
+    readonly why: string;
+}
+/**
+ * Is the Windows Sandbox on this PC ours and alive, ours and gone, or someone else's? (pure) It is "leftover" only
+ * with positive evidence: our own programs in our own session, no answer, and either the watcher saw the sandbox end
+ * or its heartbeat stopped long ago. No heartbeat at all (an older sandbox) counts as running.
+ */
+export declare function judgeSandbox(f: SandboxFacts): SandboxJudgement;

package/dist/host/health/stale.js

@@ -118,3 +118,43 @@ export function writeProblem(dir) {
         fs.rmSync(probe, { force: true });
     }
 }
+/** The Windows Sandbox programs of the user that a dead sandbox leaves behind (never the VM's own vmwp.exe). */
+export const LEFTOVER_IMAGES = [
+    'windowssandbox.exe',
+    'windowssandboxclient.exe',
+    'windowssandboxremotesession.exe',
+    'windowssandboxserver.exe',
+];
+/** A heartbeat this recent means the sandbox is alive (the sandbox writes one every 10 seconds). */
+export const ALIVE_MS = 45 * 1000;
+/** A heartbeat older than this, with the sandbox's programs still there, means the sandbox is gone. */
+export const GONE_MS = 2 * 60 * 1000;
+/** A sandbox started this recently may not have written a heartbeat yet (a first boot takes minutes). */
+export const STARTING_MS = 10 * 60 * 1000;
+const isLeftoverImage = (image) => LEFTOVER_IMAGES.includes(image.toLowerCase());
+/**
+ * Is the Windows Sandbox on this PC ours and alive, ours and gone, or someone else's? (pure) It is "leftover" only
+ * with positive evidence: our own programs in our own session, no answer, and either the watcher saw the sandbox end
+ * or its heartbeat stopped long ago. No heartbeat at all (an older sandbox) counts as running.
+ */
+export function judgeSandbox(f) {
+    const sandbox = f.rows.filter((r) => isLeftoverImage(r.image));
+    const mine = f.mySession === null ? [] : sandbox.filter((r) => r.session === f.mySession);
+    const none = (state, why) => ({ state, pids: [], images: [], why });
+    if (sandbox.length === 0)
+        return none('none', 'No Windows Sandbox program is running.');
+    if (mine.length === 0)
+        return none('foreign', 'The Windows Sandbox that runs belongs to another Windows session.');
+    const pids = mine.map((r) => r.pid);
+    const images = [...new Set(mine.map((r) => r.image))];
+    const found = (state, why) => ({ state, pids, images, why });
+    if (f.answers === true || (f.heartbeatAgeMs !== null && f.heartbeatAgeMs <= ALIVE_MS))
+        return found('running', 'The sandbox is working.');
+    if (f.startedAgeMs !== null && f.startedAgeMs <= STARTING_MS && !f.lifeEnded)
+        return found('starting', 'The sandbox started a moment ago.');
+    if (f.lifeEnded)
+        return found('leftover', 'The last sandbox has ended, but its Windows programs are still there.');
+    if (f.heartbeatAgeMs !== null && f.heartbeatAgeMs > GONE_MS)
+        return found('leftover', 'The sandbox has not shown a sign of life for ' + Math.round(f.heartbeatAgeMs / 60000) + ' minutes.');
+    return found('running', 'A sandbox is running (there is no sign that it is gone).');
+}

package/dist/host/launch/session-file.js

@@ -65,6 +65,7 @@ export function guestSession(o, parts) {
         loadProfile: loadProfileOf(config),
         pageFileMb: config.sandbox.pageFileMb,
         agentBackstop: config.sandbox.agentMemoryHeadroomMb,
+        codex: config.codex,
         pressureResponse: config.sandbox.pressureResponse,
         apps: config.apps,
         auditProcesses: config.audit.enabled && config.audit.processes,

package/dist/host/life/crash-report.d.ts

@@ -35,4 +35,4 @@ export declare function newestCrashReport(storageRoot: string): {
 /**
  * When the sandbox ended in a crash (its own, this PC's, power, low memory): writes the report and returns its path.
  */
-export declare function saveCrashReport(storageRoot: string, dataPath: string, lastSeen: string): string | null;
+export declare function saveCrashReport(storageRoot: string, dataPath: string, lastSeen: string, known?: StopCause | null): string | null;

package/dist/host/life/crash-report.js

@@ -12,6 +12,8 @@ const KEEP_REPORTS = 20;
 const MEMORY_TAIL_BYTES = 16 * 1024;
 /** A gap longer than this between "last seen running" and the restart means the PC stopped responding first. */
 const FREEZE_GAP_MS = 5 * 60 * 1000;
+/** The ends that get a crash report (not updates, restarts and sleep: those are plain). */
+const REPORTED = ['sandboxCrash', 'crash', 'memory', 'gpu', 'hyperv', 'vanished'];
 function crashDir(storageRoot) {
     return path.join(storageRoot, 'logs', 'crashes');
 }
@@ -230,10 +232,10 @@ function memoryLogTail(dataPath) {
 /**
  * When the sandbox ended in a crash (its own, this PC's, power, low memory): writes the report and returns its path.
  */
-export function saveCrashReport(storageRoot, dataPath, lastSeen) {
+export function saveCrashReport(storageRoot, dataPath, lastSeen, known = null) {
     const events = readStopEvents(new Date(Date.parse(lastSeen) - 2 * 60 * 1000), storageRoot);
-    const cause = explainStop(events);
-    if (!cause || !['sandboxCrash', 'crash', 'memory'].includes(cause.kind))
+    const cause = explainStop(events) ?? known;
+    if (!cause || !REPORTED.includes(cause.kind))
         return null;
     const dir = crashDir(storageRoot);
     fs.mkdirSync(dir, { recursive: true });

package/dist/host/life/last-end.d.ts

@@ -1,5 +1,6 @@
 import { type Heartbeat } from '../../shared/channel/index.js';
 import type { Life } from './life-record.js';
+import type { StopCause } from './stop-events.js';
 /** How the last sandbox ended, when nobody closed it. */
 export interface LastEnd {
     /** "ended unexpectedly 21:31: this PC's disks were overloaded (queue 40)". */
@@ -12,6 +13,12 @@ export declare function readHeartbeat(dataPath: string): Heartbeat | null;
 export declare function heartbeatLine(hb: Heartbeat): string;
 /** The likeliest reason, from the last heartbeat (pure). */
 export declare function guessReason(hb: Heartbeat | null): string;
+/**
+ * The sandbox went and nothing was logged (pure): its last heartbeat is fresh, from this run, says it was working
+ * (a session running, or builds slowed down) and does not say it was shutting down in order, and nobody stopped it on
+ * purpose (`sandbox stop`, a restart). The guest cannot tell a closed window from a crash, so the wording says both.
+ */
+export declare function vanishedCause(hb: Heartbeat | null, startedIso: string, closedOnPurpose: boolean, endedAtMs: number): StopCause | null;
 /**
  * How the last sandbox ended (pure): null when it was closed normally, or is still running. `heartbeat` only counts
  * when it was written during that run.

package/dist/host/life/last-end.js

@@ -49,6 +49,27 @@ export function guessReason(hb) {
         return 'the sandbox was running out of memory';
     return 'Windows stopped it (no reason was logged)';
 }
+/** A heartbeat older than this before the end is not "it was working when it went". */
+const FRESH_MS = 2 * 60 * 1000;
+/**
+ * The sandbox went and nothing was logged (pure): its last heartbeat is fresh, from this run, says it was working
+ * (a session running, or builds slowed down) and does not say it was shutting down in order, and nobody stopped it on
+ * purpose (`sandbox stop`, a restart). The guest cannot tell a closed window from a crash, so the wording says both.
+ */
+export function vanishedCause(hb, startedIso, closedOnPurpose, endedAtMs) {
+    if (!hb || closedOnPurpose || hb.phase === 'ending')
+        return null;
+    const seen = Date.parse(hb.at);
+    if (!Number.isFinite(seen) || seen < Date.parse(startedIso) - 60000 || endedAtMs - seen > FRESH_MS)
+        return null;
+    if (hb.phase !== 'working' && hb.step === 0 && hb.hostStep === 0)
+        return null;
+    return {
+        kind: 'vanished',
+        at: new Date(endedAtMs).toISOString(),
+        text: 'the sandbox ended suddenly while it was working (its window was closed, or it crashed: Windows logged nothing)',
+    };
+}
 /**
  * How the last sandbox ended (pure): null when it was closed normally, or is still running. `heartbeat` only counts
  * when it was written during that run.

package/dist/host/life/life-record.d.ts

@@ -14,6 +14,9 @@ declare const LifeSchema: z.ZodObject<{
                 sleep: "sleep";
                 memory: "memory";
                 sandboxCrash: "sandboxCrash";
+                gpu: "gpu";
+                hyperv: "hyperv";
+                vanished: "vanished";
             }>;
             at: z.ZodString;
             text: z.ZodString;

package/dist/host/life/life-record.js

@@ -5,7 +5,7 @@
 import { z } from 'zod';
 import { JsonFile } from '../../shared/io/index.js';
 import { hostStateFile } from '../storage/index.js';
-import { causeSince, IsoSchema } from './stop-events.js';
+import { causeSince, IsoSchema, STOP_KINDS } from './stop-events.js';
 import { stopWarning } from './stop-warning.js';
 import { saveCrashReport } from './crash-report.js';
 const LifeSchema = z.object({
@@ -17,7 +17,7 @@ const LifeSchema = z.object({
         at: IsoSchema,
         cause: z
             .object({
-            kind: z.enum(['updates', 'restart', 'crash', 'sleep', 'memory', 'sandboxCrash']),
+            kind: z.enum(STOP_KINDS),
             at: IsoSchema,
             text: z.string().max(400),
         })

package/dist/host/life/stop-events.d.ts

@@ -6,7 +6,9 @@ export interface StopEvent {
     provider: string;
     process: string;
 }
-export type StopKind = 'updates' | 'restart' | 'crash' | 'sleep' | 'memory' | 'sandboxCrash';
+/** The ways a sandbox can end that nobody asked for (the life record stores one of these). */
+export declare const STOP_KINDS: readonly ["updates", "restart", "crash", "sleep", "memory", "sandboxCrash", "gpu", "hyperv", "vanished"];
+export type StopKind = (typeof STOP_KINDS)[number];
 export interface StopCause {
     kind: StopKind;
     at: string;

package/dist/host/life/stop-events.js

@@ -17,6 +17,24 @@ const StopEventsSchema = z
         .transform((p) => p ?? ''),
 }))
     .max(100);
+/** The ways a sandbox can end that nobody asked for (the life record stores one of these). */
+export const STOP_KINDS = [
+    'updates',
+    'restart',
+    'crash',
+    'sleep',
+    'memory',
+    'sandboxCrash',
+    /** The graphics driver reset (display 4101, a GPU LiveKernelEvent): vGPU and the GPU's shared memory. */
+    'gpu',
+    /** Hyper-V reported an error, or a program that holds the VM (vmwp.exe, vmmem) crashed. */
+    'hyperv',
+    /** Nothing was logged, but the sandbox was working and left no word of leaving. */
+    'vanished',
+];
+/** Windows live kernel events that are a graphics driver (GPU) reset or timeout. */
+const GPU_LIVE_KERNEL = ['117', '141', '1a8'];
+const VM_PROGRAMS = /vmwp\.exe|vmmem\w*|vmcompute|windowssandbox\w*/i;
 const UPDATERS = /^(trustedinstaller|mousocoreworker|musnotification(ux)?|usoclient|wuauclt|tiworker|updateorchestrator)\.exe$/i;
 /** The stop code in Kernel-Power 41's detail ("BugcheckCode 209" -> "0xD1"); null for 0 (no blue screen). */
 export function bugcheckCode(detail) {
@@ -85,6 +103,47 @@ export function explainStop(events) {
                 },
             ];
         }
+        // The graphics driver stopped responding and was reset: with vGPU the sandbox shares the GPU, so the VM goes too.
+        if (e.id === 4101 && p === 'display')
+            return [
+                {
+                    kind: 'gpu',
+                    at: e.at,
+                    text: 'the graphics driver stopped responding and was reset while the sandbox used the GPU (vGPU)',
+                },
+            ];
+        const programs = VM_PROGRAMS.exec(e.process)?.[0];
+        if (e.id === 1001 && p.includes('windows error reporting') && /LiveKernelEvent/i.test(e.process)) {
+            const code = /\bP1:\s*([0-9a-f]{2,4})\b/i.exec(e.process)?.[1]?.toLowerCase();
+            if (code && GPU_LIVE_KERNEL.includes(code))
+                return [
+                    {
+                        kind: 'gpu',
+                        at: e.at,
+                        text: 'the graphics driver reset (Windows live kernel event ' +
+                            code +
+                            ') while the sandbox used the GPU (vGPU)',
+                    },
+                ];
+        }
+        if ((e.id === 1000 || e.id === 1001) &&
+            programs &&
+            /^(application error|windows error reporting)$/i.test(e.provider))
+            return [
+                {
+                    kind: 'hyperv',
+                    at: e.at,
+                    text: 'a program that runs the sandbox VM (' + programs.toLowerCase() + ') crashed',
+                },
+            ];
+        if (/^microsoft-windows-hyper-v-(worker|vmswitch|compute)/.test(p) && e.id !== 18590 && e.id !== 40001)
+            return [
+                {
+                    kind: 'hyperv',
+                    at: e.at,
+                    text: 'Hyper-V, which runs the sandbox VM, reported an error (event ' + e.id + ')',
+                },
+            ];
         return [];
     });
     return causes.sort((a, b) => Date.parse(a.at) - Date.parse(b.at))[0] ?? null;

package/dist/host/life/stop-warning.js

@@ -4,6 +4,9 @@ const ADVICE = {
     crash: 'sandbox logs --crash prints what Windows logged and how much memory this PC had; Event Viewer > Windows Logs > System has the rest. A laptop also needs to stay plugged in.',
     sleep: 'sandbox.keepAwake keeps this PC awake while a sandbox runs (closing a laptop lid still sleeps it). Check it is on, and that sleep is not forced by a policy.',
     sandboxCrash: 'C:\\AgentData\\logs\\memory-*.log shows what used memory just before. Fewer builds at once inside the sandbox (e.g. cargo build.jobs) makes it less likely.',
+    gpu: 'The graphics driver reset while the sandbox used the GPU (vGPU). Turn vGPU off (sandbox config set sandbox.vGpu false) or lower the GPU load, and keep heavy builds and a GPU game apart.',
+    hyperv: 'Hyper-V, which runs the sandbox, reported an error. Closing other virtual machines, updating the graphics driver, or turning vGPU off usually helps; sandbox logs --crash has the events.',
+    vanished: 'If you did not close its window, this is the known pattern of heavy builds plus a GPU game with vGPU on: turn vGPU off or run fewer builds at once. sandbox logs --crash says what it was doing in its last seconds.',
     memory: 'Give the sandbox less RAM (sandbox.maxMemoryMb, sandbox.reserveHostMb) or run fewer builds at once inside it.',
 };
 const when = (iso) => new Date(iso).toLocaleString(undefined, { weekday: 'short', hour: '2-digit', minute: '2-digit' });

package/dist/host/profile/accounts.js

@@ -9,6 +9,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { z } from 'zod';
+import { ANTHROPIC_KEY_HINT } from '../../shared/accounts/index.js';
 import { isSafeFileName } from '../../shared/paths/index.js';
 import { JsonFile } from '../../shared/io/index.js';
 import { storageOf } from '../storage/index.js';
@@ -36,10 +37,7 @@ const SealedSchema = z.object({
     email: z.string().max(200).nullable(),
     /** Missing in accounts saved before keys could be: a subscription. */
     kind: z.enum(LOGIN_KINDS).optional(),
-    keyHint: z
-        .string()
-        .regex(/^sk-ant-\.\.\.[A-Za-z0-9_-]{4}$/)
-        .optional(),
+    keyHint: z.string().regex(ANTHROPIC_KEY_HINT).optional(),
     sealed: z.string().max(200000),
 });
 const StoredSchema = z.union([SealedSchema, AccountSchema]);

package/dist/host/profile/claude-login.d.ts

@@ -1,3 +1,4 @@
+import { anthropicKeyProblem } from '../../shared/accounts/index.js';
 /** subscription: claude.ai OAuth; console: the key a Console login made; api-key: a key you gave. */
 export type LoginKind = 'subscription' | 'console' | 'api-key';
 export declare const LOGIN_KINDS: readonly ["subscription", "console", "api-key"];
@@ -16,8 +17,8 @@ export interface CaptureOptions {
     /** ANTHROPIC_API_KEY of this PC: the last place looked at (--from-host only). */
     readonly envKey?: string | null;
 }
-/** What is wrong with a typed or found API key, or null when it has the right shape. Never quotes the key. */
-export declare function apiKeyProblem(key: string): string | null;
+/** What is wrong with a typed or found API key (sk-ant-api or sk-ant-usr), or null. Never quotes the key. */
+export declare const apiKeyProblem: typeof anthropicKeyProblem;
 /** The most of a key that is ever shown: sk-ant-...abcd. */
 export declare function maskApiKey(key: string): string;
 export interface LoginFiles {

package/dist/host/profile/claude-login.js

@@ -9,23 +9,13 @@
 // written through. A key read from the sandbox must have the shape of an API key.
 import fs from 'node:fs';
 import path from 'node:path';
+import { anthropicKeyProblem } from '../../shared/accounts/index.js';
 import { assertTestWritable } from '../test-guard.js';
 import { hostDataFolder, hostDataRoot } from '../storage/index.js';
 import { assertNoLinks, fail, fileExists, isLink, removeLink, tryReadJson, writeJson } from '../../core/util/index.js';
 export const LOGIN_KINDS = ['subscription', 'console', 'api-key'];
-/** sk-ant-api03-...: a normal Anthropic API key (letters, digits, - and _, which is what Claude Code accepts). */
-const API_KEY = /^sk-ant-api\d{2}-[A-Za-z0-9_-]{20,400}$/;
-const API_USER_KEY = /^sk-ant-usr\d{2}-[A-Za-z0-9_-]{20,400}$/;
-/** What is wrong with a typed or found API key, or null when it has the right shape. Never quotes the key. */
-export function apiKeyProblem(key) {
-    if (API_KEY.test(key) || API_USER_KEY.test(key))
-        return null;
-    if (key.startsWith('sk-ant-oat'))
-        return 'That is a Claude subscription token (from claude setup-token), not an API key. Save the subscription login instead.';
-    if (key.startsWith('sk-ant-admin'))
-        return 'That is an Admin key: it cannot run Claude. Make an API key instead.';
-    return 'An Anthropic API key starts with sk-ant-api or sk-ant-usr and has only letters, digits, - and _ (copy it from the Claude Console).';
-}
+/** What is wrong with a typed or found API key (sk-ant-api or sk-ant-usr), or null. Never quotes the key. */
+export const apiKeyProblem = anthropicKeyProblem;
 /** The most of a key that is ever shown: sk-ant-...abcd. */
 export function maskApiKey(key) {
     return 'sk-ant-...' + key.slice(-4);

package/dist/host/sandbox/cleanup.d.ts

@@ -0,0 +1,37 @@
+import { LEFTOVER_IMAGES, type SandboxFacts, type SandboxJudgement } from '../health/stale.js';
+/** taskkill arguments that end exactly these programs (pure). */
+export declare function killArgs(pids: readonly number[]): string[];
+/** Ends these Windows Sandbox programs (taskkill by absolute path). Returns false when taskkill failed. */
+export declare function endSandboxPrograms(pids: readonly number[]): boolean;
+/** Restarts the Windows Sandbox service (CmService) in an elevated PowerShell: Windows asks for permission. */
+export declare function restartSandboxService(): boolean;
+/** What the person is asked, and what is done about it: everything outside the decision is passed in. */
+export interface CleanupDeps {
+    /** The facts now (a fresh process list each time). */
+    readonly facts: () => Promise<SandboxFacts>;
+    readonly end: (pids: readonly number[]) => boolean;
+    readonly restartService: () => boolean;
+    /** An interactive question: true for yes. */
+    readonly confirm: (q: {
+        title: string;
+        lines: string[];
+        yes: string;
+    }) => Promise<boolean>;
+    readonly say: (line: string) => void;
+    /** Also restart the service even when the programs ended (the caller said Windows still refuses). */
+    readonly alsoService?: boolean;
+}
+export type CleanupOutcome = 
+/** Nothing of the sandbox is on this PC. */
+'nothing'
+/** A live sandbox (or another user's): nothing was ended. */
+ | 'alive' | 'declined' | 'cleaned' | 'service-restarted' | 'failed';
+/** The question for a judgement of "leftover" (pure). */
+export declare function cleanupQuestion(j: SandboxJudgement): {
+    title: string;
+    lines: string[];
+    yes: string;
+};
+/** The whole clean-up: judge, ask, end, check, and (when needed and allowed) restart the service. */
+export declare function cleanUpLeftovers(deps: CleanupDeps): Promise<CleanupOutcome>;
+export { LEFTOVER_IMAGES };

package/dist/host/sandbox/cleanup.js

@@ -0,0 +1,82 @@
+// Windows Sandbox leaves its programs behind when the VM dies (a crash, a kill from the host side): the next start then
+// fails ("the sandbox was signed out", or "already running"). This ends those leftovers, after asking, and when Windows
+// still refuses, restarts the Windows Sandbox service (CmService), which needs administrator permission. The decisions
+// are pure and the actions are injected, so tests never end a process.
+import { spawnSync } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+import { refuseInSelfTest } from '../test-guard.js';
+import { nativeScript } from '../native.js';
+import { judgeSandbox, LEFTOVER_IMAGES } from '../health/stale.js';
+const HELPER_TIMEOUT_MS = 15000;
+const SERVICE_TIMEOUT_MS = 120000;
+/** taskkill arguments that end exactly these programs (pure). */
+export function killArgs(pids) {
+    const safe = pids.filter((pid) => Number.isInteger(pid) && pid > 4);
+    return ['/F', ...safe.flatMap((pid) => ['/PID', String(pid)])];
+}
+/** Ends these Windows Sandbox programs (taskkill by absolute path). Returns false when taskkill failed. */
+export function endSandboxPrograms(pids) {
+    refuseInSelfTest('end Windows Sandbox programs');
+    if (killArgs(pids).length <= 1)
+        return true;
+    const result = spawnSync(SYSTEM.taskkill(), killArgs(pids), { windowsHide: true, timeout: HELPER_TIMEOUT_MS });
+    return result.status === 0;
+}
+/** Restarts the Windows Sandbox service (CmService) in an elevated PowerShell: Windows asks for permission. */
+export function restartSandboxService() {
+    refuseInSelfTest('restart the Windows Sandbox service');
+    const result = spawnSync(SYSTEM.powershell(), nativeScript('run-elevated.ps1', ['-Command', 'Restart-Service -Name CmService -Force']), { windowsHide: true, timeout: SERVICE_TIMEOUT_MS });
+    return result.status === 0;
+}
+const NAMES = (j) => j.images.join(', ');
+/** The question for a judgement of "leftover" (pure). */
+export function cleanupQuestion(j) {
+    return {
+        title: 'Close the leftover Windows Sandbox programs?',
+        lines: [
+            j.why,
+            'Windows Sandbox leaves its programs behind when the sandbox dies, and then refuses to start again.',
+            'Only these programs of your Windows session are closed: ' + NAMES(j) + '. Nothing else.',
+        ],
+        yes: 'Close them',
+    };
+}
+/** The whole clean-up: judge, ask, end, check, and (when needed and allowed) restart the service. */
+export async function cleanUpLeftovers(deps) {
+    const first = judgeSandbox(await deps.facts());
+    if (first.state === 'none')
+        return 'nothing';
+    if (first.state !== 'leftover') {
+        deps.say(first.why + ' Nothing was closed.');
+        return 'alive';
+    }
+    if (!(await deps.confirm(cleanupQuestion(first))))
+        return 'declined';
+    const ended = deps.end(first.pids);
+    const after = judgeSandbox(await deps.facts());
+    const gone = after.state === 'none' || after.state === 'foreign';
+    if (gone && !deps.alsoService) {
+        deps.say('Closed ' + first.pids.length + ' leftover program(s). The sandbox can start again now.');
+        return 'cleaned';
+    }
+    if (!gone)
+        deps.say(ended ? 'Some programs are still there.' : 'Windows would not let them be closed.');
+    const restart = deps.alsoService === true ||
+        (await deps.confirm({
+            title: 'Restart the Windows Sandbox service?',
+            lines: [
+                'Windows still holds the old sandbox. Restarting its service (CmService) clears that.',
+                'Windows asks for administrator permission once.',
+            ],
+            yes: 'Restart it',
+        }));
+    if (!restart)
+        return gone ? 'cleaned' : 'declined';
+    if (!deps.restartService()) {
+        deps.say('The service was not restarted (the permission was declined, or Windows refused).');
+        return 'failed';
+    }
+    deps.say('The Windows Sandbox service was restarted.');
+    return 'service-restarted';
+}
+export { LEFTOVER_IMAGES };

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

@@ -1,4 +1,5 @@
 export * from './platform.js';
+export * from './cleanup.js';
 export * from './probe.js';
 export * from './tasklist.js';
 export * from './host-claude.js';