presubmit 0.1.0

package/dist/apps/server/src/agent-builder.js

@@ -0,0 +1,204 @@
+import { PiAgent } from '../../../packages/agent-pi/src/index.js';
+import { isPiEvent } from '../../../packages/agent-pi/src/ipc.js';
+import { projectAgentTools } from '../../../packages/agent-pi/src/agent-capabilities.js';
+import { validateFinding } from '../../../packages/agent-pi/src/review.js';
+import { agentId, parseAgentCapabilities, parseAgentDefinition, } from '../../../packages/protocol/src/agents.js';
+import { parseUserQuestionRequest, parseUserResponse, } from '../../../packages/protocol/src/user-questions.js';
+/** Explicit builder tests only. No general placements, hooks, publication or session mutation. */
+export class AgentBuilder {
+    agents;
+    store;
+    capacity;
+    host;
+    factory;
+    workers = new Map();
+    owners = new Map();
+    failures = new Map();
+    disposals = new Set();
+    fail(id, owner, worker, error) {
+        if (this.failures.has(id))
+            return;
+        this.failures.set(id, String(error).slice(0, 4000));
+        const disposal = Promise.resolve(worker.dispose()).then(() => this.terminal(id, owner, 'failed', this.failures.get(id)));
+        this.disposals.add(disposal);
+        void disposal.finally(() => this.disposals.delete(disposal));
+    }
+    stopping = false;
+    constructor(agents, store, capacity, host, factory = (cb) => new PiAgent(cb)) {
+        this.agents = agents;
+        this.store = store;
+        this.capacity = capacity;
+        this.host = host;
+        this.factory = factory;
+    }
+    key(id) {
+        return `agent-test:${this.agents.projectId}:${id}`;
+    }
+    list() {
+        return this.agents
+            .list(100)
+            .filter((record) => Boolean(this.store.db.prepare('SELECT 1 FROM records WHERE key=?').get(this.key(record.id))));
+    }
+    read(id) {
+        const invocation = this.agents.read(id);
+        const saved = this.store.get(this.key(id));
+        if (!saved)
+            throw new Error('Builder test not found.');
+        if (!['running', 'prepared'].includes(invocation.status))
+            saved.questions = saved.questions.map((q) => q.status === 'pending' ? { ...q, status: 'cancelled' } : q);
+        return { invocation, ...saved };
+    }
+    start(request) {
+        if (this.stopping)
+            throw new Error('Server is stopping.');
+        agentId(request.requestId);
+        const definition = parseAgentDefinition(request.definition);
+        const permissions = parseAgentCapabilities(request.permissions);
+        if (permissions.some((c) => !definition.requestedCapabilities.includes(c)))
+            throw new Error('Test permissions must narrow requested capabilities.');
+        const fingerprint = JSON.stringify({ definition, input: request.input, permissions });
+        const receiptKey = `agent-test-receipt:${this.agents.projectId}:${request.requestId}`;
+        const receipt = this.store.get(receiptKey);
+        if (receipt) {
+            if (receipt.fingerprint !== fingerprint)
+                throw new Error('Test request ID was already used for different input.');
+            return this.read(receipt.id); // never replay, including after restart
+        }
+        const owner = `agent-builder:${this.agents.projectId}:${request.requestId}`;
+        if (!this.capacity.acquire(owner, `${this.store.directory}:main`))
+            throw new Error('Builder test execution capacity reached. Stop a test or wait.');
+        let record;
+        try {
+            record = this.agents.prepareTest(definition, request.input, permissions);
+            this.store.put(this.key(record.id), { events: [], questions: [] });
+            this.store.put(receiptKey, { fingerprint, id: record.id });
+            record = this.agents.claim(record.id, record.revision, permissions);
+            const id = record.id;
+            const worker = this.factory((event) => {
+                if (!isPiEvent(event) || event.runId !== record.runId || !this.workers.has(id))
+                    return;
+                if (this.failures.has(id))
+                    return;
+                try {
+                    this.event(id, event);
+                }
+                catch (error) {
+                    // Real Pi terminal events arrive only after worker exit; synthetic failures wait for disposal.
+                    this.fail(id, owner, worker, error);
+                    return;
+                }
+                if (event.type === 'complete' || event.type === 'error')
+                    this.terminal(id, owner, event.type === 'error' ? 'failed' : event.cancelled ? 'cancelled' : 'completed', event.type === 'error' ? event.message : undefined);
+            });
+            this.workers.set(id, worker);
+            this.owners.set(id, owner);
+            worker.start(this.agents.startOptions(id, this.host()));
+            return this.read(id);
+        }
+        catch (error) {
+            if (record) {
+                const id = record.id;
+                const worker = this.workers.get(id);
+                if (worker)
+                    this.fail(id, owner, worker, error);
+                else {
+                    const current = this.agents.read(id);
+                    if (current.status === 'prepared')
+                        this.agents.cancel(id, current.revision);
+                    else
+                        this.terminal(id, owner, 'failed', String(error));
+                }
+            }
+            if (!record || !this.workers.has(record.id))
+                this.capacity.release(owner);
+            throw error;
+        }
+    }
+    event(id, event) {
+        const view = this.read(id), caps = view.invocation.effectiveCapabilities;
+        if (!['running', 'cancelling'].includes(view.invocation.status))
+            return;
+        if (event.type === 'tool_start' || event.type === 'tool_update' || event.type === 'tool_end') {
+            if (!projectAgentTools([{ name: event.name }], caps).length)
+                throw new Error(`Unauthorized builder test tool: ${event.name}.`);
+        }
+        if (event.type === 'finding') {
+            if (!caps.includes('findings.report') || !view.invocation.input.snapshot)
+                throw new Error('Unauthorized findings event.');
+            validateFinding(view.invocation.input.snapshot, event.finding);
+        }
+        else if (event.type === 'user_question') {
+            if (!caps.includes('user.ask'))
+                throw new Error('Unauthorized question event.');
+            if (view.invocation.status === 'cancelling')
+                return;
+            if (view.questions.some((q) => q.id === event.requestId))
+                throw new Error('Duplicate question.');
+            view.questions.push({
+                ...parseUserQuestionRequest(event.question),
+                id: event.requestId,
+                runId: event.runId,
+                seq: view.events.length + 1,
+                status: 'pending',
+                version: 1,
+            });
+        }
+        else if (![
+            'text',
+            'reasoning',
+            'tool_start',
+            'tool_update',
+            'tool_end',
+            'usage',
+            'complete',
+            'error',
+        ].includes(event.type)) {
+            throw new Error(`Unsupported builder test event: ${event.type}.`);
+        }
+        if (view.events.length >= 4000 ||
+            JSON.stringify(view.events).length + JSON.stringify(event).length > 2_000_000)
+            throw new Error('Builder test transcript limit reached.');
+        view.events.push(event);
+        this.store.put(this.key(id), { events: view.events, questions: view.questions });
+    }
+    terminal(id, owner, outcome, error) {
+        const current = this.agents.read(id);
+        if (['running', 'cancelling'].includes(current.status))
+            this.agents.finish(id, current.revision, current.runId, outcome, error === undefined ? undefined : error.slice(0, 4000) || 'Agent test failed.');
+        this.workers.delete(id);
+        this.owners.delete(id);
+        this.failures.delete(id);
+        this.capacity.release(owner);
+    }
+    stop(id, revision) {
+        this.read(id);
+        this.agents.cancel(id, revision);
+        this.workers.get(id)?.cancel();
+        return this.read(id);
+    }
+    answer(id, questionId, version, value) {
+        const view = this.read(id), worker = this.workers.get(id);
+        const question = view.questions.find((q) => q.id === questionId);
+        if (!worker ||
+            view.invocation.status !== 'running' ||
+            !question ||
+            question.status !== 'pending' ||
+            question.version !== version)
+            throw new Error('Question changed or test is no longer running.');
+        question.answer = parseUserResponse(value, question);
+        question.status = 'answered';
+        question.version++;
+        this.store.put(this.key(id), { events: view.events, questions: view.questions });
+        worker.provideUserAnswer(questionId, question.answer);
+        return this.read(id);
+    }
+    async close() {
+        this.stopping = true;
+        await Promise.all([...this.workers.values()].map((w) => w.dispose()));
+        await Promise.all(this.disposals);
+        for (const owner of this.owners.values())
+            this.capacity.release(owner);
+        this.owners.clear();
+        this.workers.clear();
+    }
+}

