mtech-ai-local-runner 0.1.30 → 0.1.31

package/dist/src/publication/execution-host.js

@@ -0,0 +1,55 @@
+import { protocolHash } from './candidate.js';
+import { PublicationOutcomeUnknownError } from './publisher.js';
+/** Binds the real candidate/publisher pipeline to coordinator ownership and keeps
+ * its lease alive through terminal publication. Model reports are never input. */
+export function createLocalFixExecutionHost(composition) {
+    const registration = composition.registration ? structuredClone(composition.registration) : undefined;
+    return { prepare: async (input) => {
+            try {
+                const scope = input.job.taskPackage.local_fix_scope;
+                if (!registration || !scope)
+                    throw Error();
+                for (const field of ['host_release_sha256', 'test_isolation_sha256', 'publisher_release_sha256'])
+                    if (!/^[a-f0-9]{64}$/.test(registration.receipt[field]) || registration.receipt[field] !== scope[field])
+                        throw Error();
+                const ids = scope.required_commands, entries = scope.registered_tests;
+                if (!Array.isArray(ids) || !ids.length || new Set(ids).size !== ids.length || ids.length !== registration.commands.length)
+                    throw Error();
+                for (const c of registration.commands) {
+                    if (c.candidateReadPaths?.some(p => !Array.isArray(scope.allowed_paths) || !scope.allowed_paths.includes(p) || Object.hasOwn(c.integrity.readFiles, p)))
+                        throw Error();
+                    const e = entries[c.id];
+                    if (!ids.includes(c.id) || !e || e.review_status !== 'reviewed' || protocolHash(c) !== protocolHash({ id: c.id, executable: e.executable, argv: e.argv, integrity: { executableSha256: e.executable_sha256, readFiles: e.read_files }, ...('candidate_read_paths' in e ? { candidateReadPaths: e.candidate_read_paths } : {}) }))
+                        throw Error();
+                }
+            }
+            catch {
+                throw Error('LOCAL_FIX_HOST_REGISTRATION_REJECTED');
+            }
+            const session = await composition.prepare(input);
+            let closed = false, closing, finalization;
+            return {
+                finalize() {
+                    if (closed)
+                        return Promise.reject(new Error('LOCAL_FIX_SESSION_CLOSED'));
+                    if (!finalization)
+                        finalization = (async () => {
+                            const candidate = await session.verifier.verify();
+                            if (closed)
+                                throw Error('LOCAL_FIX_SESSION_CLOSED');
+                            let publication;
+                            try {
+                                publication = await session.publisher.publish(candidate);
+                            }
+                            catch {
+                                throw new PublicationOutcomeUnknownError();
+                            }
+                            const e = candidate.evidence;
+                            return { publication_id: publication.publication_id, status: 'completed', candidate_fingerprint: e.candidate_fingerprint, snapshot_fingerprint: e.snapshot_fingerprint, verification_fingerprint: e.verification_fingerprint, commit_sha: publication.committed_sha, working_branch: e.working_branch, pr_url: publication.pull_request_url, pull_request_provider_id: publication.pull_request_id, changed_files: e.changed_files.map(f => f.path), diff_hash: e.diff_hash, changed_file_manifest_hash: e.changed_file_manifest_hash };
+                        })();
+                    return finalization;
+                },
+                close() { closed = true; return closing ??= session.close(); },
+            };
+        } };
+}

package/dist/src/publication/git-credential-broker.js

