windows-development-sandbox 1.14.0 → 1.16.0

package/dist/guest/daemon/live.js

@@ -0,0 +1,57 @@
+// The daemon's live-folder handler with the real bind filter (BindMount.exe, compiled from sandbox\csharp each boot and
+// run by path) and its state on the sandbox's own disk, in a folder only administrators and SYSTEM may use.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+import { ensureCompiled } from '../runtime/csc.js';
+import { isWin, localDir, run, testMode } from '../runtime/paths.js';
+import { session } from '../runtime/session.js';
+import { warn } from '../runtime/log.js';
+import { LiveFolderHandler } from './live-folders.js';
+const BIND_TIMEOUT_MS = 30000;
+/** A test (it names its own local folder) never touches C:\ProgramData of the machine it runs on. */
+const testing = Boolean(process.env.AGENT_DAEMON_STATE_DIR || process.env.AGENT_LOCAL_DIR);
+const stateDir = process.env.AGENT_DAEMON_STATE_DIR ??
+    (process.env.AGENT_LOCAL_DIR
+        ? path.join(localDir, 'daemon-state')
+        : path.join(process.env.ProgramData ?? 'C:\\ProgramData', 'AgentSandboxDaemon'));
+function bindMount(args) {
+    const r = spawnSync(ensureCompiled('bindmount'), args, {
+        windowsHide: true,
+        timeout: BIND_TIMEOUT_MS,
+        encoding: 'utf8',
+    });
+    return r.status ?? 1;
+}
+const realBind = {
+    map: (folder, share, readOnly) => bindMount(['map', folder, share, ...(readOnly ? [] : ['rw'])]),
+    unmap: (folder) => bindMount(['unmap', folder]),
+    mapped: (folder) => bindMount(['mapped', folder]),
+};
+/** The state folder, made administrator-only (inside a real sandbox; a test names its own temp folder). */
+function protectStateDir() {
+    fs.mkdirSync(stateDir, { recursive: true });
+    if (!isWin || testMode || testing)
+        return;
+    spawnSync(SYSTEM.icacls(), [stateDir, '/inheritance:r', '/grant:r', '*S-1-5-32-544:(OI)(CI)F', '*S-1-5-18:(OI)(CI)F'], {
+        windowsHide: true,
+        timeout: BIND_TIMEOUT_MS,
+    });
+}
+export const liveFolders = new LiveFolderHandler({
+    run,
+    stateFile: path.join(stateDir, 'live-folders.json'),
+    launchId: session.launchId,
+    bind: realBind,
+    log: warn,
+});
+/** At daemon start: the folder protected, the boot's key taken in, the recorded mappings made again. */
+export function startLiveFolders(key) {
+    protectStateDir();
+    if (key)
+        liveFolders.setKey(key);
+    const again = liveFolders.reapply();
+    if (again)
+        warn('Live folders: ' + again + ' shown again after the daemon restarted.');
+}

package/dist/guest/entries/daemon.js

@@ -1,5 +1,5 @@
 // Session daemon (runs detached inside the sandbox for its whole life). It is the only thing that acts on host
-// requests, and it only knows four request kinds: start a session, run a command, restart sessions, ping.
+// requests: sessions, commands, restarts, pings (run\requests) and the signed live-folder requests (run\live).
 // It must never die quietly: every iteration is guarded, and anything unexpected is written to its log.
 // The handlers live in daemon/ (session, exec); this file is the polling loop.
 import { startRelays } from '../daemon/relays.js';
@@ -9,12 +9,14 @@ import { log, warn } from '../runtime/log.js';
 import { adoptBootSecrets } from '../runtime/secrets.js';
 import { errMsg } from '../../core/util/errors.js';
 import { Daemon } from '../daemon/daemon.js';
+import { startLiveFolders } from '../daemon/live.js';
 import { sessions } from '../daemon/sessions.js';
 import { governor } from '../governor/index.js';
 process.on('uncaughtException', (e) => warn('daemon: unexpected error (continuing): ' + (e.stack ?? errMsg(e))));
 process.on('unhandledRejection', (e) => warn('daemon: unexpected error (continuing): ' + errMsg(e)));