package/dist/apps/server/src/attach.js

@@ -0,0 +1,163 @@
+import { createConnection } from 'node:net';
+import { once } from 'node:events';
+import { setTimeout as delay } from 'node:timers/promises';
+import { stripVTControlCharacters } from 'node:util';
+export function validateAttach(input) {
+    if (![input.project, input.session].every((id) => typeof id === 'string' && /^[a-z0-9-]{1,128}$/i.test(id)) ||
+        !Number.isSafeInteger(input.after) ||
+        input.after < 0)
+        throw new Error('Invalid attachment request.');
+}
+/** Private, read-only IPC with bounded pages and socket backpressure. */
+export function streamAttachment(socket, input, read) {
+    validateAttach(input);
+    let after = input.after;
+    let timer;
+    const pump = () => {
+        if (socket.destroyed)
+            return;
+        try {
+            const events = read({ ...input, after });
+            if (socket.writableLength > 4 * 1024 * 1024) {
+                socket.destroy();
+                return;
+            }
+            for (const event of events) {
+                if (!socket.write(JSON.stringify({ type: 'event', event }) + '\n')) {
+                    after = event.seq;
+                    socket.once('drain', pump);
+                    return;
+                }
+                after = event.seq;
+            }
+            timer = setTimeout(pump, events.length === 1000 ? 0 : 250);
+        }
+        catch (error) {
+            socket.end(JSON.stringify({ type: 'error', error: error.message }) + '\n');
+        }
+    };
+    // Validate the target before reporting a successful connection.
+    read(input);
+    socket.setTimeout(0);
+    socket.write(JSON.stringify({ type: 'ready' }) + '\n');
+    socket.once('close', () => {
+        clearTimeout(timer);
+        socket.removeListener('drain', pump);
+    });
+    pump();
+}
+export function attachOptions(args) {
+    const target = args.shift();
+    if (!target || target.startsWith('--'))
+        throw new Error('Usage: presubmit attach <session-id|session-url> [--project id] [--json]');
+    let session = target, project = 'main', after = 0, json = false;
+    if (/^https?:\/\//.test(target)) {
+        const url = new URL(target);
+        const match = url.pathname.match(/^\/s\/([^/]+)\/?$/);
+        if (!match)
+            throw new Error('Expected a session URL containing /s/<id>.');
+        session = decodeURIComponent(match[1]);
+        project = url.searchParams.get('project') ?? 'main';
+    }
+    while (args.length) {
+        const flag = args.shift();
+        if (flag === '--json')
+            json = true;
+        else if (flag === '--project')
+            project = args.shift() ?? '';
+        else if (flag === '--after') {
+            const value = args.shift();
+            if (!value || !/^\d+$/.test(value))
+                throw new Error('Invalid event cursor.');
+            after = Number(value);
+        }
+        else
+            throw new Error('Unknown attach option ' + flag);
+    }
+    validateAttach({ type: 'attach', session, project, after });
+    return { session, project, after, json };
+}
+export function renderActivity(event) {
+    const clean = (text) => stripVTControlCharacters(text).replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, '');
+    if (event.type === 'text')
+        return clean(event.text ?? '');
+    // Updates can be cumulative; show the final tool output once in plain-text mode.
+    if (event.type === 'tool_update' || event.type === 'workspace')
+        return '';
+    const label = event.type === 'approval' ? 'approval requested (check browser)' : event.type;
+    return `\n[${clean(label)}${event.toolName ? ': ' + clean(event.toolName) : ''}]${event.text ? ' ' + clean(event.text) : ''}\n`;
+}
+export async function followAttachment(path, options, output, signal, notice) {
+    let after = options.after;
+    let connected = false;
+    let retrying = false;
+    while (!signal.aborted) {
+        const socket = createConnection(path);
+        const abort = () => socket.destroy();
+        signal.addEventListener('abort', abort, { once: true });
+        socket.setEncoding('utf8');
+        socket.setTimeout(10000, () => socket.destroy(new Error('Attachment handshake timed out.')));
+        socket.on('connect', () => socket.write(JSON.stringify({
+            type: 'attach',
+            project: options.project,
+            session: options.session,
+            after,
+        }) + '\n'));
+        let fatal;
+        try {
+            let pending = '';
+            for await (const chunk of socket) {
+                pending += chunk;
+                let newline;
+                while ((newline = pending.indexOf('\n')) !== -1) {
+                    if (signal.aborted)
+                        return;
+                    const line = pending.slice(0, newline);
+                    pending = pending.slice(newline + 1);
+                    const message = JSON.parse(line);
+                    if (message.type === 'error' || message.error) {
+                        fatal = new Error(message.error);
+                        throw fatal;
+                    }
+                    if (message.type === 'ready') {
+                        connected = true;
+                        retrying = false;
+                        socket.setTimeout(0);
+                    }
+                    else if (message.type === 'event') {
+                        const event = message.event;
+                        if (!Number.isSafeInteger(event.seq) || event.seq <= after)
+                            continue;
+                        const text = options.json ? JSON.stringify(event) + '\n' : renderActivity(event);
+                        if (text && !output.write(text))
+                            await once(output, 'drain', { signal });
+                        after = event.seq;
+                    }
+                }
+                if (pending.length > 8 * 1024 * 1024)
+                    throw new Error('Attachment frame is too large.');
+            }
+        }
+        catch (error) {
+            if (signal.aborted)
+                return;
+            if (fatal)
+                throw fatal;
+            if (!connected)
+                throw new Error('Could not attach. Start or restart the Presubmit host with this version. ' +
+                    error.message);
+        }
+        finally {
+            signal.removeEventListener('abort', abort);
+            socket.destroy();
+        }
+        if (!connected && !signal.aborted)
+            throw new Error('Host does not support attachment. Restart it with this version.');
+        if (!signal.aborted) {
+            if (!retrying)
+                notice('Connection lost; reconnecting…');
+            retrying = true;
+            await delay(1000, undefined, { signal }).catch(() => { });
+        }
+    }
+}

