windows-development-sandbox 1.13.0 → 1.14.0

package/dist/cli/tui/terminal.js

@@ -14,6 +14,12 @@ export class ExitRequested extends Error {
 /** DEC 2026: the terminal shows a frame only when it is complete. Others ignore it, so only these are asked. */
 const SYNC_BEGIN = '\x1b[?2026h';
 const SYNC_END = '\x1b[?2026l';
+/**
+ * How long a lone ESC waits for the rest of an escape sequence before it counts as the Esc key. Node's default is
+ * 500 ms, which every Esc (back, close) waited for. Terminals send a key's whole sequence in one write, so a short wait
+ * is enough.
+ */
+export const ESCAPE_TIMEOUT_MS = 25;
 /** Whether this terminal is known to take synchronized updates (AGENT_SANDBOX_SYNC_UPDATE=1 or 0 overrides). */
 export function supportsSyncUpdate(env = process.env) {
     const forced = env.AGENT_SANDBOX_SYNC_UPDATE;
@@ -59,7 +65,8 @@ export class Terminal {
             return;
         this.active = true;
         this.frame = [];
-        readline.emitKeypressEvents(this.stdin);
+        // The first call on a stream sets its decoder; later calls (and readline interfaces) keep it.
+        readline.emitKeypressEvents(this.stdin, { escapeCodeTimeout: ESCAPE_TIMEOUT_MS });
         if (this.stdin.isTTY)
             this.stdin.setRawMode(true);
         this.stdin.on('keypress', this.onKeypress);

package/dist/cli/validate.js

@@ -4,7 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { DATABASES } from '../core/detect/index.js';
 import { fail } from '../core/util/index.js';
-import { AccountStore } from '../host/profile/index.js';
+import { AccountsService } from './services/accounts-service.js';
 /** Edit distance, for "did you mean". */
 export function distance(a, b) {
     let row = Array.from({ length: b.length + 1 }, (_, i) => i);
@@ -79,11 +79,15 @@ export function validateOptions(ctx) {
             unknownValue('database', db, DATABASES, 'Repeat --database for several.');
     }
     if (o.account !== undefined) {
-        const names = new AccountStore(ctx.storageRoot).list(ctx.dataPath).map((a) => a.name);
+        // The launched agent's saved logins (an agent that keeps none says so).
+        const agent = o.harness ?? ctx.loaded.config.defaultHarness;
+        const names = new AccountsService(ctx).list(agent).map((a) => a.name);
         if (!names.includes(o.account))
             unknownValue('account', o.account, names, names.length
-                ? 'See them with: sandbox account list'
-                : 'None saved yet: sign in inside the sandbox, then run sandbox account save <name>.');
+                ? 'See them with: sandbox account list' + (agent === 'claude' ? '' : ' --agent ' + agent)
+                : 'None saved yet: sign in inside the sandbox, then run sandbox account save <name>' +
+                    (agent === 'claude' ? '' : ' --agent ' + agent) +
+                    '.');
     }
     for (const s of o.sessions) {
         checkHarness(s.harness, harnesses);

package/dist/core/package-info.js

@@ -1,5 +1,5 @@
 // Where this package is installed and its version. This file is dist/core/package-info.js, two folders below
-// package.json.
+// package.json, or bundled into a chunk in dist/bin (scripts/bundle.mjs), also two folders below.
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';

package/dist/guest/daemon/sessions.d.ts

@@ -22,6 +22,13 @@ export declare class SessionManager {
     /** The sessions' ptyhosts, running or ended within ROOTS_KEPT_MS (audit events arrive after they happen). */
     roots(): SessionRoot[];
     private rootStarted;
+    /** What a session's ptyhost left running when it was itself ended (Task Manager, a crash) is ended now. */
+    private endLeftovers;
+    /**
+     * At the daemon's start: trees recorded by session hosts that are gone (a daemon that ended with them) are ended
+     * too. One whose session host still runs is left alone (ptyhost --end-tree checks).
+     */
+    sweepLeftovers(): void;
     private rootEnded;
     /**
      * `session` requests: an agent (or a plain shell) in its own ptyhost, in the launch folder's project or a registered

package/dist/guest/daemon/sessions.js

@@ -16,7 +16,7 @@ import { commandLine, shellLaunch } from '../sessions/cmdline.js';
 import { pwshDir } from '../toolchains/tools/pwsh.js';
 import { freePort } from '../runtime/ports.js';
 import { primaryProject } from '../boot/project-status.js';
-import { ensurePtyHost, ptyHostLogTail, startPtyHost, waitForPtyHost } from '../sessions/pty-host.js';
+import { endLeftoverTree, ensurePtyHost, ptyHostLogTail, recordedTrees, startPtyHost, waitForPtyHost, } from '../sessions/pty-host.js';
 import { agents } from '../agents/agent-installer.js';
 import { saveClaudeMem } from '../setup/claude-mem.js';
 import { saveLocalState } from '../agents/local-state.js';
@@ -224,7 +224,28 @@ export class SessionManager {
     rootStarted(id, child, from) {
         if (child.pid)
             this.ptyHosts.set(id, { session: id, pid: child.pid, from });
-        child.once('exit', () => this.rootEnded(id));
+        child.once('exit', () => {
+            this.rootEnded(id);
+            this.endLeftovers(id);
+        });
+    }
+    /** What a session's ptyhost left running when it was itself ended (Task Manager, a crash) is ended now. */
+    endLeftovers(id) {
+        void endLeftoverTree(id)
+            .then((done) => {
+            if (done)
+                log('Session ' + id + ': its session host was ended from outside; ' + done + ' it left running');
+        })
+            .catch((e) => warn('Ending what session ' + id + ' left running failed: ' + errMsg(e)));
+    }
+    /**
+     * At the daemon's start: trees recorded by session hosts that are gone (a daemon that ended with them) are ended
+     * too. One whose session host still runs is left alone (ptyhost --end-tree checks).
+     */
+    sweepLeftovers() {
+        for (const id of recordedTrees())
+            if (!this.live.has(id))
+                this.endLeftovers(id);
     }
     rootEnded(id) {
         const r = this.ptyHosts.get(id);

package/dist/guest/entries/daemon.js

@@ -17,6 +17,7 @@ adoptBootSecrets();
 log('Session daemon started (pid ' + process.pid + ').');
 safely('port forwards', startRelays);
 safely('audit', () => startProcessCollector(() => sessions.roots()));
+safely('leftover processes', () => sessions.sweepLeftovers());
 safely('memory governor', () => governor.start());
 log('Memory governor: ' + governor.describe());
 new Daemon().start();

package/dist/guest/sessions/pty-host.d.ts

@@ -20,3 +20,13 @@ export interface PtyHostOptions {
 }
 /** Starts ptyhost detached, so closing a terminal tab never kills the agent; only the agent exiting ends it. */
 export declare function startPtyHost(o: PtyHostOptions): ChildProcess;
+/**
+ * Ends what a session's ptyhost left running when it was itself ended (Task Manager, a crash): its program and what
+ * that started, from the tree it recorded in run/trees (PTYHOST_TREE_FILE). ptyhost deletes the record when it ends the
+ * tree itself, so a record left behind is the sign. `ptyhost --end-tree` checks every process by id and start time (a
+ * reused id is never ended), spares the shared ones (databases, sccache ...) and does nothing while the ptyhost that
+ * wrote it still runs. Resolves with what it did, or null when there was nothing to do.
+ */
+export declare function endLeftoverTree(id: string, exe?: string): Promise<string | null>;
+/** Session ids with a process tree recorded (running sessions, and any whose ptyhost was ended). */
+export declare function recordedTrees(): string[];

package/dist/guest/sessions/pty-host.js

@@ -1,10 +1,10 @@
 // Starts one ptyhost (the ConPTY bridge, sandbox/csharp/PtyHost.cs) per agent session and waits for it to listen.
 import fs from 'node:fs';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { ensureCompiled } from '../runtime/csc.js';
 import { portOpen } from '../runtime/ports.js';
-import { logsDir, toolsDir } from '../runtime/paths.js';
+import { logsDir, run, toolsDir } from '../runtime/paths.js';
 import { session } from '../runtime/session.js';
 export function ensurePtyHost() {
     return ensureCompiled('ptyhost');
@@ -51,10 +51,55 @@ const conptyDll = () => {
 };
 /** Starts ptyhost detached, so closing a terminal tab never kills the agent; only the agent exiting ends it. */
 export function startPtyHost(o) {
-    const env = { ...o.env, PTYHOST_BIND: o.remote ? 'any' : 'loopback' };
+    fs.mkdirSync(run.treesDir, { recursive: true });
+    const env = {
+        ...o.env,
+        PTYHOST_BIND: o.remote ? 'any' : 'loopback',
+        PTYHOST_TREE_FILE: run.treeFile(o.id),
+    };
     delete env.PTYHOST_CONPTY;
     const dll = conptyDll();
     if (dll)
         env.PTYHOST_CONPTY = dll;
     return spawn(o.exe, [String(o.port), o.token, String(o.cols), String(o.rows), ptyHostLog(o.id), o.command, o.restartCommand], { cwd: o.cwd, env, detached: true, stdio: 'ignore', windowsHide: true });
 }
+/** How long `ptyhost --end-tree` may take (a process snapshot and a few TerminateProcess calls). */
+const END_TREE_MS = 30000;
+/**
+ * Ends what a session's ptyhost left running when it was itself ended (Task Manager, a crash): its program and what
+ * that started, from the tree it recorded in run/trees (PTYHOST_TREE_FILE). ptyhost deletes the record when it ends the
+ * tree itself, so a record left behind is the sign. `ptyhost --end-tree` checks every process by id and start time (a
+ * reused id is never ended), spares the shared ones (databases, sccache ...) and does nothing while the ptyhost that
+ * wrote it still runs. Resolves with what it did, or null when there was nothing to do.
+ */
+export function endLeftoverTree(id, exe = ensurePtyHost()) {
+    const file = run.treeFile(id);
+    if (!fs.existsSync(file))
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        execFile(exe, ['--end-tree', file], { timeout: END_TREE_MS, windowsHide: true }, (error, stdout) => {
+            const code = error ? (typeof error.code === 'number' ? error.code : -1) : 0;
+            // 3: the ptyhost that wrote it still runs (its session goes on): the record stays.
+            if (code !== 3)
+                try {
+                    fs.rmSync(file, { force: true });
+                }
+                catch {
+                    /* removed by the next sweep (or the host's reset at the next launch) */
+                }
+            resolve(code === 0 ? stdout.trim().slice(0, 200) : code === 3 ? null : 'could not end them (code ' + code + ')');
+        });
+    });
+}
+/** Session ids with a process tree recorded (running sessions, and any whose ptyhost was ended). */
+export function recordedTrees() {
+    try {
+        return fs
+            .readdirSync(run.treesDir)
+            .filter((n) => /^[A-Za-z0-9_-]{1,64}\.json$/.test(n))
+            .map((n) => n.slice(0, -'.json'.length));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/host/channel/channel.js

@@ -231,7 +231,7 @@ export class SandboxChannel {
             removeLink(p.root);
             return;
         }
-        for (const target of [p.sandboxFile, p.requestsDir, p.responsesDir, p.sessionsDir, p.projectsDir]) {
+        for (const target of [p.sandboxFile, p.requestsDir, p.responsesDir, p.sessionsDir, p.projectsDir, p.treesDir]) {
             safeRemove(target, this.dataPath);
         }
     }

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

@@ -6,6 +6,7 @@ export declare const InstallRecordSchema: z.ZodObject<{
     }>;
     groupSid: z.ZodNullable<z.ZodString>;
     autoUpdate: z.ZodBoolean;
+    storageHelper: z.ZodOptional<z.ZodBoolean>;
     installedAt: z.ZodString;
 }, z.core.$strip>;
 export type InstallRecord = z.infer<typeof InstallRecordSchema>;

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

@@ -7,6 +7,8 @@ export const InstallRecordSchema = z.object({
     scope: z.enum(['user', 'machine']),
     groupSid: z.string().nullable(),
     autoUpdate: z.boolean(),
+    /** All-users installs: the storage helper service (AgentSandboxStorage) was installed. Older records have none. */
+    storageHelper: z.boolean().optional(),
     installedAt: z.string(),
 });
 export class InstallRecordFile {

package/dist/host/sandbox/contained-deps.d.ts

@@ -1,2 +1,3 @@
 import { type ContainedDeps } from '../storage/index.js';
-export declare function realContainedDeps(storageRoot: string, maxGb: number): ContainedDeps;
+/** `configOverridden`: the command runs with --config (the helper reads only your usual settings: it is not asked). */
+export declare function realContainedDeps(storageRoot: string, maxGb: number, configOverridden?: boolean): ContainedDeps;

package/dist/host/sandbox/contained-deps.js

@@ -1,17 +1,19 @@
-// The real wiring of contained storage on this PC: the permission-prompt scripts, protectPrivateFolder for new
+// The real wiring of contained storage on this PC: the storage helper when an all-users install added it, else the
+// permission-prompt scripts, protectPrivateFolder for new
 // folders, your SID, and whether a sandbox runs. Lives here (not in host/storage) so storage never imports the
 // sandbox or sharing folders, which import storage. The self-test never reaches a disk through it: the disk port
 // refuses there.
-import { ScriptDiskPort } from '../storage/index.js';
+import { HelperDiskPort, helperApplies, ScriptDiskPort } from '../storage/index.js';
 import { currentUserSid, protectPrivateFolder } from '../sharing/index.js';
 import { isSandboxRunning } from './platform.js';
-export function realContainedDeps(storageRoot, maxGb) {
+/** `configOverridden`: the command runs with --config (the helper reads only your usual settings: it is not asked). */
+export function realContainedDeps(storageRoot, maxGb, configOverridden = false) {
     return {
         storageRoot,
         maxGb,
         protect: (dir) => protectPrivateFolder(dir),
         userSid: currentUserSid,
-        port: new ScriptDiskPort(),
+        port: new HelperDiskPort(new ScriptDiskPort(), helperApplies(process.env, configOverridden)),
         sandboxRunning: isSandboxRunning,
     };
 }

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

@@ -7,6 +7,8 @@ export declare function insideSandbox(): boolean;
 export declare const GUEST_DATA_DIR = "C:\\AgentData";
 /** Whether a Windows Sandbox program is in this process list (tasklist /NH /FO CSV output). */
 export declare function sandboxInTasklist(tasklist: string): boolean;
+/** The process ids of the Windows Sandbox programs in this process list (tasklist /NH /FO CSV output). */
+export declare function sandboxPids(tasklist: string): number[];
 export declare function isSandboxRunning(): boolean;
 export declare function sandboxFeatureInstalled(): boolean;
 /** `owner`: whose sandbox runs, when the caller knows (host/sharing); it makes the message say who started it. */

package/dist/host/sandbox/platform.js

@@ -10,15 +10,19 @@ import { launchBlocked } from '../sharing/rules.js';
 const HELPER_TIMEOUT_MS = 15000;
 const START_WAIT_MS = 20000;
 const SANDBOX_PROCESSES = ['WindowsSandboxClient.exe', 'WindowsSandboxRemoteSession.exe', 'WindowsSandbox.exe'];
+/** Whether the launch and data folders are mapped in (looked for once; see insideSandbox). */
+let mappedIn;
 /**
  * Running INSIDE a Windows Sandbox this tool started (its launch folder and data folder are mapped in): then the CLI
  * talks to the sandbox it is in, through C:\\AgentData and loopback, instead of looking for one on a PC.
  */
 export function insideSandbox() {
-    return (isWin &&
-        !process.env.AGENT_SANDBOX_HOST_ONLY &&
-        fs.existsSync('C:\\AgentLaunch\\session.json') &&
-        fs.existsSync('C:\\AgentData\\run'));
+    if (!isWin || process.env.AGENT_SANDBOX_HOST_ONLY)
+        return false;
+    // The launch folder and the data folder are mapped in for the sandbox's whole life (and never exist on a PC), so
+    // they are looked for once: the menu asks this many times a second.
+    mappedIn ??= fs.existsSync('C:\\AgentLaunch\\session.json') && fs.existsSync('C:\\AgentData\\run');
+    return mappedIn;
 }
 export const GUEST_DATA_DIR = 'C:\\AgentData';
 /** Whether a Windows Sandbox program is in this process list (tasklist /NH /FO CSV output). */
@@ -26,6 +30,17 @@ export function sandboxInTasklist(tasklist) {
     const out = tasklist.toLowerCase();
     return SANDBOX_PROCESSES.some((image) => out.includes('"' + image.toLowerCase() + '"'));
 }
+/** The process ids of the Windows Sandbox programs in this process list (tasklist /NH /FO CSV output). */
+export function sandboxPids(tasklist) {
+    const images = new Set(SANDBOX_PROCESSES.map((image) => image.toLowerCase()));
+    const pids = [];
+    for (const line of tasklist.split('\n')) {
+        const row = /^"([^"]{1,260})","(\d{1,10})"/.exec(line);
+        if (row && images.has(row[1].toLowerCase()))
+            pids.push(Number(row[2]));
+    }
+    return pids;
+}
 export function isSandboxRunning() {
     if (!isWin)
         return false;

package/dist/host/sharing/lifecycle.js

@@ -43,7 +43,15 @@ export function beginSharing(deps, start, now = new Date()) {
     // The owner creates the run folder and every channel folder in it before others may write there: a folder another
     // user created would stay theirs, and writable by them, after sharing is turned off.
     const run = new RunDir(start.dataPath);
-    for (const dir of [run.root, run.requestsDir, run.responsesDir, run.sessionsDir, run.projectsDir, run.auditDir])
+    for (const dir of [
+        run.root,
+        run.requestsDir,
+        run.responsesDir,
+        run.sessionsDir,
+        run.projectsDir,
+        run.auditDir,
+        run.treesDir,
+    ])
         fs.mkdirSync(dir, { recursive: true });
     const plan = sharingAclPlan({
         storageUserDir: storageOf(start.dataPath),

package/dist/host/storage/contained/contained-storage.js

@@ -76,6 +76,19 @@ export class ContainedStorage {
             });
             this.requireOk(outcome, 'mount');
         }
+        else {
+            // Another holder vouches for the mount, but the folder could be a mount point of some other disk (one left after
+            // a restart, whose volume name an image of someone else's now has). A port that can check it without a prompt
+            // (the storage helper) is asked: it only says "mounted already" for a mount of this very image.
+            const confirmed = await this.deps.port.confirmMounted?.({
+                paths,
+                maxGb: this.deps.maxGb,
+                create: false,
+                userSid: this.deps.userSid(),
+            });
+            if (confirmed)
+                this.requireOk(confirmed, 'mount');
+        }
         this.assertReallyMounted();
         for (const name of CONTAINED_FOLDERS)
             fs.mkdirSync(path.join(paths.mount, name), { recursive: true });

package/dist/host/storage/contained/disk-port.d.ts

@@ -22,6 +22,11 @@ export interface DismountRequest {
 }
 export interface DiskPort {
     mount(request: MountRequest): Promise<ScriptOutcome>;
+    /**
+     * A mount that should be there already, checked without a permission prompt: the outcome of a mount (which, for a
+     * mount of this image, changes nothing), or null when this port cannot check without a prompt.
+     */
+    confirmMounted?(request: MountRequest): Promise<ScriptOutcome | null>;
     dismount(request: DismountRequest): Promise<ScriptOutcome>;
     reality(paths: ContainedPaths): Promise<MountReality>;
 }

package/dist/host/storage/contained/helper-port.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import type { ContainedPaths } from './layout.js';
+import type { DiskPort, DismountRequest, MountRequest, ScriptOutcome } from './disk-port.js';
+import type { MountReality } from './state.js';
+export declare const HELPER_PIPE = "\\\\.\\pipe\\AgentSandboxStorage";
+export declare const HELPER_PROTOCOL = 1;
+/** What goes to the service: exactly the verb and the data set (the service refuses anything else). */
+export declare const HelperRequestSchema: z.ZodObject<{
+    verb: z.ZodEnum<{
+        mount: "mount";
+        dismount: "dismount";
+    }>;
+    set: z.ZodString;
+}, z.core.$strict>;
+export type HelperRequest = z.infer<typeof HelperRequestSchema>;
+/** The service's answer (Protocol.Answer in Protocol.cs). */
+export declare const HelperAnswerSchema: z.ZodObject<{
+    protocol: z.ZodNumber;
+    ok: z.ZodBoolean;
+    message: z.ZodString;
+    created: z.ZodBoolean;
+    alreadyMounted: z.ZodBoolean;
+    fallback: z.ZodBoolean;
+    image: z.ZodString;
+    mount: z.ZodString;
+    notes: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type HelperAnswer = z.infer<typeof HelperAnswerSchema>;
+/** One call: the text of the answer, or why there was none. `absent`: no helper here (or not for you). */
+export type PipeResult = {
+    readonly kind: 'answer';
+    readonly text: string;
+} | {
+    readonly kind: 'absent';
+    readonly reason: string;
+} | {
+    readonly kind: 'failed';
+    readonly reason: string;
+};
+export type PipeConnector = (pipe: string, line: string, timeoutMs: number) => Promise<PipeResult>;
+export declare const pipeConnector: PipeConnector;
+/**
+ * Whether the helper may be asked at all. It reads your settings from the usual place (your profile's
+ * .agent-sandbox\config.json and the machine file), so a run with other settings (--config, AGENT_SANDBOX_CONFIG,
+ * AGENT_SANDBOX_HOME) would get other folders: those use the permission prompt.
+ */
+export declare function helperApplies(env: NodeJS.ProcessEnv, configOverridden: boolean): boolean;
+/** The answer's paths are ours (Windows paths: case does not matter, a trailing backslash neither). */
+export declare function samePaths(answer: Pick<HelperAnswer, 'image' | 'mount'>, paths: ContainedPaths): boolean;
+/** What one answer means: an outcome, or "use the permission prompt instead". */
+export declare function readAnswer(result: PipeResult, paths: ContainedPaths): {
+    readonly use: 'outcome';
+    readonly outcome: ScriptOutcome;
+} | {
+    readonly use: 'fallback';
+    readonly why: string;
+};
+/** The helper when it is there and applies, else (and whenever it says so) the permission-prompt scripts. */
+export declare class HelperDiskPort implements DiskPort {
+    private readonly fallback;
+    private readonly applies;
+    private readonly connect;
+    private readonly pipe;
+    constructor(fallback: DiskPort, applies: boolean, connect?: PipeConnector, pipe?: string);
+    mount(request: MountRequest): Promise<ScriptOutcome>;
+    /** The helper checks a mount without a prompt (it is "mounted already" only for this image); null without it. */
+    confirmMounted(request: MountRequest): Promise<ScriptOutcome | null>;
+    dismount(request: DismountRequest): Promise<ScriptOutcome>;
+    reality(paths: ContainedPaths): Promise<MountReality>;
+    /** The helper's outcome, or null to use the permission prompt. */
+    private ask;
+}

package/dist/host/storage/contained/helper-port.js

@@ -0,0 +1,162 @@
+// The storage helper (native\csharp\StorageHelper, the Windows service AgentSandboxStorage that an all-users install
+// can add): mounting and dismounting go to its pipe instead of a Windows permission prompt. The request names only the
+// data set; the service works out the folders itself from your settings, so the answer's paths must equal ours. When
+// the helper is not installed, cannot be reached, or says to (an image it leaves alone), the permission-prompt scripts
+// run as before. Looking (reality) never needs either.
+import net from 'node:net';
+import { z } from 'zod';
+import { SET_NAME_RULE } from './layout.js';
+import { refuseInSelfTest } from '../../test-guard.js';
+export const HELPER_PIPE = '\\\\.\\pipe\\AgentSandboxStorage';
+export const HELPER_PROTOCOL = 1;
+const MOUNT_TIMEOUT_MS = 10 * 60_000;
+const MAX_ANSWER_BYTES = 64 * 1024;
+/** What goes to the service: exactly the verb and the data set (the service refuses anything else). */
+export const HelperRequestSchema = z
+    .object({ verb: z.enum(['mount', 'dismount']), set: z.string().regex(SET_NAME_RULE) })
+    .strict();
+/** The service's answer (Protocol.Answer in Protocol.cs). */
+export const HelperAnswerSchema = z.object({
+    protocol: z.number().int(),
+    ok: z.boolean(),
+    message: z.string().max(4000),
+    created: z.boolean(),
+    alreadyMounted: z.boolean(),
+    fallback: z.boolean(),
+    image: z.string().max(1000),
+    mount: z.string().max(1000),
+    notes: z.array(z.string().max(1000)).max(50),
+});
+/** Errors that mean "no helper to talk to": not installed (or stopped), or this user may not open it. */
+const ABSENT_CODES = new Set(['ENOENT', 'EACCES', 'EPERM', 'ECONNREFUSED']);
+export const pipeConnector = (pipe, line, timeoutMs) => new Promise((resolve) => {
+    let text = '';
+    let connected = false;
+    let settled = false;
+    const done = (result) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        socket.destroy();
+        resolve(result);
+    };
+    const socket = net.connect(pipe);
+    const timer = setTimeout(() => done({ kind: 'failed', reason: 'the storage helper did not answer in time' }), timeoutMs);
+    socket.setEncoding('utf8');
+    socket.on('connect', () => {
+        connected = true;
+        socket.write(line + '\n');
+    });
+    socket.on('data', (chunk) => {
+        text += chunk;
+        const end = text.indexOf('\n');
+        if (end >= 0)
+            done({ kind: 'answer', text: text.slice(0, end) });
+        else if (text.length > MAX_ANSWER_BYTES)
+            done({ kind: 'failed', reason: 'the storage helper answered too much' });
+    });
+    socket.on('error', (e) => {
+        if (!connected && ABSENT_CODES.has(e.code ?? ''))
+            done({ kind: 'absent', reason: e.code ?? 'no pipe' });
+        else
+            done({ kind: 'failed', reason: e.message });
+    });
+    socket.on('close', () => done({ kind: 'failed', reason: 'the storage helper closed the connection' }));
+});
+/**
+ * Whether the helper may be asked at all. It reads your settings from the usual place (your profile's
+ * .agent-sandbox\config.json and the machine file), so a run with other settings (--config, AGENT_SANDBOX_CONFIG,
+ * AGENT_SANDBOX_HOME) would get other folders: those use the permission prompt.
+ */
+export function helperApplies(env, configOverridden) {
+    if (configOverridden)
+        return false;
+    return !env.AGENT_SANDBOX_CONFIG && !env.AGENT_SANDBOX_HOME;
+}
+/** The answer's paths are ours (Windows paths: case does not matter, a trailing backslash neither). */
+export function samePaths(answer, paths) {
+    const norm = (p) => p.replace(/\\+$/, '').toLowerCase();
+    return norm(answer.image) === norm(paths.image) && norm(answer.mount) === norm(paths.mount);
+}
+/** What one answer means: an outcome, or "use the permission prompt instead". */
+export function readAnswer(result, paths) {
+    if (result.kind === 'absent')
+        return { use: 'fallback', why: 'no storage helper (' + result.reason + ')' };
+    if (result.kind === 'failed')
+        return { use: 'outcome', outcome: failed('The storage helper did not finish: ' + result.reason + '.') };
+    let raw;
+    try {
+        raw = JSON.parse(result.text);
+    }
+    catch {
+        return { use: 'fallback', why: 'the storage helper gave an answer that is not JSON' };
+    }
+    const parsed = HelperAnswerSchema.safeParse(raw);
+    if (!parsed.success || parsed.data.protocol !== HELPER_PROTOCOL)
+        return { use: 'fallback', why: 'the storage helper speaks another version' };
+    const answer = parsed.data;
+    if (answer.fallback)
+        return { use: 'fallback', why: answer.message };
+    if (answer.ok && !samePaths(answer, paths))
+        return {
+            use: 'outcome',
+            outcome: failed('The storage helper used other folders (' +
+                answer.mount +
+                ') than this command (' +
+                paths.mount +
+                '): your settings differ from what it reads. Run sandbox doctor.'),
+        };
+    return {
+        use: 'outcome',
+        outcome: {
+            ok: answer.ok,
+            message: answer.message,
+            created: answer.created,
+            alreadyMounted: answer.alreadyMounted,
+            notes: answer.notes,
+        },
+    };
+}
+function failed(message) {
+    return { ok: false, message, created: false, alreadyMounted: false, notes: [] };
+}
+/** The helper when it is there and applies, else (and whenever it says so) the permission-prompt scripts. */
+export class HelperDiskPort {
+    fallback;
+    applies;
+    connect;
+    pipe;
+    constructor(fallback, applies, connect = pipeConnector, pipe = HELPER_PIPE) {
+        this.fallback = fallback;
+        this.applies = applies;
+        this.connect = connect;
+        this.pipe = pipe;
+    }
+    async mount(request) {
+        const answer = await this.ask({ verb: 'mount', set: request.paths.set }, request.paths);
+        return answer ?? this.fallback.mount(request);
+    }
+    /** The helper checks a mount without a prompt (it is "mounted already" only for this image); null without it. */
+    confirmMounted(request) {
+        return this.ask({ verb: 'mount', set: request.paths.set }, request.paths);
+    }
+    async dismount(request) {
+        const answer = await this.ask({ verb: 'dismount', set: request.paths.set }, request.paths);
+        return answer ?? this.fallback.dismount(request);
+    }
+    reality(paths) {
+        return this.fallback.reality(paths);
+    }
+    /** The helper's outcome, or null to use the permission prompt. */
+    async ask(request, paths) {
+        if (!this.applies)
+            return null;
+        // A test talks to a helper of its own (another pipe name); the real one could mount a real disk.
+        if (this.pipe === HELPER_PIPE)
+            refuseInSelfTest('mount or dismount a disk image');
+        const line = JSON.stringify(HelperRequestSchema.parse(request));
+        const read = readAnswer(await this.connect(this.pipe, line, MOUNT_TIMEOUT_MS), paths);
+        return read.use === 'outcome' ? read.outcome : null;
+    }
+}

package/dist/host/storage/contained/index.d.ts

@@ -2,6 +2,7 @@ export { CONTAINED_FOLDERS, containedMappings, containedPaths, setNameOf, type C
 export type { ContainedPaths } from './layout.js';
 export { ContainedStorage, type ContainedDeps, type HolderId, type ReleaseResult } from './contained-storage.js';
 export { ScriptDiskPort, spawnRunner, type DiskPort, type MountRequest, type ScriptOutcome } from './disk-port.js';
+export { HELPER_PIPE, HelperAnswerSchema, HelperDiskPort, helperApplies, HelperRequestSchema, pipeConnector, readAnswer, samePaths, type PipeConnector, type PipeResult, } from './helper-port.js';
 export { containedAvailability, containedFacts, type ContainedFacts } from './check.js';
 export { hostDataFolder, hostDataRoot } from './resolve.js';
 export { writeContainedSetting } from './setting.js';

package/dist/host/storage/contained/index.js

@@ -1,6 +1,7 @@
 export { CONTAINED_FOLDERS, containedMappings, containedPaths, setNameOf } from './layout.js';
 export { ContainedStorage } from './contained-storage.js';
 export { ScriptDiskPort, spawnRunner } from './disk-port.js';
+export { HELPER_PIPE, HelperAnswerSchema, HelperDiskPort, helperApplies, HelperRequestSchema, pipeConnector, readAnswer, samePaths, } from './helper-port.js';
 export { containedAvailability, containedFacts } from './check.js';
 export { hostDataFolder, hostDataRoot } from './resolve.js';
 export { writeContainedSetting } from './setting.js';

package/dist/host/storage/contained/state.d.ts

@@ -83,7 +83,8 @@ export declare class StateFile {
 export declare function mountedSets(storageRoot: string): string[];
 /**
  * A line for the start of a command when the record says an image is mounted that no running process holds and no
- * sandbox uses (nothing is looked up on the disk: this is only the record), or null.
+ * sandbox uses (nothing is looked up on the disk: this is only the record), or null. `sandboxRunning` can be a
+ * function: it is only asked (it runs tasklist) when the record says an image is mounted.
  */
-export declare function staleMountNote(storageRoot: string, set: string, sandboxRunning: boolean, alive?: (pid: number) => boolean): string | null;
+export declare function staleMountNote(storageRoot: string, set: string, sandboxRunning: boolean | (() => boolean), alive?: (pid: number) => boolean): string | null;
 export {};