windows-development-sandbox 1.27.3 → 1.29.0

package/dist/selftest/heavy-load.test.js

@@ -8,7 +8,7 @@ import { DEFAULTS } from '../core/config/index.js';
 import { isWin } from '../core/util/index.js';
 import { SYSTEM } from '../shared/system.js';
 import { GuestRequestSchema, PressureStatusSchema } from '../shared/channel/index.js';
-import { compilersAllowed, DIAL_CALM_SAMPLES, DIAL_STEPS, HOST_THRESHOLDS, buildJobs, cargoJobs, linkSlotsFor, usableCpus, effectiveCpuLimit, gentleCpuLimit, maxCompilers, chooseTargetDir, cargoLinkerVar, } from '../shared/memory/index.js';
+import { BURST_GATE, compilersAllowed, DIAL_CALM_SAMPLES, DIAL_STEPS, HOST_THRESHOLDS, buildJobs, cargoJobs, linkSlotsFor, usableCpus, effectiveCpuLimit, gentleCpuLimit, maxCompilers, chooseTargetDir, cargoLinkerVar, } from '../shared/memory/index.js';
 import { HeartbeatSchema } from '../shared/channel/index.js';
 import { heartbeatLine, lastEndOf, vanishedCause, stopWarning } from '../host/life/index.js';
 import { cappedMemoryMb, decideMemory, memoryNote, residentCapMb, residentNote, resolveMemoryMb, } from '../host/launch/index.js';
@@ -16,10 +16,10 @@ import { vgpuWarning, GENTLE_NOTE } from '../host/launch/risk-notes.js';
 import { judgeSandbox } from '../host/health/index.js';
 import { cleanUpLeftovers, cleanupQuestion, killArgs } from '../host/sandbox/index.js';
 import { parseTasklist } from '../host/sharing/index.js';
-import { bugcheckCode, cpuPercentBetween, explainStop, findDumps, findingLines, freezeLine, hostPressure, lowReason, severeHost, pageFileRisk, parseHostMemory, crashReportText, watchdogStep, WATCHDOG_START, } from '../host/life/index.js';
+import { bugcheckCode, cpuPercentBetween, explainStop, findDumps, findingLines, freezeLine, hostPressure, lowReason, memoryWasFineLine, severeHost, pageFileRisk, parseHostMemory, crashReportText, watchdogStep, WATCHDOG_START, } from '../host/life/index.js';
 // The pure governor files only: governor.ts loads the guest runtime (session.json), which exists only in a sandbox.