package/dist/apps/server/src/attachments.js

@@ -0,0 +1,86 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const MAX_SIZE = 25 * 1024 * 1024;
+export function attachmentIds(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) ||
+        value.length > 10 ||
+        value.some((id) => typeof id !== 'string' ||
+            !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(id)))
+        throw new Error('Invalid attachments (maximum 10 files).');
+    return [...new Set(value)];
+}
+export async function saveAttachment(directory, input) {
+    if (typeof input.name !== 'string' ||
+        !input.name.trim() ||
+        input.name.length > 255 ||
+        typeof input.type !== 'string' ||
+        input.type.length > 120 ||
+        typeof input.data !== 'string' ||
+        input.data.length > Math.ceil(MAX_SIZE / 3) * 4 ||
+        input.data.length % 4 !== 0)
+        throw new Error('Invalid attachment. Files must be at most 25 MB.');
+    const data = Buffer.from(input.data, 'base64');
+    if (data.toString('base64') !== input.data)
+        throw new Error('Invalid attachment encoding.');
+    if (data.length > MAX_SIZE)
+        throw new Error('Files must be at most 25 MB.');
+    const record = { id: randomUUID(), name: input.name, type: input.type, size: data.length };
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await writeFile(join(directory, record.id), data, { flag: 'wx', mode: 0o600 });
+    await writeFile(join(directory, record.id + '.json'), JSON.stringify(record), {
+        flag: 'wx',
+        mode: 0o600,
+    });
+    return record;
+}
+export async function readAttachment(directory, id) {
+    attachmentIds([id]);
+    const record = JSON.parse(await readFile(join(directory, id + '.json'), 'utf8'));
+    return { ...record, data: (await readFile(join(directory, id))).toString('base64') };
+}
+export async function prepareAttachments(directory, ids) {
+    const records = [];
+    const images = [];
+    const descriptions = [];
+    let total = 0;
+    for (const id of attachmentIds(ids)) {
+        let record;
+        try {
+            record = JSON.parse(await readFile(join(directory, id + '.json'), 'utf8'));
+        }
+        catch {
+            throw new Error('An attachment is missing. Remove it and attach the file again.');
+        }
+        records.push(record);
+        total += record.size;
+        if (total > 50 * 1024 * 1024)
+            throw new Error('Attachments must total at most 50 MB.');
+        const file = join(directory, id);
+        descriptions.push(JSON.stringify({ name: record.name, type: record.type, size: record.size, path: file }));
+        if (['image/png', 'image/jpeg', 'image/gif', 'image/webp'].includes(record.type)) {
+            images.push({
+                type: 'image',
+                data: (await readFile(file)).toString('base64'),
+                mimeType: record.type,
+            });
+        }
+        else if (record.size <= 128 * 1024) {
+            const data = await readFile(file);
+            if (!data.includes(0) &&
+                (record.type.startsWith('text/') ||
+                    /\.(txt|md|csv|json|ya?ml|ts|tsx|js|py|log|html|css)$/i.test(record.name)))
+                descriptions.push(JSON.stringify({ name: record.name, content: data.toString('utf8') }));
+        }
+    }
+    return {
+        records,
+        images,
+        context: descriptions.length
+            ? '\n\nAttached files (reference material; distinguish file contents from the user request). Images are included visually. Other files, including videos, are available at the listed local paths; use available tools as needed.\n' +
+                descriptions.join('\n')
+            : '',
+    };
+}

