windows-development-sandbox 1.13.2 → 1.14.0

package/dist/bin/{chunk-K4SU3MHJ.js → chunk-F7IMME5G.js}

@@ -226,7 +226,7 @@ import {
   withOperationCommands,
   working,
   writeJson
-} from "./chunk-VENWSGX2.js";
+} from "./chunk-BQ23GBLC.js";
 
 // node_modules/commander/lib/error.js
 var require_error = __commonJS({

package/dist/bin/{chunk-IL7BXJF2.js → chunk-LQHEUN2A.js}

@@ -1,7 +1,7 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   attach
-} from "./chunk-VENWSGX2.js";
+} from "./chunk-BQ23GBLC.js";
 export {
   attach
 };

package/dist/bin/claude-host.js

@@ -2,8 +2,8 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   run
-} from "./chunk-K4SU3MHJ.js";
-import "./chunk-VENWSGX2.js";
+} from "./chunk-F7IMME5G.js";
+import "./chunk-BQ23GBLC.js";
 
 // src/bin/claude-host.ts
 var args = process.argv.slice(2);

package/dist/bin/claude-sbx.js

@@ -2,8 +2,8 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   run
-} from "./chunk-K4SU3MHJ.js";
-import "./chunk-VENWSGX2.js";
+} from "./chunk-F7IMME5G.js";
+import "./chunk-BQ23GBLC.js";
 
 // src/bin/claude-sbx.ts
 run(process.argv.slice(2), { harness: "claude" });

package/dist/bin/codex-sbx.js

@@ -2,8 +2,8 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   run
-} from "./chunk-K4SU3MHJ.js";
-import "./chunk-VENWSGX2.js";
+} from "./chunk-F7IMME5G.js";
+import "./chunk-BQ23GBLC.js";
 
 // src/bin/codex-sbx.ts
 run(process.argv.slice(2), { harness: "codex" });

package/dist/bin/gemini-sbx.js

@@ -2,8 +2,8 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   run
-} from "./chunk-K4SU3MHJ.js";
-import "./chunk-VENWSGX2.js";
+} from "./chunk-F7IMME5G.js";
+import "./chunk-BQ23GBLC.js";
 
 // src/bin/gemini-sbx.ts
 run(process.argv.slice(2), { harness: "gemini" });

package/dist/bin/sandbox.js

@@ -2,8 +2,8 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   run
-} from "./chunk-K4SU3MHJ.js";
-import "./chunk-VENWSGX2.js";
+} from "./chunk-F7IMME5G.js";
+import "./chunk-BQ23GBLC.js";
 
 // src/bin/sandbox.ts
 run(process.argv.slice(2));

package/dist/bin/sbx-hide.js

@@ -2,8 +2,8 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   run
-} from "./chunk-K4SU3MHJ.js";
-import "./chunk-VENWSGX2.js";
+} from "./chunk-F7IMME5G.js";
+import "./chunk-BQ23GBLC.js";
 
 // src/bin/sbx-hide.ts
 run(process.argv.slice(2), { command: "hide" });

package/dist/bin/sbx-show.js

@@ -2,8 +2,8 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   run
-} from "./chunk-K4SU3MHJ.js";
-import "./chunk-VENWSGX2.js";
+} from "./chunk-F7IMME5G.js";
+import "./chunk-BQ23GBLC.js";
 
 // src/bin/sbx-show.ts
 run(process.argv.slice(2), { command: "show" });

package/dist/cli/commands/launch/launch.js

@@ -130,7 +130,7 @@ class Launcher {
         const engine = await openEngine(config);
         const provider = providerFor(config, config.storage.contained === 'off'
             ? {}
-            : { contained: realContainedDeps(ctx.storageRoot, config.storage.containedMaxGb) });
+            : { contained: realContainedDeps(ctx.storageRoot, config.storage.containedMaxGb, Boolean(ctx.options.config)) });
         if (!generateOnly)
             assertCanLaunch(isSandboxRunning() ? runningOwner() : undefined);
         // Contained storage: the image is mounted now (before anything reads or writes the data set), and let go of again

package/dist/cli/commands/repair/checks/contained.js

@@ -10,7 +10,7 @@ import { containedAvailability, ContainedStorage, containedPaths } from '../../.
 import { ok } from './common.js';
 function storageOf(env) {
     const { config } = env.ctx.loaded;
-    return new ContainedStorage(realContainedDeps(env.storageRoot, config.storage.containedMaxGb), config.storage.dataName);
+    return new ContainedStorage(realContainedDeps(env.storageRoot, config.storage.containedMaxGb, Boolean(env.ctx.options.config)), config.storage.dataName);
 }
 /** Only when contained storage is on, or an image or a record of one exists. */
 const inUse = (env) => {

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/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';