windows-development-sandbox 1.1.0 → 1.4.0

package/dist/host/stops.js

@@ -0,0 +1,126 @@
+// Why the last sandbox stopped, when nobody stopped it. The background watcher writes a host-only "life" record (when
+// the sandbox started, when it was last seen running, how it ended) and keeps this PC awake while it runs
+// (sandbox.keepAwake). When the PC restarts, sleeps or crashes, the watcher stops too and the record has no end: the
+// next launch reads Windows' System log from that moment on and says what happened, and what keeps it from happening.
+import { spawn, spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { z } from 'zod';
+import { SYSTEM } from '../shared/system.js';
+import { readValid, writeJsonAtomic } from '../shared/rundir.js';
+import { isWin } from '../core/util.js';
+import { refuseInSelfTest } from './test-guard.js';
+const Iso = z.string().max(40);
+const Life = z.object({
+    started: Iso, lastSeen: Iso, keepAwake: z.boolean(),
+    ended: z.object({ at: Iso, cause: z.object({ kind: z.enum(['updates', 'restart', 'crash', 'sleep', 'memory', 'sandboxCrash']), at: Iso, text: z.string().max(400) }).nullable() }).optional(),
+    reported: z.boolean().optional(),
+});
+const lifeFile = (storageRoot, dataPath) => path.join(storageRoot, 'sync', path.basename(dataPath) + '-life.json');
+export const readLife = (storageRoot, dataPath) => readValid(Life, lifeFile(storageRoot, dataPath));
+const writeLife = (storageRoot, dataPath, life) => writeJsonAtomic(lifeFile(storageRoot, dataPath), life);
+/** At launch: a fresh record (the previous one has been reported by then). */
+export const startLife = (storageRoot, dataPath, keepAwake, now = new Date()) => writeLife(storageRoot, dataPath, { started: now.toISOString(), lastSeen: now.toISOString(), keepAwake });
+/** Every minute while the sandbox runs. */
+export const beatLife = (storageRoot, dataPath, now = new Date()) => {
+    const life = readLife(storageRoot, dataPath);
+    if (life && !life.ended)
+        writeLife(storageRoot, dataPath, { ...life, lastSeen: now.toISOString() });
+};
+/** The watcher saw the sandbox close while this PC kept running: closed by you (no cause), or by sleep / low memory. */
+export const endLife = (storageRoot, dataPath, cause, now = new Date()) => {
+    const life = readLife(storageRoot, dataPath);
+    if (life && !life.ended)
+        writeLife(storageRoot, dataPath, { ...life, ended: { at: now.toISOString(), cause } });
+};
+const StopEvents = z.array(z.object({ at: Iso, id: z.number().int(), provider: z.string().max(200), process: z.string().max(400).nullable().transform((p) => p ?? '') })).max(100);
+const UPDATERS = /^(trustedinstaller|mousocoreworker|musnotification(ux)?|usoclient|wuauclt|tiworker|updateorchestrator)\.exe$/i;
+/**
+ * The first event that ends a running sandbox (pure): Windows inside the sandbox crashing (Hyper-V 18590; `process`
+ * holds its message with the stop code), a restart or shutdown, a crash or power loss, sleep, low memory. Switching
+ * user does not end it (seen on 13 Oct 2026: the sandbox ran on after a switch).
+ */
+export const explainStop = (events) => {
+    const causes = events.flatMap((e) => {
+        const p = e.provider.toLowerCase();
+        if (e.id === 1074 && p.includes('user32')) {
+            const exe = e.process.split(/[\\/]/).pop()?.replace(/\s*\(.*$/, '') ?? '';
+            return UPDATERS.test(exe)
+                ? [{ kind: 'updates', at: e.at, text: 'Windows restarted this PC to install updates' }]
+                : [{ kind: 'restart', at: e.at, text: 'this PC was restarted or shut down' + (exe ? ' (by ' + exe + ')' : '') }];
+        }
+        if ((e.id === 41 && p.includes('kernel-power')) || (e.id === 6008 && p.includes('eventlog')))
+            return [{ kind: 'crash', at: e.at, text: 'Windows stopped unexpectedly (a crash, a power cut, or the power button held down)' }];
+        if (e.id === 42 && p.includes('kernel-power'))
+            return [{ kind: 'sleep', at: e.at, text: 'this PC went to sleep or hibernated' }];
+        if (e.id === 2004 && p.includes('resource-exhaustion'))
+            return [{ kind: 'memory', at: e.at, text: 'this PC ran out of memory' }];
+        if (e.id === 18590 && p.includes('hyper-v-worker')) {
+            const code = /ErrorCode0:\s*(0x[0-9a-f]{1,8})/i.exec(e.process)?.[1];
+            const sub = /ErrorCode1:\s*(0x[0-9a-f]{1,16})/i.exec(e.process)?.[1];
+            return [{ kind: 'sandboxCrash', at: e.at, text: 'Windows inside the sandbox crashed' + (code ? ' (stop code ' + code + (sub ? ', ' + sub : '') + ')' : '') }];
+        }
+        return [];
+    });
+    return causes.sort((a, b) => Date.parse(a.at) - Date.parse(b.at))[0] ?? null;
+};
+const ADVICE = {
+    updates: 'Before leaving agents overnight, restart for pending updates first or pause them (Settings > Windows Update > Pause updates).',
+    restart: 'If that was not you, check Settings > Windows Update and Event Viewer > Windows Logs > System.',
+    crash: 'Event Viewer > Windows Logs > System has the details; a laptop also needs to stay plugged in.',
+    sleep: 'sandbox.keepAwake keeps this PC awake while a sandbox runs (closing a laptop lid still sleeps it). Check it is on, and that sleep is not forced by a policy.',
+    sandboxCrash: 'C:\\AgentData\\logs\\memory-*.log shows what used memory just before. Fewer builds at once inside the sandbox (e.g. cargo build.jobs) makes it less likely.',
+    memory: 'Give the sandbox less RAM (sandbox.maxMemoryMb, sandbox.reserveHostMb) or run fewer builds at once inside it.',
+};
+/** System log and Hyper-V events since `since` that can end a sandbox (Windows only; empty when the logs cannot be read). */
+export const readStopEvents = (since) => {
+    if (!isWin)
+        return [];
+    refuseInSelfTest('read the Windows event log');
+    const script = "$ErrorActionPreference='SilentlyContinue'; $t=[datetime]::Parse('" + since.toISOString() + "').ToLocalTime(); $e = Get-WinEvent -FilterHashtable @(@{LogName='System'; Id=1074,6008,41,42,2004; StartTime=$t}, @{LogName='Microsoft-Windows-Hyper-V-Worker-Admin'; Id=18590; StartTime=$t}) -MaxEvents 100 | ForEach-Object { [pscustomobject]@{ at=$_.TimeCreated.ToUniversalTime().ToString('o'); id=$_.Id; provider=$_.ProviderName; process=$(if ($_.Id -eq 1074) { [string]$_.Properties[0].Value } elseif ($_.Id -eq 18590) { ([string]$_.Message).Substring(0, [math]::Min(390, ([string]$_.Message).Length)) } else { '' }) } }; ConvertTo-Json -Compress -InputObject @($e)";
+    const result = spawnSync(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')], { encoding: 'utf8', windowsHide: true, timeout: 60000 });
+    try {
+        return StopEvents.parse(JSON.parse(result.stdout || '[]'));
+    }
+    catch {
+        return [];
+    }
+};
+/** Looking back from the last time the sandbox was seen running (a minute between checks, plus margin). */
+export const causeSince = (lastSeen) => explainStop(readStopEvents(new Date(Date.parse(lastSeen) - 2 * 60 * 1000)));
+const when = (iso) => new Date(iso).toLocaleString(undefined, { weekday: 'short', hour: '2-digit', minute: '2-digit' });
+/**
+ * At launch: one warning when the last sandbox ended without anyone closing it (the PC restarted, crashed, slept or ran
+ * out of memory), then never again for that run. `watcherAlive` = its watcher is still running (then it did not end).
+ */
+export const lastStopWarning = (storageRoot, dataPath, watcherAlive, find = causeSince) => {
+    const life = readLife(storageRoot, dataPath);
+    if (!life || life.reported || watcherAlive)
+        return null;
+    writeLife(storageRoot, dataPath, { ...life, reported: true });
+    if (life.ended && !life.ended.cause)
+        return null;
+    const cause = life.ended ? life.ended.cause : find(life.lastSeen);
+    const what = cause ? cause.text + ' at ' + when(cause.at) + '. ' + ADVICE[cause.kind] : 'this PC stopped (Windows logged no reason). ' + ADVICE.crash;
+    return 'The last sandbox did not close normally: it was last seen running at ' + when(life.lastSeen) + ', and ' + what + ' Agent conversations are kept: /resume in Claude picks one up.';
+};
+// ---- Windows Update and keeping awake ----------------------------------------------------------------------------
+/** Windows has installed updates and waits to restart: it may do so on its own, outside your active hours. */
+export const updateRestartPending = () => isWin && [
+    'HKLM\\SOFTWARE\\Microsoft\\WindowsUpdate\\Auto Update\\RebootRequired',
+    'HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Component Based Servicing\\RebootPending',
+].some((key) => spawnSync(SYSTEM.reg(), ['query', key], { windowsHide: true, stdio: 'ignore', timeout: 15000 }).status === 0);
+export const UPDATE_RESTART_WARNING = 'Windows is waiting to restart for updates and may do so on its own (often overnight), which closes the sandbox. Restart first, or pause updates: Settings > Windows Update > Pause updates.';
+/**
+ * sandbox.keepAwake: asks Windows not to sleep while the sandbox runs (as a video player does; the screen may still turn
+ * off). A small PowerShell holds the request until `ownerPid` exits, so it never outlives the watcher.
+ */
+export const keepAwake = (ownerPid) => {
+    if (!isWin)
+        return null;
+    refuseInSelfTest('keep this PC awake');
+    const script = "Add-Type -Name Power -Namespace AgentSandbox -MemberDefinition '[DllImport(\"kernel32.dll\")] public static extern uint SetThreadExecutionState(uint f);'; "
+        + '[void][AgentSandbox.Power]::SetThreadExecutionState([uint32]2147483649); Wait-Process -Id ' + Math.trunc(ownerPid) + ' -ErrorAction SilentlyContinue';
+    const child = spawn(SYSTEM.powershell(), ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')], { stdio: 'ignore', windowsHide: true });
+    child.on('error', () => undefined);
+    return child;
+};

package/dist/host/terminal.d.ts

@@ -29,4 +29,12 @@ export declare const ensureTerminal: (dataPath: string, refresh: boolean, option
     exe: string | null;
     message: string;
 }>;
+/** Where the sandbox finds conpty.dll + OpenConsole.exe (guest/ptyhost.ts points ptyhost at it). */
+export declare const conptyDir: (dataPath: string) => string;
+/**
+ * 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 declare const ensureConpty: (dataPath: string, refresh: boolean) => Promise<string>;
 export {};

package/dist/host/terminal.js

@@ -2,7 +2,7 @@
 // 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';
@@ -88,6 +88,50 @@ 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);

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;
+}