windows-development-sandbox 1.4.0 → 1.4.3

package/dist/host/channel/channel.js

@@ -0,0 +1,196 @@
+// Host side of the sandbox channel: follow the boot and send requests (sessions, exec, restart, ping). Attaching a
+// terminal to a session is in attach.ts. Everything read from the run folder is guest-written and treated as untrusted.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import { assertNoLinks, fail, isLink, removeLink, safeText, sleep } from '../../core/util/index.js';
+import { isWithin } from '../../shared/paths/index.js';
+import { now, RunDir } from '../../shared/channel/index.js';
+import { safeRemove, writeJsonAtomic } from '../../shared/io/index.js';
+import { isSandboxRunning } from '../sandbox/index.js';
+import { assertTestWritable, refuseInSelfTest } from '../test-guard.js';
+const BOOT_TIMEOUT_MS = 30 * 60 * 1000;
+/** Most sessions the host will ever contact for one listing: a sandbox can write as many session files as it likes. */
+export const MAX_QUERIED_SESSIONS = 32;
+const printLine = (line) => console.log(line);
+const newId = () => Date.now().toString(36) + crypto.randomBytes(3).toString('hex');
+/** Sessions in this guest folder or below (one project's) first, each group newest first. */
+export function sessionsFirstIn(sessions, guestDir) {
+    const newest = [...sessions].reverse();
+    if (!guestDir)
+        return newest;
+    return [...newest.filter((s) => isWithin(guestDir, s.cwd)), ...newest.filter((s) => !isWithin(guestDir, s.cwd))];
+}
+/** The channel to the sandbox of one data folder: requests go into its run folder, answers are polled from it. */
+export class SandboxChannel {
+    dataPath;
+    isAlive;
+    run;
+    constructor(dataPath, isAlive = isSandboxRunning) {
+        this.dataPath = dataPath;
+        this.isAlive = isAlive;
+        this.run = new RunDir(dataPath);
+    }
+    async until(timeoutMs, poll, timeoutMessage) {
+        const deadline = Date.now() + timeoutMs;
+        for (let round = 0; Date.now() < deadline; round++) {
+            const value = poll();
+            if (value !== null && value !== undefined)
+                return value;
+            if (round % 10 === 0 && !this.isAlive())
+                fail('Windows Sandbox closed (or is not running).', 'Start it again with sandbox claude; sandbox logs shows what happened.');
+            await sleep(500);
+        }
+        fail(timeoutMessage, 'Check what the sandbox is doing with sandbox logs -f (or sbx-show to see its window).');
+    }
+    /** Deletes an answer once read; a planted link means the answer is read and nothing is deleted. */
+    dropResponse(requestId) {
+        try {
+            assertNoLinks(this.dataPath, this.run.responsesDir);
+            fs.rmSync(this.run.responseFile(requestId), { force: true });
+        }
+        catch {
+            /* a planted link: the answer is read, nothing is deleted */
+        }
+    }
+    /** Waits until the sandbox finished provisioning, reporting each boot step (onStatus: every status read, validated). */
+    waitForReady(launchId, progress = (m) => printLine('  [sandbox] ' + m), onStatus) {
+        let last = '';
+        return this.until(BOOT_TIMEOUT_MS, () => {
+            const status = this.run.readSandboxStatus();
+            if (!status || (launchId !== null && status.launchId !== launchId))
+                return null;
+            onStatus?.(status);
+            if (status.message !== last) {
+                progress(safeText(status.message).slice(0, 300));
+                last = status.message;
+            }
+            if (status.phase === 'failed')
+                fail('The sandbox failed to start: ' + status.message, 'See sandbox logs for details; the sandbox window shows the error too (sbx-show if headless).');
+            return status.phase === 'ready' ? status : null;
+        }, 'Timed out waiting for the sandbox to finish provisioning.');
+    }
+    send(request) {
+        assertTestWritable(this.dataPath);
+        // Asking the sandbox to power off is the one request with an effect outside it, so the self-test never sends it.
+        if (request.kind === 'exec' && /shutdown/i.test(request.command[0] ?? ''))
+            refuseInSelfTest('shut down Windows Sandbox');
+        assertNoLinks(this.dataPath, this.run.requestsDir);
+        writeJsonAtomic(this.run.requestFile(request.id), request);
+    }
+    waitForResponse(requestId, timeoutMs) {
+        return this.until(timeoutMs, () => {
+            const response = this.run.readResponse(requestId);
+            if (response)
+                this.dropResponse(requestId);
+            return response;
+        }, 'The sandbox did not answer (its session daemon may have stopped).');
+    }
+    /**
+     * project: a project registered after boot (provisioned first). harnessSpec: the agent's definition, for an agent the
+     * sandbox did not boot with.
+     */
+    requestSession(harness, args, cwd, extra = {}) {
+        const requestId = newId();
+        this.send({
+            kind: 'session',
+            id: requestId,
+            harness,
+            args,
+            cwd,
+            ...(extra.project ? { project: extra.project } : {}),
+            ...(extra.harnessSpec ? { harnessSpec: extra.harnessSpec } : {}),
+            createdAt: now(),
+        });
+        return requestId;
+    }
+    /**
+     * Provisions a registered project without starting an agent and waits for it, printing its progress (the guest's
+     * run\projects\<name>.json) as it goes. Throws when it failed.
+     */
+    async prepareProject(project, progress = (m) => printLine('  [' + project.name + '] ' + m)) {
+        const requestId = newId();
+        this.send({ kind: 'project', id: requestId, project, createdAt: now() });
+        let last = '';
+        const response = await this.until(60 * 60 * 1000, () => {
+            const status = this.run.readProjectStatus(project.name);
+            if (status && status.message !== last) {
+                progress(safeText(status.message).slice(0, 300));
+                last = status.message;
+            }
+            return this.run.readResponse(requestId);
+        }, 'Timed out waiting for the project to be set up.');
+        this.dropResponse(requestId);
+        if (!response.ok)
+            fail(safeText(response.message), 'See sandbox logs for details.');
+        return response;
+    }
+    waitForSession(sessionId, timeoutMs = 15 * 60 * 1000, progress = (m) => printLine('  [session] ' + m)) {
+        let last = '';
+        return this.until(timeoutMs, () => {
+            const session = this.run.readSession(sessionId);
+            if (!session)
+                return null;
+            if (session.message !== last) {
+                progress(safeText(session.message).slice(0, 300));
+                last = session.message;
+            }
+            if (session.phase === 'failed')
+                fail('The agent session failed to start: ' + session.message, 'See sandbox logs for details.');
+            if (session.phase === 'exited')
+                fail('The agent exited right away (code ' + session.exitCode + ').', 'Check sandbox logs; a wrong agent argument is the usual cause.');
+            return session.phase === 'running' ? session : null;
+        }, 'Timed out waiting for the session to start.');
+    }
+    /** Runs a command inside the sandbox (in the workspace or a folder below it) and returns its output. */
+    async exec(command, cwd, timeoutSeconds) {
+        const requestId = newId();
+        this.send({ kind: 'exec', id: requestId, command, cwd, timeoutSeconds, createdAt: now() });
+        return this.waitForResponse(requestId, (timeoutSeconds + 30) * 1000);
+    }
+    /** Restarts running sessions in place (they resume via the harness's resumeArguments, e.g. claude --continue). */
+    async restart(harness, cwd) {
+        const requestId = newId();
+        this.send({ kind: 'restart', id: requestId, harness, ...(cwd ? { cwd } : {}), createdAt: now() });
+        return this.waitForResponse(requestId, 30000);
+    }
+    async ping() {
+        const requestId = newId();
+        this.send({ kind: 'ping', id: requestId, createdAt: now() });
+        return this.waitForResponse(requestId, 15000);
+    }
+    runningSessions() {
+        return this.run.listSessions().filter((s) => s.phase === 'running');
+    }
+    /** Running sessions of the sandbox that is running now (its launch id), newest last, capped. */
+    currentSessions() {
+        const launchId = this.run.readSandboxStatus()?.launchId;
+        return this.runningSessions()
+            .filter((s) => s.launchId === launchId)
+            .slice(-MAX_QUERIED_SESSIONS);
+    }
+    /**
+     * The session with this id (or id prefix), else the most recently started running one: in `guestDir` (the project
+     * you are in) when it has one, else any.
+     */
+    pickSession(sessionId, guestDir = null) {
+        const running = this.runningSessions();
+        if (running.length === 0)
+            fail('No agent session is running in the sandbox.', 'Start one with sandbox claude (it opens a new session in the running sandbox).');
+        if (!sessionId)
+            return sessionsFirstIn(running, guestDir)[0];
+        return (running.find((s) => s.id === sessionId || s.id.startsWith(sessionId)) ??
+            fail('No running session "' + sessionId + '".', 'Running sessions: ' + running.map((s) => s.id).join(', ') + ' (sandbox sessions lists them).'));
+    }
+    /** Forgets status from a previous sandbox run so nothing stale is picked up. */
+    reset() {
+        const p = this.run;
+        // A link (planted by a sandbox) is removed itself and never followed, including `run` itself.
+        if (isLink(p.root)) {
+            removeLink(p.root);
+            return;
+        }
+        for (const target of [p.sandboxFile, p.requestsDir, p.responsesDir, p.sessionsDir, p.projectsDir]) {
+            safeRemove(target, this.dataPath);
+        }
+    }
+}

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