@@ -0,0 +1,150 @@
+import { spawn } from 'node:child_process';
+import { lstat, realpath, readFile, mkdtemp, chmod, rm } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import path from 'node:path';
+import { measureCommandFile } from '../safety/registered-command-integrity.js';
+const denied = () => Error('GIT_CREDENTIAL_SCOPE_REJECTED');
+export const publicationGitConfig = '[core]\nrepositoryformatversion = 0\nbare = false\nhooksPath = /dev/null\nfsmonitor = false\n';
+export function strictPublicationOrigin(origin) {
+    const url = new URL(origin);
+    if (url.protocol !== 'https:' || url.username || url.password || url.port || url.search || url.hash || url.href !== origin || !/^\/[A-Za-z0-9_-]+\/[A-Za-z0-9_.-]+\.git$/.test(url.pathname) || url.pathname.includes('..') || !/^[a-z0-9.-]+$/.test(url.hostname))
+        throw denied();
+}
+export async function assertPinnedGit(file) { if (!path.isAbsolute(file.executable) || await realpath(file.executable) !== file.executable || await measureCommandFile(file.executable) !== file.sha256)
+    throw denied(); }
+export async function assertPrivateCheckout(checkout, privateRoot) {
+    if (!path.isAbsolute(privateRoot) || await realpath(privateRoot) !== privateRoot || !checkout.startsWith(privateRoot + '/') || await realpath(checkout) !== checkout)
+        throw denied();
+    for (const dir of [privateRoot, checkout, path.join(checkout, '.git')]) {
+        const s = await lstat(dir);
+        if (!s.isDirectory() || s.isSymbolicLink() || (s.mode & 0o077) || (process.getuid && s.uid !== process.getuid()))
+            throw denied();
+    }
+    if (await readFile(path.join(checkout, '.git', 'config'), 'utf8') !== publicationGitConfig)
+        throw denied();
+}
+/** No inherited auth, proxy, Git/SSH config or helper environment. */
+export function publicationGitEnvironment() { return { PATH: '/usr/bin:/bin', HOME: '/nonexistent', LANG: 'C', LC_ALL: 'C', GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_ATTR_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0', GIT_NO_REPLACE_OBJECTS: '1', GIT_OPTIONAL_LOCKS: '0' }; }
+export const publicationGitArgs = ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-c', 'core.attributesFile=/dev/null', '-c', 'core.excludesFile=/dev/null', '-c', 'core.logAllRefUpdates=false', '-c', 'credential.helper=', '-c', 'http.followRedirects=false', '-c', 'protocol.allow=never', '-c', 'protocol.https.allow=always'];
+/** Private one-operation Unix socket serves credentials only to the pinned Git
+ * helper for the registered HTTPS host and repository path. Secrets never enter
+ * argv/environment/disk. Owner-only directories/socket protect other UIDs; the
+ * required model/tool shutdown and OS confinement protect against the same UID. */
+export class ScopedGitCredentialBroker {
+    options;
+    constructor(options) { this.options = { ...options, git: { ...options.git }, remoteHelper: { ...options.remoteHelper }, node: options.node ? { ...options.node } : undefined, credentialHelper: options.credentialHelper ? { ...options.credentialHelper } : undefined }; }
+    async validate(scope) {
+        const o = this.options;
+        strictPublicationOrigin(o.origin);
+        if (scope.origin !== o.origin || !/^ai-work\/local\/[A-Za-z0-9-]+$/.test(o.branch) || scope.ref !== `refs/heads/${o.branch}` || !/^[a-f0-9]{40}$/.test(scope.sha) || !await o.current() || !o.privateRoot)
+            throw denied();
+        await assertPrivateCheckout(scope.checkout, o.privateRoot);
+        if (await readFile(path.join(scope.checkout, '.git', 'HEAD'), 'utf8') !== `ref: ${scope.ref}\n` || (await readFile(path.join(scope.checkout, '.git', scope.ref), 'utf8')).trim() !== scope.sha)
+            throw denied();
+        await assertPinnedGit(o.git);
+        await assertPinnedGit(o.remoteHelper);
+        if (!o.node || !o.credentialHelper)
+            throw denied();
+        await assertPinnedGit(o.node);
+        await assertPinnedGit(o.credentialHelper);
+        if (await realpath(path.join(path.dirname(o.remoteHelper.executable), 'git-remote-https')) !== o.remoteHelper.executable)
+            throw denied();
+    }
+    async run(scope, read) {
+        let directory, server;
+        const sockets = new Set();
+        try {
+            const frozen = Object.freeze({ ...scope });
+            await this.validate(frozen);
+            const o = this.options, url = new URL(o.origin);
+            directory = await mkdtemp(path.join(o.privateRoot, 'auth-'));
+            await chmod(directory, 0o700);
+            const socketPath = path.join(directory, 's');
+            let used = false;
+            server = createServer(socket => {
+                sockets.add(socket);
+                socket.on('close', () => sockets.delete(socket));
+                let body = '';
+                socket.setTimeout(10000, () => socket.destroy());
+                socket.on('error', () => { });
+                socket.on('data', chunk => {
+                    body += chunk.toString();
+                    if (body.length > 16384) {
+                        socket.destroy();
+                        return;
+                    }
+                    if (!body.endsWith('\n'))
+                        return;
+                    socket.pause();
+                    void (async () => {
+                        try {
+                            const fields = JSON.parse(body);
+                            if (used || Object.keys(fields).some(k => !['protocol', 'host', 'path', 'username', 'wwwauth[]'].includes(k)) || fields.protocol !== 'https' || fields.host !== url.host || fields.path !== url.pathname.slice(1))
+                                throw denied();
+                            used = true;
+                            await this.validate(frozen);
+                            const credential = await o.authorization(frozen);
+                            if (!credential.username || !credential.password || /[\r\n\0]/.test(credential.username + credential.password) || credential.username.length + credential.password.length > 16384)
+                                throw denied();
+                            await this.validate(frozen);
+                            socket.end(JSON.stringify(credential));
+                        }
+                        catch {
+                            socket.destroy();
+                        }
+                    })();
+                });
+            });
+            await new Promise((resolve, reject) => { server.once('error', reject); server.listen(socketPath, resolve); });
+            await chmod(socketPath, 0o600);
+            // Git parses helper strings using a shell; quote each trusted absolute path.
+            const quote = (value) => "'" + value.replace(/'/g, "'\\''") + "'";
+            const helper = `!${quote(o.node.executable)} ${quote(o.credentialHelper.executable)} --local-fix-helper ${quote(socketPath)}`;
+            const args = [...publicationGitArgs, '-c', 'credential.useHttpPath=true', '-c', `credential.helper=${helper}`, ...(read ? ['ls-remote', '--refs', scope.origin, scope.ref] : ['push', '--porcelain', '--no-verify', scope.origin, `${scope.sha}:${scope.ref}`])];
+            const output = await new Promise((resolve, reject) => {
+                const child = spawn(o.git.executable, args, { cwd: scope.checkout, env: { ...publicationGitEnvironment(), GIT_EXEC_PATH: path.dirname(o.remoteHelper.executable) }, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+                let stdout = '', bytes = 0, settled = false;
+                const fail = () => { if (!settled) {
+                    settled = true;
+                    try {
+                        if (child.pid)
+                            process.kill(-child.pid, 'SIGKILL');
+                    }
+                    catch {
+                        child.kill('SIGKILL');
+                    }
+                    reject(denied());
+                } };
+                const timeout = setTimeout(fail, 60000);
+                child.on('error', fail);
+                child.stdout.on('data', (chunk) => { bytes += chunk.length; if (bytes > 65536)
+                    fail();
+                else
+                    stdout += chunk.toString(); });
+                // Never forward stderr: a failing helper may echo credential material.
+                child.stderr.on('data', () => { });
+                child.on('close', code => { clearTimeout(timeout); if (!settled) {
+                    settled = true;
+                    code === 0 ? resolve(stdout) : reject(denied());
+                } });
+            });
+            await this.validate(frozen);
+            return output;
+        }
+        catch {
+            throw denied();
+        }
+        finally {
+            for (const socket of sockets)
+                socket.destroy();
+            server?.close();
+            if (directory)
+                await rm(directory, { recursive: true, force: true });
+        }
+    }
+    async push(scope) { await this.run(scope, false); }
+    async head(scope) { const output = await this.run(scope, true); if (!output.trim())
+        return null; const lines = output.trim().split('\n'); if (lines.length !== 1)
+        throw denied(); const match = /^([a-f0-9]{40})\t(.+)$/.exec(lines[0]); if (!match || match[2] !== scope.ref)
+        throw denied(); return match[1]; }
+}

package/dist/src/publication/git-credential-helper.js

@@ -0,0 +1,29 @@
+import { connect } from 'node:net';
+/** Dedicated child of pinned Git only. No ambient credential or environment lookup.
+ * Its private socket is passed as an argument; the socket name is not a secret. */
+export async function runGitCredentialHelper(socketPath, operation, input = process.stdin, output = process.stdout) {
+    if (operation !== 'get')
+        return;
+    let body = '';
+    for await (const chunk of input) {
+        body += chunk.toString();
+        if (body.length > 16384)
+            throw Error('CREDENTIAL_REJECTED');
+    }
+    const fields = {};
+    for (const line of body.trim().split('\n')) {
+        const i = line.indexOf('=');
+        if (i < 1 || Object.hasOwn(fields, line.slice(0, i)))
+            throw Error('CREDENTIAL_REJECTED');
+        fields[line.slice(0, i)] = line.slice(i + 1);
+    }
+    const response = await new Promise((resolve, reject) => { const socket = connect(socketPath); let data = ''; socket.setTimeout(10000, () => socket.destroy(Error('timeout'))); socket.on('connect', () => socket.write(JSON.stringify(fields) + '\n')); socket.on('data', chunk => { data += chunk.toString(); if (data.length > 32768)
+        socket.destroy(Error('overflow')); }); socket.on('end', () => resolve(data)); socket.on('error', reject); });
+    const credential = JSON.parse(response);
+    if (!credential.username || !credential.password || /[\r\n\0]/.test(credential.username + credential.password))
+        throw Error('CREDENTIAL_REJECTED');
+    output.write(`username=${credential.username}\npassword=${credential.password}\n\n`);
+}
+if (process.argv[2] === '--local-fix-helper') {
+    runGitCredentialHelper(process.argv[3], process.argv[4]).catch(() => { process.exitCode = 1; });
+}

package/dist/src/publication/git-snapshot.js

@@ -0,0 +1,321 @@
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { constants } from 'node:fs';
+import { lstat, mkdir, mkdtemp, open, realpath, readdir, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { deflateSync } from 'node:zlib';
+import path from 'node:path';
+import { measureCommandFile } from '../safety/registered-command-integrity.js';
+import { protocolHash } from './candidate.js';
+const execute = promisify(execFile), denied = () => Error('SNAPSHOT_REJECTED');
+const digest = (data) => createHash('sha256').update(data).digest('hex');
+const safe = (p) => p.length > 0 && !path.isAbsolute(p) && !p.includes('\\') && !p.includes('\0') && p.split('/').every(s => s !== '' && s !== '.' && s !== '..' && !/^(?:\.git|\.ssh|\.aws|\.codex|\.claude|\.env|\.netrc|\.npmrc|credentials(?:\..*)?)$/i.test(s));
+/** Reads only immutable Git objects and metadata. Never runs diff against worktree
+ * content, where malicious clean filters can execute even with --no-ext-diff. */
+export class GitSnapshotHost {
+    options;
+    seals = new WeakSet();
+    constructor(options) { this.options = structuredClone(options); }
+    async git(args) {
+        const o = this.options;
+        if (!path.isAbsolute(o.git.executable) || await realpath(o.git.executable) !== o.git.executable || await measureCommandFile(o.git.executable) !== o.git.sha256)
+            throw denied();
+        const result = await execute(o.git.executable, ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-c', 'core.attributesFile=/dev/null', '-c', 'core.excludesFile=/dev/null', ...args], { cwd: o.root, encoding: 'buffer', maxBuffer: o.maxTotalBytes, env: { PATH: '/usr/bin:/bin', HOME: '/nonexistent', LANG: 'C', GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_ATTR_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1' } });
+        if (await measureCommandFile(o.git.executable) !== o.git.sha256)
+            throw denied();
+        return result.stdout;
+    }
+    /** One pinned, credential-free process for exact immutable objects, rather
+     * than a subprocess and executable rehash for every file in every observation. */
+    async batchObjects(ids) {
+        const o = this.options, unique = [...new Set(ids)];
+        if (unique.some(id => !/^[a-f0-9]{40}$/.test(id)) || unique.length > 100000)
+            throw denied();
+        if (!unique.length)
+            return new Map();
+        if (await realpath(o.git.executable) !== o.git.executable || await measureCommandFile(o.git.executable) !== o.git.sha256)
+            throw denied();
+        const output = await new Promise((resolve, reject) => {
+            const child = spawn(o.git.executable, ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', 'cat-file', '--batch'], { cwd: o.root, env: { PATH: '/usr/bin:/bin', HOME: '/nonexistent', LANG: 'C', GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_ATTR_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1' }, stdio: ['pipe', 'pipe', 'ignore'] });
+            const chunks = [];
+            let size = 0, failed = false;
+            const fail = () => { if (!failed) {
+                failed = true;
+                child.kill('SIGKILL');
+                reject(denied());
+            } };
+            child.on('error', fail);
+            child.stdin.on('error', fail);
+            child.stdout.on('data', (chunk) => { size += chunk.length; if (size > o.maxTotalBytes + unique.length * 100)
+                fail();
+            else
+                chunks.push(chunk); });
+            child.on('close', code => { if (!failed) {
+                if (code !== 0)
+                    fail();
+                else
+                    resolve(Buffer.concat(chunks));
+            } });
+            child.stdin.end(unique.join('\n') + '\n');
+        });
+        if (await measureCommandFile(o.git.executable) !== o.git.sha256)
+            throw denied();
+        const result = new Map();
+        let offset = 0;
+        for (const id of unique) {
+            const end = output.indexOf(10, offset);
+            if (end < 0 || end - offset > 100)
+                throw denied();
+            const header = /^([a-f0-9]{40}) (blob|tree|commit) ([0-9]+)$/.exec(output.subarray(offset, end).toString());
+            if (!header || header[1] !== id)
+                throw denied();
+            const size = Number(header[3]);
+            if (!Number.isSafeInteger(size) || size < 0 || size > o.maxTotalBytes || end + 1 + size >= output.length || output[end + 1 + size] !== 10)
+                throw denied();
+            const bytes = output.subarray(end + 1, end + 1 + size), type = header[2];
+            if (createHash('sha1').update(Buffer.concat([Buffer.from(`${type} ${size}\0`), bytes])).digest('hex') !== id)
+                throw denied();
+            result.set(id, { type, bytes });
+            offset = end + size + 2;
+        }
+        if (offset !== output.length)
+            throw denied();
+        return result;
+    }
+    async currentFile(relative) {
+        if (!safe(relative))
+            throw denied();
+        const absolute = path.join(this.options.root, relative);
+        let component = this.options.root;
+        const parts = relative.split('/');
+        for (let i = 0; i < parts.length; i++) {
+            component = path.join(component, parts[i]);
+            let stat;
+            try {
+                stat = await lstat(component);
+            }
+            catch (e) {
+                if (e.code === 'ENOENT')
+                    return null;
+                throw e;
+            }
+            if (stat.isSymbolicLink() || (i < parts.length - 1 && !stat.isDirectory()))
+                throw denied();
+        }
+        try {
+            if (await realpath(absolute) !== absolute)
+                throw denied();
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return null;
+            throw e;
+        }
+        const fd = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const before = await fd.stat({ bigint: true });
+            if (!before.isFile() || before.nlink !== 1n || before.size > BigInt(this.options.maxFileBytes))
+                throw denied();
+            const bytes = await fd.readFile(), after = await fd.stat({ bigint: true }), named = await lstat(absolute, { bigint: true });
+            for (const s of [after, named])
+                if (!s.isFile() || s.nlink !== 1n || s.dev !== before.dev || s.ino !== before.ino || s.size !== before.size || s.mtimeNs !== before.mtimeNs || s.ctimeNs !== before.ctimeNs || s.mode !== before.mode)
+                    throw denied();
+            if (BigInt(bytes.length) !== before.size)
+                throw denied();
+            return { path: relative, mode: (Number(before.mode) & 0o111) ? 0o100755 : 0o100644, bytes };
+        }
+        finally {
+            await fd.close();
+        }
+    }
+    async capture() {
+        const o = this.options;
+        if (!/^[a-f0-9]{40}$/.test(o.baseCommitSha) || !/^ai-work\/local\/[A-Za-z0-9-]+$/.test(o.workingBranch) || await realpath(o.root) !== o.root || !Number.isSafeInteger(o.maxFileBytes) || o.maxFileBytes < 1 || !Number.isSafeInteger(o.maxTotalBytes) || o.maxTotalBytes < o.maxFileBytes)
+            throw denied();
+        const head = (await this.git(['rev-parse', '--verify', 'HEAD'])).toString().trim(), branch = (await this.git(['symbolic-ref', '--short', 'HEAD'])).toString().trim();
+        if (head !== o.baseCommitSha || branch !== o.workingBranch)
+            throw denied();
+        const base = new Map(), gitlinks = new Map();
+        for (const line of (await this.git(['ls-tree', '-r', '-z', '--full-tree', o.baseCommitSha])).toString().split('\0').filter(Boolean)) {
+            const link = /^160000 commit ([a-f0-9]{40})\t(.+)$/s.exec(line);
+            if (link) {
+                if (!safe(link[2]))
+                    throw denied();
+                gitlinks.set(link[2], link[1]);
+                continue;
+            }
+            const match = /^(100644|100755) blob ([a-f0-9]{40})\t(.+)$/s.exec(line);
+            if (!match || !safe(match[3]))
+                throw denied();
+            base.set(match[3], { mode: parseInt(match[1], 8), blob: match[2] });
+        }
+        // Gitlinks remain exact base-tree references. Never traverse or copy their source.
+        // Staged replacement/deletion is refused rather than publishing hidden changes.
+        const staged = new Map();
+        for (const line of (await this.git(['ls-files', '--stage', '-z'])).toString().split('\0').filter(Boolean)) {
+            const entry = /^(100644|100755|160000) ([a-f0-9]{40}) 0\t(.+)$/s.exec(line);
+            if (!entry || !safe(entry[3]))
+                throw denied();
+            staged.set(entry[3], entry[1] + ' ' + entry[2]);
+        }
+        const expected = new Map([...base.entries()].map(([name, value]) => [name, value.mode.toString(8) + ' ' + value.blob]));
+        for (const [name, oid] of gitlinks)
+            expected.set(name, '160000 ' + oid);
+        if (protocolHash([...expected].sort()) !== protocolHash([...staged].sort()))
+            throw denied();
+        const names = new Set([...base.keys(), ...(await this.git(['ls-files', '--others', '--exclude-standard', '-z', '--'])).toString().split('\0').filter(Boolean)]);
+        const blobs = await this.batchObjects([...base.values()].map(v => v.blob));
+        const files = [], changes = [];
+        let total = 0;
+        for (const name of [...names].sort()) {
+            if ([...gitlinks.keys()].some(p => name === p || name.startsWith(p + '/')))
+                throw denied();
+            const current = await this.currentFile(name), prior = base.get(name);
+            let before = null;
+            if (prior) {
+                const blob = blobs.get(prior.blob);
+                if (!blob || blob.type !== 'blob')
+                    throw denied();
+                before = blob.bytes;
+                if (before.length > o.maxFileBytes)
+                    throw denied();
+            }
+            total += (before?.length ?? 0) + (current?.bytes.length ?? 0);
+            if (total > o.maxTotalBytes)
+                throw denied();
+            if (current)
+                files.push(current);
+            if (!prior || !current || !before.equals(current.bytes) || prior.mode !== current.mode)
+                changes.push({ path: name, status: !prior ? 'added' : !current ? 'deleted' : 'modified', before: before?.toString('base64') ?? null, after: current?.bytes.toString('base64') ?? null, before_mode: prior?.mode ?? null, after_mode: current?.mode ?? null });
+        }
+        const observation = { base_commit_sha: o.baseCommitSha, head_commit_sha: head, working_branch: branch, diff: JSON.stringify({ format: 'local-candidate-binary-diff-v1', changes }), changed_files: changes.map(({ path, status }) => ({ path, status })) };
+        return { observation, files, fingerprint: protocolHash({ observation, files: files.map(f => ({ path: f.path, mode: f.mode, sha256: digest(f.bytes) })) }) };
+    }
+    /** Creates a separate local-only Git checkout with exact base parent objects.
+     * Raw object copying and raw file writes invoke no filters, templates or hooks;
+     * no local fetch/upload-pack, network or account credentials are involved. */
+    async publicationCheckout(sealed) {
+        try {
+            if (!this.seals.has(sealed))
+                throw denied();
+            await sealed.assertUnchanged();
+            const o = this.options, parent = o.privateRoot;
+            if (await realpath(parent) !== parent || (await lstat(parent)).mode & 0o077)
+                throw denied();
+            const root = await mkdtemp(path.join(parent, 'publisher-')), gitdir = path.join(root, '.git');
+            await mkdir(path.join(gitdir, 'objects'), { recursive: true, mode: 0o700 });
+            const ref = path.join(gitdir, 'refs', 'heads', o.workingBranch);
+            await mkdir(path.dirname(ref), { recursive: true, mode: 0o700 });
+            await writeFile(path.join(gitdir, 'HEAD'), `ref: refs/heads/${o.workingBranch}\n`, { mode: 0o600, flag: 'wx' });
+            await writeFile(ref, o.baseCommitSha + '\n', { mode: 0o600, flag: 'wx' });
+            await writeFile(path.join(gitdir, 'config'), '[core]\nrepositoryformatversion = 0\nbare = false\nhooksPath = /dev/null\nfsmonitor = false\n', { mode: 0o600, flag: 'wx' });
+            const objects = new Map([[o.baseCommitSha, 'commit']]);
+            const commit = await this.git(['cat-file', 'commit', o.baseCommitSha]);
+            const tree = /^tree ([a-f0-9]{40})\n/.exec(commit.toString());
+            if (!tree)
+                throw denied();
+            objects.set(tree[1], 'tree');
+            for (const entry of (await this.git(['ls-tree', '-r', '-t', '-z', o.baseCommitSha])).toString().split('\0').filter(Boolean)) {
+                if (/^160000 commit [a-f0-9]{40}\t/.test(entry))
+                    continue;
+                const match = /^(?:100644|100755|040000) (blob|tree) ([a-f0-9]{40})\t/.exec(entry);
+                if (!match)
+                    throw denied();
+                objects.set(match[2], match[1]);
+            }
+            const contents = await this.batchObjects([...objects.keys()]);
+            for (const [oid, type] of objects) {
+                const value = contents.get(oid);
+                if (!value || value.type !== type)
+                    throw denied();
+                const content = value.bytes, raw = Buffer.concat([Buffer.from(`${type} ${content.length}\0`), content]);
+                if (createHash('sha1').update(raw).digest('hex') !== oid)
+                    throw denied();
+                const dir = path.join(gitdir, 'objects', oid.slice(0, 2));
+                await mkdir(dir, { recursive: true, mode: 0o700 });
+                await writeFile(path.join(dir, oid.slice(2)), deflateSync(raw), { flag: 'wx', mode: 0o400 });
+            }
+            const copy = async (from, to) => { for (const name of await readdir(from)) {
+                const source = path.join(from, name), target = path.join(to, name), stat = await lstat(source);
+                if (stat.isSymbolicLink())
+                    throw denied();
+                if (stat.isDirectory()) {
+                    await mkdir(target, { mode: 0o700 });
+                    await copy(source, target);
+                }
+                else {
+                    const fd = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+                    try {
+                        await writeFile(target, await fd.readFile(), { flag: 'wx', mode: (stat.mode & 0o111) ? 0o700 : 0o600 });
+                    }
+                    finally {
+                        await fd.close();
+                    }
+                }
+            } };
+            await copy(sealed.root, root);
+            await sealed.assertUnchanged();
+            return root;
+        }
+        catch {
+            throw denied();
+        }
+    }
+    async observe() { try {
+        const a = await this.capture(), b = await this.capture();
+        if (a.fingerprint !== b.fingerprint)
+            throw denied();
+        return structuredClone(a.observation);
+    }
+    catch {
+        throw denied();
+    } }
+    /** Call only after coordinator has stopped its owned model and revoked tools.
+     * Materialization is outside model grants; permissions are defense in depth,
+     * not independent protection from a malicious process running as the host UID. */
+    async materialize() {
+        try {
+            const parent = this.options.privateRoot;
+            if (await realpath(parent) !== parent)
+                throw denied();
+            const stat = await lstat(parent);
+            if (!stat.isDirectory() || (stat.mode & 0o077) !== 0 || (process.getuid && stat.uid !== process.getuid()))
+                throw denied();
+            const capture = await this.capture(), root = await mkdtemp(path.join(parent, 'candidate-'));
+            for (const f of capture.files) {
+                const file = path.join(root, f.path);
+                await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+                await writeFile(file, f.bytes, { flag: 'wx', mode: (f.mode & 0o111) ? 0o500 : 0o400 });
+            }
+            if ((await this.capture()).fingerprint !== capture.fingerprint)
+                throw denied();
+            const expected = protocolHash(capture.files.map(f => ({ path: f.path, mode: f.mode, sha256: digest(f.bytes) })));
+            const assertUnchanged = async () => {
+                const entries = [];
+                const walk = async (dir, prefix = '') => { for (const item of (await readdir(dir)).sort()) {
+                    const rel = prefix ? prefix + '/' + item : item, file = path.join(dir, item), s = await lstat(file);
+                    if (s.isSymbolicLink())
+                        throw denied();
+                    if (s.isDirectory())
+                        await walk(file, rel);
+                    else {
+                        if (!s.isFile() || s.nlink !== 1 || s.size > this.options.maxFileBytes)
+                            throw denied();
+                        entries.push({ path: rel, mode: (s.mode & 0o111) ? 0o100755 : 0o100644, sha256: await measureCommandFile(file) });
+                    }
+                } };
+                await walk(root);
+                entries.sort((a, b) => a.path < b.path ? -1 : 1);
+                if (protocolHash(entries) !== expected)
+                    throw denied();
+            };
+            await assertUnchanged();
+            const seal = { root, observation: structuredClone(capture.observation), treeFingerprint: expected, assertUnchanged };
+            this.seals.add(seal);
+            return Object.freeze(seal);
+        }
+        catch {
+            throw denied();
+        }
+    }
+}