windows-development-sandbox 1.4.3 → 1.7.0

package/dist/selftest/sharing.test.js

@@ -0,0 +1,250 @@
+// Machine-wide settings (the machine file under the user file), the records of who started a sandbox, who owns the
+// running one, and the folder permissions for sharing. Everything happens in temp folders; the folder-permission
+// script runs on the temp folders only, and only on Windows.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { DEFAULTS, loadConfig, machineConfigPath } from '../core/config/index.js';
+import { ConfigSchema, LocalOverridesSchema } from '../core/schema/index.js';
+import { nativeFile, nativeScript } from '../host/native.js';
+import { ActiveRecords, parseTasklist, runFolderAccess, runPrivateFolder, sharingAclPlan, whoOwnsSandbox, } from '../host/sharing/index.js';
+import { SYSTEM } from '../shared/system.js';
+const ALICE_SID = 'S-1-5-21-1111111111-2222222222-3333333333-1001';
+const BOB_SID = 'S-1-5-21-1111111111-2222222222-3333333333-1002';
+const GROUP_SID = 'S-1-5-21-1111111111-2222222222-3333333333-5000';
+/** A record as a starter writes it. */
+function record(sid, extra = {}) {
+    return {
+        user: sid === ALICE_SID ? 'alice' : 'bob',
+        sid,
+        windowsSession: 2,
+        dataPath: 'C:\\Users\\alice\\AgentSandbox\\data\\default',
+        shared: true,
+        startedAt: '2026-10-14T09:00:00Z',
+        version: '1.4.3',
+        projects: [{ id: 'app', hostPath: 'C:\\Dev\\app', guestPath: 'C:\\Workspace\\app' }],
+        ...extra,
+    };
+}
+// Five process rows (the sandbox window in session 2) and the INFO line tasklist prints when a filter matches nothing.
+const TASKLIST = [
+    '"explorer.exe","4120","Console","1","123,456 K"',
+    '"WindowsSandboxClient.exe","8124","Console","2","1,234 K"',
+    '"svchost.exe","900","Services","0","12,345 K"',
+    '"conhost.exe","8130","Console","2","4,096 K"',
+    '',
+    'INFO: No tasks are running which match the specified criteria.',
+    '',
+].join('\r\n');
+/** Layers: defaults, the machine file, the user file. */
+async function layering(t) {
+    t.section('layering: machine file under the user file');
+    t.check(machineConfigPath({ ProgramData: 'D:\\PD' }) === path.join('D:\\PD', 'AgentSandbox', 'config.json') &&
+        machineConfigPath({ AGENT_SANDBOX_MACHINE_HOME: t.at('m') }) === path.join(t.at('m'), 'config.json'), 'the machine file is %ProgramData%\\AgentSandbox\\config.json, movable with AGENT_SANDBOX_MACHINE_HOME (tests)');
+    const quiet = loadConfig();
+    const machineFile = t.writeJson(machineConfigPath(), {
+        sharing: { otherUsers: true },
+        storage: { root: t.at('machine-storage') },
+    });
+    const machineOnly = loadConfig();
+    const userFile = t.writeJson(t.at('user', 'config.json'), { sharing: { otherUsers: false } });
+    const both = loadConfig(userFile);
+    t.equal([
+        [quiet.layers?.machine, quiet.layers?.user, quiet.config.sharing.otherUsers],
+        [machineOnly.config.sharing.otherUsers, machineOnly.config.storage.root, machineOnly.configPath],
+        [both.config.sharing.otherUsers, both.config.storage.root, both.layers],
+    ], [
+        [null, null, false],
+        [true, t.at('machine-storage'), null],
+        [false, t.at('machine-storage'), { machine: machineFile, user: userFile }],
+    ], 'no files: defaults (sharing off); a machine file alone applies; the user file wins but keys it leaves out keep the machine value');
+    t.writeJson(machineFile, { storage: { root: 'relative\\store' } });
+    await t.throws(() => loadConfig(), 'storage.root', 'a relative folder in the machine file is refused, naming the key');
+    t.writeJson(machineFile, { sharing: { otherUsers: 'yes' } });
+    await t.throws(() => loadConfig(), 'otherUsers', 'a machine file is validated like a user file');
+}
+/** A project file can never make this PC's sandbox shared; the user file can. */
+function projectCannotShare(t) {
+    t.check(!LocalOverridesSchema.safeParse({ sharing: { otherUsers: true } }).success &&
+        ConfigSchema.safeParse({ ...DEFAULTS, sharing: { otherUsers: true } }).success, 'sharing is a user (or machine) setting only: a project file cannot set sharing.otherUsers');
+}
+/** Records: write, read, clear, and what is skipped (corrupt, mismatched, a folder, a link). */
+function recordsSection(t) {
+    t.section('active records');
+    const dir = t.dir('active');
+    const records = new ActiveRecords(dir);
+    t.equal(records.readAll(), [], 'a missing folder reads as no records');
+    records.write(record(ALICE_SID));
+    records.write(record(BOB_SID, { shared: false, windowsSession: 3 }));
+    const both = records.readAll().length;
+    records.clear(BOB_SID);
+    t.check(both === 2 &&
+        records
+            .readAll()
+            .map((r) => r.sid)
+            .join() === ALICE_SID, 'each user has their own record; clear removes only that user’s');
+    t.write(path.join(dir, 'S-1-5-21-1111111111-2222222222-3333333333-1003.json'), '{ not json');
+    t.writeJson(path.join(dir, 'S-1-5-21-1111111111-2222222222-3333333333-1004.json'), record('S-1-5-21-1111111111-2222222222-3333333333-1005'));
+    fs.mkdirSync(path.join(dir, 'S-1-5-21-1111111111-2222222222-3333333333-1006.json'));
+    const linked = 'S-1-5-21-1111111111-2222222222-3333333333-1007';
+    const outside = t.writeJson(t.at('outside', 'record.json'), record(linked));
+    try {
+        fs.symlinkSync(outside, path.join(dir, linked + '.json'), 'file');
+    }
+    catch {
+        t.skip('file links need a privilege this user may lack; the link check did not run');
+    }
+    t.equal(records.readAll().map((r) => r.sid), [ALICE_SID], 'a corrupt file, a file named for another SID, a folder and a link are skipped (links never followed)');
+    let refused = false;
+    try {
+        records.write({ ...record(ALICE_SID), sid: '..\\evil' });
+    }
+    catch {
+        refused = true;
+    }
+    t.check(refused, 'a record with a bad SID is refused on write (its file name would leave the folder)');
+}
+/** Who owns the running sandbox, from a recorded tasklist sample. */
+function ownership(t) {
+    t.section('tasklist and the sandbox owner');
+    const rows = parseTasklist(TASKLIST);
+    t.check(rows.length === 4 &&
+        JSON.stringify(rows[1]) === JSON.stringify({ image: 'WindowsSandboxClient.exe', pid: 8124, session: 2 }), 'tasklist rows are read; the INFO line is skipped and a Mem with a thousands separator does not break a row');
+    const none = parseTasklist('"explorer.exe","4120","Console","1","123,456 K"');
+    const aliceShared = whoOwnsSandbox(rows, 1, [record(ALICE_SID, { windowsSession: 2, shared: true })]);
+    const bobPrivate = whoOwnsSandbox(rows, 1, [record(BOB_SID, { windowsSession: 2, shared: false })]);
+    const remoteOnly = parseTasklist('"WindowsSandboxRemoteSession.exe","777","Console","3","900 K"');
+    t.equal([
+        whoOwnsSandbox(none, 1, []).kind,
+        whoOwnsSandbox(rows, 2, []).kind,
+        aliceShared.kind === 'other' ? [aliceShared.user, aliceShared.shared] : aliceShared.kind,
+        bobPrivate.kind === 'other' ? [bobPrivate.user, bobPrivate.shared] : bobPrivate.kind,
+        whoOwnsSandbox(rows, 1, []).kind,
+        whoOwnsSandbox(rows, 1, [record(ALICE_SID, { windowsSession: 9 })]).kind,
+        whoOwnsSandbox(remoteOnly, 1, [record(ALICE_SID, { windowsSession: 3 })]).kind,
+    ], ['none', 'mine', ['alice', true], ['bob', false], 'unknown-other', 'unknown-other', 'other'], 'owner: none, mine, another user (shared or not), no record, a stale record, and the remote-session process');
+}
+/** The permission entries sharing needs, on and off. */
+async function permissionPlan(t) {
+    t.section('folder permissions for sharing');
+    const storageUserDir = t.at('ProgramData', 'AgentSandbox', 'users', 'alice');
+    const dataPath = path.join(storageUserDir, 'data', 'default');
+    const entries = (add) => [
+        { path: storageUserDir, sid: GROUP_SID, rights: 'Traverse', scope: 'this-folder', add },
+        { path: path.join(storageUserDir, 'data'), sid: GROUP_SID, rights: 'Traverse', scope: 'this-folder', add },
+        { path: dataPath, sid: GROUP_SID, rights: 'Traverse', scope: 'this-folder', add },
+        { path: path.join(dataPath, 'run'), sid: GROUP_SID, rights: 'Modify', scope: 'inherit', add },
+    ];
+    t.equal([
+        sharingAclPlan({ storageUserDir, dataPath, groupSid: GROUP_SID, on: true }),
+        sharingAclPlan({ storageUserDir, dataPath, groupSid: GROUP_SID, on: false }),
+    ], [entries(true), entries(false)], 'sharing on: traverse on the user folder, data folder and data set, modify (inherited) on run; off removes the same entries');
+    await t.throws(() => sharingAclPlan({ storageUserDir, dataPath: t.at('elsewhere', 'default'), groupSid: GROUP_SID, on: true }), 'not under', 'a data set outside the user folder is refused');
+}
+/** The PowerShell script: it parses, changes a temp folder's permissions, and refuses links. Windows only. */
+function folderScript(t) {
+    t.section('set-folder-access.ps1');
+    if (process.platform !== 'win32') {
+        t.skip('the folder-permission script runs only on Windows');
+        return;
+    }
+    const parsed = spawnSync(SYSTEM.powershell(), nativeScript('check-syntax.ps1', ['-Path', nativeFile('scripts', 'set-folder-access.ps1')]), { encoding: 'utf8', windowsHide: true });
+    t.equal(parsed.status, 0, 'set-folder-access.ps1 parses with Windows PowerShell 5.1 (' + (parsed.stderr || '').trim() + ')');
+    const who = spawnSync(SYSTEM.whoami(), ['/user', '/fo', 'csv', '/nh'], { encoding: 'utf8', windowsHide: true });
+    const match = /"([^"]+)","(S-1-[0-9-]+)"/.exec(who.stdout ?? '');
+    if (!match) {
+        t.skip('could not read the current user SID with whoami');
+        return;
+    }
+    const [, account, sid] = match;
+    const target = t.dir('acl-target');
+    const icacls = () => (spawnSync(SYSTEM.icacls(), [target], { encoding: 'utf8', windowsHide: true }).stdout ?? '').toLowerCase();
+    const explicitRead = account.toLowerCase() + ':(r)';
+    runFolderAccess([{ path: target, sid, rights: 'Read', scope: 'this-folder', add: true }]);
+    const granted = icacls().includes(explicitRead);
+    runFolderAccess([{ path: target, sid, rights: 'Read', scope: 'this-folder', add: false }]);
+    t.check(granted && !icacls().includes(explicitRead), 'adding a Read entry grants it on the temp folder; removing takes it away');
+    const link = t.at('acl-link');
+    fs.symlinkSync(target, link, 'junction');
+    let refused = '';
+    try {
+        runFolderAccess([{ path: link, sid, rights: 'Read', scope: 'this-folder', add: true }]);
+    }
+    catch (e) {
+        refused = e.message;
+    }
+    t.includes(refused, 'link', 'a junction is refused, and nothing is changed through it');
+    // Nothing to change: removing an entry that is not there leaves the permissions as they were.
+    const before = icacls();
+    runFolderAccess([{ path: target, sid, rights: 'Read', scope: 'this-folder', add: false }]);
+    t.equal(icacls(), before, 'removing an entry that is not there changes nothing');
+    // A this-folder entry is written to that folder only: it stays auto-inherited (D:AI) and a child is not touched; an
+    // entry that changes nothing writes nothing (the change time of the folder does not move).
+    const sddls = (folder, also) => (spawnSync(SYSTEM.powershell(), nativeScript('read-folder-sddl.ps1', ['-Path', folder, ...(also ? ['-Also', also] : [])]), {
+        encoding: 'utf8',
+        windowsHide: true,
+    }).stdout ?? '')
+        .split(/\r?\n/)
+        .filter(Boolean);
+    const inherits = t.dir('acl-inherits');
+    // Set-Acl marks the folder auto-inherited, whatever its parent says: start from that state.
+    runFolderAccess([{ path: inherits, sid, rights: 'Modify', scope: 'inherit', add: true }]);
+    const child = path.join(inherits, 'child');
+    fs.mkdirSync(child);
+    fs.writeFileSync(path.join(child, 'a.txt'), 'x');
+    const [folderBefore, childBefore] = sddls(inherits, child);
+    if (!folderBefore?.includes('D:AI')) {
+        t.skip('the temp folder does not inherit its permissions here, so D:AI cannot be checked');
+    }
+    else {
+        const childChange = fs.statSync(child).ctimeMs;
+        runFolderAccess([{ path: inherits, sid, rights: 'Read', scope: 'this-folder', add: true }]);
+        const [folderAfter, childAfter] = sddls(inherits, child);
+        t.check(folderAfter !== folderBefore && folderAfter.includes('D:AI'), 'a this-folder entry changes the folder and keeps it auto-inherited (D:AI)');
+        t.check(childAfter === childBefore && fs.statSync(child).ctimeMs === childChange, 'a this-folder entry leaves a child’s permissions byte for byte the same');
+        runFolderAccess([{ path: inherits, sid, rights: 'Read', scope: 'this-folder', add: true }]);
+        const changed = fs.statSync(inherits).ctimeMs;
+        runFolderAccess([{ path: inherits, sid, rights: 'Read', scope: 'this-folder', add: true }]);
+        runFolderAccess([{ path: inherits, sid, rights: 'Modify', scope: 'this-folder', add: false }]);
+        t.check(fs.statSync(inherits).ctimeMs === changed && sddls(inherits)[0] === folderAfter, 'an entry that changes nothing writes nothing');
+        runFolderAccess([{ path: inherits, sid, rights: 'Read', scope: 'this-folder', add: false }]);
+        t.equal(sddls(inherits)[0], folderBefore, 'removing the entry restores the folder exactly');
+    }
+    // A private folder: inheritance off, only you, SYSTEM and Administrators; a second run changes nothing.
+    const own = t.dir('acl-private');
+    runPrivateFolder(own);
+    const first = (spawnSync(SYSTEM.icacls(), [own], { encoding: 'utf8', windowsHide: true }).stdout ?? '').toLowerCase();
+    runPrivateFolder(own);
+    const second = (spawnSync(SYSTEM.icacls(), [own], { encoding: 'utf8', windowsHide: true }).stdout ?? '').toLowerCase();
+    t.check(first === second &&
+        first.includes('nt authority\\system:(oi)(ci)(f)') &&
+        first.includes('builtin\\administrators:(oi)(ci)(f)') &&
+        !first.includes('builtin\\users'), 'a private folder is closed to other users, and making it private again changes nothing');
+    fs.mkdirSync(path.join(own, 'child'));
+    fs.writeFileSync(path.join(own, 'child', 'a.txt'), 'x');
+    t.check(fs.readFileSync(path.join(own, 'child', 'a.txt'), 'utf8') === 'x', 'the owner can still use a private folder');
+}
+export const sharingSuite = {
+    name: 'sharing',
+    title: 'machine settings, sharing records, sandbox owner, folder permissions',
+    run: async (t) => {
+        const savedMachine = process.env.AGENT_SANDBOX_MACHINE_HOME;
+        process.env.AGENT_SANDBOX_MACHINE_HOME = t.at('machine-home');
+        try {
+            await layering(t);
+            projectCannotShare(t);
+            recordsSection(t);
+            ownership(t);
+            await permissionPlan(t);
+            folderScript(t);
+        }
+        finally {
+            // Later suites load the settings too: the machine file this suite wrote must not outlive it.
+            fs.rmSync(t.at('machine-home'), { recursive: true, force: true });
+            if (savedMachine === undefined)
+                delete process.env.AGENT_SANDBOX_MACHINE_HOME;
+            else
+                process.env.AGENT_SANDBOX_MACHINE_HOME = savedMachine;
+        }
+    },
+};

