windows-development-sandbox 1.14.0 → 1.16.0

package/dist/host/projects/join.js

@@ -1,7 +1,7 @@
 // Joining the running sandbox from another folder. The folder's run is resolved exactly as a fresh launch would
 // resolve it (its approved .sandbox-config.json, versions, toolchain detection, database plan), checked against the
 // running sandbox's machine-wide protections, made visible inside (host/projects: a project root, a project
-// mapped at boot, or wsb share) and described to the guest, which provisions what is missing before its session.
+// mapped at boot, wsb share, or HCS) and described to the guest, which provisions what is missing before its session.
 // When none of those can make it visible, NeedsRestart reaches the caller, which offers a restart. So does a project
 // that wants what the sandbox only gets at its start (a .wsb device, more memory, its mappings) when you choose to
 // restart for it; otherwise it joins without them and they are named.
@@ -98,14 +98,22 @@ export async function joinRunning(o) {
         if (choice === 'restart')
             throw new NeedsRestart(root, 'it wants what the sandbox only gets at its start', missing);
     }
-    const mapper = o.mapper ?? projectMapper({ storageRoot: o.storageRoot, packageRoot: o.packageRoot, wsbShare: o.wsbShare });
+    const mapper = o.mapper ??
+        projectMapper({
+            storageRoot: o.storageRoot,
+            packageRoot: o.packageRoot,
+            wsbShare: o.wsbShare,
+            liveFolders: o.liveFolders,
+            dataPath: o.dataPath,
+        });
     // Guarded from now on. A folder the sandbox could already write (inside a root, or mapped at boot) and that has no
     // snapshot from the launch gets an empty one: what is there now may have been planted, so it counts as new.
     // Anything else is snapshotted before it becomes visible.
     new RepoGuardStore(o.dataPath).add(root, {
         empty: Boolean(here) || Boolean(registryFile.rootHere(root)),
     });
-    const entry = mapper.register(root);
+    // A live folder (HCS alpha) is always read-only until the real-PC test shows whose rights the share uses.
+    const entry = await mapper.register(root, { readOnly: true, onNote: o.onNote });
     new KnownProjects(o.storageRoot).remember(entry.host);
     // Your hooks in ~/.agent-sandbox/hooks ran at boot (once per sandbox); the project's own scripts ("scripts" in its
     // .sandbox-config.json, --script) run before its first agent. The launch folder is read-only for the sandbox, but

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

@@ -1,5 +1,6 @@
 import type { Missing } from '../../core/local-config/index.js';
 import { type Wsb } from '../sandbox/index.js';
+import { type LiveFolders } from '../engines/index.js';
 import { type RegistryEntry } from './registry.js';
 /**
  * Why a folder cannot join the running sandbox without a restart (the caller offers one). With `missing`: it could
@@ -14,16 +15,44 @@ export declare class NeedsRestart extends Error {
 export interface ProjectMapper {
     /** The projects of the running sandbox (the launch folder first). */
     list(): RegistryEntry[];
-    /** Makes a folder of this PC a project of the running sandbox; throws NeedsRestart when that needs a restart. */
-    register(hostDir: string): RegistryEntry;
-    /** Forgets a project (never the launch folder). Its folder stays visible until the next start if it is mapped. */
-    unregister(name: string): void;
+    /**
+     * Makes a folder of this PC a project of the running sandbox; throws NeedsRestart when that needs a restart.
+     * `readOnly`: how the project's own settings would map it (a live folder is read-only when this is not known).
+     */
+    register(hostDir: string, o?: {
+        readOnly?: boolean;
+        onNote?: (note: string) => void;
+    }): Promise<RegistryEntry>;
+    /**
+     * Forgets a project (never the launch folder). A live folder (hcs) is hidden in the sandbox and its share removed;
+     * any other mapped folder stays visible until the next start.
+     */
+    unregister(name: string): Promise<void>;
 }