-adoptBootSecrets();
+const liveKey = adoptBootSecrets();
 log('Session daemon started (pid ' + process.pid + ').');
+safely('live folders', () => startLiveFolders(liveKey));
 safely('port forwards', startRelays);
 safely('audit', () => startProcessCollector(() => sessions.roots()));
 safely('leftover processes', () => sessions.sweepLeftovers());

package/dist/guest/runtime/csc.d.ts

@@ -8,6 +8,7 @@ declare const SOURCES: {
     readonly linkgate: "LinkGate.cs";
     readonly pathsync: "PathSync.cs";
     readonly memgov: "MemGov.cs";
+    readonly bindmount: "BindMount.cs";
 };
 export type Helper = keyof typeof SOURCES;
 /** %TEMP%\agent-sandbox\<name>-<hash>.exe, compiled from this launch's source the first time it is needed. */

package/dist/guest/runtime/csc.js

@@ -21,6 +21,7 @@ const SOURCES = {
     linkgate: 'LinkGate.cs',
     pathsync: 'PathSync.cs',
     memgov: 'MemGov.cs',
+    bindmount: 'BindMount.cs',
 };
 function sourceOf(name) {
     return path.join(launchDir, 'sandbox', 'csharp', SOURCES[name]);

package/dist/guest/runtime/secrets.d.ts

@@ -6,7 +6,10 @@ export declare const BOOT_SECRETS_VARIABLE = "SBX_BOOT_SECRETS";
 export declare function takeSecrets(id: string): SecretsFile;
 /** The agent the sandbox booted with gets its environment (in memory only). */
 export declare function applyBootEnvironment(environment: Record<string, string> | undefined): void;
-/** The daemon takes what main.js passed it, and removes it from its own environment before any session starts. */
-export declare function adoptBootSecrets(): void;
+/**
+ * The daemon takes what main.js passed it, and removes it from its own environment before any session starts. Returns
+ * the live-folder key, if the launch made one (the daemon keeps it in its own state).
+ */
+export declare function adoptBootSecrets(): string | undefined;
 /** A request with the agent environment values that travelled in its own secrets file put back (in memory only). */
 export declare function withRequestSecrets(req: GuestRequest): GuestRequest;

package/dist/guest/runtime/secrets.js

@@ -40,20 +40,27 @@ export function applyBootEnvironment(environment) {
     if (session.harness && environment)
         session.harness.environment = { ...environment };
 }
-/** The daemon takes what main.js passed it, and removes it from its own environment before any session starts. */
+/**
+ * The daemon takes what main.js passed it, and removes it from its own environment before any session starts. Returns
+ * the live-folder key, if the launch made one (the daemon keeps it in its own state).
+ */
 export function adoptBootSecrets() {
     const text = process.env[BOOT_SECRETS_VARIABLE];
     delete process.env[BOOT_SECRETS_VARIABLE];
     if (!text)
-        return;
+        return undefined;
     try {
-        const parsed = SecretsFileSchema.pick({ harnessEnvironment: true }).safeParse(JSON.parse(text));
-        if (parsed.success)
+        const parsed = SecretsFileSchema.pick({ harnessEnvironment: true, liveFoldersKey: true }).safeParse(JSON.parse(text));
+        if (parsed.success) {
             applyBootEnvironment(parsed.data.harnessEnvironment);
+            return parsed.data.liveFoldersKey;
+        }
     }
     catch {
-        warn('The boot secrets given to the daemon were not valid.');
+        // Reported below.
     }
+    warn('The boot secrets given to the daemon were not valid.');
+    return undefined;
 }
 /** A request with the agent environment values that travelled in its own secrets file put back (in memory only). */
 export function withRequestSecrets(req) {

package/dist/host/engines/hcs/live-folders.d.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+import { SecretStore } from '../../secrets/index.js';
+/** The warning shown wherever live folders are offered or used. */
+export declare const LIVE_FOLDERS_WARNING = "Live folders through HCS are an alpha, untested on a real PC: if it fails, the sandbox may close, so save your work first. Each add or remove asks for administrator permission.";
+declare const ShareSchema: z.ZodObject<{
+    name: z.ZodString;
+    host: z.ZodString;
+    guest: z.ZodString;
+    folder: z.ZodString;
+    readOnly: z.ZodBoolean;
+    addedAt: z.ZodString;
+}, z.core.$strip>;
+declare const RecordSchema: z.ZodObject<{
+    launchId: z.ZodString;
+    dataPath: z.ZodString;
+    key: z.ZodString;
+    systemId: z.ZodNullable<z.ZodString>;
+    shares: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        host: z.ZodString;
+        guest: z.ZodString;
+        folder: z.ZodString;
+        readOnly: z.ZodBoolean;
+        addedAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type LiveRecord = z.output<typeof RecordSchema>;
+export type LiveShare = z.output<typeof ShareSchema>;
+/** What the elevated script was asked (request.json; HcsHost checks every field again). */
+export interface LiveShareRequest {
+    readonly action: 'add' | 'remove';
+    readonly id: string;
+    readonly name: string;
+    readonly path?: string;
+    readonly readOnly?: boolean;
+    readonly storageRoot: string;
+    readonly dataPath: string;
+    readonly userSid: string;
+}
+declare const OutcomeSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    message: z.ZodString;
+    id: z.ZodOptional<z.ZodString>;
+    canary: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type LiveOutcome = z.output<typeof OutcomeSchema>;
+/** The elevated half: one run of hcs-live-share.ps1. `onCanary` gets the canary share's name, returns its token. */
+export interface ElevatedLivePort {
+    run(request: LiveShareRequest, onCanary: (share: string) => Promise<string | null>): Promise<LiveOutcome>;
+}
+export type LiveRunner = (file: string, args: readonly string[], timeoutMs: number) => Promise<{
+    status: number | null;
+}>;
+export declare const spawnLiveRunner: LiveRunner;
+/** run-elevated.ps1 -Script hcs-live-share.ps1 with the request in a private temp folder; relays the canary. */
+export declare class ScriptLivePort implements ElevatedLivePort {
+    private readonly runner;
+    private readonly tempRoot;
+    private readonly pollMs;
+    constructor(runner?: LiveRunner, tempRoot?: string, pollMs?: number);
+    run(request: LiveShareRequest, onCanary: (share: string) => Promise<string | null>): Promise<LiveOutcome>;
+}
+export interface LiveFolderDeps {
+    readonly storageRoot: string;
+    readonly dataPath: string;
+    readonly secrets: SecretStore;
+    readonly elevated: ElevatedLivePort;
+    readonly userSid: () => string;
+    readonly isAlive?: () => boolean;
+    readonly pollMs?: number;
+    readonly now?: () => Date;
+    /** How long the sandbox's daemon has for the canary and for a map or unmap (tests make them short). */
+    readonly canaryMs?: number;
+    readonly mapMs?: number;
+}
+/** <storage>\state\live-folders.json. */
+export declare function liveRecordFile(storageRoot: string): string;
+export declare class LiveFolders {
+    private readonly d;
+    private readonly file;
+    private readonly run;
+    constructor(d: LiveFolderDeps);
+    read(): LiveRecord | null;
+    /** At launch (projects.liveFolders "hcs"): a new key for this launch, kept sealed; returned for the secrets file. */
+    startLaunch(launchId: string): string;
+    /** The sandbox stopped (its shares ended with it), or a launch without live folders: the record goes. */
+    clear(): void;
+    /** Why live folders cannot be used for this launch now (null: they can). */
+    unavailable(launchId: string): string | null;
+    private log;
+    private key;
+    /** Sends one signed request to the sandbox's daemon and waits for its reply. */
+    private ask;
+    private request;
+    /**
+     * Shares `host` (its real path) into the running sandbox and shows it at C:\Workspace\`folder`. Throws with the
+     * reason when anything refuses or fails; the folder is then not shared.
+     */
+    add(o: {
+        launchId: string;
+        host: string;
+        guest: string;
+        folder: string;
+        readOnly: boolean;
+    }): Promise<LiveShare>;
+    /** The share itself (elevated). True when it is gone; the record is kept when not. */
+    private removeShare;
+    /** The live folder of `host`, if there is one. */
+    shareOf(host: string): LiveShare | null;
+    /** Removes a live folder: the guest mapping first, then the share. Throws (and keeps it) when either fails. */
+    remove(launchId: string, host: string): Promise<void>;
+}
+/** The real thing: DPAPI, the elevated script (it builds HcsHost.exe itself), this user's SID. */
+export declare function realLiveFolders(storageRoot: string, dataPath: string): LiveFolders;
+/** The sandbox of `dataPath` stopped: its live-folder record (and key) goes; its shares ended with the VM. */
+export declare function clearLiveRecord(storageRoot: string, dataPath: string): boolean;
+export {};

package/dist/host/engines/hcs/live-folders.js

@@ -0,0 +1,347 @@
+// Live folders through HCS (opt-in alpha, projects.liveFolders "hcs"; docs/design/hcs-live-folders.md): adds a folder
+// of this PC to the RUNNING Windows Sandbox where `wsb share` is missing. Two halves:
+//  - the share: native\scripts\hcs-live-share.ps1, run elevated (one Windows permission prompt per add or remove),
+//    runs HcsHost.exe wsb-share, which finds the one running Windows Sandbox, proves with a canary share that it is
+//    the sandbox whose daemon answers in our run folder, and only then shares the folder (read-only unless asked);
+//  - the guest mapping: a request signed with this launch's key (shared/channel/live.ts) asks the sandbox's daemon to
+//    show the share at C:\Workspace\<name>.
+// The record is host-only, <storage>\state\live-folders.json (never in the data folder): the launch, its key (sealed
+// with DPAPI), the Windows Sandbox id the first canary proved, and the shares this tool added. Remove takes only names
+// in that record. A stop of the sandbox clears it (shares end with the VM). Nothing read from the sandbox can ask for a
+// share: the host only ever compares the canary token the daemon read.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { z } from 'zod';
+import { assertNoLinks, fail, safeText, sleep } from '../../../core/util/index.js';
+import { LIVE_SHARE_NAME, LIVE_TOKEN, LiveReplySchema, newLiveKey, newShareName, RunDir, signLive, } from '../../../shared/channel/index.js';
+import { JsonFile, readValid, writeFileAtomic, writeJsonAtomic } from '../../../shared/io/index.js';
+import { SYSTEM } from '../../../shared/system.js';
+import { nativeFile, nativeScript } from '../../native.js';
+import { refuseInSelfTest } from '../../test-guard.js';
+import { SecretStore } from '../../secrets/index.js';
+import { isSandboxRunning } from '../../sandbox/index.js';
+import { currentUserSid } from '../../sharing/index.js';
+const GUID = /^[0-9A-Fa-f]{8}-([0-9A-Fa-f]{4}-){3}[0-9A-Fa-f]{12}$/;
+/** The prompt, the canary (45 s at most in HcsHost) and three HCS operations of 60 s at most. */
+const ELEVATED_TIMEOUT_MS = 6 * 60_000;
+const CANARY_REPLY_MS = 30_000;
+const MAP_REPLY_MS = 60_000;
+const MAX_LOG_BYTES = 256 * 1024;
+/** The warning shown wherever live folders are offered or used. */
+export const LIVE_FOLDERS_WARNING = 'Live folders through HCS are an alpha, untested on a real PC: if it fails, the sandbox may close, so save your work first. Each add or remove asks for administrator permission.';
+const ShareSchema = z.object({
+    name: z.string().regex(LIVE_SHARE_NAME),
+    host: z.string().min(3).max(1024),
+    guest: z.string().max(1024),
+    folder: z.string().max(64),
+    readOnly: z.boolean(),
+    addedAt: z.string().max(40),
+});
+const RecordSchema = z.object({
+    launchId: z.string().min(1).max(64),
+    dataPath: z.string().max(1024),
+    /** This launch's key for signed requests, sealed (SecretStore). */
+    key: z.string().max(4096),
+    /** The running Windows Sandbox's HCS id, once the first canary proved it. */
+    systemId: z.string().regex(GUID).nullable(),
+    shares: z.array(ShareSchema).max(256),
+});
+const OutcomeSchema = z.object({
+    ok: z.boolean(),
+    message: z.string().max(4000),
+    id: z.string().max(64).optional(),
+    canary: z.string().max(64).optional(),
+});
+export const spawnLiveRunner = (file, args, timeoutMs) => new Promise((resolve) => {
+    const child = spawn(file, [...args], { windowsHide: true, stdio: 'ignore' });
+    const timer = setTimeout(() => child.kill(), timeoutMs);
+    child.on('error', () => {
+        clearTimeout(timer);
+        resolve({ status: null });
+    });
+    child.on('close', (code) => {
+        clearTimeout(timer);
+        resolve({ status: code });
+    });
+});
+/** run-elevated.ps1 -Script hcs-live-share.ps1 with the request in a private temp folder; relays the canary. */
+export class ScriptLivePort {
+    runner;
+    tempRoot;
+    pollMs;
+    constructor(runner = spawnLiveRunner, tempRoot = os.tmpdir(), pollMs = 300) {
+        this.runner = runner;
+        this.tempRoot = tempRoot;
+        this.pollMs = pollMs;
+    }
+    async run(request, onCanary) {
+        if (this.runner === spawnLiveRunner)
+            refuseInSelfTest('add a folder to the running Windows Sandbox');
+        const dir = fs.mkdtempSync(path.join(this.tempRoot, 'agent-sandbox-live-'));
+        try {
+            const file = path.join(dir, 'request.json');
+            fs.writeFileSync(file, JSON.stringify(request, null, 2), 'utf8');
+            const sha = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+            let done = false;
+            const finished = this.runner(SYSTEM.powershell(), nativeScript('run-elevated.ps1', [
+                '-Script',
+                nativeFile('scripts', 'hcs-live-share.ps1'),
+                '-Json',
+                file,
+                '-Sha256',
+                sha,
+            ]), ELEVATED_TIMEOUT_MS).then((r) => {
+                done = true;
+                return r;
+            });
+            let relayed = false;
+            while (!done) {
+                if (!relayed) {
+                    const share = readCanary(path.join(dir, 'canary.json'));
+                    if (share) {
+                        relayed = true;
+                        const token = await onCanary(share).catch(() => null);
+                        writeFileAtomic(path.join(dir, 'answer.txt'), token && LIVE_TOKEN.test(token) ? token : 'none');
+                    }
+                }
+                await sleep(this.pollMs);
+            }
+            const r = await finished;
+            const answer = readValid(OutcomeSchema, path.join(dir, 'result.json'));
+            if (!answer)
+                return fail(r.status === 1
+                    ? 'Windows did not give permission (the prompt was declined or closed).'
+                    : 'The live-folder helper gave no answer.', 'Run the command again and choose Yes in the Windows prompt, or restart the sandbox to add the folder.');
+            return answer;
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+}
+/** canary.json from the elevated helper: {"share": "agentsbx-..."} (small, checked). */
+function readCanary(file) {
+    try {
+        if (fs.statSync(file).size > 1024)
+            return null;
+        const parsed = z
+            .object({ share: z.string().regex(LIVE_SHARE_NAME) })
+            .safeParse(JSON.parse(fs.readFileSync(file, 'utf8')));
+        return parsed.success ? parsed.data.share : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** <storage>\state\live-folders.json. */
+export function liveRecordFile(storageRoot) {
+    return path.join(storageRoot, 'state', 'live-folders.json');
+}
+export class LiveFolders {
+    d;
+    file;
+    run;
+    constructor(d) {
+        this.d = d;
+        this.file = new JsonFile(RecordSchema, liveRecordFile(d.storageRoot));
+        this.run = new RunDir(d.dataPath);
+    }
+    read() {
+        return this.file.read();
+    }
+    /** At launch (projects.liveFolders "hcs"): a new key for this launch, kept sealed; returned for the secrets file. */
+    startLaunch(launchId) {
+        const key = newLiveKey();
+        this.file.write({
+            launchId,
+            dataPath: this.d.dataPath,
+            key: this.d.secrets.seal(key),
+            systemId: null,
+            shares: [],
+        });
+        return key;
+    }
+    /** The sandbox stopped (its shares ended with it), or a launch without live folders: the record goes. */
+    clear() {
+        fs.rmSync(liveRecordFile(this.d.storageRoot), { force: true });
+    }
+    /** Why live folders cannot be used for this launch now (null: they can). */
+    unavailable(launchId) {
+        const record = this.read();
+        if (!record)
+            return 'the running sandbox was started while projects.liveFolders was off (turn it on before it starts)';
+        if (record.launchId !== launchId)
+            return 'the live-folder record belongs to an earlier sandbox';
+        if (path.resolve(record.dataPath).toLowerCase() !== path.resolve(this.d.dataPath).toLowerCase())
+            return 'the live-folder record belongs to another data folder';
+        return null;
+    }
+    log(line) {
+        try {
+            const file = path.join(this.d.storageRoot, 'state', 'live-folders.log');
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            try {
+                if (fs.statSync(file).size > MAX_LOG_BYTES)
+                    fs.renameSync(file, file + '.old');
+            }
+            catch {
+                // No log yet.
+            }
+            fs.appendFileSync(file, (this.d.now ?? (() => new Date()))().toISOString() + ' ' + line + '\n', 'utf8');
+        }
+        catch {
+            // The log is a convenience.
+        }
+    }
+    key(record) {
+        return this.d.secrets.open(record.key);
+    }
+    /** Sends one signed request to the sandbox's daemon and waits for its reply. */
+    async ask(record, p, timeoutMs) {
+        const id = Date.now().toString(36) + crypto.randomBytes(4).toString('hex');
+        const payload = {
+            v: 1,
+            id,
+            launchId: record.launchId,
+            createdAt: (this.d.now ?? (() => new Date()))().toISOString(),
+            ...p,
+        };
+        assertNoLinks(this.d.dataPath, this.run.liveDir);
+        assertNoLinks(this.d.dataPath, this.run.liveRepliesDir);
+        writeJsonAtomic(this.run.liveFile(id), signLive(this.key(record), payload));
+        const reply = this.run.liveReplyFile(id);
+        const deadline = Date.now() + timeoutMs;
+        for (let round = 0; Date.now() < deadline; round++) {
+            const answer = readValid(LiveReplySchema, reply);
+            if (answer && answer.id === id) {
+                fs.rmSync(reply, { force: true });
+                // Guest text: printable only before it can reach a message or the terminal.
+                return { ...answer, message: safeText(answer.message).slice(0, 300) };
+            }
+            if (round % 10 === 9 && this.d.isAlive && !this.d.isAlive())
+                break;
+            await sleep(this.d.pollMs ?? 300);
+        }
+        fs.rmSync(this.run.liveFile(id), { force: true });
+        return { id, ok: false, message: 'the sandbox did not answer', finishedAt: '' };
+    }
+    request(record, action, name, extra) {
+        return {
+            action,
+            id: record.systemId ?? '',
+            name,
+            ...extra,
+            storageRoot: this.d.storageRoot,
+            dataPath: this.d.dataPath,
+            userSid: this.d.userSid(),
+        };
+    }
+    /**
+     * Shares `host` (its real path) into the running sandbox and shows it at C:\Workspace\`folder`. Throws with the
+     * reason when anything refuses or fails; the folder is then not shared.
+     */
+    async add(o) {
+        const why = this.unavailable(o.launchId);
+        if (why)
+            fail('Live folders cannot be used: ' + why + '.');
+        const record = this.read();
+        if (record.shares.some((s) => s.host.toLowerCase() === o.host.toLowerCase()))
+            fail(o.host + ' is a live folder already.');
+        const name = newShareName();
+        const onCanary = async (share) => {
+            const reply = await this.ask(record, { kind: 'canary', share, folder: 'live-canary-' + crypto.randomBytes(4).toString('hex'), readOnly: true }, this.d.canaryMs ?? CANARY_REPLY_MS);
+            return reply.ok && reply.token ? reply.token : null;
+        };
+        const outcome = await this.d.elevated.run(this.request(record, 'add', name, { path: o.host, readOnly: o.readOnly }), onCanary);
+        this.log('add ' +
+            name +
+            ' ' +
+            o.host +
+            ' -> ' +
+            o.guest +
+            ' id=' +
+            (outcome.id ?? '') +
+            ' canary=' +
+            (outcome.canary ?? '') +
+            ' ' +
+            (outcome.ok ? 'ok' : 'failed: ' + outcome.message));
+        if (!outcome.ok)
+            fail('The folder was not shared: ' + safeText(outcome.message) + '.');
+        if (!outcome.id || !GUID.test(outcome.id))
+            fail('The live-folder helper did not say which sandbox it shared the folder with; it ends when the sandbox stops.');
+        const unexpected = Boolean(record.systemId && record.systemId.toLowerCase() !== outcome.id.toLowerCase());
+        const share = {
+            name,
+            host: o.host,
+            guest: o.guest,
+            folder: o.folder,
+            readOnly: o.readOnly,
+            addedAt: new Date().toISOString(),
+        };
+        const latest = this.read() ?? record;
+        // Recorded before anything else can fail, so remove can still take it away.
+        this.file.write({ ...latest, systemId: latest.systemId ?? outcome.id, shares: [...latest.shares, share] });
+        if (unexpected)
+            fail('The live-folder helper answered for an unexpected sandbox; nothing more is done.');
+        const mapped = await this.ask(record, { kind: 'map', share: name, folder: o.folder, readOnly: o.readOnly }, this.d.mapMs ?? MAP_REPLY_MS);
+        if (!mapped.ok) {
+            this.log('map ' + name + ' failed: ' + mapped.message);
+            const undone = await this.removeShare(share).catch((e) => (e instanceof Error ? e.message : String(e)));
+            fail('The folder was shared but the sandbox could not show it: ' +
+                mapped.message +
+                (undone === true ? ' (the share was removed again).' : ' (the share stays until the sandbox stops).'));
+        }
+        return share;
+    }
+    /** The share itself (elevated). True when it is gone; the record is kept when not. */
+    async removeShare(share) {
+        const record = this.read();
+        if (!record?.systemId || !record.shares.some((s) => s.name === share.name))
+            fail('That share is not in the live-folder record.');
+        const outcome = await this.d.elevated.run(this.request(record, 'remove', share.name, {}), async () => null);
+        this.log('remove ' + share.name + ' ' + share.host + ' ' + (outcome.ok ? 'ok' : 'failed: ' + outcome.message));
+        if (!outcome.ok)
+            fail('The share could not be removed: ' + safeText(outcome.message) + '. It ends when the sandbox stops.');
+        const latest = this.read() ?? record;
+        this.file.write({ ...latest, shares: latest.shares.filter((s) => s.name !== share.name) });
+        return true;
+    }
+    /** The live folder of `host`, if there is one. */
+    shareOf(host) {
+        return this.read()?.shares.find((s) => s.host.toLowerCase() === host.toLowerCase()) ?? null;
+    }
+    /** Removes a live folder: the guest mapping first, then the share. Throws (and keeps it) when either fails. */
+    async remove(launchId, host) {
+        const why = this.unavailable(launchId);
+        if (why)
+            fail('Live folders cannot be used: ' + why + '.');
+        const record = this.read();
+        const share = this.shareOf(host) ?? fail(host + ' is not a live folder.');
+        const hidden = await this.ask(record, { kind: 'unmap', folder: share.folder, readOnly: share.readOnly }, this.d.mapMs ?? MAP_REPLY_MS);
+        if (!hidden.ok)
+            fail('The sandbox could not hide ' + share.guest + ': ' + hidden.message + '.', 'Close what uses it in the sandbox and try again; otherwise it stays until the sandbox stops.');
+        await this.removeShare(share);
+    }
+}
+/** The real thing: DPAPI, the elevated script (it builds HcsHost.exe itself), this user's SID. */
+export function realLiveFolders(storageRoot, dataPath) {
+    return new LiveFolders({
+        storageRoot,
+        dataPath,
+        secrets: SecretStore.standard(),
+        elevated: new ScriptLivePort(),
+        userSid: currentUserSid,
+        isAlive: isSandboxRunning,
+    });
+}
+/** The sandbox of `dataPath` stopped: its live-folder record (and key) goes; its shares ended with the VM. */
+export function clearLiveRecord(storageRoot, dataPath) {
+    const record = new JsonFile(RecordSchema, liveRecordFile(storageRoot)).read();
+    if (!record || path.resolve(record.dataPath).toLowerCase() !== path.resolve(dataPath).toLowerCase())
+        return false;
+    fs.rmSync(liveRecordFile(storageRoot), { force: true });
+    return true;
+}

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

@@ -6,3 +6,4 @@ export { wsbText } from './windows-sandbox/wsb-text.js';
 export { HcsEngine, HCS_CAPABILITIES, hcsStartEnabled } from './hcs/engine.js';
 export { checkHcs, realHcsProbes, type HcsProbes } from './hcs/check.js';
 export { lookForLeftovers, stopLeftovers, LEFTOVER_DEPS, type LeftoverDeps, type LeftoverLook, type LeftoverOutcome, type LeftoverSystem, } from './hcs/leftovers.js';
+export { LiveFolders, ScriptLivePort, clearLiveRecord, realLiveFolders, liveRecordFile, LIVE_FOLDERS_WARNING, type LiveRecord, type LiveShare, type LiveShareRequest, type LiveOutcome, type ElevatedLivePort, type LiveRunner, } from './hcs/live-folders.js';

package/dist/host/engines/index.js

@@ -4,3 +4,4 @@ export { wsbText } from './windows-sandbox/wsb-text.js';
 export { HcsEngine, HCS_CAPABILITIES, hcsStartEnabled } from './hcs/engine.js';
 export { checkHcs, realHcsProbes } from './hcs/check.js';
 export { lookForLeftovers, stopLeftovers, LEFTOVER_DEPS, } from './hcs/leftovers.js';
+export { LiveFolders, ScriptLivePort, clearLiveRecord, realLiveFolders, liveRecordFile, LIVE_FOLDERS_WARNING, } from './hcs/live-folders.js';

package/dist/host/launch/generate.js

@@ -6,7 +6,7 @@ import crypto from 'node:crypto';
 import os from 'node:os';
 import { widenForProjects } from '../../core/local-config/index.js';
 import { dirExists, ensureDir, fail, writeJson } from '../../core/util/index.js';
-import { engineFor } from '../engines/index.js';
+import { engineFor, realLiveFolders } from '../engines/index.js';
 import { capturePersonalization, stageClaudeProfile } from '../profile/index.js';
 import { clearSecrets, writeSecrets } from '../secrets/index.js';
 import { githubTokenAllowed } from '../github/index.js';
@@ -102,7 +102,14 @@ opened) {
         profile: loadProfileOf(config),
         reserveHostMb: config.sandbox.reserveHostMb,
     });
+    // Live folders through HCS (opt-in alpha, Windows Sandbox only): a new key per launch, sealed on this side and handed
+    // over in the one-shot file; without the setting, an earlier launch's record goes.
+    const live = realLiveFolders(storageRoot, dataPath);
+    const liveFoldersKey = config.projects.liveFolders === 'hcs' && engine.id === 'windows-sandbox' ? live.startLaunch(launchId) : undefined;
+    if (!liveFoldersKey)
+        live.clear();
     writeSecrets(dataPath, launchId, {
+        ...(liveFoldersKey ? { liveFoldersKey } : {}),
         ...(harness && Object.keys(harness.environment).length ? { harnessEnvironment: harness.environment } : {}),
         ...(claudeCredentials ? { claudeCredentials } : {}),
         ...(o.vpn?.credentials ? { vpn: o.vpn.credentials } : {}),

package/dist/host/projects/join.d.ts

@@ -35,6 +35,10 @@ export declare function joinRunning(o: {
     packageRoot: string;
     hostDir: string;
     wsbShare: boolean;
+    /** projects.liveFolders ("hcs": the opt-in alpha that adds folders through HCS where wsb share is missing). */
+    liveFolders?: 'off' | 'hcs';
+    /** Shown at once (the live-folder warning comes before its permission prompt). */
+    onNote?: (note: string) => void;
     resolve: (projectRoot: string) => Promise<ResolvedRun>;
     mapper?: ProjectMapper;
     /** Asked before anything is registered when something is missing (default: continue without it). */