windows-development-sandbox 1.0.5 → 1.4.0

package/dist/host/terminal.js

@@ -2,8 +2,9 @@
 // logon.cmd can open it the moment the sandbox logs in (no PowerShell window first).
 import fs from 'node:fs';
 import path from 'node:path';
-import { githubAsset, installArchive } from '../shared/download.js';
+import { download, extractArchive, fetchJson, githubAsset, installArchive, moveIntoPlace, stagingFolder } from '../shared/download.js';
 import { safeRemove } from '../shared/safe-remove.js';
+import { assertTestWritable } from './test-guard.js';
 import { z } from 'zod';
 import { assertNoLinks, errMsg, fileExists, parseJsonc, writeJson } from '../core/util.js';
 export const terminalDir = (dataPath) => path.join(dataPath, 'tools', 'terminal');
@@ -55,6 +56,7 @@ export const withPwshProfile = (settings, visible) => {
  */
 export const syncPwshProfile = (dataPath, allowed) => {
     const file = path.join(terminalDir(dataPath), 'settings', 'settings.json');
+    assertTestWritable(file);
     assertNoLinks(dataPath, file);
     if (!fileExists(file) || fs.statSync(file).size > MAX_SETTINGS_BYTES)
         return;
@@ -86,9 +88,54 @@ export const ensureTerminal = async (dataPath, refresh, options = {}) => {
     }
     return result;
 };
+// ---- conpty.dll ------------------------------------------------------------------------------------------------------
+/** Where the sandbox finds conpty.dll + OpenConsole.exe (guest/ptyhost.ts points ptyhost at it). */
+export const conptyDir = (dataPath) => path.join(dataPath, 'tools', 'conpty');
+const NUGET_CONPTY = 'https://api.nuget.org/v3-flatcontainer/microsoft.windows.console.conpty/';
+const NugetVersions = z.object({ versions: z.array(z.string()) });
+const NugetLeaf = z.object({ catalogEntry: z.string().url() });
+const NugetCatalog = z.object({ packageHash: z.string(), packageHashAlgorithm: z.literal('SHA512') });
+/**
+ * Microsoft's newer pseudo console (the Microsoft.Windows.Console.ConPTY package: conpty.dll and OpenConsole.exe, the
+ * same one Windows Terminal and VS Code use), downloaded once and verified against the SHA-512 NuGet publishes. Agent
+ * sessions use it instead of the one built into Windows, which re-renders the screen and garbles it after resizes.
+ */
+export const ensureConpty = async (dataPath, refresh) => {
+    const dir = conptyDir(dataPath);
+    assertTestWritable(dir);
+    assertNoLinks(dataPath, dir);
+    if (fileExists(path.join(dir, 'conpty.dll')) && fileExists(path.join(dir, 'OpenConsole.exe')) && !refresh)
+        return 'cached';
+    const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
+    const work = stagingFolder(dir);
+    try {
+        const version = NugetVersions.parse(await fetchJson(NUGET_CONPTY + 'index.json')).versions.filter((v) => !v.includes('-')).pop();
+        if (!version)
+            throw new Error('no release found');
+        const leaf = NugetLeaf.parse(await fetchJson('https://api.nuget.org/v3/registration5-gz-semver2/microsoft.windows.console.conpty/' + version + '.json'));
+        const sha512 = Buffer.from(NugetCatalog.parse(await fetchJson(leaf.catalogEntry)).packageHash, 'base64').toString('hex');
+        const pkg = path.join(work, 'conpty.nupkg');
+        await download(NUGET_CONPTY + version + '/microsoft.windows.console.conpty.' + version + '.nupkg', pkg, { sha512 });
+        const files = { 'conpty.dll': 'runtimes/win-' + arch + '/native/conpty.dll', 'OpenConsole.exe': 'build/native/runtimes/' + arch + '/OpenConsole.exe' };
+        await extractArchive(pkg, path.join(work, 'x'), Object.values(files));
+        fs.mkdirSync(path.join(work, 'out'));
+        for (const [name, member] of Object.entries(files))
+            fs.copyFileSync(path.join(work, 'x', ...member.split('/')), path.join(work, 'out', name));
+        fs.writeFileSync(path.join(work, 'out', 'VERSION'), version);
+        moveIntoPlace(path.join(work, 'out'), dir);
+        return 'downloaded ' + version;
+    }
+    catch (e) {
+        return 'not downloaded, sessions use Windows\' own pseudo console (' + errMsg(e) + ')';
+    }
+    finally {
+        safeRemove(work, path.dirname(work));
+    }
+};
 const installTerminal = async (dataPath, refresh) => {
     const exe = terminalExe(dataPath);
     const dir = terminalDir(dataPath);
+    assertTestWritable(dir);
     const settings = path.join(dir, 'settings');
     // installArchive replaces tools\terminal: the portable settings folder waits here meanwhile (and goes back also when
     // the download fails). One still parked from an interrupted earlier run is the one to keep.

package/dist/host/test-guard.d.ts

@@ -0,0 +1,6 @@
+import { selfTestRunning } from '../shared/test-guard.js';
+export { selfTestRunning };
+/** Refuses an action that reaches outside the test's own temp folder (a no-op outside the self-test). */
+export declare const refuseInSelfTest: (what: string) => void;
+/** A write, copy or delete on the host: during the self-test only the temp folder is allowed. */
+export declare const assertTestWritable: (target: string) => void;

package/dist/host/test-guard.js

@@ -0,0 +1,15 @@
+// Host side of the self-test guard (see shared/test-guard.ts): outward actions refuse, with a message the user can read.
+import { testWriteRefusal, selfTestRunning } from '../shared/test-guard.js';
+import { fail } from '../core/util.js';
+export { selfTestRunning };
+/** Refuses an action that reaches outside the test's own temp folder (a no-op outside the self-test). */
+export const refuseInSelfTest = (what) => {
+    if (selfTestRunning())
+        fail('The self-test does not ' + what + '.', 'It only works in temp folders, so it can never change this PC.');
+};
+/** A write, copy or delete on the host: during the self-test only the temp folder is allowed. */
+export const assertTestWritable = (target) => {
+    const refusal = testWriteRefusal(target);
+    if (refusal)
+        fail(refusal);
+};

package/dist/host/window.js

@@ -1,7 +1,9 @@
 // Headless mode: Windows Sandbox always opens its client window, so we hide it (ShowWindow SW_HIDE) as soon as it
 // appears. The VM and the logged-in session keep running; `sbx-show` brings the window back.
 import path from 'node:path';
-import { isWin, runPowerShell, runPowerShellAsync, tryReadJson, writeJson } from '../core/util.js';
+import { writeJsonAtomic } from '../shared/rundir.js';
+import { refuseInSelfTest } from './test-guard.js';
+import { isWin, runPowerShell, runPowerShellAsync, tryReadJson } from '../core/util.js';
 const PRELUDE = `
 $ErrorActionPreference = 'Stop'
 Add-Type -Namespace AgentSandbox -Name Win -MemberDefinition @'
@@ -34,6 +36,7 @@ function Get-SandboxWindows([bool]$visibleOnly) {
 const stateFile = (storageRoot) => path.join(storageRoot, 'run', 'hidden-windows.json');
 /** Waits for the sandbox window and hides it; keeps watching briefly in case Windows re-shows it while connecting. */
 export const hideSandboxWindow = async (storageRoot, waitSeconds = 180) => {
+    refuseInSelfTest('hide windows');
     if (!isWin)
         return false;
     const script = PRELUDE + `
@@ -48,11 +51,12 @@ while ((Get-Date) -lt $deadline) {
 ConvertTo-Json -Compress @($hidden)`;
     const stdout = await runPowerShellAsync(script);
     const handles = JSON.parse(stdout.trim() || '[]').filter((h) => Number.isSafeInteger(h));
-    writeJson(stateFile(storageRoot), { handles });
+    writeJsonAtomic(stateFile(storageRoot), { handles });
     return handles.length > 0;
 };
 /** Shows the sandbox window again (the ones we hid, or any hidden Windows Sandbox window). */
 export const showSandboxWindow = (storageRoot) => {
+    refuseInSelfTest('show windows');
     if (!isWin)
         return false;
     // Only integers go into the script, whatever the file contains.
@@ -63,6 +67,6 @@ if (-not $handles) { $handles = Get-SandboxWindows $false }
 foreach ($h in $handles) { [void][AgentSandbox.Win]::ShowWindow([IntPtr]$h, 5); [void][AgentSandbox.Win]::ShowWindow([IntPtr]$h, 9); [void][AgentSandbox.Win]::SetForegroundWindow([IntPtr]$h) }
 @($handles).Count`;
     const { stdout } = runPowerShell(script, true);
-    writeJson(stateFile(storageRoot), { handles: [] });
+    writeJsonAtomic(stateFile(storageRoot), { handles: [] });
     return Number(stdout.trim()) > 0;
 };

package/dist/host/workspace-view/index.d.ts

@@ -0,0 +1,20 @@
+import type { Config } from '../../core/types.js';
+import { type ViewOptions } from './view.js';
+export { IgnoreRules } from './rules.js';
+export { WorkspaceView, type SyncStats, type ViewOptions } from './view.js';
+/** The project's .git as the sandbox sees it: next to the workspace (C:\Workspace\app -> C:\Workspace\app.git). */
+export declare const guestGitDir: (guestWorkspace: string) => string;
+export interface ViewPlan {
+    options: ViewOptions; /** The project's real .git folder, mapped at options.guestGitDir (null: none). */
+    hostGit: string | null;
+    note?: string;
+}
+/**
+ * The view for a launch, or null when the folder itself is mapped: workspaceFilter off, or a git worktree (its .git is
+ * a file pointing elsewhere, which a view cannot follow; then the folder is mapped as before and a note says so).
+ */
+export declare const planView: (config: Config, storageRoot: string, workspaceHost: string) => ViewPlan | null;
+/** Why a filtered launch maps the folder itself after all (for the launch notes). */
+export declare const viewSkipped: (config: Config, workspaceHost: string) => string | null;
+export declare const saveActiveViews: (storageRoot: string, dataPath: string, views: ViewOptions[]) => void;
+export declare const readActiveViews: (storageRoot: string, dataPath: string) => ViewOptions[];

package/dist/host/workspace-view/index.js

@@ -0,0 +1,53 @@
+// workspaceFilter in practice: which view a launch maps instead of the project, the project's .git mapped beside it,
+// and the host-only list of views the background watcher keeps in step while the sandbox runs.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { readValid, writeJsonAtomic } from '../../shared/rundir.js';
+import { WorkspaceView } from './view.js';
+export { IgnoreRules } from './rules.js';
+export { WorkspaceView } from './view.js';
+/** The project's .git as the sandbox sees it: next to the workspace (C:\Workspace\app -> C:\Workspace\app.git). */
+export const guestGitDir = (guestWorkspace) => guestWorkspace.replace(/[\\/]+$/, '') + '.git';
+/**
+ * The view for a launch, or null when the folder itself is mapped: workspaceFilter off, or a git worktree (its .git is
+ * a file pointing elsewhere, which a view cannot follow; then the folder is mapped as before and a note says so).
+ */
+export const planView = (config, storageRoot, workspaceHost) => {
+    if (!config.workspaceFilter.enabled)
+        return null;
+    const git = path.join(workspaceHost, '.git');
+    let gitIsDir = false;
+    try {
+        const s = fs.lstatSync(git);
+        if (s.isFile())
+            return null;
+        gitIsDir = s.isDirectory() && !s.isSymbolicLink();
+    }
+    catch { /* no .git */ }
+    // git access "none": the agent gets no .git at all.
+    const hostGit = gitIsDir && config.provisioning.git.enabled && config.provisioning.git.access !== 'none' ? git : null;
+    return {
+        options: { ...WorkspaceView.pathsFor(storageRoot, workspaceHost), exclude: config.workspaceFilter.exclude, include: config.workspaceFilter.include, guestGitDir: hostGit ? guestGitDir(config.guestWorkspace) : null },
+        hostGit,
+    };
+};
+/** Why a filtered launch maps the folder itself after all (for the launch notes). */
+export const viewSkipped = (config, workspaceHost) => {
+    if (!config.workspaceFilter.enabled)
+        return null;
+    try {
+        if (fs.lstatSync(path.join(workspaceHost, '.git')).isFile())
+            return 'workspaceFilter: ' + workspaceHost + ' is a git worktree (.git is a file); the folder is mapped as it is, git-ignored files included.';
+    }
+    catch { /* fine */ }
+    return null;
+};
+// ---- the views the watcher keeps in step (host-only, next to the sync state) ------------------------------------------
+const ActiveView = z.object({
+    host: z.string().max(1024), view: z.string().max(1024), state: z.string().max(1024),
+    exclude: z.array(z.string().max(500)).max(500), include: z.array(z.string().max(500)).max(500), guestGitDir: z.string().max(1024).nullable(),
+});
+const activeFile = (storageRoot, dataPath) => path.join(storageRoot, 'sync', path.basename(dataPath) + '-views.json');
+export const saveActiveViews = (storageRoot, dataPath, views) => writeJsonAtomic(activeFile(storageRoot, dataPath), views.map((v) => ({ host: v.host, view: v.view, state: v.state, exclude: v.exclude ?? [], include: v.include ?? [], guestGitDir: v.guestGitDir ?? null })));
+export const readActiveViews = (storageRoot, dataPath) => readValid(z.array(ActiveView).max(64), activeFile(storageRoot, dataPath)) ?? [];

package/dist/host/workspace-view/rules.d.ts

@@ -0,0 +1,26 @@
+export declare class IgnoreRules {
+    private readonly root;
+    private readonly include;
+    /** One matcher per folder that has a .gitignore (null = the folder has none), by its path relative to the root. */
+    private readonly perFolder;
+    private readonly extra;
+    private readonly forced;
+    /** `root`: the project folder on this PC (its .gitignore files are the rules); `exclude` / `include`: your patterns. */
+    constructor(root: string, exclude?: string[], include?: string[]);
+    /** One of your include patterns lets this path in, whatever .gitignore says (even inside an ignored folder). */
+    isForced(rel: string): boolean;
+    /** Could one of your include patterns match something inside this ignored folder (so a walk must look inside)? */
+    mayIncludeInside(dir: string): boolean;
+    /** Forget the .gitignore files read so far (one of them changed). */
+    reset(): void;
+    private matcher;
+    /**
+     * Is this one entry ignored, given that its parent folder is not? `rel` uses / and has no leading slash. Your include
+     * patterns win over everything, your exclude patterns over .gitignore.
+     */
+    private ignoredHere;
+    /** Is `rel` (a file, or a folder with isDir) ignored, counting its folders: inside an ignored folder is ignored. */
+    isIgnored(rel: string, isDir?: boolean): boolean;
+    /** For a walk that already checked the parent folder: is this child ignored? */
+    isIgnoredChild(rel: string, isDir: boolean): boolean;
+}

package/dist/host/workspace-view/rules.js

@@ -0,0 +1,93 @@
+// Which files of a project git ignores, read the way git reads them: the .gitignore in every folder (deeper files win,
+// `!pattern` lets a file back in), .git/info/exclude, and nothing inside an ignored folder ever comes back. Plus your
+// own extra patterns (workspaceFilter.exclude) and exceptions (workspaceFilter.include). Bounded reads: a .gitignore
+// over 256 KB is treated as empty.
+import fs from 'node:fs';
+import path from 'node:path';
+import ignore from 'ignore';
+const MAX_RULES_BYTES = 256 * 1024;
+const readRules = (file) => {
+    try {
+        const stat = fs.lstatSync(file);
+        return stat.isFile() && stat.size <= MAX_RULES_BYTES ? fs.readFileSync(file, 'utf8') : '';
+    }
+    catch {
+        return '';
+    }
+};
+export class IgnoreRules {
+    root;
+    include;
+    /** One matcher per folder that has a .gitignore (null = the folder has none), by its path relative to the root. */
+    perFolder = new Map();
+    extra;
+    forced;
+    /** `root`: the project folder on this PC (its .gitignore files are the rules); `exclude` / `include`: your patterns. */
+    constructor(root, exclude = [], include = []) {
+        this.root = root;
+        this.include = include;
+        this.extra = ignore().add(exclude);
+        this.forced = ignore().add(include);
+    }
+    /** One of your include patterns lets this path in, whatever .gitignore says (even inside an ignored folder). */
+    isForced(rel) { return this.include.length > 0 && this.forced.ignores(rel); }
+    /** Could one of your include patterns match something inside this ignored folder (so a walk must look inside)? */
+    mayIncludeInside(dir) {
+        return this.include.some((p) => { const clean = p.replace(/^\//, ''); return clean.startsWith('**') || clean.startsWith(dir + '/'); });
+    }
+    /** Forget the .gitignore files read so far (one of them changed). */
+    reset() { this.perFolder.clear(); }
+    matcher(folder) {
+        if (this.perFolder.has(folder))
+            return this.perFolder.get(folder);
+        const dir = path.join(this.root, ...folder.split('/').filter(Boolean));
+        let text = readRules(path.join(dir, '.gitignore'));
+        if (folder === '')
+            text += '\n' + readRules(path.join(this.root, '.git', 'info', 'exclude'));
+        const matcher = text.trim() ? ignore().add(text) : null;
+        this.perFolder.set(folder, matcher);
+        return matcher;
+    }
+    /**
+     * Is this one entry ignored, given that its parent folder is not? `rel` uses / and has no leading slash. Your include
+     * patterns win over everything, your exclude patterns over .gitignore.
+     */
+    ignoredHere(rel, isDir) {
+        const probe = isDir ? rel + '/' : rel;
+        if (this.forced.ignores(probe))
+            return false;
+        if (this.extra.ignores(probe))
+            return true;
+        const parts = rel.split('/');
+        let ignored = false;
+        for (let i = 0; i < parts.length; i++) {
+            const folder = parts.slice(0, i).join('/');
+            const m = this.matcher(folder);
+            if (!m)
+                continue;
+            const below = parts.slice(i).join('/') + (isDir ? '/' : '');
+            const result = m.test(below);
+            if (result.ignored)
+                ignored = true;
+            else if (result.unignored)
+                ignored = false;
+        }
+        return ignored;
+    }
+    /** Is `rel` (a file, or a folder with isDir) ignored, counting its folders: inside an ignored folder is ignored. */
+    isIgnored(rel, isDir = false) {
+        const parts = rel.split('/').filter(Boolean);
+        if (parts[0] === '.git')
+            return true;
+        if (!isDir && this.isForced(parts.join('/')))
+            return false;
+        for (let i = 1; i < parts.length; i++)
+            if (this.ignoredHere(parts.slice(0, i).join('/'), true))
+                return true;
+        return this.ignoredHere(parts.join('/'), isDir);
+    }
+    /** For a walk that already checked the parent folder: is this child ignored? */
+    isIgnoredChild(rel, isDir) {
+        return rel.split('/')[0] === '.git' || this.ignoredHere(rel, isDir);
+    }
+}

package/dist/host/workspace-view/view.d.ts

@@ -0,0 +1,50 @@
+import { IgnoreRules } from './rules.js';
+export interface ViewPaths {
+    /** The project on this PC. */
+    host: string;
+    /** Its filtered copy (mapped into the sandbox as the workspace). */
+    view: string;
+    /** Host-only: what both sides looked like after the last sync. */
+    state: string;
+}
+export interface ViewOptions extends ViewPaths {
+    exclude?: string[];
+    include?: string[];
+    /** The project's .git as the sandbox sees it (written into the view's .git file); null = the project has no .git. */
+    guestGitDir?: string | null;
+    note?: (message: string) => void;
+}
+export interface SyncStats {
+    toView: number;
+    toHost: number;
+    deleted: number;
+    conflicts: number;
+    skipped: number;
+}
+export declare class WorkspaceView {
+    private readonly o;
+    readonly rules: IgnoreRules;
+    private seen;
+    constructor(o: ViewOptions);
+    /** Where a project's view and its sync state live: <storage>\views\<id> and <storage>\views\<id>.json. */
+    static pathsFor(storageRoot: string, host: string): ViewPaths;
+    private abs;
+    /** Creates the view (with its .git file) and brings it fully in step with the project. */
+    prepare(): SyncStats;
+    /** Every file not ignored, on one side (bounded, links skipped, ignored folders not entered). */
+    private walk;
+    /** A full pass over both sides and everything synced before. */
+    syncAll(): SyncStats;
+    /** Paths that changed (from file events): files, or folders whose contents are walked. */
+    syncChanged(rels: Iterable<string>): SyncStats;
+    private syncPaths;
+    private syncOne;
+    /** Copies (keeping the file time) or deletes on the other side. */
+    private carry;
+    private pruneEmpty;
+    /**
+     * Keeps both sides in step while it runs: file events from both, batched every 300 ms, plus a full pass every
+     * `fullEveryMs` to catch anything an event missed. Returns a function that stops it.
+     */
+    watch(fullEveryMs?: number): () => void;
+}

package/dist/host/workspace-view/view.js

@@ -0,0 +1,281 @@
+// A project as the sandbox sees it with workspaceFilter on: a copy of the project on this PC (in storage, outside the
+// project) that holds only what git does not ignore, kept in step with the project both ways. The sandbox maps the view
+// instead of the project, and the project's real .git separately (a "gitdir:" file in the view points at it), so git
+// works as usual. What the sandbox creates that is ignored (node_modules, build output) stays in the view; what is
+// ignored in your project (.env, your node_modules) never enters the sandbox.
+//
+// Each file is compared on both sides with what both looked like after the last sync (size + time): a change on one
+// side is copied to the other, a deletion is repeated, and a file changed on both sides keeps yours in the project and
+// the sandbox's next to it as <name>.sandbox-conflict-<time><ext>. Copies keep the file time, so an unchanged file is
+// never copied again. Links are never followed or created on either side.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { z } from 'zod';
+import { readValid, writeJsonAtomic } from '../../shared/rundir.js';
+import { IgnoreRules } from './rules.js';
+const Manifest = z.record(z.string().max(1024), z.tuple([z.number(), z.number(), z.number(), z.number()]));
+/** Most entries one walk looks at: a sandbox can create files faster than they are worth syncing. */
+const MAX_ENTRIES = 300000;
+const stamp = (file) => {
+    try {
+        const s = fs.lstatSync(file);
+        return s.isFile() ? [s.size, Math.round(s.mtimeMs)] : [-1, -1];
+    }
+    catch {
+        return [-1, -1];
+    }
+};
+const sameContent = (a, b) => {
+    const hash = (f) => crypto.createHash('sha256').update(fs.readFileSync(f)).digest('hex');
+    try {
+        return fs.statSync(a).size === fs.statSync(b).size && hash(a) === hash(b);
+    }
+    catch {
+        return false;
+    }
+};
+/** A path from an event or the manifest: relative, forward slashes, no way out of the root. */
+const safeRel = (rel) => {
+    const clean = rel.replace(/\\/g, '/').replace(/^\/+/, '');
+    if (!clean || clean.length > 1000 || clean.split('/').some((p) => p === '..' || p === '' || p.includes(':')))
+        return null;
+    return clean;
+};
+export class WorkspaceView {
+    o;
+    rules;
+    seen;
+    constructor(o) {
+        this.o = o;
+        this.rules = new IgnoreRules(o.host, o.exclude, o.include);
+        this.seen = readValid(Manifest, o.state) ?? {};
+    }
+    /** Where a project's view and its sync state live: <storage>\views\<id> and <storage>\views\<id>.json. */
+    static pathsFor(storageRoot, host) {
+        const id = path.basename(host).replace(/[^A-Za-z0-9._-]/g, '_') + '-' + crypto.createHash('sha256').update(path.resolve(host).toLowerCase()).digest('hex').slice(0, 8);
+        const view = path.join(storageRoot, 'views', id);
+        return { host, view, state: view + '.json' };
+    }
+    abs(root, rel) { return path.join(root, ...rel.split('/')); }
+    /** Creates the view (with its .git file) and brings it fully in step with the project. */
+    prepare() {
+        fs.mkdirSync(this.o.view, { recursive: true });
+        const gitFile = path.join(this.o.view, '.git');
+        if (this.o.guestGitDir)
+            fs.writeFileSync(gitFile, 'gitdir: ' + this.o.guestGitDir.replace(/\\/g, '/') + '\n');
+        else
+            fs.rmSync(gitFile, { force: true });
+        return this.syncAll();
+    }
+    /** Every file not ignored, on one side (bounded, links skipped, ignored folders not entered). */
+    walk(root, under = '') {
+        const files = [];
+        // An ignored folder is only entered when one of your include patterns could match inside it; then only files those
+        // patterns let in are taken.
+        const queue = [{ rel: under, ignored: under !== '' && this.rules.isIgnored(under, true) }];
+        let count = 0;
+        while (queue.length) {
+            const { rel, ignored } = queue.shift();
+            let entries;
+            try {
+                entries = fs.readdirSync(this.abs(root, rel), { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const e of entries) {
+                if (++count > MAX_ENTRIES) {
+                    this.o.note?.('stopped listing ' + root + ' after ' + MAX_ENTRIES + ' entries');
+                    return files;
+                }
+                const child = rel ? rel + '/' + e.name : e.name;
+                if (e.isSymbolicLink() || child === '.git')
+                    continue;
+                if (e.isDirectory()) {
+                    const childIgnored = ignored || this.rules.isIgnoredChild(child, true);
+                    if (!childIgnored || this.rules.mayIncludeInside(child))
+                        queue.push({ rel: child, ignored: childIgnored });
+                }
+                else if (e.isFile() && ((!ignored && !this.rules.isIgnoredChild(child, false)) || this.rules.isForced(child)))
+                    files.push(child);
+            }
+        }
+        return files;
+    }
+    /** A full pass over both sides and everything synced before. */
+    syncAll() {
+        this.rules.reset();
+        const all = new Set([...this.walk(this.o.host), ...this.walk(this.o.view), ...Object.keys(this.seen)]);
+        return this.syncPaths(all);
+    }
+    /** Paths that changed (from file events): files, or folders whose contents are walked. */
+    syncChanged(rels) {
+        const files = new Set();
+        for (const raw of rels) {
+            const rel = safeRel(raw);
+            if (!rel)
+                continue;
+            if (rel.endsWith('.gitignore')) {
+                this.rules.reset();
+                return this.syncAll();
+            }
+            const isDir = [this.o.host, this.o.view].some((root) => { try {
+                return fs.lstatSync(this.abs(root, rel)).isDirectory();
+            }
+            catch {
+                return false;
+            } });
+            if (isDir) {
+                if (this.rules.isIgnored(rel, true) && !this.rules.mayIncludeInside(rel))
+                    continue;
+                for (const f of [...this.walk(this.o.host, rel), ...this.walk(this.o.view, rel)])
+                    files.add(f);
+                for (const k of Object.keys(this.seen))
+                    if (k.startsWith(rel + '/'))
+                        files.add(k);
+            }
+            else
+                files.add(rel);
+        }
+        return this.syncPaths(files);
+    }
+    syncPaths(rels) {
+        const stats = { toView: 0, toHost: 0, deleted: 0, conflicts: 0, skipped: 0 };
+        for (const rel of rels) {
+            if (this.rules.isIgnored(rel)) {
+                delete this.seen[rel];
+                continue;
+            }
+            try {
+                this.syncOne(rel, stats);
+            }
+            catch (e) {
+                stats.skipped++;
+                this.o.note?.('could not sync ' + rel + ': ' + (e instanceof Error ? e.message : String(e)));
+            }
+        }
+        writeJsonAtomic(this.o.state, this.seen);
+        return stats;
+    }
+    syncOne(rel, stats) {
+        const hostFile = this.abs(this.o.host, rel);
+        const viewFile = this.abs(this.o.view, rel);
+        const [hs, hm] = stamp(hostFile);
+        const [vs, vm] = stamp(viewFile);
+        const before = this.seen[rel];
+        const record = () => { const h = stamp(hostFile); const v = stamp(viewFile); if (h[0] < 0 && v[0] < 0)
+            delete this.seen[rel];
+        else
+            this.seen[rel] = [h[0], h[1], v[0], v[1]]; };
+        if (hs < 0 && vs < 0) {
+            delete this.seen[rel];
+            return;
+        }
+        const hostChanged = !before || before[0] !== hs || before[1] !== hm;
+        const viewChanged = !before || before[2] !== vs || before[3] !== vm;
+        if (!hostChanged && !viewChanged)
+            return;
+        if (hostChanged && !viewChanged) {
+            this.carry(hostFile, viewFile, hs < 0, stats, 'toView');
+            record();
+            return;
+        }
+        if (viewChanged && !hostChanged) {
+            this.carry(viewFile, hostFile, vs < 0, stats, 'toHost');
+            record();
+            return;
+        }
+        // Changed on both sides (or never synced): the same content is no conflict.
+        if (hs >= 0 && vs >= 0 && sameContent(hostFile, viewFile)) {
+            record();
+            return;
+        }
+        if (hs < 0) {
+            this.carry(viewFile, hostFile, false, stats, 'toHost');
+            record();
+            return;
+        }
+        if (vs < 0) {
+            this.carry(hostFile, viewFile, false, stats, 'toView');
+            record();
+            return;
+        }
+        // Yours stays in the project; the sandbox's version is kept next to it, and the view gets yours.
+        const ext = path.extname(hostFile);
+        const conflict = hostFile.slice(0, hostFile.length - ext.length) + '.sandbox-conflict-' + new Date().toISOString().replace(/\D/g, '').slice(0, 14) + ext;
+        fs.copyFileSync(viewFile, conflict);
+        this.carry(hostFile, viewFile, false, stats, 'toView');
+        stats.conflicts++;
+        this.o.note?.('both sides changed ' + rel + ': kept yours, the sandbox\'s version is ' + path.basename(conflict));
+        record();
+    }
+    /** Copies (keeping the file time) or deletes on the other side. */
+    carry(from, to, deleted, stats, way) {
+        if (deleted) {
+            if (stamp(to)[0] < 0)
+                return;
+            fs.rmSync(to, { force: true });
+            this.pruneEmpty(path.dirname(to), way === 'toView' ? this.o.view : this.o.host);
+            stats.deleted++;
+            return;
+        }
+        // Never write through a link that is already there.
+        try {
+            if (fs.lstatSync(to).isSymbolicLink())
+                throw new Error('a link is in the way');
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        fs.mkdirSync(path.dirname(to), { recursive: true });
+        fs.copyFileSync(from, to);
+        const t = fs.statSync(from).mtime;
+        fs.utimesSync(to, t, t);
+        stats[way]++;
+    }
+    pruneEmpty(dir, root) {
+        for (let d = dir; d.length > root.length && d.startsWith(root); d = path.dirname(d)) {
+            try {
+                if (fs.readdirSync(d).length)
+                    return;
+                fs.rmdirSync(d);
+            }
+            catch {
+                return;
+            }
+        }
+    }
+    /**
+     * Keeps both sides in step while it runs: file events from both, batched every 300 ms, plus a full pass every
+     * `fullEveryMs` to catch anything an event missed. Returns a function that stops it.
+     */
+    watch(fullEveryMs = 60000) {
+        const pending = new Set();
+        let timer;
+        const flush = () => {
+            timer = undefined;
+            const batch = [...pending];
+            pending.clear();
+            const s = this.syncChanged(batch);
+            if (s.toHost || s.toView || s.deleted || s.conflicts)
+                this.o.note?.('synced: ' + s.toView + ' in, ' + s.toHost + ' out, ' + s.deleted + ' deleted, ' + s.conflicts + ' conflicts');
+        };
+        const onEvent = (_event, file) => {
+            if (!file)
+                return;
+            pending.add(String(file));
+            timer ??= setTimeout(flush, 300);
+        };
+        const watchers = [this.o.host, this.o.view].map((dir) => fs.watch(dir, { recursive: true }, onEvent));
+        const full = setInterval(() => { try {
+            this.syncAll();
+        }
+        catch (e) {
+            this.o.note?.('full sync failed: ' + (e instanceof Error ? e.message : String(e)));
+        } }, fullEveryMs);
+        return () => { watchers.forEach((w) => w.close()); clearInterval(full); clearTimeout(timer); if (pending.size)
+            flush(); };
+    }
+}