windows-development-sandbox 1.14.0 → 1.16.0

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

@@ -1,7 +1,7 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   attach
-} from "./chunk-BQ23GBLC.js";
+} from "./chunk-HIC4CUMY.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-F7IMME5G.js";
-import "./chunk-BQ23GBLC.js";
+} from "./chunk-7EXDUNE7.js";
+import "./chunk-HIC4CUMY.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-F7IMME5G.js";
-import "./chunk-BQ23GBLC.js";
+} from "./chunk-7EXDUNE7.js";
+import "./chunk-HIC4CUMY.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-F7IMME5G.js";
-import "./chunk-BQ23GBLC.js";
+} from "./chunk-7EXDUNE7.js";
+import "./chunk-HIC4CUMY.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-F7IMME5G.js";
-import "./chunk-BQ23GBLC.js";
+} from "./chunk-7EXDUNE7.js";
+import "./chunk-HIC4CUMY.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-F7IMME5G.js";
-import "./chunk-BQ23GBLC.js";
+} from "./chunk-7EXDUNE7.js";
+import "./chunk-HIC4CUMY.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-F7IMME5G.js";
-import "./chunk-BQ23GBLC.js";
+} from "./chunk-7EXDUNE7.js";
+import "./chunk-HIC4CUMY.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-F7IMME5G.js";
-import "./chunk-BQ23GBLC.js";
+} from "./chunk-7EXDUNE7.js";
+import "./chunk-HIC4CUMY.js";
 
 // src/bin/sbx-show.ts
 run(process.argv.slice(2), { command: "show" });

package/dist/cli/commands/projects/here.js

