windows-development-sandbox 1.13.2 → 1.15.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/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

@@ -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,14 +9,17 @@ 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());
 safely('memory governor', () => governor.start());
 log('Memory governor: ' + governor.describe());
 new Daemon().start();

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/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/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 {};