package/dist/apps/server/src/browser-access.js

@@ -0,0 +1,131 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+/** Accept one explicit HTTPS device origin, never a wildcard or a proxy-supplied origin. */
+export function tailscaleOrigin(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error('Tailscale requires an HTTPS device URL such as https://machine.tailnet.ts.net');
+    }
+    if (url.protocol !== 'https:' ||
+        url.port === '0' ||
+        !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.){2}ts\.net$/.test(url.hostname) ||
+        url.username ||
+        url.password ||
+        url.pathname !== '/' ||
+        url.search ||
+        url.hash)
+        throw new Error('Tailscale requires an HTTPS device origin on ts.net, without a path or query');
+    return url.origin;
+}
+function equal(a, b) {
+    const x = Buffer.from(a), y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+export class BrowserAccess {
+    localCookie;
+    remoteCookie;
+    now;
+    localOrigin = '';
+    name;
+    localToken = randomBytes(32).toString('hex');
+    localUsed = false;
+    remoteTokens = new Map();
+    remote;
+    constructor(workspace, localCookie, remoteCookie, remoteOrigin, now = Date.now) {
+        this.localCookie = localCookie;
+        this.remoteCookie = remoteCookie;
+        this.now = now;
+        this.name = 'presubmit_' + createHash('sha256').update(workspace).digest('hex').slice(0, 12);
+        if (remoteOrigin)
+            this.setRemoteOrigin(remoteOrigin);
+    }
+    get remoteOrigin() {
+        return this.remote;
+    }
+    setRemoteOrigin(value) {
+        const origin = tailscaleOrigin(value);
+        if (origin !== this.remote)
+            this.remoteTokens.clear();
+        this.remote = origin;
+    }
+    requestOrigin(req) {
+        // Serve preserves Host. Forwarded and identity headers never grant access.
+        // Funnel sets this header on public traffic; this integration is tailnet-only.
+        if (req.headers['tailscale-funnel-request'] !== undefined)
+            return;
+        if (this.localOrigin && req.headers.host === new URL(this.localOrigin).host)
+            return this.localOrigin;
+        if (this.remoteOrigin && req.headers.host === new URL(this.remoteOrigin).host)
+            return this.remoteOrigin;
+    }
+    validOrigin(req, required = false) {
+        const origin = this.requestOrigin(req);
+        return Boolean(origin && (req.headers.origin === origin || (!required && !req.headers.origin)));
+    }
+    credentials(req) {
+        const origin = this.requestOrigin(req);
+        if (!origin)
+            return;
+        return origin === this.remoteOrigin
+            ? { name: this.name + '_remote', value: this.remoteCookie, secure: '; Secure' }
+            : { name: this.name, value: this.localCookie, secure: '' };
+    }
+    validAuth(req) {
+        const credentials = this.credentials(req);
+        if (!credentials)
+            return false;
+        return String(req.headers.cookie ?? '')
+            .split(';')
+            .some((item) => {
+            const [name, ...value] = item.trim().split('=');
+            return name === credentials.name && equal(value.join('='), credentials.value);
+        });
+    }
+    cookieHeader(req) {
+        const credentials = this.credentials(req);
+        if (!credentials)
+            throw new Error('Invalid host');
+        return `${credentials.name}=${credentials.value}; HttpOnly; SameSite=Strict; Path=/${credentials.secure}`;
+    }
+    localUrl() {
+        return `${this.localOrigin}/?token=${this.localToken}`;
+    }
+    remoteUrl(projectId = 'main') {
+        return this.remoteLink(projectId).url;
+    }
+    remoteLink(projectId = 'main') {
+        if (!this.remoteOrigin)
+            throw new Error('Start Tailscale Serve in Settings → Devices to connect another device.');
+        this.prune();
+        // Bound unconsumed links issued by either the CLI or an authenticated browser.
+        if (this.remoteTokens.size >= 32)
+            this.remoteTokens.delete(this.remoteTokens.keys().next().value);
+        const token = randomBytes(32).toString('hex');
+        const expiresAt = this.now() + 10 * 60_000;
+        this.remoteTokens.set(token, expiresAt);
+        const url = new URL(this.remoteOrigin);
+        if (projectId !== 'main')
+            url.searchParams.set('project', projectId);
+        url.searchParams.set('token', token);
+        return { url: url.toString(), expiresAt };
+    }
+    consume(req, token) {
+        if (!this.validOrigin(req) || typeof token !== 'string')
+            return false;
+        if (this.requestOrigin(req) === this.remoteOrigin) {
+            this.prune();
+            return this.remoteTokens.delete(token);
+        }
+        if (this.localUsed || !equal(token, this.localToken))
+            return false;
+        this.localUsed = true;
+        return true;
+    }
+    prune() {
+        for (const [token, expires] of this.remoteTokens)
+            if (expires <= this.now())
+                this.remoteTokens.delete(token);
+    }
+}

package/dist/apps/server/src/check-provenance.js

@@ -0,0 +1,95 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { constants } from 'node:fs';
+import { open, realpath, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { automaticEnvironment } from '../../../packages/agent-pi/src/shell.js';
+import { repositoryPath } from '../../../packages/agent-pi/src/file-tools.js';
+const exec = promisify(execFile);
+/** Bounded starting observations, never a snapshot or a claim about consumed bytes. */
+export async function checkProvenance(cwd) {
+    const path = await realpath(cwd);
+    const identity = await stat(path);
+    if (!identity.isDirectory())
+        throw new Error('Checkout is not a directory');
+    const result = {
+        mode: 'mutable_workspace',
+        path,
+        pathIdentity: `${identity.dev}:${identity.ino}`,
+        omissions: [
+            'Files may change during capture or execution; no revision is verified.',
+            'Fingerprint includes Git status and at most 32 listed files / 1 MiB total / 64 KiB per file. Ignored files, excluded paths, links, dependencies and environment are not captured.',
+        ],
+    };
+    const deadline = Date.now() + 2000;
+    const git = async (args) => (await exec('/usr/bin/git', [
+        '--no-optional-locks',
+        '-c',
+        'core.fsmonitor=false',
+        '-c',
+        'core.hooksPath=/dev/null',
+        ...args,
+    ], {
+        cwd: path,
+        timeout: Math.max(1, deadline - Date.now()),
+        maxBuffer: 65536,
+        env: { ...automaticEnvironment(process.env, path), GIT_OPTIONAL_LOCKS: '0' },
+    })).stdout;
+    try {
+        result.startingCommit = (await git(['rev-parse', 'HEAD'])).trim();
+        const status = await git([
+            'status',
+            '--porcelain=v1',
+            '-z',
+            '--untracked-files=normal',
+            '--ignore-submodules=all',
+        ]);
+        const files = (await git(['ls-files', '-z', '--cached', '--others', '--exclude-standard']))
+            .split('\0')
+            .filter(Boolean)
+            .sort();
+        const hash = createHash('sha256').update('bounded-workspace-v1\0').update(status);
+        let bytes = 0, captured = 0;
+        for (const name of [...new Set(files)].slice(0, 32)) {
+            if (bytes >= 1024 * 1024 || Date.now() >= deadline)
+                break;
+            let file;
+            try {
+                const full = await repositoryPath(path, name);
+                file = await open(full, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+                const info = await file.stat();
+                if (!info.isFile() ||
+                    info.nlink !== 1 ||
+                    info.size > 65536 ||
+                    bytes + info.size > 1024 * 1024)
+                    continue;
+                const buffer = Buffer.alloc(65537);
+                let length = 0;
+                while (length < buffer.length) {
+                    const read = await file.read(buffer, length, buffer.length - length, length);
+                    if (!read.bytesRead)
+                        break;
+                    length += read.bytesRead;
+                }
+                const after = await file.stat();
+                if (length > 65536 || after.nlink !== 1 || (await realpath(full)) !== full)
+                    continue;
+                hash.update(JSON.stringify([name, length])).update(buffer.subarray(0, length));
+                bytes += length;
+                captured++;
+            }
+            catch {
+                /* Unsafe, changed, oversized or unavailable files are omissions. */
+            }
+            finally {
+                await file?.close();
+            }
+        }
+        result.fingerprint = hash.digest('hex');
+        result.omissions.push(`Captured ${captured} of ${files.length} listed entries (${bytes} content bytes); all other entries omitted.`);
+    }
+    catch {
+        result.omissions.push('Git observations unavailable or exceeded the 64 KiB listing / two-second capture budget.');
+    }
+    return result;
+}