package/dist/selftest/storage.test.d.ts

@@ -0,0 +1,2 @@
+import type { Suite } from './support/suite.js';
+export declare const storageSuite: Suite;

package/dist/selftest/storage.test.js

@@ -0,0 +1,363 @@
+// The data folder: the pin migration and the two that must leave it alone, the move engine (rename, copy, failures),
+// the estimate and checks, the offer to move, and the path picker's helpers and screen. Temp folders only.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from 'jsonc-parser';
+import { DEFAULTS, machineConfigPath } from '../core/config/index.js';
+import { MIGRATIONS } from '../host/migrate/index.js';
+import { DEFAULTS_SNAPSHOTS } from '../host/migrate/snapshots.js';
+import { describeDuration, ensureStorageRoot, estimateMove, holdsData, measureFolder, moveProblem, moveWarning, oldDefaultRoot, pinValue, planOffer, privateFolderOf, sharedDefaultRoot, StorageHistory, StorageMove, usersFolder, BIG_BYTES, } from '../host/storage/index.js';
+import { PathPickerScreen } from '../cli/tui/dialogs/path-picker.js';
+import { completeInput, folderNameProblem, listFolder, narrow, parentOf, splitInput, } from '../cli/tui/dialogs/path-listing.js';
+const GB = 1024 ** 3;
+const readText = (file) => fs.readFileSync(file, 'utf8');
+const key = (name, text = '', ctrl = false) => ({ name, text, ctrl, meta: false, shift: false });
+function migration(id) {
+    const found = MIGRATIONS.find((m) => m.id === id);
+    if (!found)
+        throw new Error('no migration ' + id);
+    return found;
+}
+function ctxOf(userDir, configPath) {
+    return { storageRoot: path.join(userDir, 'storage'), userDir, configPath, sandboxRunning: () => false };
+}
+/** Three files in two levels, 10 + 100 + 1 bytes. */
+function makeTree(root) {
+    fs.mkdirSync(path.join(root, 'sub', 'deep'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'a.txt'), '0123456789');
+    fs.writeFileSync(path.join(root, 'sub', 'b.bin'), 'b'.repeat(100));
+    fs.writeFileSync(path.join(root, 'sub', 'deep', 'c.txt'), 'c');
+}
+const noBusy = () => null;
+const idle = () => false;
+async function pinMigration(t) {
+    t.section('pin-storage-root: nobody loses sight of their data on upgrade');
+    const pin = migration('2026-10-pin-storage-root');
+    const oldDir = path.join(process.env.LOCALAPPDATA ?? '', 'AgentSandbox');
+    const machineFile = machineConfigPath();
+    fs.rmSync(oldDir, { recursive: true, force: true });
+    const user = t.dir('pin', 'user');
+    t.check(!pin.applies(ctxOf(user, null)), 'a fresh install (no config, no old folder) keeps the shared default: nothing to pin');
+    fs.mkdirSync(oldDir, { recursive: true });
+    t.check(!pin.applies(ctxOf(user, null)), 'an old folder with nothing in it is not data: nothing to pin');
+    fs.writeFileSync(path.join(oldDir, 'x.txt'), 'data');
+    t.check(pin.applies(ctxOf(user, null)), 'an old folder with data and no config.json: pinned');
+    const notes = [];
+    {
+        await pin.run(ctxOf(user, null), (line) => notes.push(line));
+        const created = path.join(user, 'config.json');
+        t.check(fs.existsSync(created) &&
+            parse(readText(created)).storage.root === '%LOCALAPPDATA%\\AgentSandbox' &&
+            !pin.applies(ctxOf(user, created)) &&
+            notes.length === 1, 'the config is created with storage.root = %LOCALAPPDATA%\\AgentSandbox, and it is applied once');
+        const commented = t.write(t.at('pin', 'c.json'), '// mine\n{\n  "sandbox": { "memoryMb": 4096 } // keep\n}\n');
+        await pin.run(ctxOf(user, commented), () => undefined);
+        const text = readText(commented);
+        t.check(text.includes('// mine') &&
+            text.includes('// keep') &&
+            parse(text).sandbox.memoryMb === 4096 &&
+            text.includes('AgentSandbox'), 'an existing config keeps its comments and values; the pin is added');
+        const chosen = t.write(t.at('pin', 'chosen.json'), JSON.stringify({ storage: { root: 'D:\\Mine' } }));
+        t.check(!pin.applies(ctxOf(user, chosen)), 'a storage.root the user chose is never replaced');
+        const broken = t.write(t.at('pin', 'broken.json'), '{ not json');
+        t.check(!pin.applies(ctxOf(user, broken)), 'a config that cannot be read is left alone');
+        t.write(machineFile, JSON.stringify({ storage: { root: t.at('machine-data') } }));
+        try {
+            t.check(!pin.applies(ctxOf(user, commented.replace('c.json', 'none.json'))), 'an all-users install: nothing pinned');
+        }
+        finally {
+            fs.rmSync(machineFile);
+        }
+        t.section('unpin-config-defaults and follow-machine-storage leave the pin alone');
+        const unpin = migration('2026-10-unpin-config-defaults');
+        const old = DEFAULTS_SNAPSHOTS.find((s) => s.defaults.storage?.root);
+        if (!old)
+            return t.check(false, 'a snapshot with a storage.root exists');
+        const full = t.write(t.at('pin', 'full.json'), JSON.stringify({ ...JSON.parse(JSON.stringify(old.defaults)), sandbox: { memoryMb: 4096 } }));
+        await unpin.run(ctxOf(user, full), () => undefined);
+        const rest = parse(readText(full));
+        t.check(rest.storage?.root === old.defaults.storage.root && rest.sandbox?.memoryMb === 4096, 'a full old config keeps its pinned storage.root (the old default no longer is the default)');
+        t.check(!unpin.applies(ctxOf(user, full)), 'and the migration is then done');
+        const follow = migration('2026-10-follow-machine-storage');
+        const pinned = t.write(t.at('pin', 'pinned.json'), JSON.stringify({ storage: { root: DEFAULTS.storage.root } }));
+        const oldPinned = t.write(t.at('pin', 'oldpinned.json'), JSON.stringify(old.defaults));
+        const partial = t.write(t.at('pin', 'partial.json'), JSON.stringify({ storage: { root: '%LOCALAPPDATA%\\AgentSandbox' } }));
+        const shared = t.at('machine-users');
+        t.write(machineFile, JSON.stringify({ storage: { root: shared } }));
+        try {
+            t.check(!follow.applies(ctxOf(user, oldPinned)), 'with an all-users install, a pin that holds the data is kept while the shared folder is empty');
+            t.check(follow.applies(ctxOf(user, pinned)), 'a pin of the shared default still follows the machine config');
+            t.check(!follow.applies(ctxOf(user, partial)), 'a pin written on its own (not an old full init) is never dropped');
+            fs.mkdirSync(shared, { recursive: true });
+            fs.writeFileSync(path.join(shared, 'x'), '1');
+            t.check(follow.applies(ctxOf(user, oldPinned)), 'once the shared folder has data, the old pin is dropped as before');
+        }
+        finally {
+            fs.rmSync(machineFile);
+            fs.rmSync(oldDir, { recursive: true, force: true });
+        }
+    }
+}
+async function moveEngine(t) {
+    t.section('storage move: rename on one drive');
+    const root = t.dir('mv');
+    const config = t.write(t.at('mv', 'config.json'), '// mine\n{ "sandbox": { "memoryMb": 4096 } }\n');
+    const src = t.at('mv', 'src');
+    makeTree(src);
+    const measured = measureFolder(src);
+    t.equal({ files: measured.files, bytes: measured.bytes, partial: measured.partial }, { files: 3, bytes: 111, partial: false }, 'measuring counts files and bytes');
+    const mover = new StorageMove(config, noBusy, idle);
+    const dst = t.at('mv', 'dst');
+    const renamed = await mover.move(src, dst);
+    t.check(!renamed.copied &&
+        renamed.removedOld &&
+        !fs.existsSync(src) &&
+        measureFolder(dst).files === 3 &&
+        fs.readFileSync(path.join(dst, 'sub', 'b.bin'), 'utf8').length === 100, 'same drive: the folders are renamed, nothing is copied, the old folder is gone');
+    const written = readText(config);
+    t.check(written.includes('// mine') &&
+        parse(written).storage.root === dst &&
+        renamed.pinned === dst, 'storage.root is pinned in the config (the literal path), comments kept');
+    t.section('storage move: copy to another drive (forced), progress, keep old');
+    const src2 = t.at('mv', 'src2');
+    makeTree(src2);
+    const progress = [];
+    const copied = await mover.move(src2, t.at('mv', 'dst2'), { forceCopy: true, onProgress: (p) => progress.push(p) });
+    const last = progress[progress.length - 1];
+    t.check(copied.copied &&
+        copied.files === 3 &&
+        copied.bytes === 111 &&
+        copied.removedOld &&
+        !fs.existsSync(src2) &&
+        measureFolder(t.at('mv', 'dst2')).bytes === 111 &&
+        last?.files === 3, 'copy: files and bytes verified, progress reported, the old folder removed');
+    const src3 = t.at('mv', 'src3');
+    makeTree(src3);
+    const kept = await mover.move(src3, t.at('mv', 'dst3'), { keepOld: true });
+    t.check(kept.copied && !kept.removedOld && measureFolder(src3).files === 3 && kept.notes.join().includes('kept'), '--keep-old copies even on one drive and leaves the old folder');
+    t.section('storage move: failures leave everything as it was');
+    const blocker = t.write(t.at('mv', 'blocker'), 'a file where a folder should be');
+    const badConfig = path.join(blocker, 'config.json');
+    const failing = new StorageMove(badConfig, noBusy, idle);
+    for (const force of [false, true]) {
+        const s = t.at('mv', force ? 'fail-copy' : 'fail-rename');
+        makeTree(s);
+        const target = t.at('mv', force ? 'fail-copy-to' : 'fail-rename-to');
+        await t.throws(() => failing.move(s, target, { forceCopy: force }), /./, 'a config that cannot be written fails the move');
+        t.check(measureFolder(s).files === 3 && !fs.existsSync(target), (force ? 'copy' : 'rename') + ': the old folder is whole and nothing is left in the target');
+    }
+    const existing = t.dir('mv', 'empty-target');
+    const s4 = t.at('mv', 'fail-existing');
+    makeTree(s4);
+    await t.throws(() => failing.move(s4, existing, { forceCopy: true }), /./, 'a failed copy into an existing empty folder');
+    t.check(fs.existsSync(existing) && fs.readdirSync(existing).length === 0, 'the empty folder you gave stays, emptied again');
+    t.section('storage move: checks before anything happens');
+    const a = t.dir('mv', 'chk', 'a');
+    fs.writeFileSync(path.join(a, 'f'), '1');
+    await t.throws(() => new StorageMove(config, noBusy, () => true).move(a, t.at('mv', 'chk', 'b')), 'Sandbox is running', 'refused while a sandbox runs');
+    await t.throws(() => new StorageMove(config, () => 'The background sync is still finishing.', idle).move(a, t.at('mv', 'chk', 'b')), 'background sync', 'refused while the background sync runs');
+    t.equal(moveProblem(a, path.join(a, 'in'))?.message, 'The new folder is inside the old one.', 'the target may not be inside the source');
+    t.equal(moveProblem(path.join(a, 'in'), a)?.message, 'The old folder is inside the new one.', 'the source may not be inside the target');
+    t.equal(moveProblem(a, a)?.message, 'Your data is in that folder already.', 'the same folder is refused');
+    t.check(moveProblem(a, path.parse(a).root)?.message.includes('whole drive') === true, 'a whole drive is refused');
+    const full = t.dir('mv', 'chk', 'full');
+    fs.writeFileSync(path.join(full, 'x'), '1');
+    t.check(moveProblem(a, full)?.message.includes('not empty') === true && moveProblem(a, full, true) === null, 'a target with files is refused, unless only switching');
+    const link = t.at('mv', 'chk', 'link');
+    fs.symlinkSync(t.dir('mv', 'chk', 'real'), link, 'junction');
+    t.check(moveProblem(a, link)?.message.includes('link') === true, 'a link is refused as a target');
+    t.check(moveProblem(a, t.at('mv', 'chk', 'new')) === null, 'a new folder is fine');
+    void root;
+}
+async function privateRoot(t) {
+    t.section('the storage root is created private under the users folder');
+    const users = usersFolder();
+    const calls = [];
+    const spy = (dir) => {
+        calls.push(dir + ':' + fs.readdirSync(dir).length);
+    };
+    const mine = path.join(users, 'alice');
+    fs.rmSync(users, { recursive: true, force: true });
+    ensureStorageRoot(mine, spy);
+    t.check(fs.existsSync(mine) && calls.join() === mine + ':0' && privateFolderOf(mine) === mine, 'a missing root is created (with the users folder as the user) and made private while empty');
+    ensureStorageRoot(mine, spy);
+    t.check(calls.length === 2, 'an existing empty root is made private again; ');
+    fs.writeFileSync(path.join(mine, 'x'), '1');
+    ensureStorageRoot(mine, spy);
+    t.check(calls.length === 2, 'a root that holds data is not touched');
+    const plain = t.at('plain', 'root');
+    ensureStorageRoot(plain, spy);
+    t.check(fs.existsSync(plain) && calls.length === 3 && calls[2] === plain + ':0' && privateFolderOf(plain) === null, 'elsewhere: created and made private while empty');
+    ensureStorageRoot(plain, spy);
+    t.check(calls.length === 3, 'an existing folder elsewhere is never touched (it may hold a big tree)');
+    const noPermissions = t.at('plain2', 'root');
+    ensureStorageRoot(noPermissions, () => {
+        throw new Error('drive without permissions');
+    });
+    t.check(fs.existsSync(noPermissions), 'a drive that cannot be made private is still used');
+    const deep = path.join(users, 'bob', 'sub');
+    ensureStorageRoot(deep, spy);
+    t.check(calls[calls.length - 1] === path.join(users, 'bob') + ':0' && fs.existsSync(deep), 'a deeper root: the user folder is the private one');
+    const failing = () => {
+        throw new Error('no access');
+    };
+    await t.throws(() => ensureStorageRoot(path.join(users, 'carol'), failing), 'Could not make', 'a folder that cannot be made private stops the command');
+    const src = t.at('mvp', 'src');
+    makeTree(src);
+    const seen = [];
+    const config = t.at('mvp', 'config.json');
+    const mover = new StorageMove(config, noBusy, idle, (dir) => seen.push(dir + ':' + fs.readdirSync(dir).length));
+    const target = path.join(users, 'dave');
+    await mover.move(src, target);
+    t.check(seen[0] === target + ':0' && measureFolder(target).files === 3, 'a move into the users folder makes the target private before writing');
+}
+function estimates(t) {
+    t.section('estimate, warnings and the pinned form');
+    const same = estimateMove({ bytes: 50 * GB, files: 400000, partial: false }, true, null);
+    t.check(same.sameVolume && same.seconds <= 10 && same.fits && same.big, 'same drive: seconds, always fits, big when big');
+    const copy = estimateMove({ bytes: 8 * GB, files: 100000, partial: false }, false, 100 * GB);
+    t.check(copy.seconds > 250 && copy.seconds < 350 && copy.fits && copy.big, '8 GB, 100k files: about 5 minutes (80 MB/s plus a cost per file)');
+    const tight = estimateMove({ bytes: 8 * GB, files: 10, partial: false }, false, 8 * GB);
+    t.check(!tight.fits && (moveWarning({ bytes: 8 * GB, files: 10, partial: false }, tight) ?? '').includes('free'), 'not enough room: it does not fit, and the warning says so');
+    const small = estimateMove({ bytes: 10 * 1024 * 1024, files: 20, partial: false }, false, 100 * GB);
+    t.check(!small.big && moveWarning({ bytes: 10, files: 1, partial: false }, small) === null, 'a small move has no warning');
+    t.check(estimateMove({ bytes: 1, files: 1, partial: false }, false, null).fits, 'unknown free space is assumed to be enough');
+    t.check(BIG_BYTES === 5 * GB, 'big starts at 5 GB');
+    t.equal([describeDuration(3), describeDuration(45), describeDuration(180), describeDuration(7200)], ['a few seconds', 'about 50 seconds', 'about 3 minutes', 'about 2 hours'], 'durations are spoken');
+    t.equal(pinValue(sharedDefaultRoot()), DEFAULTS.storage.root, 'the shared default is pinned in its %VARIABLE% form');
+    const old = oldDefaultRoot();
+    t.equal(old ? pinValue(old) : '', '%LOCALAPPDATA%\\AgentSandbox', 'the old default is pinned in its %VARIABLE% form');
+    t.equal(pinValue('D:\\Sandbox\\x'), 'D:\\Sandbox\\x', 'any other folder is pinned as the full path');
+}
+async function offers(t) {
+    t.section('the offer to move');
+    const savedProgramData = process.env.ProgramData;
+    process.env.ProgramData = t.dir('offer', 'programdata');
+    const oldDir = path.join(process.env.LOCALAPPDATA ?? '', 'AgentSandbox');
+    fs.rmSync(oldDir, { recursive: true, force: true });
+    try {
+        const history = new StorageHistory(t.dir('offer', 'user'));
+        const shared = sharedDefaultRoot();
+        t.check(planOffer(shared, history) === null, 'a fresh install: nothing to offer');
+        fs.mkdirSync(oldDir, { recursive: true });
+        fs.writeFileSync(path.join(oldDir, 'x'), '1');
+        const upgraded = planOffer(oldDir, history);
+        t.check(upgraded?.from === oldDir && upgraded.to === shared && upgraded.toIsDefault, 'after an upgrade (pinned to the old folder): offer the shared default');
+        const switched = planOffer(shared, history);
+        t.check(switched?.from === oldDir && switched.to === shared && switched.toIsDefault, 'after switching to an all-users install (empty shared folder): offer to move the old data there');
+        const mine = t.at('offer', 'mine');
+        const named = planOffer(mine, history);
+        t.check(named?.from === oldDir && named.to === mine && !named.toIsDefault, 'a configured folder that is empty while another holds data: offer to move it there');
+        const chosen = t.dir('offer', 'chosen');
+        fs.writeFileSync(path.join(chosen, 'y'), '1');
+        t.check(planOffer(chosen, history) === null, 'a folder with data that was chosen on purpose is never asked about');
+        history.setNotNow();
+        t.check(planOffer(oldDir, history) === null, '"Not now" is not asked again at once');
+        t.check(history.mayAsk(new Date(Date.now() + 15 * 24 * 3600 * 1000)), '... but after two weeks it is');
+        history.setDontAsk();
+        t.check(planOffer(oldDir, history) === null && !history.mayAsk(new Date(Date.now() + 400 * 24 * 3600 * 1000)), '"Don\'t ask again" is final');
+        const fresh = new StorageHistory(t.dir('offer', 'user2'));
+        fs.rmSync(oldDir, { recursive: true, force: true });
+        const earlier = t.dir('offer', 'earlier');
+        fs.writeFileSync(path.join(earlier, 'z'), '1');
+        fresh.remember(earlier);
+        fresh.remember(earlier);
+        t.check(fresh.read().previous.length === 1 && planOffer(shared, fresh)?.from === earlier, 'a folder remembered earlier (downgrade, then upgrade) is offered');
+        t.check(!holdsData(t.at('offer', 'nowhere')) && holdsData(earlier), 'holdsData: missing is no data');
+    }
+    finally {
+        if (savedProgramData === undefined)
+            delete process.env.ProgramData;
+        else
+            process.env.ProgramData = savedProgramData;
+        fs.rmSync(oldDir, { recursive: true, force: true });
+    }
+}
+function pickerHelpers(t) {
+    t.section('path picker: helpers');
+    t.equal(splitInput(''), { dir: '', prefix: '' }, 'nothing typed: This PC');
+    t.equal(splitInput('C:'), { dir: 'C:\\', prefix: '' }, 'a drive letter is its root');
+    t.equal(splitInput('D:\\Sand'), { dir: 'D:\\', prefix: 'Sand' }, 'the last name is the prefix');
+    t.equal(splitInput('D:\\Sandbox\\'), { dir: 'D:\\Sandbox\\', prefix: '' }, 'a trailing backslash names the folder');
+    t.equal([parentOf('D:\\a\\b'), parentOf('D:\\a'), parentOf('D:\\'), parentOf('')], ['D:\\a', 'D:\\', '', ''], 'up one level; above a drive is This PC');
+    const root = t.dir('pick');
+    for (const name of ['alpha', 'alpine', 'beta'])
+        fs.mkdirSync(path.join(root, name));
+    fs.writeFileSync(path.join(root, 'f.txt'), '1');
+    fs.symlinkSync(path.join(root, 'alpha'), path.join(root, 'jlink'), 'junction');
+    const folders = listFolder(root);
+    t.equal(folders.entries.map((e) => e.kind + ':' + e.name), ['dir:alpha', 'dir:alpine', 'dir:beta', 'link:jlink'], 'folders only, sorted, links marked');
+    t.equal(listFolder(root, true).entries.map((e) => e.name), ['alpha', 'alpine', 'beta', 'jlink', 'f.txt'], 'files come last when asked for');
+    const capped = listFolder(root, false, 2);
+    t.check(capped.entries.length === 2 && capped.more === 2, 'the listing is capped and counts the rest');
+    t.check(listFolder(path.join(root, 'nope')).error === 'No such folder', 'a missing folder reports why');
+    t.equal(narrow(folders.entries, 'al').map((e) => e.name), ['alpha', 'alpine'], 'typing narrows by start');
+    t.equal(narrow(folders.entries, '', 'ET').map((e) => e.name), ['beta'], 'the filter matches anywhere, ignoring case');
+    t.equal(completeInput(root + '\\al', folders.entries), root + '\\alp', 'Tab completes the shared start');
+    t.equal(completeInput(root + '\\alph', folders.entries), root + '\\alpha\\', 'a single match gets its backslash');
+    t.equal(completeInput(root + '\\zz', folders.entries), root + '\\zz', 'no match: unchanged');
+    t.equal(completeInput(root + '\\ALPH', folders.entries), root + '\\alpha\\', 'completion ignores case');
+    t.equal([
+        folderNameProblem('ok name'),
+        folderNameProblem(''),
+        folderNameProblem('a:b') !== null,
+        folderNameProblem('con') !== null,
+        folderNameProblem('x.') !== null,
+    ], [null, 'Type a name.', true, true, true], 'folder names are checked');
+}
+async function pickerScreen(t) {
+    t.section('path picker: the screen');
+    const root = t.at('pick');
+    const size = { width: 100, height: 30 };
+    const text = (s) => s.render(size).body.join('\n');
+    const only = (name) => (p) => p.toLowerCase().endsWith('\\' + name) ? true : 'only ' + name;
+    const screen = new PathPickerScreen({ path: ['T'], title: 'Pick', initial: root + '\\', validate: only('new1') });
+    const first = text(screen);
+    t.check(first.includes('alpha') && first.includes('jlink') && !first.includes('f.txt'), 'it opens on the folders of the start path, links shown, files hidden');
+    for (const ch of 'al')
+        await screen.handle(key(ch, ch));
+    const narrowed = text(screen);
+    t.check(narrowed.includes('alpha') && narrowed.includes('alpine') && !narrowed.includes('beta'), 'typing narrows the list live');
+    await screen.handle(key('tab'));
+    await screen.handle(key('h', 'h'));
+    await screen.handle(key('tab'));
+    t.includes(text(screen), root + '\\alpha\\', 'Tab completes the name');
+    const shown = screen.render(size);
+    t.check(shown.keys.some(([k]) => k === 'tab') && shown.keys.some(([k]) => k === 'esc'), 'the key bar lists the keys');
+    const cancelled = await screen.handle(key('escape'));
+    t.check(cancelled !== undefined && cancelled.done === undefined, 'Esc cancels');
+    const second = new PathPickerScreen({ path: ['T'], title: 'Pick', initial: root + '\\', validate: only('new1') });
+    await second.handle(key('down'));
+    await second.handle(key('n', 'n'));
+    for (const ch of 'new1')
+        await second.handle(key(ch, ch));
+    await second.handle(key('return'));
+    t.check(fs.existsSync(path.join(root, 'new1')), 'n asks for a name and creates the folder, then opens it');
+    const picked = await second.handle(key('s', 's'));
+    t.check(picked?.done === path.join(root, 'new1'), 's picks the folder shown');
+    const nope = new PathPickerScreen({ path: ['T'], title: 'Pick', initial: root + '\\', validate: only('zzz') });
+    await nope.handle(key('down'));
+    const refused = await nope.handle(key('s', 's'));
+    t.check(refused === undefined && text(nope).includes('only zzz'), 'a path the check refuses is not picked and says why');
+    // Move onto the link row: names sort alpha, alpine, beta, jlink, new1 -> jlink is the fifth entry after "..".
+    const fourth = new PathPickerScreen({ path: ['T'], title: 'Pick', initial: root + '\\' });
+    await fourth.handle(key('down'));
+    for (let i = 0; i < 4; i++)
+        await fourth.handle(key('down'));
+    await fourth.handle(key('return'));
+    t.check((fourth.render(size).notice ?? '').includes('link'), 'a link is not opened: a notice says so');
+    t.check(!text(fourth).includes('Nothing here'), 'and the folder stays as it was');
+}
+export const storageSuite = {
+    name: 'storage',
+    title: 'data folder: pin migration, move engine, offer, path picker',
+    run: async (t) => {
+        await pinMigration(t);
+        await moveEngine(t);
+        await privateRoot(t);
+        estimates(t);
+        await offers(t);
+        pickerHelpers(t);
+        await pickerScreen(t);
+    },
+};