+/** The parts of LiveFolders the mapper uses (a test hands in a fake). */
+export type LivePort = Pick<LiveFolders, 'add' | 'remove' | 'unavailable' | 'shareOf'>;
 export interface MapperOptions {
     storageRoot: string;
     packageRoot: string;
     wsbShare: boolean;
+    /** projects.liveFolders: "hcs" adds folders through HCS where wsb share is missing (alpha). */
+    liveFolders?: 'off' | 'hcs';
+    /** The data folder of the running sandbox (needed for live folders). */
+    dataPath?: string;
     detect?: () => Wsb | null;
+    live?: () => LivePort;
+    /** This Windows user started the running sandbox (not another user's, shared or not). */
+    isMine?: () => boolean;
 }
-/** Roots first (instant), then `wsb share` where the Windows Sandbox CLI exists, else NeedsRestart. */
+/** Roots first (instant), then `wsb share` where Windows has it, then HCS (opt-in), else NeedsRestart. */
 export declare function projectMapper(o: MapperOptions): ProjectMapper;
+/**
+ * The doctor's "Add folders while the sandbox runs": which way a folder outside every root would get in (wsb share, HCS
+ * or a restart) and why. `liveUnavailable`: why the running sandbox cannot take live folders (null: it can).
+ */
+export declare function addFoldersRow(o: {
+    wsbShare: boolean;
+    liveFolders: 'off' | 'hcs';
+    wsbHasShare: boolean;
+    liveUnavailable: string | null;
+}): string;

package/dist/host/projects/mapper.js

@@ -1,8 +1,11 @@
+import fs from 'node:fs';
 import path from 'node:path';
 import { assertSafeWorkspace } from '../../core/safe-paths.js';
 import { dirExists, fail } from '../../core/util/index.js';
-import { guestDirFor, hubName, ownGuestFolder, projectForHostDir } from '../../shared/paths/index.js';
+import { guestDirFor, hubName, liveGuestFolder, ownGuestFolder, projectForHostDir, } from '../../shared/paths/index.js';
 import { detectWsb, runningSandboxId, shareFolder } from '../sandbox/index.js';
