windows-development-sandbox 1.5.0 → 1.9.0

package/dist/host/projects/registry.js

@@ -15,26 +15,28 @@ export const AbsolutePathSchema = z
     .string()
     .max(1024)
     .refine((p) => path.isAbsolute(p), 'must be an absolute path');
-const RegistryEntrySchema = z.strictObject({
+// Not strict: another copy or version of this tool may have written the file with more fields, and a registry that
+// reads as nothing would make a running sandbox look like one that cannot take another folder.
+const RegistryEntrySchema = z.object({
     name: IdSchema,
     host: AbsolutePathSchema,
     guest: z.string().max(1024),
     primary: z.boolean(),
-    mechanism: z.enum(['launch', 'root', 'boot', 'wsb']),
+    mechanism: z.enum(['launch', 'root', 'boot', 'wsb']).catch('root'),
     registeredAt: z.string().max(64),
 });
-const RegistrySchema = z.strictObject({
+const RegistrySchema = z.object({
     launchId: z.string().max(64),
     /** The running sandbox's protections (core/project-policy.ts), fixed at boot. */
     protections: z.record(z.string(), z.union([z.boolean(), z.string()])),
-    roots: z.array(z.strictObject({ host: AbsolutePathSchema, guest: z.string().max(1024) })).max(64),
+    roots: z.array(z.object({ host: AbsolutePathSchema, guest: z.string().max(1024) })).max(64),
     projects: z.array(RegistryEntrySchema).max(1024),
     /** What the sandbox booted with that a joining project may also want (missing in registries of 1.4.0 and older). */
     atBoot: z
-        .strictObject({
+        .object({
         memoryMb: z.number().int().positive().nullable(),
         mappings: z
-            .array(z.strictObject({ host: z.string().max(1024), guest: z.string().max(1024), readOnly: z.boolean() }))
+            .array(z.object({ host: z.string().max(1024), guest: z.string().max(1024), readOnly: z.boolean() }))
             .max(1024),
         /** Boot settings turned on for a project mapped at boot (setting -> project): other projects share them. */
         widened: z.record(z.string().max(100), z.string().max(100)),
@@ -116,6 +118,72 @@ export class ProjectRegistry {
     rootHere(hostDir) {
         return projectForHostDir(this.read()?.roots ?? [], hostDir);
     }
+    /**
+     * The record rebuilt from the running sandbox's launch folder (host-only storage), for when run\projects.json is
+     * missing, cannot be read or belongs to an earlier sandbox: the launch folder, and every folder mapped for other
+     * projects at boot as a root. Saved and returned; null when the launch folder does not have what it takes.
+     */
+    rebuild(launchPath, launchId, protections) {
+        const session = readBounded(path.join(launchPath, 'session.json'), MAX_SESSION_BYTES);
+        const wsb = readBounded(path.join(launchPath, 'agent.wsb'), MAX_WSB_BYTES);
+        if (session === null || wsb === null)
+            return null;
+        let parsed;
+        try {
+            const result = LaunchSessionSchema.safeParse(JSON.parse(session));
+            if (!result.success || result.data.launchId !== launchId)
+                return null;
+            parsed = result.data;
+        }
+        catch {
+            return null;
+        }
+        const atBoot = parseWsbBoot(wsb);
+        const forProjects = new Set(parsed.roots.map((guest) => guest.toLowerCase()));
+        const roots = atBoot.mappings
+            .filter((m) => forProjects.has(m.guest.toLowerCase()) && path.isAbsolute(m.host))
+            .slice(0, 64)
+            .map((m) => ({ host: m.host, guest: m.guest }));
+        const registry = {
+            launchId,
+            protections,
+            roots,
+            projects: [
+                {
+                    name: hubName(parsed.workspaceHost, []),
+                    host: parsed.workspaceHost,
+                    guest: parsed.workspace,
+                    primary: true,
+                    mechanism: 'launch',
+                    registeredAt: new Date().toISOString(),
+                },
+            ],
+            atBoot,
+        };
+        this.save(registry);
+        return registry;
+    }
+}
+const MAX_SESSION_BYTES = 4 * 1024 * 1024;
+const MAX_WSB_BYTES = 1024 * 1024;
+/** What rebuild() needs from a launch folder's session.json (written on this PC by the launch). */
+const LaunchSessionSchema = z.object({
+    launchId: z.string().max(64),
+    workspace: z.string().min(1).max(1024),
+    workspaceHost: AbsolutePathSchema,
+    roots: z.array(z.string().max(1024)).max(1024).default([]),
+});
+/** A file's text when it exists, is not a link and is at most `max` bytes; null otherwise. */
+function readBounded(file, max) {
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.size > max)
+            return null;
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
 }
 /**
  * The projects of a sandbox another user started and shares: what that user's record lists, in the shape of a registry.

package/dist/host/sandbox/contained-deps.d.ts

@@ -0,0 +1,2 @@
+import { type ContainedDeps } from '../storage/index.js';
+export declare function realContainedDeps(storageRoot: string, maxGb: number): ContainedDeps;

package/dist/host/sandbox/contained-deps.js

@@ -0,0 +1,17 @@
+// The real wiring of contained storage on this PC: the permission-prompt scripts, protectPrivateFolder for new
+// folders, your SID, and whether a sandbox runs. Lives here (not in host/storage) so storage never imports the
+// sandbox or sharing folders, which import storage. The self-test never reaches a disk through it: the disk port
+// refuses there.
+import { ScriptDiskPort } from '../storage/index.js';
+import { currentUserSid, protectPrivateFolder } from '../sharing/index.js';
+import { isSandboxRunning } from './platform.js';
+export function realContainedDeps(storageRoot, maxGb) {
+    return {
+        storageRoot,
+        maxGb,
+        protect: (dir) => protectPrivateFolder(dir),
+        userSid: currentUserSid,
+        port: new ScriptDiskPort(),
+        sandboxRunning: isSandboxRunning,
+    };
+}

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

@@ -1,6 +1,8 @@
 export * from './platform.js';
 export * from './probe.js';
+export * from './tasklist.js';
 export * from './host-claude.js';
 export * from './doctor.js';
 export * from './window.js';
 export * from './wsb-cli.js';
+export * from './contained-deps.js';

package/dist/host/sandbox/index.js

@@ -1,6 +1,8 @@
 export * from './platform.js';
 export * from './probe.js';
+export * from './tasklist.js';
 export * from './host-claude.js';
 export * from './doctor.js';
 export * from './window.js';
 export * from './wsb-cli.js';
+export * from './contained-deps.js';

package/dist/host/sandbox/platform.d.ts

@@ -5,6 +5,8 @@ import type { SandboxOwner } from '../sharing/owner.js';
  */
 export declare function insideSandbox(): boolean;
 export declare const GUEST_DATA_DIR = "C:\\AgentData";
+/** Whether a Windows Sandbox program is in this process list (tasklist /NH /FO CSV output). */
+export declare function sandboxInTasklist(tasklist: string): boolean;
 export declare function isSandboxRunning(): boolean;
 export declare function sandboxFeatureInstalled(): boolean;
 /** `owner`: whose sandbox runs, when the caller knows (host/sharing); it makes the message say who started it. */
@@ -12,5 +14,7 @@ export declare function assertCanLaunch(owner?: SandboxOwner): void;
 /** cmd.exe expands %VAR% and ^ even inside quotes, and a quote ends them: such a path could run something else. */
 export declare function assertCmdSafePath(file: string): void;
 export declare function startSandbox(wsbPath: string): void;
+/** After startSandbox: waits up to 20 seconds for the Windows Sandbox program to show up, or fails naming the .wsb. */
+export declare function confirmSandboxStarted(wsbPath: string, waitMs?: number): Promise<void>;
 /** Runs a detached copy of this CLI (used for the background history/claude-mem sync watcher). */
 export declare function spawnDetached(entry: string, args: string[]): void;

package/dist/host/sandbox/platform.js

@@ -2,9 +2,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { SYSTEM } from '../../shared/system.js';
+import { readTasklist } from './tasklist.js';
 import { refuseInSelfTest } from '../test-guard.js';
-import { fail, fileExists, isWin } from '../../core/util/index.js';
+import { fail, fileExists, isWin, sleep } from '../../core/util/index.js';
 import { launchBlocked } from '../sharing/rules.js';
+/** The longest a Windows helper program (tasklist, cmd start) may take before it counts as stuck. */
+const HELPER_TIMEOUT_MS = 15000;
+const START_WAIT_MS = 20000;
 const SANDBOX_PROCESSES = ['WindowsSandboxClient.exe', 'WindowsSandboxRemoteSession.exe', 'WindowsSandbox.exe'];
 /**
  * Running INSIDE a Windows Sandbox this tool started (its launch folder and data folder are mapped in): then the CLI
@@ -17,14 +21,17 @@ export function insideSandbox() {
         fs.existsSync('C:\\AgentData\\run'));
 }
 export const GUEST_DATA_DIR = 'C:\\AgentData';
+/** Whether a Windows Sandbox program is in this process list (tasklist /NH /FO CSV output). */
+export function sandboxInTasklist(tasklist) {
+    const out = tasklist.toLowerCase();
+    return SANDBOX_PROCESSES.some((image) => out.includes('"' + image.toLowerCase() + '"'));
+}
 export function isSandboxRunning() {
     if (!isWin)
         return false;
     if (insideSandbox())
         return true;
-    const result = spawnSync(SYSTEM.tasklist(), ['/NH', '/FO', 'CSV'], { encoding: 'utf8', windowsHide: true });
-    const out = (result.stdout ?? '').toLowerCase();
-    return SANDBOX_PROCESSES.some((image) => out.includes('"' + image.toLowerCase() + '"'));
+    return sandboxInTasklist(readTasklist());
 }
 export function sandboxFeatureInstalled() {
     return isWin && fileExists(path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32', 'WindowsSandbox.exe'));
@@ -55,10 +62,22 @@ export function startSandbox(wsbPath) {
     const result = spawnSync(SYSTEM.cmd(), ['/d', '/c', 'start', '""', '"' + wsbPath + '"'], {
         stdio: 'inherit',
         windowsVerbatimArguments: true,
+        timeout: HELPER_TIMEOUT_MS,
     });
     if (result.error)
         throw result.error;
 }
+/** After startSandbox: waits up to 20 seconds for the Windows Sandbox program to show up, or fails naming the .wsb. */
+export async function confirmSandboxStarted(wsbPath, waitMs = START_WAIT_MS) {
+    const deadline = Date.now() + waitMs;
+    while (!isSandboxRunning()) {
+        if (Date.now() >= deadline)
+            fail('Windows Sandbox did not start within ' + Math.round(waitMs / 1000) + ' seconds.', 'Open ' +
+                wsbPath +
+                ' yourself to see the message Windows gives, or run sandbox doctor to check the Windows Sandbox feature.');
+        await sleep(1000);
+    }
+}
 /** Runs a detached copy of this CLI (used for the background history/claude-mem sync watcher). */
 export function spawnDetached(entry, args) {
     refuseInSelfTest('start background programs');

package/dist/host/sandbox/tasklist.d.ts

@@ -0,0 +1,13 @@
+/** Runs tasklist: the real one, or what a test put in its place. */
+export interface TasklistRunners {
+    sync(): string;
+    async(): Promise<string>;
+}
+/** Replaces how tasklist runs (tests count the calls); no argument puts the real one back. */
+export declare function useTasklistRunners(replacement?: TasklistRunners): void;
+/** While set, a synchronous read returns this copy (undefined: none yet, run tasklist). Null removes it. */
+export declare function useTasklistCache(read: (() => string | undefined) | null): void;
+/** The process list now: the cached copy when the menu keeps one, else a run of tasklist the caller waits for. */
+export declare function readTasklist(): string;
+/** The process list from a run of tasklist that does not block the program (the menu's background refresh). */
+export declare function readTasklistAsync(): Promise<string>;

package/dist/host/sandbox/tasklist.js

@@ -0,0 +1,47 @@
+// The process list (`tasklist /NH /FO CSV`) that "is the sandbox running?" and "whose is it?" come from. Commands
+// ask it synchronously. The menu cannot wait for a child process on every key, so it keeps a copy fresh in the
+// background (readTasklistAsync) and installs it with useTasklistCache: until then, and after it is removed, every
+// question runs tasklist itself.
+import { spawn, spawnSync } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+/** The longest tasklist may take before it counts as stuck. */
+const TASKLIST_TIMEOUT_MS = 15000;
+const ARGS = ['/NH', '/FO', 'CSV'];
+const REAL_RUNNERS = {
+    sync: () => spawnSync(SYSTEM.tasklist(), ARGS, { encoding: 'utf8', windowsHide: true, timeout: TASKLIST_TIMEOUT_MS }).stdout ??
+        '',
+    async: () => new Promise((resolve) => {
+        let out = '';
+        const child = spawn(SYSTEM.tasklist(), ARGS, { windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
+        const timer = setTimeout(() => child.kill(), TASKLIST_TIMEOUT_MS);
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => (out += chunk));
+        // A tasklist that cannot start or is killed counts as an empty list, like the synchronous one.
+        child.on('error', () => {
+            clearTimeout(timer);
+            resolve('');
+        });
+        child.on('close', () => {
+            clearTimeout(timer);
+            resolve(out);
+        });
+    }),
+};
+let runners = REAL_RUNNERS;
+let cache = null;
+/** Replaces how tasklist runs (tests count the calls); no argument puts the real one back. */
+export function useTasklistRunners(replacement = REAL_RUNNERS) {
+    runners = replacement;
+}
+/** While set, a synchronous read returns this copy (undefined: none yet, run tasklist). Null removes it. */
+export function useTasklistCache(read) {
+    cache = read;
+}
+/** The process list now: the cached copy when the menu keeps one, else a run of tasklist the caller waits for. */
+export function readTasklist() {
+    return cache?.() ?? runners.sync();
+}
+/** The process list from a run of tasklist that does not block the program (the menu's background refresh). */
+export function readTasklistAsync() {
+    return runners.async();
+}

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

@@ -0,0 +1,2 @@
+export { SecretStore, type SecretBox } from './secret-store.js';
+export { clearSecrets, withoutSecrets, writeSecrets } from './launch-secrets.js';

package/dist/host/secrets/index.js

@@ -0,0 +1,2 @@
+export { SecretStore } from './secret-store.js';
+export { clearSecrets, withoutSecrets, writeSecrets } from './launch-secrets.js';

package/dist/host/secrets/launch-secrets.d.ts

@@ -0,0 +1,17 @@
+import { type SecretsFile } from '../../shared/channel/index.js';
+import type { GuestRequest } from '../../core/types.js';
+/** Writes <data>\secrets\<id>.json (nothing at all when there is nothing secret to hand over). */
+export declare function writeSecrets(dataPath: string, id: string, secrets: SecretsFile): string | null;
+/**
+ * Removes whatever one-shot files are left (the sandbox did not start, or did not get to read them) and, from older
+ * versions, a login copy in a launch folder. Called before a launch writes new ones and when the sandbox stops.
+ */
+export declare function clearSecrets(storageRoot: string, dataPath: string): number;
+/**
+ * A request with every agent's environment taken out (those values may be keys) and the values to hand over in the
+ * secrets file of that request. Requests that carry none come back untouched.
+ */
+export declare function withoutSecrets(request: GuestRequest): {
+    request: GuestRequest;
+    secrets: SecretsFile | null;
+};

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

@@ -0,0 +1,94 @@
+// The one-shot secrets file: written before the sandbox starts (or with a request), read and deleted by the sandbox at
+// once. See shared/channel/secrets.ts for what it holds and why it is not in session.json or the launch folder.
+import fs from 'node:fs';
+import path from 'node:path';
+import { RunDir } from '../../shared/channel/index.js';
+import { writeJsonAtomic } from '../../shared/io/index.js';
+import { assertNoLinks } from '../../core/util/index.js';
+/** Writes <data>\secrets\<id>.json (nothing at all when there is nothing secret to hand over). */
+export function writeSecrets(dataPath, id, secrets) {
+    const empty = !Object.keys(secrets.harnessEnvironment ?? {}).length &&
+        !Object.keys(secrets.harnessSpecEnvironment ?? {}).length &&
+        !Object.keys(secrets.projectHarnessEnvironment ?? {}).length &&
+        !secrets.claudeCredentials &&
+        !secrets.vpn &&
+        !secrets.wireguardConfig;
+    if (empty)
+        return null;
+    const run = new RunDir(dataPath);
+    assertNoLinks(dataPath, run.secretsDir);
+    const file = run.secretFile(id);
+    writeJsonAtomic(file, secrets);
+    return file;
+}
+/**
+ * Removes whatever one-shot files are left (the sandbox did not start, or did not get to read them) and, from older
+ * versions, a login copy in a launch folder. Called before a launch writes new ones and when the sandbox stops.
+ */
+export function clearSecrets(storageRoot, dataPath) {
+    let removed = 0;
+    const secrets = new RunDir(dataPath).secretsDir;
+    try {
+        assertNoLinks(dataPath, secrets);
+        for (const name of fs.readdirSync(secrets)) {
+            fs.rmSync(path.join(secrets, name), { recursive: true, force: true });
+            removed++;
+        }
+    }
+    catch {
+        // No such folder, or a link planted there: nothing to remove.
+    }
+    const launches = path.join(storageRoot, 'launches');
+    try {
+        for (const launch of fs.readdirSync(launches)) {
+            const old = path.join(launches, launch, 'claude-profile', '.credentials.json');
+            if (fs.existsSync(old)) {
+                fs.rmSync(old, { force: true });
+                removed++;
+            }
+        }
+    }
+    catch {
+        // No launches yet.
+    }
+    return removed;
+}
+const blank = (h) => ({ ...h, environment: {} });
+const hasValues = (e) => Object.keys(e).length > 0;
+/**
+ * A request with every agent's environment taken out (those values may be keys) and the values to hand over in the
+ * secrets file of that request. Requests that carry none come back untouched.
+ */
+export function withoutSecrets(request) {
+    if (request.kind !== 'session' && request.kind !== 'project')
+        return { request, secrets: null };
+    const project = request.project;
+    const spec = request.kind === 'session' ? request.harnessSpec : undefined;
+    const projectEnv = Object.fromEntries(Object.entries(project?.harnesses ?? {}).filter(([, h]) => hasValues(h.environment)));
+    const specEnv = spec && hasValues(spec.environment) ? spec.environment : undefined;
+    if (!specEnv && !Object.keys(projectEnv).length)
+        return { request, secrets: null };
+    const cleaned = {
+        ...request,
+        ...(project
+            ? {
+                project: {
+                    ...project,
+                    harnesses: Object.fromEntries(Object.entries(project.harnesses).map(([n, h]) => [n, blank(h)])),
+                },
+            }
+            : {}),
+        ...(spec ? { harnessSpec: blank(spec) } : {}),
+    };
+    return {
+        request: cleaned,
+        secrets: {
+            ...(specEnv ? { harnessSpecEnvironment: specEnv } : {}),
+            ...(Object.keys(projectEnv).length
+                ? {
+                    projectHarnessEnvironment: Object.fromEntries(Object.entries(projectEnv).map(([n, h]) => [n, h.environment])),
+                }
+                : {}),
+        },
+    };
+}

package/dist/host/secrets/secret-store.d.ts

@@ -0,0 +1,25 @@
+/** Something that turns bytes into a sealed string and back. */
+export interface SecretBox {
+    readonly kind: string;
+    seal(plain: Buffer): string;
+    open(sealed: string): Buffer;
+}
+/** Seals and opens text and JSON with one box. The sealed form says which box made it. */
+export declare class SecretStore {
+    private readonly box;
+    constructor(box: SecretBox);
+    /** Windows DPAPI, current user. */
+    static dpapi(): SecretStore;
+    /** The test stand-in (not secure). */
+    static memory(): SecretStore;
+    /** What the program uses: DPAPI, except during the self-test (it never spawns Windows for this). */
+    static standard(): SecretStore;
+    /** True when `value` looks like something seal() made (any box). */
+    static isSealed(value: unknown): value is string;
+    seal(text: string): string;
+    open(sealed: string): string;
+    sealBytes(plain: Buffer): string;
+    openBytes(sealed: string): Buffer;
+    sealJson(value: unknown): string;
+    openJson(sealed: string): unknown;
+}

package/dist/host/secrets/secret-store.js

@@ -0,0 +1,89 @@
+// Encryption at rest for what must not sit in plain files (saved logins, the VPN login). The real box is Windows DPAPI
+// for the current user (native\scripts\protect-data.ps1: data on standard input, never on a command line); the memory
+// box is the self-test's stand-in and is not secure. A sealed value is a short string: "<kind>:<base64>".
+import { spawnSync } from 'node:child_process';
+import { fail } from '../../core/util/index.js';
+import { SYSTEM } from '../../shared/system.js';
+import { selfTestRunning } from '../../shared/test-guard.js';
+import { nativeScript } from '../native.js';
+const TIMEOUT_MS = 60000;
+/** DPAPI for the current Windows user, through powershell.exe 5.1. */
+class DpapiBox {
+    kind = 'dpapi1';
+    seal(plain) {
+        return this.run('protect', plain.toString('base64'));
+    }
+    open(sealed) {
+        return Buffer.from(this.run('unprotect', sealed), 'base64');
+    }
+    run(mode, input) {
+        const result = spawnSync(SYSTEM.powershell(), nativeScript('protect-data.ps1', ['-Mode', mode]), {
+            input,
+            encoding: 'utf8',
+            windowsHide: true,
+            timeout: TIMEOUT_MS,
+        });
+        if (result.status !== 0 || result.error)
+            fail('Windows could not ' +
+                (mode === 'protect' ? 'encrypt' : 'decrypt') +
+                ' a saved secret: ' +
+                (result.stderr || result.error?.message || 'no answer').trim().slice(0, 300), mode === 'protect'
+                ? 'Check that powershell.exe runs for your user.'
+                : 'It can only be opened by the Windows user that saved it, on the PC that saved it. Save it again.');
+        return result.stdout.trim();
+    }
+}
+/** A reversible stand-in for tests: it only proves the callers seal and open, not that anything is secret. */
+class MemoryBox {
+    kind = 'mem1';
+    seal(plain) {
+        return Buffer.from(plain.toString('base64')).toString('base64');
+    }
+    open(sealed) {
+        return Buffer.from(Buffer.from(sealed, 'base64').toString('utf8'), 'base64');
+    }
+}
+/** Seals and opens text and JSON with one box. The sealed form says which box made it. */
+export class SecretStore {
+    box;
+    constructor(box) {
+        this.box = box;
+    }
+    /** Windows DPAPI, current user. */
+    static dpapi() {
+        return new SecretStore(new DpapiBox());
+    }
+    /** The test stand-in (not secure). */
+    static memory() {
+        return new SecretStore(new MemoryBox());
+    }
+    /** What the program uses: DPAPI, except during the self-test (it never spawns Windows for this). */
+    static standard() {
+        return selfTestRunning() ? SecretStore.memory() : SecretStore.dpapi();
+    }
+    /** True when `value` looks like something seal() made (any box). */
+    static isSealed(value) {
+        return typeof value === 'string' && /^(dpapi1|mem1):[A-Za-z0-9+/=]+$/.test(value);
+    }
+    seal(text) {
+        return this.box.kind + ':' + this.box.seal(Buffer.from(text, 'utf8'));
+    }
+    open(sealed) {
+        return this.openBytes(sealed).toString('utf8');
+    }
+    sealBytes(plain) {
+        return this.box.kind + ':' + this.box.seal(plain);
+    }
+    openBytes(sealed) {
+        const at = sealed.indexOf(':');
+        if (at < 0 || sealed.slice(0, at) !== this.box.kind)
+            fail('A saved secret was made on another system or with another store.', 'Save it again.');
+        return this.box.open(sealed.slice(at + 1));
+    }
+    sealJson(value) {
+        return this.seal(JSON.stringify(value));
+    }
+    openJson(sealed) {
+        return JSON.parse(this.open(sealed));
+    }
+}

package/dist/host/sharing/acl.d.ts

@@ -21,10 +21,24 @@ export declare function sharingAclPlan(o: {
     on: boolean;
 }): AclChange[];
 /**
- * Applies the changes with native\scripts\set-folder-access.ps1 (Get-Acl / Set-Acl, refusing links). Throws with the
- * script's reason when a change fails. The self-test guard is in applyAcl; the self-test calls this only on its temp
+ * Applies the changes with native\scripts\set-folder-access.ps1 (refusing links; writing nothing when an entry would
+ * change nothing, and a folder's own entry without touching what is inside it). Throws with the script's reason when a
+ * change fails or takes over 30 seconds. The self-test guard is in applyAcl; the self-test calls this only on its temp
  * folders.
  */
 export declare function runFolderAccess(changes: readonly AclChange[]): void;
 /** Applies sharing changes on this PC (refused inside the self-test). */
 export declare function applyAcl(changes: readonly AclChange[]): void;
+/** Makes an existing folder private (see protectPrivateFolder) without the self-test guard: for temp folders only. */
+export declare function runPrivateFolder(dir: string, options?: PrivateOptions): void;
+export interface PrivateOptions {
+    /** The folder holds files and every one of them has to be walked: wait up to 30 minutes instead of 30 seconds. */
+    readonly walkAll?: boolean;
+}
+/**
+ * Makes an existing folder (not a link) private: inheritance off, full control for you, SYSTEM and Administrators
+ * only, inherited by what is created in it. Nothing is written when it already is; an empty folder is changed without
+ * walking inside it. A folder with files is walked (minutes for a large one), so it stops after 30 seconds unless the
+ * caller asks for `walkAll` (only an explicit repair does, after saying so). Launch paths never do.
+ */
+export declare function protectPrivateFolder(dir: string, options?: PrivateOptions): void;

package/dist/host/sharing/acl.js

@@ -32,23 +32,23 @@ export function sharingAclPlan(o) {
         entry(path.join(o.dataPath, 'run'), 'Modify', 'inherit'),
     ];
 }
-/**
- * Applies the changes with native\scripts\set-folder-access.ps1 (Get-Acl / Set-Acl, refusing links). Throws with the
- * script's reason when a change fails. The self-test guard is in applyAcl; the self-test calls this only on its temp
- * folders.
- */
-export function runFolderAccess(changes) {
-    if (changes.length === 0)
-        return;
+const ACL_TIMEOUT_MS = 30000;
+/** Making a folder that holds files private walks all of it: a few hundred thousand files take minutes. */
+const WALK_TIMEOUT_MS = 30 * 60000;
+/** One run of native\scripts\set-folder-access.ps1 over `entries` (the JSON's "changes"); throws a UserError. */
+function runScript(entries, timeoutMs = ACL_TIMEOUT_MS) {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-sandbox-acl-'));
     const file = path.join(dir, 'changes.json');
     try {
-        fs.writeFileSync(file, JSON.stringify({ changes }, null, 2), 'utf8');
+        fs.writeFileSync(file, JSON.stringify({ changes: entries }, null, 2), 'utf8');
         const run = spawnSync(SYSTEM.powershell(), nativeScript('set-folder-access.ps1', ['-Json', file]), {
             encoding: 'utf8',
             windowsHide: true,
-            timeout: 120000,
+            timeout: timeoutMs,
         });
+        const timedOut = run.error?.code === 'ETIMEDOUT';
+        if (timedOut)
+            fail('Changing the folder permissions took longer than ' + timeoutMs / 1000 + ' seconds and was stopped.', 'Close programs that scan or lock the folders (virus scanners, file explorers) and try again.');
         if (run.status !== 0 || run.error) {
             const reason = (run.stderr || run.stdout || run.error?.message || 'no output').trim();
             fail('Could not change the folder permissions: ' + reason, 'Check that the folders are not links and that you can change their permissions, then try again.');
@@ -58,8 +58,33 @@ export function runFolderAccess(changes) {
         fs.rmSync(dir, { recursive: true, force: true });
     }
 }
+/**
+ * Applies the changes with native\scripts\set-folder-access.ps1 (refusing links; writing nothing when an entry would
+ * change nothing, and a folder's own entry without touching what is inside it). Throws with the script's reason when a
+ * change fails or takes over 30 seconds. The self-test guard is in applyAcl; the self-test calls this only on its temp
+ * folders.
+ */
+export function runFolderAccess(changes) {
+    if (changes.length === 0)
+        return;
+    runScript(changes);
+}
 /** Applies sharing changes on this PC (refused inside the self-test). */
 export function applyAcl(changes) {
     refuseInSelfTest('change folder permissions');
     runFolderAccess(changes);
 }
+/** Makes an existing folder private (see protectPrivateFolder) without the self-test guard: for temp folders only. */
+export function runPrivateFolder(dir, options = {}) {
+    runScript([{ op: 'private', path: dir }], options.walkAll ? WALK_TIMEOUT_MS : ACL_TIMEOUT_MS);
+}
+/**
+ * Makes an existing folder (not a link) private: inheritance off, full control for you, SYSTEM and Administrators
+ * only, inherited by what is created in it. Nothing is written when it already is; an empty folder is changed without
+ * walking inside it. A folder with files is walked (minutes for a large one), so it stops after 30 seconds unless the
+ * caller asks for `walkAll` (only an explicit repair does, after saying so). Launch paths never do.
+ */
+export function protectPrivateFolder(dir, options = {}) {
+    refuseInSelfTest('change folder permissions');
+    runPrivateFolder(dir, options);
+}

package/dist/host/sharing/current.js

@@ -3,13 +3,14 @@ import os from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { SYSTEM } from '../../shared/system.js';
 import { insideSandbox } from '../sandbox/platform.js';
+import { readTasklist } from '../sandbox/tasklist.js';
 import { activeDir } from './machine-paths.js';
 import { ActiveRecords } from './active-record.js';
 import { parseTasklist, whoOwnsSandbox } from './owner.js';
+const HELPER_TIMEOUT_MS = 15000;
 /** The rows of `tasklist /NH /FO CSV`: every process of every session (standard users may see these). */
 export function listProcesses() {
-    const run = spawnSync(SYSTEM.tasklist(), ['/NH', '/FO', 'CSV'], { encoding: 'utf8', windowsHide: true });
-    return parseTasklist(run.stdout ?? '');
+    return parseTasklist(readTasklist());
 }
 /** The Windows session this process runs in (0 = services, 1 = the first signed-in user ...), or null when unknown. */
 export function sessionOf(rows, pid = process.pid) {
@@ -17,7 +18,11 @@ export function sessionOf(rows, pid = process.pid) {
 }
 /** This user's SID, from `whoami /user`: `"DOMAIN\name","S-1-5-21-..."`. */
 export function currentUserSid() {
-    const run = spawnSync(SYSTEM.whoami(), ['/user', '/fo', 'csv', '/nh'], { encoding: 'utf8', windowsHide: true });
+    const run = spawnSync(SYSTEM.whoami(), ['/user', '/fo', 'csv', '/nh'], {
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: HELPER_TIMEOUT_MS,
+    });
     const sid = /"(S-1-[0-9-]+)"\s*$/.exec((run.stdout ?? '').trim())?.[1];
     if (!sid)
         throw new Error('Could not find out who you are (whoami /user gave: ' + (run.stdout || run.stderr) + ').');