@@ -0,0 +1,2 @@
+export * from './channel.js';
+export * from './attach.js';

package/dist/host/channel/index.js

@@ -0,0 +1,2 @@
+export * from './channel.js';
+export * from './attach.js';

package/dist/host/guard/agent-files.d.ts

@@ -0,0 +1,7 @@
+import type { GuardRule, RepoFinding, RepoSnapshot } from './types.js';
+export declare function agentSnapshot(workspace: string): Record<string, string>;
+/** Hooks, helper commands and MCP servers in .claude/ and .mcp.json, VS Code folder-open tasks and programs, .envrc. */
+export declare class AgentFilesRule implements GuardRule {
+    readonly kind = "agent-files";
+    check(workspace: string, before: RepoSnapshot): RepoFinding[];
+}

package/dist/host/guard/agent-files.js

@@ -0,0 +1,103 @@
+// Agent and editor files that tools on this PC run things from: only their runnable part is fingerprinted and guarded.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import _ from 'lodash';
+import { parse as parseJsonc } from 'jsonc-parser';
+import { fileExists, isLink } from '../../core/util/index.js';
+import { hash } from './file-hash.js';
+const CLAUDE_RISKY_KEYS = [
+    'hooks',
+    'apiKeyHelper',
+    'awsAuthRefresh',
+    'awsCredentialExport',
+    'otelHeadersHelper',
+    'statusLine',
+    'env',
+    'enableAllProjectMcpServers',
+    'enabledMcpjsonServers',
+    'disableAllHooks',
+];
+const VSCODE_RISKY_KEY = /path|executable|command|interpreter|shell|profile|args|env|exec|program|server|launch|runtime|binary/i;
+const MAX_AGENT_FILE_BYTES = 1024 * 1024;
+function claudeRisk(d) {
+    const s = (_.isPlainObject(d) ? d : {});
+    const permissions = (_.isPlainObject(s.permissions) ? s.permissions : {});
+    return {
+        ..._.pick(s, CLAUDE_RISKY_KEYS),
+        permissions: _.pick(permissions, ['defaultMode', 'additionalDirectories']),
+    };
+}
+/**
+ * Project files that tools on this PC act on by themselves: Claude Code runs a project's hooks, helpers and MCP
+ * servers, VS Code runs folder-open tasks and the programs workspace settings point at, direnv runs .envrc. For each,
+ * only the part that can run something is compared (`risky`), so the agent may still edit the rest.
+ */
+const AGENT_FILES = {
+    '.claude/settings.json': (d) => claudeRisk(d),
+    '.claude/settings.local.json': (d) => claudeRisk(d),
+    '.mcp.json': (_d, text) => text,
+    '.vscode/tasks.json': (d) => (JSON.stringify(d).match(/"runOn"\s*:\s*"folderOpen"/) ? d : null),
+    '.vscode/settings.json': (d) => _.pickBy(_.isPlainObject(d) ? d : {}, (_v, k) => VSCODE_RISKY_KEY.test(k)),
+    '.envrc': (_d, text) => text,
+};
+const AGENT_FILE_NAMES = Object.keys(AGENT_FILES);
+/** What can run in one agent file, as a short fingerprint (null = the file is not there). */
+function agentRisk(workspace, rel) {
+    const file = path.join(workspace, ...rel.split('/'));
+    if (!fs.existsSync(file))
+        return null;
+    if (isLink(file) || isLink(path.dirname(file)) || !fileExists(file))
+        return 'link-or-not-a-file';
+    if (fs.statSync(file).size > MAX_AGENT_FILE_BYTES)
+        return 'too-large-' + hash(file);
+    const text = fs.readFileSync(file, 'utf8');
+    const errors = [];
+    const data = parseJsonc(text, errors, { allowTrailingComma: true });
+    const risk = AGENT_FILES[rel](rel === '.envrc' ? null : data, text);
+    return crypto
+        .createHash('sha256')
+        .update(JSON.stringify(risk ?? null) + (errors.length && rel !== '.envrc' && rel !== '.mcp.json' ? hash(file) : ''))
+        .digest('hex');
+}
+export function agentSnapshot(workspace) {
+    return Object.fromEntries(AGENT_FILE_NAMES.flatMap((rel) => {
+        const r = agentRisk(workspace, rel);
+        return r ? [[rel, r]] : [];
+    }));
+}
+/** Agent files whose runnable part changed are moved to the quarantine folder (with the rest of your edits). */
+function guardAgentFiles(workspace, before) {
+    const changed = AGENT_FILE_NAMES.filter((rel) => {
+        const now = agentRisk(workspace, rel);
+        return now !== null && now !== before[rel];
+    });
+    if (!changed.length)
+        return [];
+    const target = path.join(workspace, 'agent-sandbox-quarantine', String(Date.now()));
+    fs.mkdirSync(target, { recursive: true });
+    return changed.map((rel) => {
+        const what = rel + ' (the sandbox added something it would run on this PC: hooks, MCP servers, helper commands or tasks';
+        try {
+            fs.renameSync(path.join(workspace, ...rel.split('/')), path.join(target, rel.replace(/\//g, '_')));
+        }
+        catch (e) {
+            return {
+                kind: 'agent',
+                detail: what +
+                    '; could not be moved: ' +
+                    e.code +
+                    '. Check it before you open this folder in Claude Code or VS Code)',
+            };
+        }
+        return { kind: 'agent', detail: what + '; moved to ' + target + ')' };
+    });
+}
+/** Hooks, helper commands and MCP servers in .claude/ and .mcp.json, VS Code folder-open tasks and programs, .envrc. */
+export class AgentFilesRule {
+    kind = 'agent-files';
+    check(workspace, before) {
+        // Snapshots from before these checks existed have no baseline: checking against nothing would move your own files.
+        return before.agent ? guardAgentFiles(workspace, before.agent) : [];
+    }
+}

package/dist/host/guard/commands.d.ts

@@ -0,0 +1,10 @@
+import type { GuardRule, RepoFinding, RepoSnapshot } from './types.js';
+/** Names you are likely to run in a project folder; with any of these extensions Windows would pick the local copy. */
+export declare const COMMANDS: RegExp;
+/** Fingerprints of the files in the project root named like one of COMMANDS. */
+export declare function plantedCommands(workspace: string): Record<string, string>;
+/** Executables dropped in the project root under the name of something you type there (Windows runs those first). */
+export declare class PlantedCommandsRule implements GuardRule {
+    readonly kind = "commands";
+    check(workspace: string, before: RepoSnapshot): RepoFinding[];
+}

package/dist/host/guard/commands.js

@@ -0,0 +1,123 @@
+import { filesIn } from './file-hash.js';
+import { quarantine } from './quarantine.js';
+/** Names you are likely to run in a project folder; with any of these extensions Windows would pick the local copy. */
+export const COMMANDS = new RegExp('^(' +
+    [
+        // this tool's own commands (package.json "bin")
+        'sandbox',
+        'windows-development-sandbox',
+        'agent-sandbox',
+        'claude-sbx',
+        'claude-sandbox',
+        'codex-sbx',
+        'codex-sandbox',
+        'gemini-sbx',
+        'gemini-sandbox',
+        'claude-host',
+        'sbx-show',
+        'sbx-hide',
+        // agents
+        'claude',
+        'codex',
+        'gemini',
+        'opencode',
+        'qwen',
+        'crush',
+        'copilot',
+        'kilo',
+        'kilocode',
+        'amp',
+        'cline',
+        'cn',
+        'kimi',
+        'reasonix',
+        'codewhale',
+        'aider',
+        'cursor-agent',
+        'agent',
+        'goose',
+        // toolchains and everyday tools
+        'node',
+        'npm',
+        'npx',
+        'pnpm',
+        'pnpx',
+        'yarn',
+        'corepack',
+        'volta',
+        'nvm',
+        'deno',
+        'bun',
+        'bunx',
+        'tsc',
+        'git',
+        'gh',
+        'code',
+        'python',
+        'python3',
+        'py',
+        'pip',
+        'pip3',
+        'uv',
+        'uvx',
+        'pyenv',
+        'poetry',
+        'cargo',
+        'rustc',
+        'rustup',
+        'dotnet',
+        'nuget',
+        'msbuild',
+        'go',
+        'java',
+        'javac',
+        'mvn',
+        'mvnw',
+        'gradle',
+        'gradlew',
+        'ruby',
+        'gem',
+        'bundle',
+        'rake',
+        'rails',
+        'php',
+        'composer',
+        'make',
+        'cmake',
+        'ninja',
+        'gcc',
+        'g\\+\\+',
+        'clang',
+        'psql',
+        'mysql',
+        'mariadb',
+        'mongosh',
+        'redis-cli',
+        'docker',
+        'kubectl',
+        'terraform',
+        'az',
+        'aws',
+        'powershell',
+        'pwsh',
+        'cmd',
+        'where',
+        'tasklist',
+        'tar',
+        'curl',
+        'ssh',
+        'scp',
+    ].join('|') +
+    ')\\.(exe|com|bat|cmd|vbs|vbe|js|jse|wsf|wsh|msc|ps1)$', 'i');
+/** Fingerprints of the files in the project root named like one of COMMANDS. */
+export function plantedCommands(workspace) {
+    return filesIn(workspace, (n) => COMMANDS.test(n));
+}
+/** Executables dropped in the project root under the name of something you type there (Windows runs those first). */
+export class PlantedCommandsRule {
+    kind = 'commands';
+    check(workspace, before) {
+        const now = plantedCommands(workspace);
+        return quarantine(workspace, Object.keys(now).filter((n) => before.commands[n] !== now[n]), workspace, 'command');
+    }
+}

package/dist/host/guard/file-hash.d.ts

@@ -0,0 +1,4 @@
+/** SHA-256 in small chunks: a sandbox can plant a multi-gigabyte "node.exe" to exhaust this PC's memory. */
+export declare function hash(file: string): string;
+/** The accepted files (and links) directly in a folder, by name, with their fingerprints. Links are not followed. */
+export declare function filesIn(dir: string, accept: (name: string) => boolean): Record<string, string>;

package/dist/host/guard/file-hash.js

@@ -0,0 +1,37 @@
+// Fingerprints of the files the guard compares (planted commands, git hooks).
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { dirExists, isLink } from '../../core/util/index.js';
+/** SHA-256 in small chunks: a sandbox can plant a multi-gigabyte "node.exe" to exhaust this PC's memory. */
+export function hash(file) {
+    if (isLink(file))
+        return 'link';
+    const sum = crypto.createHash('sha256');
+    const buffer = Buffer.alloc(1 << 20);
+    let fd;
+    // A file that cannot be read (locked by a program in the sandbox) never matches the snapshot, so it is dealt with.
+    try {
+        fd = fs.openSync(file, 'r');
+    }
+    catch {
+        return 'unreadable-' + crypto.randomBytes(4).toString('hex');
+    }
+    try {
+        for (let n = fs.readSync(fd, buffer, 0, buffer.length, null); n > 0; n = fs.readSync(fd, buffer, 0, buffer.length, null))
+            sum.update(buffer.subarray(0, n));
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return sum.digest('hex');
+}
+/** The accepted files (and links) directly in a folder, by name, with their fingerprints. Links are not followed. */
+export function filesIn(dir, accept) {
+    return dirExists(dir) && !isLink(dir)
+        ? Object.fromEntries(fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => (e.isFile() || e.isSymbolicLink()) && accept(e.name))
+            .map((e) => [e.name, hash(path.join(dir, e.name))]))
+        : {};
+}

package/dist/host/guard/git-config.d.ts

@@ -0,0 +1,5 @@
+import type { RepoFinding } from './types.js';
+/** The lines of <dir>\config (none for a link or a file over 4 MB). */
+export declare function configLines(dir: string): string[];
+/** Comments out newly added config lines that make git run programs. Existing lines are never touched. */
+export declare function disableConfig(dir: string, before: readonly string[]): RepoFinding[];

package/dist/host/guard/git-config.js

@@ -0,0 +1,62 @@
+// Git config lines that make git run a program on this PC: found by comparing with the snapshot, then commented out.
+import fs from 'node:fs';
+import path from 'node:path';
+import _ from 'lodash';
+import { writeFileAtomic } from '../../shared/io/index.js';
+import { fileExists, isLink } from '../../core/util/index.js';
+/** Config keys that make git run a program, or load more config. */
+const DANGEROUS_KEY = /^(fsmonitor|hookspath|sshcommand|pager|editor|askpass|program|gpgprogram|textconv|command|cmd|clean|smudge|process|driver|helper|uploadpack|receivepack|path|attributesfile|excludesfile|worktree|worktreeconfig|gitproxy|proxycommand|sendemailvalidate|tool|external|difffilter|defaultkeycommand|alternaterefscommand)\s*=/i;
+const SECTION = /^\s*\[([^\]]*)\]\s*/;
+const MARK = '# [agent-sandbox] disabled, added inside the sandbox: ';
+const MAX_CONFIG_BYTES = 4 * 1024 * 1024;
+/** Sections where any key runs a program ([pager] log = x), or where a "!" value does ([alias] st = !x). */
+function dangerousInSection(section, keyPart) {
+    return (section === 'pager' && keyPart.includes('=')) || (section === 'alias' && /^[^=]+=\s*"?\s*!/.test(keyPart));
+}
+/** The lines of <dir>\config (none for a link or a file over 4 MB). */
+export function configLines(dir) {
+    const file = path.join(dir, 'config');
+    return fileExists(file) && !isLink(file) && fs.statSync(file).size <= MAX_CONFIG_BYTES
+        ? fs.readFileSync(file, 'utf8').split(/\r?\n/)
+        : [];
+}
+/** Comments out newly added config lines that make git run programs. Existing lines are never touched. */
+export function disableConfig(dir, before) {
+    const lines = configLines(dir);
+    const known = _.countBy(before);
+    const seen = {};
+    const findings = [];
+    let inInclude = false;
+    let section = '';
+    const fixed = lines.map((line) => {
+        const header = SECTION.exec(line);
+        if (header) {
+            section = header[1].trim().toLowerCase().split(/\s/)[0];
+            inInclude = /^include(if\s+"[^"]*")?$/i.test(header[1].trim());
+        }
+        seen[line] = (seen[line] ?? 0) + 1;
+        if (line.startsWith(MARK) || seen[line] <= (known[line] ?? 0))
+            return line;
+        // git also accepts "[core] fsmonitor = x" on one line, so look past a leading section header.
+        const keyPart = line.replace(SECTION, '').trim();
+        if (!(DANGEROUS_KEY.test(keyPart) || (inInclude && keyPart.includes('=')) || dangerousInSection(section, keyPart)))
+            return line;
+        findings.push({ kind: 'config', detail: line.trim() });
+        return MARK + line.trim();
+    });
+    if (findings.length)
+        writeFileAtomic(path.join(dir, 'config'), fixed.join('\n'));
+    const file = path.join(dir, 'config');
+    // A link or a huge file is not read at all, so say so instead of letting it pass as "nothing found".
+    const unchecked = isLink(file)
+        ? '.git/config is a link'
+        : lines.length === 0 && fileExists(file) && fs.statSync(file).size > MAX_CONFIG_BYTES
+            ? '.git/config is over 4 MB'
+            : null;
+    if (unchecked)
+        findings.push({
+            kind: 'git',
+            detail: unchecked + ', so it cannot be checked. Do not run git in this folder until you have looked at it.',
+        });
+    return findings;
+}

package/dist/host/guard/git-dirs.d.ts

@@ -0,0 +1,12 @@
+import type { GitState, GuardRule, RepoFinding, RepoSnapshot } from './types.js';
+export declare const EMPTY_GIT: GitState;
+/** <workspace>\.git when it is a real folder (not a link or a "gitdir:" file). */
+export declare function plainGitDir(workspace: string): string | null;
+export declare function gitState(dir: string | null): GitState;
+/** New or changed hooks and new redirect files are quarantined; new config that runs programs is commented out. */
+export declare function guardGitDir(dir: string, before: GitState): RepoFinding[];
+/** The project's own .git; a .git replaced by a link or a "gitdir:" file is reported, never followed. */
+export declare class GitDirRule implements GuardRule {
+    readonly kind = "git-dir";
+    check(workspace: string, before: RepoSnapshot): RepoFinding[];
+}

package/dist/host/guard/git-dirs.js

@@ -0,0 +1,53 @@
+// A git folder's hooks, config and redirect files, and the rule that guards the project's own .git.
+import fs from 'node:fs';
+import path from 'node:path';
+import { dirExists, isLink } from '../../core/util/index.js';
+import { filesIn } from './file-hash.js';
+import { configLines, disableConfig } from './git-config.js';
+import { quarantine } from './quarantine.js';
+/** Files in .git that make git read config/hooks from somewhere else. */
+const REDIRECTS = ['commondir', 'config.worktree'];
+const isHook = (name) => !name.endsWith('.sample');
+export const EMPTY_GIT = { config: [], hooks: {}, redirects: [] };
+/** <workspace>\.git when it is a real folder (not a link or a "gitdir:" file). */
+export function plainGitDir(workspace) {
+    const dir = path.join(workspace, '.git');
+    return dirExists(dir) && !isLink(dir) ? dir : null;
+}
+export function gitState(dir) {
+    return {
+        config: dir ? configLines(dir) : [],
+        hooks: dir ? filesIn(path.join(dir, 'hooks'), isHook) : {},
+        redirects: dir ? REDIRECTS.filter((n) => fs.existsSync(path.join(dir, n))) : [],
+    };
+}
+/** New or changed hooks and new redirect files are quarantined; new config that runs programs is commented out. */
+export function guardGitDir(dir, before) {
+    const hooksDir = path.join(dir, 'hooks');
+    const hooksNow = filesIn(hooksDir, isHook);
+    return [
+        ...quarantine(hooksDir, Object.keys(hooksNow).filter((n) => before.hooks[n] !== hooksNow[n]), dir, 'hook'),
+        ...quarantine(dir, REDIRECTS.filter((n) => fs.existsSync(path.join(dir, n)) && !before.redirects.includes(n)), dir, 'git'),
+        ...disableConfig(dir, before.config),
+    ];
+}
+/** The project's own .git; a .git replaced by a link or a "gitdir:" file is reported, never followed. */
+export class GitDirRule {
+    kind = 'git-dir';
+    check(workspace, before) {
+        const dir = plainGitDir(workspace);
+        if (dir)
+            return guardGitDir(dir, before);
+        const replaced = before.gitDir && fs.existsSync(path.join(workspace, '.git'));
+        if (!replaced)
+            return [];
+        return [
+            {
+                kind: 'git',
+                detail: '.git was replaced by a link or a "gitdir:" file inside the sandbox. Do not run git in ' +
+                    workspace +
+                    ' until you have checked it.',
+            },
+        ];
+    }
+}

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

@@ -0,0 +1,5 @@
+export type { GitState, RepoFinding, RepoSnapshot } from './types.js';
+export { RepoGuard } from './repo-guard.js';
+export { RepoGuardStore, type RecordedFinding } from './store.js';
+export { RISKY, isMarked, markFromSandbox, watchAndMark } from './mark-of-the-web.js';
+export { readDataSize, readMarkedProjects, saveDataSize, saveMarkedProjects } from './watch-state.js';

package/dist/host/guard/index.js

@@ -0,0 +1,4 @@
+export { RepoGuard } from './repo-guard.js';
+export { RepoGuardStore } from './store.js';
+export { RISKY, isMarked, markFromSandbox, watchAndMark } from './mark-of-the-web.js';
+export { readDataSize, readMarkedProjects, saveDataSize, saveMarkedProjects } from './watch-state.js';

package/dist/host/guard/mark-of-the-web.d.ts

@@ -0,0 +1,8 @@
+/** What Windows runs when you open it (not source files such as .js or .py: those need a program you choose). */
+export declare const RISKY: RegExp;
+/** Marks one file if it is a program or script (and a plain file, not a link). Returns true when it marked it. */
+export declare function markFromSandbox(file: string): boolean;
+/** Has this file the mark? */
+export declare function isMarked(file: string): boolean;
+/** Watches the projects while the sandbox runs and marks what appears or changes; returns a function that stops it. */
+export declare function watchAndMark(projects: readonly string[], note?: (message: string) => void): () => void;