@@ -77,6 +77,8 @@ export async function joinHere(ctx, status, o = {}) {
         packageRoot,
         hostDir: dir,
         wsbShare: loaded.config.projects.wsbShare,
+        liveFolders: loaded.config.projects.liveFolders,
+        onNote: (note) => console.log(c.yellow(note)),
         resolve: (root) => resolveRun({
             packageRoot,
             loaded,

package/dist/cli/index.js

@@ -12,7 +12,7 @@ import { takeHiddenInstallNotice } from '../host/install/index.js';
 import { c } from './output/index.js';
 import { dropInheritedModulePath } from '../shared/system.js';
 import { withConfig, hoistConfig, withoutConfig } from './argv.js';
-import { report } from './report.js';
+import { recordUnexpected, report } from './report.js';
 import { versionText } from './version.js';
 import { HANDLERS } from './commands/index.js';
 import { definitionHandler, operationHandler } from './operations/index.js';
@@ -121,6 +121,9 @@ export async function main(rawArgv, preset = {}) {
 }
 export function run(argv, preset) {
     dropInheritedModulePath();
+    // Background work that throws must not end the menu or the web server: the error is kept with its stack instead.
+    process.on('unhandledRejection', (e) => recordUnexpected(e, 'unhandled rejection'));
+    process.on('uncaughtException', (e) => recordUnexpected(e, 'uncaught exception'));
     main(argv, preset).then((code) => {
         process.exitCode = code;
     }, (e) => {

package/dist/cli/report.d.ts

@@ -1,2 +1,9 @@
+/** Where errors nobody caught are written in full (this user's temp folder; kept under 1 MB). */
+export declare const UNEXPECTED_LOG: string;
+/**
+ * An error thrown by background work (a timer, a promise nobody awaited): written in full to UNEXPECTED_LOG and named
+ * in one line, instead of ending the menu, the web server or a command half-way.
+ */
+export declare function recordUnexpected(e: unknown, kind: string): void;
 /** Prints a problem the way a user can act on it: what happened, how to fix it; stack traces only for real bugs. */
 export declare function report(e: unknown): number;

package/dist/cli/report.js

@@ -1,6 +1,37 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { CommanderError } from 'commander';
 import { c } from './output/index.js';
 import { UserError, errMsg, plainText } from '../core/util/index.js';
+/** Where errors nobody caught are written in full (this user's temp folder; kept under 1 MB). */
+export const UNEXPECTED_LOG = path.join(os.tmpdir(), 'windows-development-sandbox-errors.log');
+const UNEXPECTED_LOG_MAX = 1024 * 1024;
+/**
+ * An error thrown by background work (a timer, a promise nobody awaited): written in full to UNEXPECTED_LOG and named
+ * in one line, instead of ending the menu, the web server or a command half-way.
+ */
+export function recordUnexpected(e, kind) {
+    const text = new Date().toISOString() +
+        ' ' +
+        kind +
+        ' (pid ' +
+        process.pid +
+        ', ' +
+        process.argv.slice(2).join(' ') +
+        ')\n' +
+        (e instanceof Error && e.stack ? e.stack : errMsg(e)) +
+        '\n\n';
+    try {
+        if (fs.existsSync(UNEXPECTED_LOG) && fs.statSync(UNEXPECTED_LOG).size > UNEXPECTED_LOG_MAX)
+            fs.rmSync(UNEXPECTED_LOG, { force: true });
+        fs.appendFileSync(UNEXPECTED_LOG, text);
+    }
+    catch {
+        // Nowhere to write it: the line below still says what happened.
+    }
+    console.error(c.red('Unexpected error (kept running): ') + plainText(errMsg(e)) + c.dim('  Details: ' + UNEXPECTED_LOG));
+}
 /** Prints a problem the way a user can act on it: what happened, how to fix it; stack traces only for real bugs. */
 export function report(e) {
     if (e instanceof CommanderError)

package/dist/cli/services/health-service.js

@@ -4,7 +4,8 @@ import { spawnSync } from 'node:child_process';
 import { expandPath, fail, isWin } from '../../core/util/index.js';
 import { detectWsb, doctorRows, insideSandbox, isSandboxRunning } from '../../host/sandbox/index.js';
 import { machineDoctorRows } from '../../host/sharing/index.js';
-import { KnownProjects, ProjectRegistry } from '../../host/projects/index.js';
+import { addFoldersRow, KnownProjects, ProjectRegistry } from '../../host/projects/index.js';
+import { realLiveFolders } from '../../host/engines/index.js';
 import { nativeScript } from '../../host/native.js';
 import { refuseInSelfTest } from '../../host/test-guard.js';
 import { SYSTEM } from '../../shared/system.js';
@@ -29,7 +30,9 @@ export class HealthService {
         // Several projects: the roots mapped at every start, what the running sandbox has, and whether wsb share is there.
         const p = ctx.loaded.config.projects;
         const registry = isSandboxRunning() ? new ProjectRegistry(ctx.storageRoot).read() : null;
-        const wsb = p.wsbShare ? detectWsb() : null;
+        const wsb = p.wsbShare || p.liveFolders === 'hcs' ? detectWsb() : null;
+        const launchId = registry?.launchId ?? null;
+        const liveUnavailable = p.liveFolders === 'hcs' && launchId ? realLiveFolders(ctx.storageRoot, ctx.dataPath).unavailable(launchId) : null;
         return [
             ...rows,
             ...machineDoctorRows(ctx.packageRoot, ctx.dataPath),
@@ -59,7 +62,16 @@ export class HealthService {
                             wsb.exe +
                             (wsb.version ? ' ' + wsb.version : '') +
                             ' (untested; a failure offers a restart instead)'
-                        : 'not on this Windows (needs Windows 11 24H2+ with the updated Windows Sandbox): folders outside your roots need a restart',
+                        : 'not on this Windows (needs Windows 11 24H2+ with the updated Windows Sandbox)',
+            ],
+            [
+                'Add folders while the sandbox runs',
+                addFoldersRow({
+                    wsbShare: p.wsbShare,
+                    liveFolders: p.liveFolders,
+                    wsbHasShare: wsb?.has('share') === true,
+                    liveUnavailable,
+                }),
             ],
         ];
     }

package/dist/cli/services/projects-service.d.ts

@@ -26,11 +26,16 @@ export declare class ProjectsService {
     list(): ProjectsListing;
     /** Remembers a project folder (it must pass the same checks as a workspace). Returns the folder. */
     add(folder: string): string;
-    /** Forgets a project, in the running sandbox too (its folder stays visible until the sandbox stops). */
-    forget(folder: string): {
+    /**
+     * Forgets a project, in the running sandbox too (a mapped folder stays visible until the sandbox stops; a live folder
+     * is hidden and its share removed, with one permission prompt).
+     */
+    forget(folder: string): Promise<{
         dir: string;
         removed: boolean;
-    };
+    }>;
+    /** The folder is a live folder (HCS) of the running sandbox: forgetting it removes its share (one prompt). */
+    isLive(folder: string): boolean;
     /** Excludes a folder from the projects mapped at every start. True when that changed anything. */
     exclude(folder: string): boolean;
     /** Includes a folder again (and remembers it). True when it was excluded before. */

package/dist/cli/services/projects-service.js

@@ -51,20 +51,37 @@ export class ProjectsService {
         new KnownProjects(this.ctx.storageRoot).remember(dir);
         return dir;
     }
-    /** Forgets a project, in the running sandbox too (its folder stays visible until the sandbox stops). */
-    forget(folder) {
+    /**
+     * Forgets a project, in the running sandbox too (a mapped folder stays visible until the sandbox stops; a live folder
+     * is hidden and its share removed, with one permission prompt).
+     */
+    async forget(folder) {
         const { ctx } = this;
         const dir = path.resolve(folder);
-        const forgot = new KnownProjects(ctx.storageRoot).forget(dir);
         const registered = isSandboxRunning()
             ? new ProjectRegistry(ctx.storageRoot)
                 .read()
                 ?.projects.find((p) => !p.primary && p.host.toLowerCase() === dir.toLowerCase())
             : undefined;
+        // The live folder first: when it cannot be removed, the project stays (in the list and in the sandbox).
         if (registered)
-            projectMapper({ storageRoot: ctx.storageRoot, packageRoot: ctx.packageRoot, wsbShare: false }).unregister(registered.name);
+            await projectMapper({
+                storageRoot: ctx.storageRoot,
+                packageRoot: ctx.packageRoot,
+                wsbShare: false,
+                dataPath: ctx.dataPath,
+            }).unregister(registered.name);
+        const forgot = new KnownProjects(ctx.storageRoot).forget(dir);
         return { dir, removed: forgot || Boolean(registered) };
     }
+    /** The folder is a live folder (HCS) of the running sandbox: forgetting it removes its share (one prompt). */
+    isLive(folder) {
+        const dir = path.resolve(folder);
+        return (isSandboxRunning() &&
+            new ProjectRegistry(this.ctx.storageRoot)
+                .read()
+                ?.projects.some((p) => p.mechanism === 'hcs' && p.host.toLowerCase() === dir.toLowerCase()) === true);
+    }
     /** Excludes a folder from the projects mapped at every start. True when that changed anything. */
     exclude(folder) {
         return addToList(this.ctx, ['projects', 'exclude'], path.resolve(folder));

package/dist/core/config/defaults.js

@@ -292,5 +292,6 @@ export const DEFAULTS = {
         declinedRoots: [],
         allowOutsideMappings: 'ask',
         wsbShare: true,
+        liveFolders: 'off',
     },
 };

package/dist/core/schema/config.d.ts

@@ -356,6 +356,10 @@ export declare const ConfigSchema: z.ZodObject<{
         declinedRoots: z.ZodArray<z.ZodString>;
         allowOutsideMappings: z.ZodUnion<readonly [z.ZodLiteral<"ask">, z.ZodBoolean]>;
         wsbShare: z.ZodBoolean;
+        liveFolders: z.ZodEnum<{
+            hcs: "hcs";
+            off: "off";
+        }>;
     }, z.core.$strict>;
     resume: z.ZodObject<{
         sessions: z.ZodEnum<{

package/dist/core/schema/projects.d.ts

@@ -7,4 +7,8 @@ export declare const ProjectsSchema: z.ZodObject<{
     declinedRoots: z.ZodArray<z.ZodString>;
     allowOutsideMappings: z.ZodUnion<readonly [z.ZodLiteral<"ask">, z.ZodBoolean]>;
     wsbShare: z.ZodBoolean;
+    liveFolders: z.ZodEnum<{
+        hcs: "hcs";
+        off: "off";
+    }>;
 }, z.core.$strict>;

package/dist/core/schema/projects.js

@@ -19,4 +19,7 @@ export const ProjectsSchema = z.strictObject({
     wsbShare: z
         .boolean()
         .describe('On Windows 11 24H2+ with the Windows Sandbox command line (wsb), add other folders to the running sandbox with `wsb share` (untested). Otherwise starting a project outside every root offers a restart.'),
+    liveFolders: z
+        .enum(['off', 'hcs'])
+        .describe('ALPHA, UNTESTED ON A REAL PC: "hcs" adds a project folder to the running sandbox through the Host Compute Service where `wsb share` is missing (one administrator prompt per add or remove; always read-only in this alpha). If it fails, the sandbox may close: save your work first. Turn it on before the sandbox starts. "off" (default) offers a restart instead. The real-PC tests still to pass are in docs/design/hcs-live-folders.md ("Test plan").'),
 });

package/dist/guest/boot/boot.js

@@ -73,8 +73,14 @@ function startDaemon(env, secrets) {
             ...env,
             AGENT_LOG_PREFIX: 'daemon',
             // The agent's environment (it may hold API keys): the daemon moves it into memory and removes this at once.
-            ...(secrets.harnessEnvironment
-                ? { [BOOT_SECRETS_VARIABLE]: JSON.stringify({ harnessEnvironment: secrets.harnessEnvironment }) }
+            // The live-folder key (projects.liveFolders "hcs") goes the same way into the daemon's own state.
+            ...(secrets.harnessEnvironment || secrets.liveFoldersKey
+                ? {
+                    [BOOT_SECRETS_VARIABLE]: JSON.stringify({
+                        ...(secrets.harnessEnvironment ? { harnessEnvironment: secrets.harnessEnvironment } : {}),
+                        ...(secrets.liveFoldersKey ? { liveFoldersKey: secrets.liveFoldersKey } : {}),
+                    }),
+                }
                 : {}),
         },
     }).unref();

package/dist/guest/daemon/daemon.js

@@ -8,6 +8,7 @@ import { governor } from '../governor/index.js';
 import { respond, safely } from './state.js';
 import { run } from '../runtime/paths.js';
 import { withRequestSecrets } from '../runtime/secrets.js';
+import { liveFolders } from './live.js';
 import { warn } from '../runtime/log.js';
 import { errMsg } from '../../core/util/errors.js';
 const POLL_MS = 400;
@@ -38,6 +39,8 @@ export class Daemon {
             // Not awaited: starting a session or running a command must not hold up other requests.
             void Promise.resolve(this.handle(withRequestSecrets(req))).catch((e) => respond(req.id, { ok: false, message: errMsg(e) }));
         }
+        // Live folders (signed host requests in run\live): claimed here, handled one after another.
+        safely('live folders', () => liveFolders.tick());
         if (Date.now() - this.lastMemSave > MEM_SAVE_MS) {
             this.lastMemSave = Date.now();
             safely('claude-mem save', saveClaudeMem);

package/dist/guest/daemon/live-folders.d.ts

@@ -0,0 +1,48 @@
+import type { RunDir } from '../../shared/channel/run-dir.js';
+/** The bind filter, behind an interface so the self-test can run the handler without one. */
+export interface BindPort {
+    /** BindMount map: 0 done, 3 the share is not there (yet), anything else failed. */
+    map(folder: string, share: string, readOnly: boolean): number;
+    unmap(folder: string): number;
+    /** BindMount mapped: 0 mapped, 4 not mapped, anything else unknown. */
+    mapped(folder: string): number;
+}
+export interface LiveFolderOptions {
+    readonly run: RunDir;
+    /** The daemon's own state file on the sandbox's disk (made administrator-only by the caller). */
+    readonly stateFile: string;
+    readonly launchId: string;
+    readonly bind: BindPort;
+    readonly workspaces?: string;
+    readonly now?: () => number;
+    readonly sleep?: (ms: number) => Promise<void>;
+    /** How often a missing share is tried again (0.5 s apart). */
+    readonly tries?: number;
+    readonly log?: (line: string) => void;
+}
+export declare class LiveFolderHandler {
+    private readonly o;
+    private queue;
+    constructor(o: LiveFolderOptions);
+    private now;
+    private log;
+    private read;
+    private save;
+    /** The key the boot handed over (from the one-shot secrets file). */
+    setKey(key: string): void;
+    /** C:\Workspace\<name> from a checked name only. */
+    private folderPath;
+    /** One pass over run\live: every file is claimed (deleted) at once; valid ones are handled one after another. */
+    tick(): void;
+    /** Waits for what tick() queued (tests). */
+    idle(): Promise<void>;
+    handle(envelope: unknown): Promise<void>;
+    private reply;
+    /** map with retries while the share is not there yet. */
+    private mapWithRetry;
+    /** The folder must not exist yet: not as a folder, a file or a link. */
+    private assertFree;
+    private act;
+    /** When the daemon starts: the recorded mappings this launch made, made again where they are gone. */
+    reapply(): number;
+}

package/dist/guest/daemon/live-folders.js

@@ -0,0 +1,245 @@
+// Live folders, the daemon's half (opt-in alpha, docs/design/hcs-live-folders.md): the host shares a folder into the
+// running sandbox (vSMB), then asks here, with a request signed by this launch's key (shared/channel/live.ts), to show
+// it at C:\Workspace\<name> through the bind filter (sandbox\csharp\BindMount.cs). A canary request does the same for a
+// test share, reads the token in it and hides it again: that proves to the host that the share reached THIS sandbox.
+// Every file in run\live is read at most 16 KB, links and bad names are deleted unread, and a request is acted on only
+// with a valid signature, this launch's id, a fresh time and an id not seen before (the seen ids are kept on the
+// sandbox's own disk, so restarting the daemon does not reopen them). Guest paths come only from the strict folder
+// name: never a path from the request. The mappings made are recorded and made again when the daemon starts.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { LIVE_FOLDER_NAME, LIVE_KEY, LIVE_SHARE_NAME, LIVE_TOKEN, openLive } from '../../shared/channel/live.js';
+import { writeJsonAtomic } from '../../shared/io/json.js';
+import { WORKSPACES_GUEST } from '../../shared/paths/projects.js';
+import { errMsg } from '../../core/util/errors.js';
+const MAX_REQUEST_BYTES = 16 * 1024;
+const MAX_SEEN = 512;
+/** BindMount's exit codes. */
+const EXIT_OK = 0;
+const EXIT_NO_SHARE = 3;
+const EXIT_NOT_MAPPED = 4;
+const StateSchema = z.object({
+    key: z.string().regex(LIVE_KEY).nullable(),
+    launchId: z.string().max(64),
+    seen: z.array(z.object({ id: z.string().max(64), at: z.number() })).max(MAX_SEEN),
+    mappings: z
+        .array(z.object({
+        folder: z.string().regex(LIVE_FOLDER_NAME),
+        share: z.string().regex(LIVE_SHARE_NAME),
+        readOnly: z.boolean(),
+    }))
+        .max(256),
+});
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class LiveFolderHandler {
+    o;
+    queue = Promise.resolve();
+    constructor(o) {
+        this.o = o;
+    }
+    now() {
+        return (this.o.now ?? Date.now)();
+    }
+    log(line) {
+        this.o.log?.(line);
+    }
+    read() {
+        try {
+            const text = fs.readFileSync(this.o.stateFile, 'utf8');
+            const parsed = StateSchema.safeParse(JSON.parse(text));
+            if (parsed.success && parsed.data.launchId === this.o.launchId)
+                return parsed.data;
+        }
+        catch {
+            // No state yet (or unreadable): a fresh one for this launch.
+        }
+        return { key: null, launchId: this.o.launchId, seen: [], mappings: [] };
+    }
+    save(state) {
+        fs.mkdirSync(path.dirname(this.o.stateFile), { recursive: true });
+        writeJsonAtomic(this.o.stateFile, state);
+    }
+    /** The key the boot handed over (from the one-shot secrets file). */
+    setKey(key) {
+        if (!LIVE_KEY.test(key))
+            return;
+        this.save({ ...this.read(), key });
+    }
+    /** C:\Workspace\<name> from a checked name only. */
+    folderPath(name) {
+        if (!LIVE_FOLDER_NAME.test(name))
+            throw new Error('not a plain folder name');
+        return path.win32.join(this.o.workspaces ?? WORKSPACES_GUEST, name);
+    }
+    /** One pass over run\live: every file is claimed (deleted) at once; valid ones are handled one after another. */
+    tick() {
+        const dir = this.o.run.liveDir;
+        let names;
+        try {
+            names = fs.readdirSync(dir);
+        }
+        catch {
+            return; // no requests yet
+        }
+        for (const name of names.slice(0, 64)) {
+            if (name.endsWith('.tmp'))
+                continue;
+            const file = path.join(dir, name);
+            let envelope = null;
+            try {
+                const stat = fs.lstatSync(file);
+                if (stat.isFile() && stat.size <= MAX_REQUEST_BYTES && /^[A-Za-z0-9_-]{1,64}\.json$/.test(name))
+                    envelope = JSON.parse(fs.readFileSync(file, 'utf8'));
+            }
+            catch {
+                envelope = null;
+            }
+            finally {
+                try {
+                    fs.rmSync(file, { recursive: true, force: true });
+                }
+                catch {
+                    // Locked for a moment: the next pass deletes it (the id is then seen already).
+                }
+            }
+            if (envelope === null)
+                continue;
+            this.queue = this.queue
+                .then(() => this.handle(envelope))
+                .catch((e) => this.log('live folder: ' + errMsg(e)));
+        }
+    }
+    /** Waits for what tick() queued (tests). */
+    idle() {
+        return this.queue;
+    }
+    async handle(envelope) {
+        const state = this.read();
+        const now = this.now();
+        const opened = openLive(state.key, envelope, { launchId: this.o.launchId, now });
+        if ('refused' in opened) {
+            this.log('live folder request ignored: ' + opened.refused);
+            return;
+        }
+        const p = opened.payload;
+        const seen = state.seen.filter((s) => now - s.at < 10 * 60 * 1000);
+        if (seen.some((s) => s.id === p.id)) {
+            this.log('live folder request ignored: seen before (' + p.id + ')');
+            return;
+        }
+        this.save({ ...state, seen: [...seen, { id: p.id, at: now }].slice(-MAX_SEEN) });
+        let reply;
+        try {
+            reply = await this.act(p);
+        }
+        catch (e) {
+            reply = { ok: false, message: errMsg(e).slice(0, 900) };
+        }
+        this.reply(p.id, reply);
+    }
+    reply(id, r) {
+        try {
+            fs.mkdirSync(this.o.run.liveRepliesDir, { recursive: true });
+            writeJsonAtomic(this.o.run.liveReplyFile(id), { id, ...r, finishedAt: new Date(this.now()).toISOString() });
+        }
+        catch (e) {
+            this.log('live folder reply not written: ' + errMsg(e));
+        }
+    }
+    /** map with retries while the share is not there yet. */
+    async mapWithRetry(folder, share, readOnly) {
+        const tries = this.o.tries ?? 20;
+        let code = EXIT_NO_SHARE;
+        for (let i = 0; i < tries; i++) {
+            code = this.o.bind.map(folder, share, readOnly);
+            if (code !== EXIT_NO_SHARE)
+                return code;
+            await (this.o.sleep ?? wait)(500);
+        }
+        return code;
+    }
+    /** The folder must not exist yet: not as a folder, a file or a link. */
+    assertFree(folder) {
+        let exists = true;
+        try {
+            fs.lstatSync(folder);
+        }
+        catch {
+            exists = false;
+        }
+        if (exists)
+            throw new Error(folder + ' exists already');
+        // The bind filter needs the parent (C:\Workspace) to exist: without it BfSetupFilter answers "not found", exactly
+        // like a share that has not arrived (seen in a Windows Sandbox, 2026-10-23). It must be a plain folder.
+        const parent = path.dirname(folder);
+        fs.mkdirSync(parent, { recursive: true });
+        if (!fs.lstatSync(parent).isDirectory())
+            throw new Error(parent + ' is not a plain folder');
+    }
+    async act(p) {
+        const folder = this.folderPath(p.folder);
+        if (p.kind === 'unmap') {
+            const state = this.read();
+            const known = state.mappings.find((m) => m.folder === p.folder);
+            if (!known)
+                return { ok: false, message: 'no live folder at ' + folder };
+            const code = this.o.bind.unmap(folder);
+            if (code !== EXIT_OK || this.o.bind.mapped(folder) !== EXIT_NOT_MAPPED)
+                return { ok: false, message: 'the folder could not be hidden again (are files in it open?)' };
+            const after = this.read();
+            this.save({ ...after, mappings: after.mappings.filter((m) => m.folder !== p.folder) });
+            return { ok: true, message: 'hidden: ' + folder };
+        }
+        const share = p.share ?? '';
+        this.assertFree(folder);
+        if (p.kind === 'canary') {
+            const code = await this.mapWithRetry(folder, share, true);
+            if (code !== EXIT_OK)
+                return { ok: false, message: 'the test share could not be shown (' + code + ')' };
+            try {
+                const file = path.join(folder, 'token.txt');
+                const stat = fs.statSync(file);
+                const token = stat.size <= 64 ? fs.readFileSync(file, 'utf8').trim() : '';
+                return LIVE_TOKEN.test(token)
+                    ? { ok: true, message: 'read the test share', token }
+                    : { ok: false, message: 'the test share holds no token' };
+            }
+            finally {
+                this.o.bind.unmap(folder);
+            }
+        }
+        const code = await this.mapWithRetry(folder, share, p.readOnly);
+        if (code !== EXIT_OK)
+            return {
+                ok: false,
+                message: code === EXIT_NO_SHARE
+                    ? 'the share did not reach the sandbox'
+                    : 'the folder could not be shown (' + code + ')',
+            };
+        const state = this.read();
+        this.save({
+            ...state,
+            mappings: [
+                ...state.mappings.filter((m) => m.folder !== p.folder),
+                { folder: p.folder, share, readOnly: p.readOnly },
+            ],
+        });
+        return { ok: true, message: 'shown at ' + folder };
+    }
+    /** When the daemon starts: the recorded mappings this launch made, made again where they are gone. */
+    reapply() {
+        let done = 0;
+        for (const m of this.read().mappings) {
+            const folder = this.folderPath(m.folder);
+            if (this.o.bind.mapped(folder) === EXIT_OK)
+                continue;
+            fs.mkdirSync(path.dirname(folder), { recursive: true });
+            if (this.o.bind.map(folder, m.share, m.readOnly) === EXIT_OK)
+                done++;
+            else
+                this.log('live folder ' + folder + ' could not be shown again');
+        }
+        return done;
+    }
+}

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

@@ -0,0 +1,4 @@
+import { LiveFolderHandler } from './live-folders.js';
+export declare const liveFolders: LiveFolderHandler;
+/** At daemon start: the folder protected, the boot's key taken in, the recorded mappings made again. */
+export declare function startLiveFolders(key: string | undefined): void;