-import { canLower, canPause, decide, INITIAL_STATE, isLinker, linkerSlots, ROTATE_MS, } from '../guest/governor/decide.js';
-import { GovernorCore } from '../guest/governor/core.js';
+import { canLower, canPause, decide, GATE_NAMES, INITIAL_STATE, isLinker, isNeverTouched, linkerSlots, ROTATE_MS, } from '../guest/governor/decide.js';
+import { GateEventSchema, GovernorCore, memgovArgs } from '../guest/governor/core.js';
 const GB = 1024;
 const MB_SANDBOX = DEFAULTS.sandbox;
 const proc = (pid, name, mb, prio = 'normal') => ({
@@ -374,6 +374,105 @@ export const heavyLoadSuite = {
         t.check(decide({ ...INITIAL_STATE, hostUntil: clock + 60000, hostStep: 4 }, sample(60, 40, procs), clock, 'normal').state
             .step === 4, 'with plenty of memory in the sandbox, a severe PC still turns the dial to 4');
         t.check(core.current.hostUntil === clock + 60000, 'a host request is remembered for its seconds');
+        t.section('the memory gate (rate of growth)');
+        t.check(['cl', 'link', 'rustc', 'clang-cl', 'lld-link', 'shadercompileworker'].every((n) => GATE_NAMES.includes(n)), 'the gate may freeze compilers, linkers and Unreal shader workers', GATE_NAMES.join(','));
+        t.check([
+            'node',
+            'claude',
+            'codex',
+            'opencode',
+            'cmd',
+            'pwsh',
+            'powershell',
+            'msbuild',
+            'dotnet',
+            'cargo',
+            'ninja',
+            'unrealbuildtool',
+            'ubahost',
+            'unrealeditor',
+            'unrealeditor-cmd',
+            'mspdbsrv',
+            'ptyhost',
+            'memgov',
+        ].every((n) => !GATE_NAMES.includes(n)) &&
+            GATE_NAMES.every((n) => (canPause(n) || n === 'shadercompileworker') && !isNeverTouched(n)), 'agents, shells, build coordinators, the editor and the tools themselves are never frozen');
+        t.check(JSON.stringify(memgovArgs('normal')) ===
+            JSON.stringify([
+                'serve',
+                '--interval',
+                '2',
+                '--gate',
+                '4096:3000:1500:30000',
+                '--gate-names',
+                GATE_NAMES.join(','),
+            ]) && memgovArgs('gentle').includes('3072:3000:2000:30000'), 'memgov starts with the gate for the profile', memgovArgs('gentle').join(' '));
+        t.check(['normal', 'gentle'].every((p) => {
+            const g = BURST_GATE[p];
+            return g.growthMb >= 1024 && g.maxHoldMs <= 30000 && g.releaseMs < g.maxHoldMs && g.windowMs >= 1000;
+        }) && BURST_GATE.gentle.growthMb <= BURST_GATE.normal.growthMb, 'the gate is sane: a real burst size, every hold ends within 30 s, vGPU is not looser');
+        const gateExamples = [
+            { event: 'gate', at: 1, kind: 'ready', mode: 'notify', growthMb: 4096, windowMs: 3000 },
+            { event: 'gate', at: 1, kind: 'off', reason: 'bad --gate' },
+            { event: 'gate', at: 1, kind: 'trip', grewMb: 4210, ms: 1800, jobMb: 23456, held: [{ pid: 101, name: 'cl' }] },
+            { event: 'gate', at: 1, kind: 'hold', pid: 101, name: 'cl' },
+            { event: 'gate', at: 1, kind: 'release', pid: 101, name: 'cl', heldMs: 1500, forced: false },
+        ];
+        const heldOf = (n) => Array.from({ length: n }, (_, i) => ({ pid: i, name: 'cl' }));
+        t.check(gateExamples.every((e) => GateEventSchema.safeParse(e).success) &&
+            !GateEventSchema.safeParse({ event: 'gate', at: 1, kind: 'hold', pid: 1, name: 'x'.repeat(129) }).success &&
+            !GateEventSchema.safeParse({ event: 'gate', at: 1, kind: 'trip', grewMb: 1, ms: 1, jobMb: 1, held: heldOf(65) })
+                .success &&
+            !GateEventSchema.safeParse({ event: 'gate', at: 1, kind: 'boom' }).success &&
+            !GateEventSchema.safeParse({ at: 1, kind: 'hold', pid: 1, name: 'cl' }).success, 'gate events from memgov are checked: one of each kind passes; a long name, 65 held, a bad kind or no event fail');
+        {
+            const gateLogs = [];
+            const gateCore = new GovernorCore({
+                port,
+                profile: 'normal',
+                now: () => 0,
+                logLine: (l) => gateLogs.push(l),
+                saveStatus: () => undefined,
+                warn: (line) => gateLogs.push(line),
+            });
+            gateCore.onGate({
+                event: 'gate',
+                at: 1,
+                kind: 'trip',
+                grewMb: 4210,
+                ms: 1800,
+                jobMb: 23456,
+                held: [{ pid: 101, name: 'cl' }],
+            });
+            gateCore.onGate({
+                event: 'gate',
+                at: 2,
+                kind: 'release',
+                pid: 101,
+                name: 'cl',
+                heldMs: 30000,
+                forced: true,
+            });
+            t.check(gateLogs.some((l) => l.includes("governor: gate: the agents' programs grew 4210 MB in 1.8 s (now 23456 MB); holding 1: cl (101)")) &&
+                gateLogs.some((l) => l.endsWith('(the longest it may wait)')) &&
+                gateCore.current.step === 0, 'gate events go to the memory log and leave the dial alone', gateLogs.join('\n'));
+            const heldStatuses = [];
+            const heldCore = new GovernorCore({
+                port,
+                profile: 'normal',
+                now: () => 0,
+                logLine: () => undefined,
+                saveStatus: (s) => heldStatuses.push(s),
+                warn: () => undefined,
+            });
+            heldCore.onSample({ ...sample(60, 40, procs), gateHeld: 3 });
+            const heldStatus = heldStatuses[heldStatuses.length - 1];
+            t.check(PressureStatusSchema.safeParse(heldStatus).success &&
+                heldStatus.held === 3 &&
+                heldCore.snapshot?.held === 3, 'the number of held builds reaches the status file and the snapshot', JSON.stringify(heldStatus));
+            t.check(HeartbeatSchema.safeParse({ ...beat, held: 3 }).success &&
+                heartbeatLine({ ...beat, held: 3 }).includes('3 builds held by the memory gate'), 'the heartbeat carries the held builds into the crash report line');
+        }
         t.section("the PC's watchdog");
         const input = (memory, nowMs, cpu = 10, profile = 'normal') => ({
             memory,
@@ -541,6 +640,13 @@ export const heavyLoadSuite = {
             meaning.includes('froze, lost power') &&
             meaning.includes('hardware error') &&
             meaning.includes('vmwp.exe'), 'what each finding usually means, in plain words', meaning);
+        t.check(findingLines([ev(1000, 'Application Error', '2026-10-15T19:41:12Z', 'Faulting application name: vmwp.exe')])
+            .join('\n')
+            .includes('not a program inside the sandbox running out of memory'), 'a crash of vmwp.exe is named as a fault in Windows or a driver, not memory');
+        t.check(memoryWasFineLine('x\n2026-11-08T15:30:05.411Z | RAM free/total MB 42325/63170 | commit free/limit MB 52051/75458 | page file auto\n')?.includes('still had 41 GB of RAM and 50 GB') === true &&
+            memoryWasFineLine('2026-10-15T19:40:50Z | RAM free/total MB 900/32768 | commit free/limit MB 9000/40000') ===
+                null &&
+            memoryWasFineLine('') === null, 'the report says when this PC still had plenty of memory, and says nothing when it was low');
         const dumps = path.join(t.at('crash-dumps'), 'Minidump');
         fs.mkdirSync(dumps, { recursive: true });
         fs.writeFileSync(path.join(dumps, '101526-1.dmp'), 'x');
@@ -576,6 +682,7 @@ export const heavyLoadSuite = {
         };
         const sandboxCs = (n) => path.join(t.packageRoot, 'sandbox', 'csharp', n);
         build('ptyhost', [sandboxCs('PtyHost.cs')]);
+        build('clipboardwatch', [sandboxCs('ClipboardWatch.cs')], 'library');
         const memgov = build('memgov', [sandboxCs('MemGov.cs')]);
         const hostDir = path.join(t.packageRoot, 'native', 'csharp', 'HostTools');
         const tools = build('HostTools', fs
@@ -607,6 +714,7 @@ export const heavyLoadSuite = {
             // Not JSON: the check below fails.
         }
         t.check(sampleOk && served.status === 0, 'memgov serve prints a well-formed sample and ends when its input closes', firstLine);
+        t.check(!(served.stdout ?? '').split(/\r?\n/).some((l) => l.includes('"event":"gate"')), 'a memgov started without --gate never takes the job port (no gate events)');
         for (const script of ['memory-status.ps1', 'stop-events.ps1']) {
             const text = fs.readFileSync(path.join(t.packageRoot, 'native', 'scripts', script), 'utf8');
             t.check(text.startsWith('#Requires -Version 5.1'), script + ' says its PowerShell version');

package/dist/selftest/host-sim.test.js

@@ -27,9 +27,9 @@ const SANDBOX_ONLY_VARS = [
     'AGENT_SANDBOX_CONFIG',
 ];
 const PARALLEL = 2;
-const sandbox = (label, ...args) => ({ bin: 'agent-sandbox', label, args, config: true });
+const sandbox = (label, ...args) => ({ bin: 'sandbox', label, args, config: true });
 const COMMANDS = [
-    { bin: 'agent-sandbox', label: '--help', args: ['--help'] },
+    { bin: 'sandbox', label: '--help', args: ['--help'] },
     sandbox('status', 'status'),
     sandbox('status --json', 'status', '--json'),
     sandbox('sessions', 'sessions'),
@@ -38,26 +38,25 @@ const COMMANDS = [
     sandbox('vpn status', 'vpn', 'status'),
     sandbox('vpn status --json', 'vpn', 'status', '--json'),
     sandbox('account use nobody', 'account', 'use', 'nobody'),
-    { bin: 'agent-sandbox', label: 'config path', args: ['config', 'path'] },
+    { bin: 'sandbox', label: 'config path', args: ['config', 'path'] },
     sandbox('config show', 'config', 'show'),
-    { bin: 'agent-sandbox', label: 'config schema', args: ['config', 'schema'] },
+    { bin: 'sandbox', label: 'config schema', args: ['config', 'schema'] },
     sandbox('clean', 'clean'),
     sandbox('sync', 'sync'),
     sandbox('logs', 'logs'),
     sandbox('attach', 'attach'),
-    { bin: 'agent-sandbox', label: 'exec', args: ['exec'], after: ['--', 'echo', 'hi'], config: true },
+    { bin: 'sandbox', label: 'exec', args: ['exec'], after: ['--', 'echo', 'hi'], config: true },
     sandbox('restart', 'restart'),
     sandbox('stop', 'stop'),
     sandbox('show', 'show'),
     sandbox('hide', 'hide'),
     sandbox('generate', 'generate'),
     sandbox('launch', 'launch'),
-    { bin: 'agent-sandbox', label: 'unknown command', args: ['frobnicate'] },
-    { bin: 'claude-sbx', label: 'claude-sbx --headless --continue', args: ['--headless', '--continue'], config: true },
-    { bin: 'codex-sbx', label: 'codex-sbx', args: [], config: true },
-    { bin: 'gemini-sbx', label: 'gemini-sbx', args: [], config: true },
-    { bin: 'sbx-show', label: 'sbx-show', args: [], config: true },
-    { bin: 'claude-host', label: 'claude-host --version', args: ['--version'] },
+    { bin: 'sandbox', label: 'unknown command', args: ['frobnicate'] },
+    { bin: 'sandbox', label: 'claude --headless --continue', args: ['claude', '--headless', '--continue'], config: true },
+    { bin: 'sandbox', label: 'codex', args: ['codex'], config: true },
+    { bin: 'sandbox', label: 'gemini', args: ['gemini'], config: true },
+    { bin: 'sandbox', label: 'host claude --version', args: ['host', 'claude', '--', '--version'] },
 ];
 export const hostSimSuite = {
     name: 'host-sim',
@@ -93,7 +92,7 @@ export const hostSimSuite = {
             const args = command.config ? [...command.args, '--config', pc.config, ...(command.after ?? [])] : command.args;
             const r = await f.runBin(command.bin, args, { cwd: project, env: envFor(pc.home), timeoutMs: 120000 });
             const crashed = r.status === null || r.status > 1 || /Unexpected error|node:internal|^\s+at .+:\d+:\d+\)?$/m.test(r.out);
-            const unexplained = r.status === 1 && !/(^|\n)(Error: |error: )/.test(r.out) && command.bin !== 'claude-host';
+            const unexplained = r.status === 1 && !/(^|\n)(Error: |error: )/.test(r.out) && !command.label.startsWith('host ');
             if (crashed || unexplained)
                 broken.push(command.label +
                     ' (exit ' +
@@ -110,8 +109,8 @@ export const hostSimSuite = {
                 await runOne(next.command, next.index);
         });
         const initRuns = (async () => {
-            await runOne({ bin: 'agent-sandbox', label: 'config init', args: ['config', 'init'] }, 1000, initPc);
-            await runOne({ bin: 'agent-sandbox', label: 'config init (again)', args: ['config', 'init'] }, 1001, initPc);
+            await runOne({ bin: 'sandbox', label: 'config init', args: ['config', 'init'] }, 1000, initPc);
+            await runOne({ bin: 'sandbox', label: 'config init (again)', args: ['config', 'init'] }, 1001, initPc);
         })();
         await Promise.all([...workers, initRuns]);
         t.equal(broken, [], 'all ' + (COMMANDS.length + 2) + ' commands work or fail with a clear message when run outside a sandbox');

package/dist/selftest/install.test.js

@@ -3,7 +3,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { shimText } from '../host/install/index.js';
+import { REMOVED_COMMANDS, shimText } from '../host/install/index.js';
 import { nativeScript } from '../host/native.js';
 import { SYSTEM } from '../shared/system.js';
 /** The text install.ps1 writes for one shim, run by powershell.exe as a script file. */
@@ -39,11 +39,15 @@ function installerText(t, script) {
     const cases = [
         ['sandbox', undefined],
         ['claude-sbx', 'dist/bin/claude-sbx.js'],
-        ['agent-sandbox', 'dist/bin/agent-sandbox.js'],
+        ['sbx-show', undefined],
     ];
     for (const [name, target] of cases)
         for (const kind of ['cmd', 'sh'])
             t.equal(printedShim(script, kind, name, target), shimText(name, kind, target), name + '.' + kind + ' is identical');
+    t.section('install.ps1 and package.json: the commands');
+    const bin = JSON.parse(fs.readFileSync(path.join(t.packageRoot, 'package.json'), 'utf8')).bin;
+    t.equal(Object.keys(bin).sort(), ['sandbox', 'windows-development-sandbox'], 'the package declares only those commands');
+    t.equal(Object.keys(REMOVED_COMMANDS).filter((name) => !source.includes("'" + name + "'")), [], 'the installer removes the shim of every removed command');
     t.includes(printedShim(script, 'cmd', 'x y'), 'exit', 'a name that is not a command name is refused');
 }
 export const installSuite = {

package/dist/selftest/live-terminal.test.js

@@ -11,6 +11,7 @@ import { spawn, spawnSync } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
 import { encodeFrame, FrameType } from '../shared/pty/index.js';
 import { SYSTEM } from '../shared/system.js';
+import { GateEventSchema } from '../guest/governor/core.js';
 import { CSC, openViewer, tail, WAIT } from './support/live.js';
 /**
  * The stand-in agent: VT input and SGR mouse tracking on, echoes what it reads ("got <1b>[<0;10;5M"). L prints 500
@@ -268,6 +269,108 @@ export const liveTerminalSuite = {
                 Number(set[1]) === Math.max(Math.floor(commit / 2), commit - Math.max(1536, Math.floor((commit * 3) / 100))), 'the ptyhost that creates the job sets the backstop just below the commit limit (auto: 3 %, at least 1.5 GB)', read('job-first.log'));
             t.check(read('job-second.log').includes('joined the existing one'), 'a ptyhost that joins the job never changes its backstop', read('job-second.log'));
         }
+        t.section('the memory gate: a burst is held at once and let go in turn');
+        {
+            // A job of the test's own (never the agents' real one) for both ptyhosts and memgov.
+            const jobName = 'Local\\AgentSandboxAgentsJobTest' + process.pid + '-gate-' + Date.now();
+            const memgovExe = t.at('memgov-gate.exe');
+            const burstExe = t.at('MemoryBurst.exe');
+            const gateErrors = compile(path.join(t.packageRoot, 'sandbox', 'csharp', 'MemGov.cs'), memgovExe) ||
+                compile(path.join(t.packageRoot, 'src', 'selftest', 'fixtures', 'memory-burst', 'MemoryBurst.cs'), burstExe);
+            t.check(!gateErrors, 'memgov and the memory burst program compile', gateErrors);
+            if (!gateErrors) {
+                const ping = path.join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'PING.EXE');
+                const holder = '"' + SYSTEM.cmd() + '" /c "' + ping + '" -n 60 127.0.0.1 >nul';
+                const progress = t.at('burst-progress.txt');
+                const startHost = async (command, log) => spawn(ptyhost, [String(await freePort()), 'tok', '80', '24', t.at(log), command], {
+                    env: { ...process.env, PTYHOST_BIND: 'loopback', PTYHOST_BACKSTOP_MB: 'none', PTYHOST_JOB_NAME: jobName },
+                    stdio: 'ignore',
+                    windowsHide: true,
+                });
+                const read = (file) => (fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '');
+                const hosts = [];
+                let memgov = null;
+                try {
+                    hosts.push(await startHost(holder, 'gate-a.log'));
+                    await t.waitFor(() => read(t.at('gate-a.log')).includes('agent job:'), WAIT.screen);
+                    memgov = spawn(memgovExe, ['serve', '--interval', '1', '--gate', '512:3000:800:4000', '--gate-names', 'memoryburst'], {
+                        env: { ...process.env, MEMGOV_JOB_NAME: jobName },
+                        stdio: ['pipe', 'pipe', 'ignore'],
+                        windowsHide: true,
+                    });
+                    let text = '';
+                    memgov.stdout.on('data', (chunk) => (text += chunk.toString('utf8')));
+                    const events = () => text
+                        .split(/\r?\n/)
+                        .filter((l) => l.includes('"event":"gate"'))
+                        .flatMap((l) => {
+                        try {
+                            const parsed = GateEventSchema.safeParse(JSON.parse(l));
+                            return parsed.success ? [parsed.data] : [];
+                        }
+                        catch {
+                            return [];
+                        }
+                    });
+                    const ready = await t.waitFor(() => events().some((e) => e.kind === 'ready'), WAIT.screen);
+                    const readyEvent = events().find((e) => e.kind === 'ready');
+                    t.check(Boolean(ready) && readyEvent?.kind === 'ready' && readyEvent.mode === 'notify', "the gate listens to the job's notifications (no polling)", text.slice(-400));
+                    hosts.push(await startHost('"' + burstExe + '" 1536 "' + progress + '"', 'gate-b.log'));
+                    const finished = await t.waitFor(() => read(progress).includes('done'), 15000);
+                    const marks = read(progress)
+                        .split(/\r?\n/)
+                        .flatMap((l) => {
+                        const m = /^(\d+) \d+$/.exec(l.trim());
+                        return m ? [Number(m[1])] : [];
+                    });
+                    const all = events();
+                    const trips = all.flatMap((e) => (e.kind === 'trip' ? [e] : []));
+                    const releases = all.flatMap((e) => (e.kind === 'release' ? [e] : []));
+                    const evidence = text.slice(-1200) + '\nprogress: ' + marks.length + ' lines';
+                    const firstTrip = trips[0];
+                    t.check(trips.some((e) => e.held.some((h) => h.name === 'memoryburst')) &&
+                        firstTrip !== undefined &&
+                        firstTrip.grewMb >= 512 &&
+                        firstTrip.grewMb <= 1024, 'a burst past the gate is held at once', evidence);
+                    const stalls = [];
+                    for (const trip of trips) {
+                        if (!trip.held.some((h) => h.name === 'memoryburst'))
+                            continue;
+                        const release = releases.find((r) => r.at >= trip.at && r.name === 'memoryburst');
+                        const until = release ? release.at : Infinity;
+                        if (marks.some((m) => m > trip.at + 200 && m < until))
+                            stalls.push('trip at ' + trip.at);
+                    }
+                    t.check(stalls.length === 0, 'the held program made no progress more than 200 ms after the trip until it was let go', stalls.join(', ') + '\n' + evidence);
+                    t.check(releases.length > 0 && releases.every((r) => r.heldMs <= 4500) && releases.some((r) => !r.forced), 'held programs go on in turn, never longer than the most allowed', evidence);
+                    t.check(Boolean(finished) && trips.length >= 2, 'the burst program reached its end after at least 2 trips', evidence);
+                }
+                finally {
+                    if (memgov) {
+                        memgov.stdin.end();
+                        const ended = memgov;
+                        await t.waitFor(() => ended.exitCode !== null, 5000);
+                        t.check(ended.exitCode === 0, 'memgov with the gate ends cleanly when its input closes');
+                        try {
+                            if (ended.exitCode === null)
+                                ended.kill();
+                        }
+                        catch {
+                            /* it ended between the check and the kill: nothing left to stop */
+                        }
+                    }
+                    for (const c of hosts) {
+                        try {
+                            if (c.exitCode === null)
+                                c.kill();
+                        }
+                        catch {
+                            /* it ended between the check and the kill: nothing left to stop */
+                        }
+                    }
+                }
+            }
+        }
         const client = t.at('client.mjs');
         fs.writeFileSync(client, [
             'import { connect, runTerminalClient } from ' +

package/dist/selftest/personalization.test.js

@@ -47,7 +47,8 @@ export const personalizationSuite = {
         const untouched = fs.readFileSync(settings, 'utf8');
         t.check(untouched.startsWith('// edited') &&
             /"guid": "\{x\}",\s*\}/.test(untouched) &&
-            /"reloadEnvironmentVariables":\s*true/.test(untouched), 'until pwsh is installed only the reload switch is added (comments and trailing commas survive)');
+            /"reloadEnvironmentVariables":\s*true/.test(untouched) &&
+            /"copyOnSelect":\s*true/.test(untouched), 'until pwsh is installed only the default switches are added (comments and trailing commas survive)');
         t.write(path.join(data, 'tools', 'pwsh', 'pwsh.exe'), 'MZ');
         syncPwshProfile(data, true);
         const added = read();

package/dist/selftest/store-app.test.js

@@ -8,11 +8,12 @@ import { DEFAULTS } from '../core/config/index.js';
 import { OFF_IS_SAFER } from '../core/local-config/index.js';
 import { HOST_SOURCES } from '../host/accounts/index.js';
 import { prepareStorePackages, stagedPackageDir, StorePackages } from '../host/apps/index.js';
+import { prepareServiceAccounts } from '../host/accounts/index.js';
 import { checkedPackage } from '../guest/apps/store-check.js';
 import { peekPendingPerplexityApp, perplexityAppPendingFile } from '../guest/accounts/kinds/perplexityapp.js';
 import { perplexityAppShortcutArgs, restoreAppSignIn } from '../guest/browser/perplexity-app.js';
-import { appsToInstall, appById, isStorePackageFile, PERPLEXITY_DESKTOP_FAMILY, PERPLEXITY_DESKTOP_PACKAGE, PERPLEXITY_DESKTOP_PRODUCT_ID, storeApps, StorePackageManifestSchema, storePackageRole, } from '../shared/apps/index.js';
-import { appUsersOn, PAYLOADS, SERVICE_SPECS, serviceWanted, usedByText, } from '../shared/accounts/index.js';
+import { appsToInstall, appById, isStorePackageFile, PERPLEXITY_DESKTOP_FAMILY, PERPLEXITY_DESKTOP_PACKAGE, PERPLEXITY_DESKTOP_PRODUCT_ID, assignStoreRoles, storeApps, StorePackageManifestSchema, storePackageFitsX64, storePackageRole, } from '../shared/apps/index.js';
+import { appsNeededFor, appUsersOn, PAYLOADS, SERVICE_SPECS, serviceWanted, usedByText, } from '../shared/accounts/index.js';
 const MAIN = 'PerplexityAI.PerplexityApp_1.2.3.0_x64__3jh4kjrg4dzr2.msix';
 const FRAMEWORK = 'Microsoft.VCLibs.140.00_14.0.33519.0_x64__8wekyb3d8bbwe.appx';
 const sha = (text) => crypto.createHash('sha256').update(text).digest('hex');
@@ -137,7 +138,9 @@ export const storeAppSuite = {
             run: fakeStore({}, false).run,
         });
         t.check(outcome.notes.length === 1 &&
-            outcome.notes[0].includes('is not prepared') &&
+            outcome.notes[0].includes('NOT installed in this sandbox') &&
+            outcome.notes[0].includes('no Store access') &&
+            outcome.notes[0].startsWith('perplexity-desktop:') &&
             outcome.notes[0].includes('winget download --id 9P9XG917PWCJ'), 'with nothing kept the launch goes on, with a note that says what to fix');
         const good = await prepareStorePackages([app], {
             storageRoot: emptyRoot,
@@ -145,12 +148,67 @@ export const storeAppSuite = {
             run: fakeStore({ [MAIN]: 'a' }).run,
         });
         t.check(good.notes[0].includes('downloaded') && fs.existsSync(path.join(stagedPackageDir(emptyData, app.id), MAIN)), 'and a working Store stages it');
+        t.section('frameworks: the right builds, and the app told from them');
+        const VCLIBS_X86 = 'Microsoft.VCLibs.140.00_14.0.33519.0_x86__8wekyb3d8bbwe.appx';
+        const VCLIBS_ARM = 'Microsoft.VCLibs.140.00_14.0.33519.0_arm64__8wekyb3d8bbwe.appx';
+        t.check(storePackageFitsX64(FRAMEWORK) &&
+            !storePackageFitsX64(VCLIBS_X86) &&
+            !storePackageFitsX64(VCLIBS_ARM) &&
+            storePackageFitsX64('Microsoft.WindowsAppRuntime.1.6_6000.311.0_neutral__8wekyb3d8bbwe.msix'), '32-bit and ARM frameworks are left out, x64 and neutral ones stay');
+        t.equal(assignStoreRoles(['Perplexity_x64.msixbundle', FRAMEWORK], PERPLEXITY_DESKTOP_PACKAGE, [FRAMEWORK]).map((f) => f.role), ['main', 'dependency'], 'an app winget names another way is still found: it is the file outside Dependencies');
+        t.check((() => {
+            try {
+                assignStoreRoles([FRAMEWORK], PERPLEXITY_DESKTOP_PACKAGE, [FRAMEWORK]);
+                return false;
+            }
+            catch (e) {
+                return String(e).includes('only frameworks');
+            }
+        })(), 'frameworks without the app are refused with a plain reason');
+        const rich = await new StorePackages({
+            storageRoot: t.dir('pc3', 'storage'),
+            dataPath: t.dir('pc3', 'storage', 'data', 'set'),
+            run: (_exe, args) => {
+                const out = args[args.indexOf('-OutDir') + 1];
+                fs.mkdirSync(out, { recursive: true });
+                for (const n of ['Perplexity_1.2_x64.msixbundle', FRAMEWORK, VCLIBS_X86, VCLIBS_ARM])
+                    fs.writeFileSync(path.join(out, n), n);
+                return Promise.resolve({
+                    status: 0,
+                    stdout: JSON.stringify({
+                        ok: true,
+                        message: 'ok',
+                        files: ['Perplexity_1.2_x64.msixbundle', FRAMEWORK, VCLIBS_X86, VCLIBS_ARM],
+                        dependencies: [FRAMEWORK, VCLIBS_X86, VCLIBS_ARM],
+                    }),
+                    stderr: '',
+                });
+            },
+        }).fetch(app);
+        t.check(rich.files.map((f) => f.role).join() === 'main,dependency' &&
+            rich.files.every((f) => storePackageFitsX64(f.name)), 'a fetch keeps the app and only the x64 framework, with the roles the script reported');
+        t.section('a sign-in for an app that is not installed says so');
+        t.equal(appsNeededFor('perplexityapp'), ['perplexity-desktop'], 'the app a sign-in needs');
+        t.equal(appsNeededFor('epic'), [], 'a sign-in a toolchain uses needs no app');
+        const sharing = { ...DEFAULTS, accounts: { ...DEFAULTS.accounts, perplexityapp: { share: true } } };
+        const deliverFor = (on) => prepareServiceAccounts({
+            config: sharing,
+            others: [],
+            on: new Set(on),
+            storageRoot: t.dir('pc4', 'storage'),
+            dataPath: t.dir('pc4', 'storage', 'data', 'set'),
+            launchId: 'L-1',
+            isRunning: () => false,
+        });
+        const missing = deliverFor([]);
+        t.check(missing.notes.some((n) => n.includes('accounts.perplexityapp.share') && n.includes('Fix: turn the app on in Apps')) && !missing.leased.length, 'share on with the app off: a launch note names the setting and the app to turn on');
+        t.check(!deliverFor(['perplexityapp']).notes.some((n) => n.includes('is not installed')), 'with the app on there is no such note');
         t.section('the sandbox checks the kept files');
         const checked = await checkedPackage(staged);
         t.check(path.basename(checked.main) === MAIN && checked.dependencies.map((d) => path.basename(d)).join() === FRAMEWORK, 'the app and its frameworks, in order');
         fs.writeFileSync(path.join(staged, FRAMEWORK), 'tampered');
         t.check((await t.thrownMessage(() => checkedPackage(staged))).includes('missing or changed'), 'a changed file stops the install');
-        t.check((await t.thrownMessage(() => checkedPackage(t.dir('nothing')))).includes('not handed over'), 'no package says so');
+        t.check((await t.thrownMessage(() => checkedPackage(t.dir('nothing')))).includes('did not hand over its package'), 'no package says so');
         t.section('the shortcut');
         const args = perplexityAppShortcutArgs('C:\\AgentLaunch\\sandbox\\scripts\\start-store-app.ps1', 'C:\\Users\\X\\profile');
         t.check(args.includes('-File "C:\\AgentLaunch\\sandbox\\scripts\\start-store-app.ps1"') &&

package/dist/selftest/support/engine-golden.js

@@ -62,6 +62,7 @@ export const LAUNCH_FILES_GOLDEN = [
     'sandbox/csharp/AppActivation.cs',
     'sandbox/csharp/BindMount.cs',
     'sandbox/csharp/CargoShim.cs',
+    'sandbox/csharp/ClipboardWatch.cs',
     'sandbox/csharp/Desktop.cs',
     'sandbox/csharp/EnvBroadcast.cs',
     'sandbox/csharp/GitShim.cs',
@@ -95,6 +96,7 @@ export const LAUNCH_FILES_GOLDEN = [
     'sandbox/scripts/set-machine-environment.ps1',
     'sandbox/scripts/set-registry-values.ps1',
     'sandbox/scripts/start-store-app.ps1',
+    'sandbox/scripts/watch-clipboard.ps1',
     'sandbox/templates/fivem/README.txt',
     'sandbox/templates/fivem/cs/Client/Client.csproj',
     'sandbox/templates/fivem/cs/Client/ClientMain.cs',

package/dist/selftest/support/web-preview.js

@@ -563,7 +563,7 @@ export function sampleAuditLog(dir) {
         proc(94, 'C:\\AgentData\\tools\\uv\\uv.exe', 'uv tool install aider-chat', {}),
         { t: at(90), k: 'session', a: 'start', p: 'claude', w: SESSIONS[0].cwd, c: claude.s, ...claude, sv: undefined },
         proc(88, git, 'git status --short', claude),
-        proc(87, node, 'node dist/bin/agent-sandbox.js self-test audit', claude, 2),
+        proc(87, node, 'node dist/bin/sandbox.js self-test audit', claude, 2),
         file(80, 'src/host/audit/collect.ts', ws, claude),
         file(79, 'src/app/features/audit/audit.def.ts', ws, claude),
         proc(70, 'C:\\nvm\\nodejs\\npm.cmd', 'npm run build', claude),
@@ -613,7 +613,7 @@ export function sampleAuditLog(dir) {
             ...codex,
             sv: undefined,
         },
-        proc(5, node, 'node dist/bin/agent-sandbox.js self-test app', claude),
+        proc(5, node, 'node dist/bin/sandbox.js self-test app', claude),
         { t: at(4), k: 'remote', p: 'sessions.restart', a: 'ok', au: "device Josh's iPhone" },
         { t: at(3), k: 'remote', p: 'settings.set', a: 'refused', au: 'Windows user DESKTOP-JOSH\\sam' },
     ]);

package/dist/shared/accounts/kinds.d.ts

@@ -58,3 +58,8 @@ export declare function usedByText(usedBy: readonly string[]): string;
 export declare function appUsersOn(install: readonly string[]): AppUser[];
 /** Whether a sign-in is wanted when these toolchains (and apps) are on. */
 export declare function serviceWanted(kind: ServiceKind, on: ReadonlySet<UsedBy>): boolean;
+/**
+ * For a sign-in that only apps use (Perplexity API, Comet, the Perplexity app): the apps.install ids to turn on for it
+ * to be handed over; empty for a kind a toolchain uses. A sign-in shared with its app off would otherwise do nothing.
+ */
+export declare function appsNeededFor(kind: ServiceKind): string[];

package/dist/shared/accounts/kinds.js

@@ -256,3 +256,11 @@ export function serviceWanted(kind, on) {
         return true;
     return spec.usedBy.includes('android') && ANDROID_USERS.some((u) => on.has(u));
 }
+/**
+ * For a sign-in that only apps use (Perplexity API, Comet, the Perplexity app): the apps.install ids to turn on for it
+ * to be handed over; empty for a kind a toolchain uses. A sign-in shared with its app off would otherwise do nothing.
+ */
+export function appsNeededFor(kind) {
+    const { usedBy } = SERVICE_SPECS[kind];
+    return usedBy.every((u) => u in APP_USERS) ? usedBy.flatMap((u) => [...APP_USERS[u]]) : [];
+}

package/dist/shared/apps/index.d.ts

@@ -5,4 +5,4 @@ export { exeMatcher, appsToInstall, appsNeedMesa, appsNeedUv, storeApps } from '
 export { signerMatches, type AppSigner, type Signature } from '../signer.js';
 export { AGENTS_WEB_APPS, BROWSER_USE_VERSION, CHROME_DEVTOOLS_MCP_VERSION, COMET_DOWNLOAD_URL, PERPLEXITY_DESKTOP_FAMILY, PERPLEXITY_DESKTOP_PACKAGE, PERPLEXITY_DESKTOP_PRODUCT_ID, COMET_MCP_VERSION, COMET_SIGNER, PERPLEXITY_COMPUTER_MCP_URL, PERPLEXITY_MCP_VERSION, } from './catalogue-agents-web.js';
 export { ADDON_MCP_PREFIX, addonGuideLine, addonMcpServer, type AddonPlace, claudeManagedSettings, codexWithAddonMcpServers, type CodexMcpServer, HEADROOM_ENV, HEADROOM_PORT, HEADROOM_UPSTREAM, headroomArgs, headroomEnv, headroomGuideLine, headroomUrl, type ManagedSettings, type McpServerConfig, rtkHookCommand, RTK_GUIDE_LINE, withAddonMcpServers, } from './agent-addons.js';
-export { isStorePackageFile, STORE_PACKAGE_MANIFEST, StorePackageFileSchema, StorePackageManifestSchema, storePackageRole, type StorePackageFile, type StorePackageManifest, } from './store-package.js';
+export { isStorePackageFile, STORE_PACKAGE_MANIFEST, StorePackageFileSchema, StorePackageManifestSchema, storePackageRole, storePackageFitsX64, assignStoreRoles, type StorePackageFile, type StorePackageManifest, } from './store-package.js';

package/dist/shared/apps/index.js

@@ -5,4 +5,4 @@ export { exeMatcher, appsToInstall, appsNeedMesa, appsNeedUv, storeApps } from '
 export { signerMatches } from '../signer.js';
 export { AGENTS_WEB_APPS, BROWSER_USE_VERSION, CHROME_DEVTOOLS_MCP_VERSION, COMET_DOWNLOAD_URL, PERPLEXITY_DESKTOP_FAMILY, PERPLEXITY_DESKTOP_PACKAGE, PERPLEXITY_DESKTOP_PRODUCT_ID, COMET_MCP_VERSION, COMET_SIGNER, PERPLEXITY_COMPUTER_MCP_URL, PERPLEXITY_MCP_VERSION, } from './catalogue-agents-web.js';
 export { ADDON_MCP_PREFIX, addonGuideLine, addonMcpServer, claudeManagedSettings, codexWithAddonMcpServers, HEADROOM_ENV, HEADROOM_PORT, HEADROOM_UPSTREAM, headroomArgs, headroomEnv, headroomGuideLine, headroomUrl, rtkHookCommand, RTK_GUIDE_LINE, withAddonMcpServers, } from './agent-addons.js';
-export { isStorePackageFile, STORE_PACKAGE_MANIFEST, StorePackageFileSchema, StorePackageManifestSchema, storePackageRole, } from './store-package.js';
+export { isStorePackageFile, STORE_PACKAGE_MANIFEST, StorePackageFileSchema, StorePackageManifestSchema, storePackageRole, storePackageFitsX64, assignStoreRoles, } from './store-package.js';

package/dist/shared/apps/selection.d.ts

@@ -14,6 +14,7 @@ export declare function appsNeedMesa(apps: Config['apps'] | undefined): boolean;
 /** The chosen apps that come from the Microsoft Store: what this PC has to fetch for them. */
 export declare function storeApps(install: readonly string[]): {
     id: string;
+    name: string;
     productId: string;
     packageName: string;
 }[];

package/dist/shared/apps/selection.js

@@ -50,9 +50,10 @@ export function appsNeedMesa(apps) {
 /** The chosen apps that come from the Microsoft Store: what this PC has to fetch for them. */
 export function storeApps(install) {
     return install.flatMap((id) => {
-        const source = appById(id)?.source;
-        return source !== undefined && 'store' in source
-            ? [{ id, productId: source.store.productId, packageName: source.store.packageName }]
+        const entry = appById(id);
+        const source = entry?.source;
+        return entry && source !== undefined && 'store' in source
+            ? [{ id, name: entry.name, productId: source.store.productId, packageName: source.store.packageName }]
             : [];
     });
 }

package/dist/shared/apps/store-package.d.ts

@@ -29,3 +29,16 @@ export declare const STORE_PACKAGE_MANIFEST = "store-package.json";
 export declare function isStorePackageFile(name: string): boolean;
 /** The app itself (named <package name>_<version>_...), as opposed to a framework it depends on (VCLibs ...). */
 export declare function storePackageRole(fileName: string, packageName: string): 'main' | 'dependency';
+/**
+ * Whether a dependency package suits this sandbox (64-bit Windows): winget may also fetch the 32-bit and ARM builds
+ * of a framework, and Add-AppxPackage is only handed the builds that can run here.
+ */
+export declare function storePackageFitsX64(fileName: string): boolean;
+/**
+ * Which fetched file is the app and which are its frameworks. The app is named after its package; when winget names
+ * it otherwise, the one file that did not come from the Dependencies folder is the app. Throws when that is unclear.
+ */
+export declare function assignStoreRoles(names: readonly string[], packageName: string, dependencyNames: readonly string[]): {
+    name: string;
+    role: 'main' | 'dependency';
+}[];

package/dist/shared/apps/store-package.js

@@ -32,3 +32,27 @@ export function isStorePackageFile(name) {
 export function storePackageRole(fileName, packageName) {
     return fileName.toLowerCase().startsWith(packageName.toLowerCase() + '_') ? 'main' : 'dependency';
 }
+/**
+ * Whether a dependency package suits this sandbox (64-bit Windows): winget may also fetch the 32-bit and ARM builds
+ * of a framework, and Add-AppxPackage is only handed the builds that can run here.
+ */
+export function storePackageFitsX64(fileName) {
+    return !/[_.-](x86|arm|arm64)(?=[_.-]|$)/i.test(fileName.replace(/\.(msix|appx|msixbundle|appxbundle)$/i, ''));
+}
+/**
+ * Which fetched file is the app and which are its frameworks. The app is named after its package; when winget names
+ * it otherwise, the one file that did not come from the Dependencies folder is the app. Throws when that is unclear.
+ */
+export function assignStoreRoles(names, packageName, dependencyNames) {
+    const listed = new Set(dependencyNames.map((n) => n.toLowerCase()));
+    let mains = names.filter((n) => storePackageRole(n, packageName) === 'main');
+    if (mains.length === 0)
+        mains = names.filter((n) => !listed.has(n.toLowerCase()));
+    if (mains.length > 1)
+        mains = mains.filter(storePackageFitsX64);
+    if (mains.length !== 1)
+        throw new Error(mains.length === 0
+            ? 'winget gave only frameworks, not the app itself (' + names.join(', ') + ')'
+            : 'winget gave more than one app package and it is not clear which to install (' + mains.join(', ') + ')');
+    return names.map((name) => ({ name, role: name === mains[0] ? 'main' : 'dependency' }));
+}