+import { runningOwner } from '../sharing/index.js';
+import { LIVE_FOLDERS_WARNING, realLiveFolders } from '../engines/index.js';
 import { ProjectRegistry } from './registry.js';
 /**
  * Why a folder cannot join the running sandbox without a restart (the caller offers one). With `missing`: it could
@@ -19,7 +22,7 @@ export class NeedsRestart extends Error {
         this.missing = missing;
     }
 }
-/** Roots first (instant), then `wsb share` where the Windows Sandbox CLI exists, else NeedsRestart. */
+/** Roots first (instant), then `wsb share` where Windows has it, then HCS (opt-in), else NeedsRestart. */
 export function projectMapper(o) {
     const store = new ProjectRegistry(o.storageRoot);
     const registry = () => store.read() ??
@@ -41,9 +44,40 @@ export function projectMapper(o) {
         store.save({ ...latest, projects: [...latest.projects, entry] });
         return entry;
     };
+    const live = () => o.live
+        ? o.live()
+        : realLiveFolders(o.storageRoot, o.dataPath ?? fail('Live folders need the data folder of the running sandbox.'));
+    const taken = (reg) => [...reg.projects.map((p) => p.guest), ...reg.roots.map((r) => r.guest)];
+    /** Through HCS (projects.liveFolders "hcs", alpha): any refusal or failure is a NeedsRestart with the reason. */
+    const addLive = async (reg, host, name, readOnly, note) => {
+        if (!(o.isMine ?? (() => runningOwner().kind === 'mine'))())
+            throw new NeedsRestart(host, 'the running sandbox was not started by you, so no folder is added to it through HCS');
+        const port = live();
+        const why = port.unavailable(reg.launchId);
+        if (why)
+            throw new NeedsRestart(host, 'live folders through HCS cannot be used: ' + why);
+        // The real path (a subst drive is resolved here: the elevated helper does not see this session's drives).
+        let real;
+        try {
+            real = fs.realpathSync.native(host);
+        }
+        catch {
+            throw new NeedsRestart(host, 'the folder cannot be read');
+        }
+        assertSafeWorkspace(real, o.packageRoot, o.storageRoot);
+        const guest = liveGuestFolder(host, taken(reg));
+        note?.(LIVE_FOLDERS_WARNING);
+        try {
+            await port.add({ launchId: reg.launchId, host: real, guest, folder: path.win32.basename(guest), readOnly });
+        }
+        catch (e) {
+            throw new NeedsRestart(host, 'adding it through HCS failed (alpha): ' + (e instanceof Error ? e.message : String(e)));
+        }
+        return add(reg, host, guest, 'hcs', name);
+    };
     return {
         list: () => store.read()?.projects ?? [],
-        register: (hostDir) => {
+        register: async (hostDir, opts = {}) => {
             const host = path.resolve(hostDir);
             const reg = registry();
             const known = reg.projects.find((p) => p.host.toLowerCase() === host.toLowerCase());
@@ -57,32 +91,66 @@ export function projectMapper(o) {
             const root = projectForHostDir(reg.roots, host);
             if (root)
                 return add(reg, host, guestDirFor(root, host), 'root', name);
+            const hcs = o.liveFolders === 'hcs';
+            const wsb = o.wsbShare || hcs ? (o.detect ?? detectWsb)() : null;
+            // The official way wins wherever it exists: HCS only where wsb share is missing.
+            if (o.wsbShare && wsb?.has('share')) {
+                const sandbox = runningSandboxId(wsb);
+                if (!sandbox.id)
+                    throw new NeedsRestart(host, 'wsb share could not find the running sandbox: ' + sandbox.error);
+                // Where it is as a launch folder too (C:\Workspace\<name>), unless another project already uses that place.
+                const guest = ownGuestFolder(host, false, taken(reg));
+                const shared = shareFolder(wsb, sandbox.id, host, guest);
+                if (!shared.ok)
+                    throw new NeedsRestart(host, 'wsb share failed (untested on this Windows): ' + shared.error);
+                return add(reg, host, guest, 'wsb', name);
+            }
+            if (hcs && !wsb?.has('share'))
+                return addLive(reg, host, name, opts.readOnly ?? true, opts.onNote);
             if (!o.wsbShare)
                 throw new NeedsRestart(host, 'it is not inside a project root (projects.roots), and adding folders with wsb share is off (projects.wsbShare)');
-            const wsb = (o.detect ?? detectWsb)();
-            if (!wsb?.has('share'))
-                throw new NeedsRestart(host, 'it is not inside a project root (projects.roots), and this Windows has no Windows Sandbox command line (wsb share needs Windows 11 24H2+ with the updated Windows Sandbox)');
-            const sandbox = runningSandboxId(wsb);
-            if (!sandbox.id)
-                throw new NeedsRestart(host, 'wsb share could not find the running sandbox: ' + sandbox.error);
-            // Where it is as a launch folder too (C:\Workspace\<name>), unless another project already uses that place.
-            const guest = ownGuestFolder(host, false, [
-                ...reg.projects.map((p) => p.guest),
-                ...reg.roots.map((r) => r.guest),
-            ]);
-            const shared = shareFolder(wsb, sandbox.id, host, guest);
-            if (!shared.ok)
-                throw new NeedsRestart(host, 'wsb share failed (untested on this Windows): ' + shared.error);
-            return add(reg, host, guest, 'wsb', name);
+            throw new NeedsRestart(host, 'it is not inside a project root (projects.roots), and this Windows has no Windows Sandbox command line (wsb share needs Windows 11 24H2+ with the updated Windows Sandbox; projects.liveFolders "hcs" is an untested alpha for older Windows)');
         },
-        unregister: (name) => {
+        unregister: async (name) => {
             const reg = registry();
             const entry = reg.projects.find((p) => p.name.toLowerCase() === name.toLowerCase());
             if (!entry)
                 fail('No project "' + name + '" in the running sandbox.', 'sandbox projects lists them.');
             if (entry.primary)
                 fail(entry.host + ' is the folder the sandbox started from; it stays until the sandbox stops.');
-            store.save({ ...reg, projects: reg.projects.filter((p) => p !== entry) });
+            // A live folder: hidden in the sandbox first, then its share removed (one permission prompt); kept on failure.
+            if (entry.mechanism === 'hcs') {
+                const port = live();
+                let real = entry.host;
+                try {
+                    real = fs.realpathSync.native(entry.host);
+                }
+                catch {
+                    // Gone from this PC: its record still names the real path it had.
+                }
+                const share = port.shareOf(real) ?? port.shareOf(entry.host);
+                if (share)
+                    await port.remove(reg.launchId, share.host);
+            }
+            const latest = store.read() ?? reg;
+            store.save({ ...latest, projects: latest.projects.filter((p) => p.name !== entry.name) });
         },
     };
 }
+/**
+ * The doctor's "Add folders while the sandbox runs": which way a folder outside every root would get in (wsb share, HCS
+ * or a restart) and why. `liveUnavailable`: why the running sandbox cannot take live folders (null: it can).
+ */
+export function addFoldersRow(o) {
+    if (o.wsbHasShare && o.wsbShare)
+        return 'wsb share (untested; a failure offers a restart instead)';
+    if (o.liveFolders === 'hcs') {
+        if (o.wsbHasShare)
+            return 'restart: wsb share is on this Windows but switched off (projects.wsbShare); HCS is not used where wsb share exists';
+        return ('HCS (alpha, untested on a real PC): needs an administrator prompt each time' +
+            (o.liveUnavailable ? '; not for the running sandbox: ' + o.liveUnavailable : ''));
+    }
+    return o.wsbHasShare
+        ? 'restart (wsb share is switched off: projects.wsbShare)'
+        : 'restart (no wsb share on this Windows; projects.liveFolders "hcs" is an untested alpha that adds folders without one)';
+}

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

@@ -10,6 +10,7 @@ declare const RegistryEntrySchema: z.ZodObject<{
     guest: z.ZodString;
     primary: z.ZodBoolean;
     mechanism: z.ZodCatch<z.ZodEnum<{
+        hcs: "hcs";
         root: "root";
         launch: "launch";
         boot: "boot";
@@ -30,6 +31,7 @@ declare const RegistrySchema: z.ZodObject<{
         guest: z.ZodString;
         primary: z.ZodBoolean;
         mechanism: z.ZodCatch<z.ZodEnum<{
+            hcs: "hcs";
             root: "root";
             launch: "launch";
             boot: "boot";

package/dist/host/projects/registry.js

@@ -22,7 +22,7 @@ const RegistryEntrySchema = z.object({
     host: AbsolutePathSchema,
     guest: z.string().max(1024),
     primary: z.boolean(),
-    mechanism: z.enum(['launch', 'root', 'boot', 'wsb']).catch('root'),
+    mechanism: z.enum(['launch', 'root', 'boot', 'wsb', 'hcs']).catch('root'),
     registeredAt: z.string().max(64),
 });
 const RegistrySchema = z.object({

package/dist/host/secrets/launch-secrets.js

@@ -13,7 +13,8 @@ export function writeSecrets(dataPath, id, secrets) {
         !secrets.claudeCredentials &&
         !secrets.vpn &&
         !secrets.wireguardConfig &&
-        !secrets.githubToken;
+        !secrets.githubToken &&
+        !secrets.liveFoldersKey;
     if (empty)
         return null;
     const run = new RunDir(dataPath);

package/dist/runtime/agent.js

@@ -26645,6 +26645,9 @@ var ProjectsSchema = external_exports.strictObject({
   ),
   wsbShare: external_exports.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: external_exports.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").'
   )
 });
 
@@ -27180,6 +27183,9 @@ var RunDir = class {
   treesDir;
   /** One-shot secrets the host hands over (see secrets.ts). Next to run, not in it: shared-use users can change run. */
   secretsDir;
+  /** Live folders (live.ts): signed host requests, and the daemon's replies. */
+  liveDir;
+  liveRepliesDir;
   constructor(dataDir2) {
     this.root = path5.join(dataDir2, "run");
     this.sandboxFile = path5.join(this.root, "sandbox.json");
@@ -27193,6 +27199,14 @@ var RunDir = class {
     this.auditDir = path5.join(this.root, "audit");
     this.treesDir = path5.join(this.root, "trees");
     this.secretsDir = path5.join(dataDir2, "secrets");
+    this.liveDir = path5.join(this.root, "live");
+    this.liveRepliesDir = path5.join(this.root, "live-replies");
+  }
+  liveFile(id) {
+    return path5.join(this.liveDir, safeId(id) + ".json");
+  }
+  liveReplyFile(id) {
+    return path5.join(this.liveRepliesDir, safeId(id) + ".json");
   }
   requestFile(id) {
     return path5.join(this.requestsDir, safeId(id) + ".json");