@userreason/cli 0.1.1 → 0.2.0

package/dist/setup-executor.js

@@ -0,0 +1,329 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, opendir, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { SetupError, setupPrivateDirectory, setupProjectFingerprint, withSetupProjectLock } from './setup-store.js';
+import { parseSetupCommandResultInput, parseSetupLocalPlan } from './setup-wire.js';
+import { readSetupFile, setupDigest, setupHash, verifySetupFiles } from './setup-files.js';
+const terminal = new Set(['complete', 'cancelled', 'expired']);
+const stopped = new Set(['ready_for_recommendations', 'analyzing', 'selecting_drafts', 'creating_drafts', 'agent_test']);
+const limit = 8_000_000;
+const retention = 7 * 86_400_000;
+function validatePrepared(value) {
+    if (!value || Object.keys(value).some(key => !['wire', 'operations'].includes(key)))
+        throw new SetupError('setup_plan_invalid', 'Invalid local plan.');
+    const wire = parseSetupLocalPlan(value.wire);
+    if (!Array.isArray(value.operations) || value.operations.length !== wire.effects.length)
+        throw new SetupError('setup_plan_invalid', 'The local plan is incomplete.');
+    for (const effect of wire.effects) {
+        const operation = value.operations.find(item => item.effect.effect_id === effect.effect_id);
+        if (!operation || setupDigest(operation.effect) !== setupDigest(effect) || operation.files.length !== effect.files.length)
+            throw new SetupError('setup_plan_invalid', 'The local operation differs from its reviewed metadata.');
+        if (Object.keys(operation).some(key => !['effect', 'files', 'guards'].includes(key)))
+            throw new SetupError('setup_plan_invalid', 'Unknown local operation metadata.');
+        for (const file of operation.files) {
+            const metadata = effect.files.find(item => item.path === file.path);
+            if (Object.keys(file).some(key => !['path', 'before', 'after'].includes(key)) || !metadata || typeof file.after !== 'string' || file.before !== null && typeof file.before !== 'string' ||
+                metadata.before_hash !== (file.before === null ? null : setupHash(file.before)) || metadata.after_hash !== setupHash(file.after))
+                throw new SetupError('setup_plan_invalid', 'The reviewed file hashes do not match the local plan.');
+        }
+        if (new Set(operation.files.map(file => file.path)).size !== operation.files.length)
+            throw new SetupError('setup_plan_invalid', 'The local plan contains duplicate paths.');
+        if (operation.guards && (!Array.isArray(operation.guards) || operation.guards.length > 8 || new Set(operation.guards.map(item => item.path)).size !== operation.guards.length || operation.guards.some(item => Object.keys(item).some(key => !['path', 'before_hash'].includes(key)) || !['.npmrc', '.yarnrc', '.yarnrc.yml'].includes(item.path) || item.before_hash !== null && !/^[a-f0-9]{64}$/.test(item.before_hash))))
+            throw new SetupError('setup_plan_invalid', 'Invalid local package configuration guards.');
+    }
+    return { wire, operations: value.operations };
+}
+async function journalPath(client) {
+    const directory = await setupPrivateDirectory('receipts');
+    await pruneSetupExecutionReceipts();
+    return join(directory, `${setupHash(`${client.identity.api_url}\n${client.identity.setup_id}`)}.json`);
+}
+/** Bounded local cleanup never restores authority or follows an unknown file/link. */
+export async function pruneSetupExecutionReceipts(now = Date.now()) {
+    const directory = await setupPrivateDirectory('receipts');
+    let removed = 0, scanned = 0, bytes = 0;
+    for await (const entry of await opendir(directory)) {
+        if (++scanned > 128)
+            break;
+        if (!entry.isFile() || !/^[a-f0-9]{64}\.json$/.test(entry.name))
+            continue;
+        const path = join(directory, entry.name);
+        let handle;
+        try {
+            const info = await lstat(path);
+            if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1 || info.size > limit)
+                continue;
+            bytes += info.size;
+            if (bytes > 16_000_000)
+                break;
+            handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+            const opened = await handle.stat();
+            if (opened.ino !== info.ino || opened.dev !== info.dev)
+                continue;
+            const data = JSON.parse(await handle.readFile('utf8'));
+            validateJournal(data, data, false);
+            if (data.version !== 1 || typeof data.api_url !== 'string' || typeof data.setup_id !== 'string' || entry.name !== `${setupHash(`${data.api_url}\n${data.setup_id}`)}.json` ||
+                !Number.isFinite(Date.parse(data.created_at)) || Date.parse(data.retain_until) > Date.parse(data.created_at) + retention || !(Date.parse(data.retain_until) < now))
+                continue;
+            const current = await lstat(path);
+            if (current.ino === info.ino && current.dev === info.dev && current.isFile() && !current.isSymbolicLink()) {
+                await rm(path);
+                removed++;
+            }
+        }
+        catch { /* Unknown or damaged files stay for explicit local review. */ }
+        finally {
+            await handle?.close();
+        }
+    }
+    return removed;
+}
+function validateJournal(data, identity, active = true) {
+    const uuid = (value) => typeof value === 'string' && /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i.test(value);
+    if (Object.keys(data).some(key => !['version', 'setup_id', 'api_url', 'project_fingerprint', 'created_at', 'retain_until', 'plan', 'target_digest', 'plan_request_id', 'claim_request_id', 'receipts'].includes(key)) ||
+        data.version !== 1 || !uuid(data.setup_id) || typeof data.api_url !== 'string' || !/^[a-f0-9]{64}$/.test(data.project_fingerprint) || data.setup_id !== identity.setup_id || data.api_url !== identity.api_url || data.project_fingerprint !== identity.project_fingerprint ||
+        !Number.isFinite(Date.parse(data.created_at)) || !Number.isFinite(Date.parse(data.retain_until)) || Date.parse(data.retain_until) <= Date.parse(data.created_at) || Date.parse(data.retain_until) > Date.parse(data.created_at) + retention ||
+        !data.receipts || typeof data.receipts !== 'object' || Array.isArray(data.receipts) || Object.keys(data.receipts).length > 32 ||
+        !uuid(data.plan_request_id) || !uuid(data.claim_request_id) || data.target_digest !== undefined && !/^[a-f0-9]{64}$/.test(data.target_digest))
+        throw new Error('invalid receipt');
+    if (active && Date.parse(data.retain_until) <= Date.now())
+        throw new Error('expired local receipt');
+    if (data.plan)
+        data.plan = validatePrepared(data.plan);
+    for (const [operationId, receipt] of Object.entries(data.receipts)) {
+        if (!uuid(operationId) || !receipt || typeof receipt !== 'object' || Array.isArray(receipt) ||
+            Object.keys(receipt).some(key => !['input_digest', 'stage', 'outcome', 'outputs', 'request_id'].includes(key)) ||
+            !/^[a-f0-9]{64}$/.test(receipt.input_digest) || !['claimed', 'running', 'settled'].includes(receipt.stage) || !uuid(receipt.request_id) ||
+            (receipt.stage === 'settled') !== Boolean(receipt.outcome))
+            throw new Error('invalid operation receipt');
+        const operation = data.plan?.operations.find(item => setupDigest(item.effect) === receipt.input_digest);
+        if (!operation)
+            throw new Error('receipt has no prepared operation');
+        if (receipt.outcome) {
+            const parsed = parseSetupCommandResultInput({ schema_version: 1, setup_id: data.setup_id, operation_id: operationId, executor_generation: 1, lease_generation: 1, ...receipt.outcome });
+            if (Object.keys(receipt.outcome).some(key => !['status', 'result'].includes(key)))
+                throw new Error('invalid outcome');
+            receipt.outcome = { status: parsed.status, result: parsed.result };
+        }
+        if (receipt.outputs !== undefined) {
+            const allowed = operation.effect.kind === 'install_packages' ? operation.effect.managed_outputs?.map(item => item.path) ?? [] : [];
+            if (!receipt.outputs || typeof receipt.outputs !== 'object' || Array.isArray(receipt.outputs) || Object.entries(receipt.outputs).some(([key, value]) => !allowed.includes(key) || value !== null && (typeof value !== 'string' || !/^[a-f0-9]{64}$/.test(value))))
+                throw new Error('invalid managed outputs');
+        }
+    }
+    return data;
+}
+async function loadJournal(path, client) {
+    let handle;
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1 || info.size > limit)
+            throw new Error('unsafe receipt');
+        handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const current = await handle.stat();
+        if (info.ino !== current.ino || info.dev !== current.dev || current.size > limit)
+            throw new Error('changed receipt');
+        const bytes = await handle.readFile();
+        if (bytes.length > limit)
+            throw new Error('large receipt');
+        const data = JSON.parse(bytes.toString());
+        return validateJournal(data, client.identity);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            const now = Date.now();
+            return { version: 1, setup_id: client.identity.setup_id, api_url: client.identity.api_url, project_fingerprint: client.identity.project_fingerprint, created_at: new Date(now).toISOString(), retain_until: new Date(now + retention).toISOString(), plan_request_id: randomUUID(), claim_request_id: randomUUID(), receipts: {} };
+        }
+        throw new SetupError('setup_receipt_invalid', 'The local receipt needs review. No local effects were repeated.');
+    }
+    finally {
+        await handle?.close();
+    }
+}
+async function saveJournal(path, journal) {
+    const contents = JSON.stringify(journal);
+    if (Buffer.byteLength(contents) > limit)
+        throw new SetupError('setup_plan_too_large', 'The prepared local plan exceeds the private receipt limit.');
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        const handle = await open(temporary, 'wx', 0o600);
+        try {
+            await handle.writeFile(contents);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => { });
+    }
+}
+async function outputs(directory, operation) {
+    const entries = operation.effect.kind === 'install_packages' ? operation.effect.managed_outputs ?? [] : [];
+    const result = {};
+    for (const file of entries) {
+        const content = await readSetupFile(directory, file.path);
+        result[file.path] = content === null ? null : setupHash(content);
+    }
+    return result;
+}
+async function verified(directory, operation, runtime, receipt) {
+    if (!await verifySetupFiles(directory, operation.files, 'after'))
+        return false;
+    const managed = operation.effect.kind === 'install_packages' ? operation.effect.managed_outputs ?? [] : [];
+    if (managed.length && (!receipt?.outputs || setupDigest(await outputs(directory, operation)) !== setupDigest(receipt.outputs)))
+        return false;
+    return runtime.verify ? runtime.verify(operation) : operation.effect.kind !== 'install_packages';
+}
+/** Runs only after browser approval. Durable intents precede effects and durable outcomes precede reports. */
+export async function runSetupExecutor(client, directory, runtime, options = {}) {
+    if (await setupProjectFingerprint(directory) !== client.identity.project_fingerprint)
+        throw new SetupError('setup_binding_mismatch', 'This executor belongs to another project.');
+    return withSetupProjectLock(directory, async () => {
+        const path = await journalPath(client), journal = await loadJournal(path, client);
+        let session = await client.poll(), polls = 0;
+        const scope = { schema_version: 1, setup_id: client.identity.setup_id };
+        const pause = async () => { if (options.sleep)
+            await options.sleep(options.pollMs ?? 2000);
+        else
+            await new Promise((resolve, reject) => { const timer = setTimeout(done, options.pollMs ?? 2000); function done() { options.signal?.removeEventListener('abort', abort); resolve(); } function abort() { clearTimeout(timer); reject(options.signal?.reason); } options.signal?.addEventListener('abort', abort, { once: true }); }); };
+        while (true) {
+            options.signal?.throwIfAborted();
+            options.onSession?.(session);
+            if (terminal.has(session.phase) || stopped.has(session.phase) || options.maxPolls !== undefined && polls++ >= options.maxPolls) {
+                if (session.phase === 'cancelled') {
+                    const known = session.commands.find(command => command.status === 'running' && journal.receipts[command.operation_id]?.outcome);
+                    if (known)
+                        session = await client.report({ ...scope, operation_id: known.operation_id, executor_generation: known.executor_generation, lease_generation: known.lease_generation, ...journal.receipts[known.operation_id].outcome });
+                }
+                return session;
+            }
+            if (session.phase === 'configuring') {
+                if (!session.site_id || !session.workspace_id) {
+                    session = await client.heartbeat({ ...scope, executor_generation: session.executor_generation, operation_id: null, lease_generation: null });
+                    await pause();
+                    session = await client.poll();
+                    continue;
+                }
+                const targetDigest = setupDigest({ workspace_id: session.workspace_id, site_id: session.site_id, api_url: client.identity.api_url });
+                if (!journal.plan || journal.plan.wire.choices_digest !== setupDigest(session.choices) || journal.target_digest !== targetDigest) {
+                    if (Object.keys(journal.receipts).length)
+                        throw new SetupError('setup_plan_changed', 'A completed local plan cannot be replaced without a new setup.');
+                    journal.plan = validatePrepared(await runtime.prepare(session));
+                    journal.target_digest = targetDigest;
+                    journal.plan_request_id = randomUUID();
+                    await saveJournal(path, journal);
+                }
+                session = await client.plan({ ...scope, request_id: journal.plan_request_id, expected_revision: session.revision, plan: journal.plan.wire });
+                continue;
+            }
+            if (!journal.plan || !session.local_plan || setupDigest(session.local_plan) !== setupDigest(journal.plan.wire))
+                throw new SetupError('setup_plan_missing', 'The browser-approved local plan is unavailable on this computer. No effects were applied.');
+            if (session.phase !== 'applying') {
+                session = await client.heartbeat({ ...scope, executor_generation: session.executor_generation, operation_id: null, lease_generation: null });
+                await pause();
+                session = await client.poll();
+                continue;
+            }
+            const unknown = session.commands.find(command => command.status === 'outcome_unknown' || command.status === 'running' || command.status === 'leased' && journal.receipts[command.operation_id]);
+            if (unknown) {
+                const operation = journal.plan.operations.find(item => setupDigest(item.effect) === unknown.input_digest);
+                if (!operation)
+                    throw new SetupError('setup_command_mismatch', 'The command does not match the local reviewed plan.');
+                const receipt = journal.receipts[unknown.operation_id];
+                // A running command belongs to an interrupted process. Wait for the server
+                // to close its lease; never issue the side effect a second time.
+                if (unknown.status !== 'outcome_unknown') {
+                    await pause();
+                    session = await client.poll();
+                    continue;
+                }
+                const stillVerified = await verified(directory, operation, runtime, receipt);
+                const outcome = receipt?.outcome && receipt.outcome.status !== 'succeeded' ? receipt.outcome : stillVerified
+                    ? { status: 'succeeded', result: { code: 'already_present', verified: true } }
+                    : { status: 'manual', result: { code: receipt?.outcome?.status === 'succeeded' ? 'review_required' : 'outcome_unknown' } };
+                const requestId = receipt?.request_id ?? randomUUID();
+                journal.receipts[unknown.operation_id] = { input_digest: unknown.input_digest, stage: 'settled', outcome, outputs: receipt?.outputs, request_id: requestId };
+                await saveJournal(path, journal);
+                session = await client.reconcile({ ...scope, request_id: requestId, project_fingerprint: client.identity.project_fingerprint, executor_generation: session.executor_generation, operation_id: unknown.operation_id, input_digest: unknown.input_digest, ...outcome });
+                continue;
+            }
+            const claimed = await client.claim({ ...scope, request_id: journal.claim_request_id, executor_generation: session.executor_generation });
+            session = claimed.session;
+            const command = claimed.command;
+            if (!command) {
+                await pause();
+                session = await client.poll();
+                continue;
+            }
+            if (command.status !== 'leased')
+                continue;
+            const operation = journal.plan.operations.find(item => item.effect.effect_id === command.input.effect_id);
+            if (!operation || setupDigest(operation.effect) !== command.input_digest || setupDigest(operation.effect) !== setupDigest(command.input))
+                throw new SetupError('setup_command_mismatch', 'The command differs from the approved local plan.');
+            const lease = { ...scope, operation_id: command.operation_id, executor_generation: command.executor_generation, lease_generation: command.lease_generation };
+            if (journal.receipts[command.operation_id])
+                throw new SetupError('setup_replay_refused', 'A local receipt already exists. Reconcile before attempting this command again.');
+            const receipt = { input_digest: command.input_digest, stage: 'claimed', request_id: randomUUID() };
+            journal.receipts[command.operation_id] = receipt;
+            await saveJournal(path, journal);
+            session = await client.startCommand(lease);
+            receipt.stage = 'running';
+            await saveJournal(path, journal);
+            const controller = new AbortController();
+            const abort = () => controller.abort(options.signal?.reason);
+            options.signal?.addEventListener('abort', abort, { once: true });
+            if (options.signal?.aborted)
+                abort();
+            if (terminal.has(session.phase))
+                controller.abort(new Error('Setup ended before local execution'));
+            let heartbeatFailure, heartbeatBusy = false;
+            let inFlightHeartbeat;
+            const timer = setInterval(() => {
+                if (heartbeatBusy)
+                    return;
+                heartbeatBusy = true;
+                inFlightHeartbeat = client.heartbeat(lease).then(value => { session = value; if (terminal.has(value.phase))
+                    controller.abort(new Error('Setup ended')); }, error => { heartbeatFailure = error; controller.abort(error); }).finally(() => { heartbeatBusy = false; });
+            }, options.heartbeatMs ?? 10_000);
+            try {
+                controller.signal.throwIfAborted();
+                if (!await verifySetupFiles(directory, operation.files, 'before'))
+                    throw new SetupError('setup_files_changed', 'Files changed after browser approval.');
+                for (const guard of operation.guards ?? []) {
+                    const content = await readSetupFile(directory, guard.path);
+                    if ((content === null ? null : setupHash(content)) !== guard.before_hash)
+                        throw new SetupError('setup_files_changed', 'A package configuration changed after review.');
+                }
+                if (operation.effect.kind === 'install_packages')
+                    for (const file of operation.effect.managed_outputs ?? []) {
+                        const content = await readSetupFile(directory, file.path);
+                        if ((content === null ? null : setupHash(content)) !== file.before_hash)
+                            throw new SetupError('setup_files_changed', 'Package-manager outputs changed after approval.');
+                    }
+                const code = await runtime.apply(operation, controller.signal);
+                controller.signal.throwIfAborted();
+                receipt.outputs = await outputs(directory, operation);
+                if (!await verified(directory, operation, runtime, receipt))
+                    throw new SetupError('setup_verification_failed', 'The completed effect did not match the reviewed files.');
+                receipt.outcome = { status: 'succeeded', result: { code, verified: true } };
+            }
+            catch (error) {
+                receipt.outcome = { status: error instanceof SetupError && error.code === 'setup_files_changed' ? 'manual' : 'failed', result: { code: controller.signal.aborted || heartbeatFailure ? 'outcome_unknown' : error instanceof SetupError && error.code === 'setup_files_changed' ? 'review_required' : 'operation_failed' } };
+            }
+            finally {
+                clearInterval(timer);
+                await inFlightHeartbeat;
+                options.signal?.removeEventListener('abort', abort);
+            }
+            receipt.stage = 'settled';
+            journal.claim_request_id = randomUUID();
+            await saveJournal(path, journal);
+            // A lost report is retried from its saved receipt on resume; the effect is never rerun.
+            session = await client.report({ ...lease, ...receipt.outcome });
+        }
+    });
+}

package/dist/setup-files.d.ts

@@ -0,0 +1,11 @@
+export declare const setupHash: (value: string | Buffer) => string;
+export declare function setupCanonical(value: unknown): string;
+export declare const setupDigest: (value: unknown) => string;
+export interface SetupLocalFile {
+    path: string;
+    before: string | null;
+    after: string;
+}
+export declare function readSetupFile(directory: string, path: string): Promise<string | null>;
+export declare function writeSetupFile(directory: string, file: SetupLocalFile): Promise<void>;
+export declare function verifySetupFiles(directory: string, files: SetupLocalFile[], state: 'before' | 'after'): Promise<boolean>;

package/dist/setup-files.js

@@ -0,0 +1,96 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, realpath } from 'node:fs/promises';
+import { join, relative, resolve, sep } from 'node:path';
+import { SetupError } from './setup-store.js';
+export const setupHash = (value) => createHash('sha256').update(value).digest('hex');
+export function setupCanonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(setupCanonical).join(',')}]`;
+    if (value && typeof value === 'object')
+        return `{${Object.entries(value).filter(([, v]) => v !== undefined).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${setupCanonical(v)}`).join(',')}}`;
+    return JSON.stringify(value);
+}
+export const setupDigest = (value) => setupHash(setupCanonical(value));
+/** All paths are project relative. Refuse links, hard links and escaping ancestors. */
+async function checkedPath(directory, name, createParents = false) {
+    const root = await realpath(directory);
+    if (!name || name.length > 240 || /[\\:\x00-\x1f\x7f]/.test(name) || name.split('/').some(p => !p || p === '.' || p === '..'))
+        throw new SetupError('setup_path_unsafe', 'The reviewed path must be inside the original real project directory.');
+    const target = resolve(root, name);
+    if (relative(root, target).startsWith(`..${sep}`))
+        throw new SetupError('setup_path_unsafe', 'The reviewed path escapes the project.');
+    let parent = root;
+    for (const part of name.split('/').slice(0, -1)) {
+        parent = join(parent, part);
+        let info = await lstat(parent).catch(error => { if (error.code === 'ENOENT')
+            return null; throw error; });
+        if (!info && createParents) {
+            await mkdir(parent);
+            info = await lstat(parent);
+        }
+        if (!info)
+            return target;
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new SetupError('setup_path_unsafe', 'A reviewed directory was replaced or is a link.');
+    }
+    return target;
+}
+export async function readSetupFile(directory, path) {
+    const target = await checkedPath(directory, path);
+    let before;
+    try {
+        before = await lstat(target);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.size > 2_000_000)
+        throw new SetupError('setup_path_unsafe', 'A reviewed file is not a bounded ordinary file.');
+    const handle = await open(target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const current = await handle.stat();
+        if (before.dev !== current.dev || before.ino !== current.ino || current.nlink !== 1 || current.size > 2_000_000)
+            throw new SetupError('setup_path_unsafe', 'A reviewed file changed while reading.');
+        const bytes = await handle.readFile();
+        if (bytes.length > 2_000_000)
+            throw new SetupError('setup_path_unsafe', 'A reviewed file exceeds the size limit.');
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function writeSetupFile(directory, file) {
+    // Verify drift before creating even a parent directory for a planned file.
+    if (await readSetupFile(directory, file.path) !== file.before)
+        throw new SetupError('setup_files_changed', 'The reviewed file changed. Review a new plan before applying it.');
+    const target = await checkedPath(directory, file.path, true);
+    if (await readSetupFile(directory, file.path) !== file.before)
+        throw new SetupError('setup_files_changed', 'The reviewed file changed. Review a new plan before applying it.');
+    if (file.before === file.after)
+        return;
+    const info = file.before === null ? null : await lstat(target);
+    const handle = await open(target, info ? constants.O_WRONLY | (constants.O_NOFOLLOW ?? 0) : constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o644);
+    try {
+        const now = await handle.stat();
+        if (!now.isFile() || now.nlink !== 1 || info && (now.dev !== info.dev || now.ino !== info.ino))
+            throw new SetupError('setup_files_changed', 'The reviewed file changed while opening.');
+        if (info && await readSetupFile(directory, file.path) !== file.before)
+            throw new SetupError('setup_files_changed', 'The reviewed file changed while opening.');
+        await handle.writeFile(file.after);
+        await handle.truncate(Buffer.byteLength(file.after));
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function verifySetupFiles(directory, files, state) {
+    for (const file of files)
+        if (await readSetupFile(directory, file.path) !== file[state])
+            return false;
+    return true;
+}

package/dist/setup-runner.d.ts

@@ -0,0 +1,14 @@
+import { type BrowserSetupClient } from './setup.js';
+import { type SetupExecutorOptions, type SetupExecutorRuntime } from './setup-executor.js';
+import { type PreparedSetupSource } from './setup-source.js';
+import { type SetupSessionView } from './setup-wire.js';
+export interface BrowserSetupRunnerOptions extends SetupExecutorOptions {
+    onSourceIssue?: (code: string) => void;
+    /** Local display only. Never forward this callback's source content to telemetry. */
+    onSourcePrepared?: (packet: PreparedSetupSource) => void;
+    onSample?: (session: SetupSessionView) => void;
+}
+export type BrowserSetupRunnerClient = Pick<BrowserSetupClient, 'identity' | 'poll' | 'plan' | 'claim' | 'startCommand' | 'report' | 'heartbeat' | 'reconcile' | 'discovery' | 'sourceInfo' | 'sourcePlan' | 'sourceUpload'>;
+/** Browser controls consent and drafts. This runner holds only the setup capability,
+ * executes reviewed local effects, and uploads the separately approved source packet. */
+export declare function runBrowserSetup(client: BrowserSetupRunnerClient, directory: string, runtime: SetupExecutorRuntime, options?: BrowserSetupRunnerOptions): Promise<SetupSessionView>;

package/dist/setup-runner.js

@@ -0,0 +1,142 @@
+import { randomUUID } from 'node:crypto';
+import { realpath } from 'node:fs/promises';
+import { BrowserSetupUnavailable } from './setup.js';
+import { runSetupExecutor } from './setup-executor.js';
+import { prepareSetupSource, restoreSetupSource, verifySetupSource } from './setup-source.js';
+import { SetupError, withSetupProjectLock } from './setup-store.js';
+const terminal = new Set(['complete', 'cancelled', 'expired']);
+const localPhases = new Set(['configuring', 'awaiting_local_approval', 'applying']);
+function pause(milliseconds, options) {
+    options.signal?.throwIfAborted();
+    if (options.sleep)
+        return options.sleep(milliseconds).then(() => options.signal?.throwIfAborted());
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { options.signal?.removeEventListener('abort', abort); resolve(); }, milliseconds);
+        function abort() { clearTimeout(timer); reject(options.signal?.reason); }
+        options.signal?.addEventListener('abort', abort, { once: true });
+    });
+}
+/** Browser controls consent and drafts. This runner holds only the setup capability,
+ * executes reviewed local effects, and uploads the separately approved source packet. */
+export async function runBrowserSetup(client, directory, runtime, options = {}) {
+    // Canonicalize platform parent aliases before the executor verifies the
+    // approved fingerprint. Source descendants still reject every symlink.
+    directory = await realpath(directory);
+    let polls = 0;
+    while (true) {
+        let session = await runSetupExecutor(client, directory, runtime, options);
+        if (terminal.has(session.phase) || localPhases.has(session.phase))
+            return session;
+        const result = await withSetupProjectLock(directory, async () => {
+            let packet, observedPreparation;
+            let preparationAttempted = false, failedPreparationRevision, notifiedSample = false, heartbeatError;
+            const uploadAttempts = new Set(), issues = new Set();
+            const scope = { schema_version: 1, setup_id: client.identity.setup_id };
+            const accept = (next) => { if (BigInt(next.revision) >= BigInt(session.revision))
+                session = next; };
+            const issue = (code) => { if (!issues.has(code)) {
+                issues.add(code);
+                options.onSourceIssue?.(code);
+            } };
+            let sourceAvailable = false;
+            try {
+                sourceAvailable = (await client.discovery()).browser_setup.source_analysis && session.capabilities.source_review;
+            }
+            catch (error) {
+                if (!(error instanceof BrowserSetupUnavailable))
+                    throw error;
+            }
+            let heartbeat;
+            const timer = setInterval(() => {
+                if (heartbeat)
+                    return;
+                heartbeat = client.heartbeat({ ...scope, executor_generation: session.executor_generation, operation_id: null, lease_generation: null })
+                    .then(accept, error => { heartbeatError = error; }).finally(() => { heartbeat = undefined; });
+            }, options.heartbeatMs ?? 10_000);
+            try {
+                while (true) {
+                    options.signal?.throwIfAborted();
+                    if (heartbeatError)
+                        throw heartbeatError;
+                    options.onSession?.(session);
+                    if (terminal.has(session.phase) || localPhases.has(session.phase) || options.maxPolls !== undefined && polls++ >= options.maxPolls)
+                        return session;
+                    if (session.phase === 'agent_test' && session.sample.status === 'waiting' && !notifiedSample) {
+                        notifiedSample = true;
+                        options.onSample?.(session);
+                    }
+                    const source = session.source;
+                    // A browser retry with no preparation (for example provider config
+                    // unavailable) changes revision. Heartbeat never changes revision.
+                    if (!source && failedPreparationRevision && session.revision !== failedPreparationRevision) {
+                        preparationAttempted = false;
+                        failedPreparationRevision = undefined;
+                        issues.clear();
+                    }
+                    if (source?.preparation_id !== observedPreparation) {
+                        // Retry is a new browser decision, never an automatic second spend.
+                        if (observedPreparation && !source)
+                            preparationAttempted = false;
+                        packet = undefined;
+                        observedPreparation = source?.preparation_id;
+                        issues.clear();
+                    }
+                    if (session.phase === 'ready_for_recommendations' && !source && sourceAvailable && !preparationAttempted) {
+                        preparationAttempted = true;
+                        try {
+                            packet = await prepareSetupSource(directory, randomUUID(), options.signal);
+                            options.onSourcePrepared?.(packet);
+                            accept(await client.sourcePlan({ ...scope, request_id: packet.preparation_id, expected_revision: session.revision,
+                                manifest: packet.manifest, packages: packet.packages }));
+                            observedPreparation = session.source?.preparation_id;
+                        }
+                        catch (error) {
+                            options.signal?.throwIfAborted();
+                            failedPreparationRevision = session.revision;
+                            issue(error instanceof SetupError ? error.code : 'source_unavailable');
+                        }
+                    }
+                    else if (source?.status === 'approved' && sourceAvailable && !uploadAttempts.has(source.preparation_id)) {
+                        uploadAttempts.add(source.preparation_id);
+                        try {
+                            const info = await client.sourceInfo();
+                            accept(info.session);
+                            const approved = info.preparation, current = session.source;
+                            if (!approved || current?.status !== 'approved' || approved.preparation_id !== source.preparation_id ||
+                                approved.manifest.packet_digest !== current.packet_digest || approved.configuration.configuration_fingerprint !== current.provider_fingerprint)
+                                throw new SetupError('setup_source_changed', 'Review a new source packet in the browser.');
+                            if (Date.parse(current.expires_at) <= Date.now())
+                                throw new SetupError('planning_consent_expired', 'Review source consent again in the browser.');
+                            // Resume never trusts a stale in-memory packet or stores raw source.
+                            packet = packet?.preparation_id === approved.preparation_id ? packet : await restoreSetupSource(directory, approved, options.signal);
+                            options.onSourcePrepared?.(packet);
+                            await verifySetupSource(directory, packet, options.signal);
+                            if (heartbeatError)
+                                throw heartbeatError;
+                            if (terminal.has(session.phase) || session.source?.preparation_id !== approved.preparation_id || session.source.status !== 'approved')
+                                throw new SetupError('setup_source_changed', 'Source approval changed before upload.');
+                            accept(await client.sourceUpload({ ...scope, preparation_id: packet.preparation_id,
+                                project_fingerprint: client.identity.project_fingerprint, evidence: packet.evidence }));
+                            packet = undefined;
+                        }
+                        catch (error) {
+                            options.signal?.throwIfAborted();
+                            issue(error instanceof SetupError ? error.code : 'source_unavailable');
+                            // A dropped reply can hide an accepted upload. Poll instead of
+                            // resending or collecting a different packet under old consent.
+                        }
+                    }
+                    await pause(options.pollMs ?? 2_000, options);
+                    accept(await client.poll());
+                }
+            }
+            finally {
+                clearInterval(timer);
+                await heartbeat;
+                packet = undefined;
+            }
+        });
+        if (!localPhases.has(result.phase) || options.maxPolls !== undefined)
+            return result;
+    }
+}

package/dist/setup-source.d.ts

@@ -0,0 +1,31 @@
+import { type LocalEvidence } from './first-survey-source.js';
+/** One memory-only packet. The wire manifest contains hashes/ranges, never source text. */
+export interface PreparedSetupSource {
+    preparation_id: string;
+    manifest: {
+        packet_digest: string;
+        snapshot_id: string;
+        files: {
+            path: string;
+            file_hash: string;
+            excerpt_hash: string;
+            bytes: number;
+            start_line: number;
+            end_line: number;
+        }[];
+        omitted_files: number;
+        truncated: boolean;
+        git_included: false;
+    };
+    packages: {
+        name: string;
+        version: string;
+    }[];
+    evidence: LocalEvidence[];
+}
+/** Reuse the bounded application collector without Git, provider calls or local packet persistence. */
+export declare function prepareSetupSource(directory: string, preparationId?: string, signal?: AbortSignal): Promise<PreparedSetupSource>;
+/** An approved preparation is rebuilt with its original snapshot ID; no raw source needs a receipt. */
+export declare function restoreSetupSource(directory: string, approved: Pick<PreparedSetupSource, 'preparation_id' | 'manifest' | 'packages'>, signal?: AbortSignal): Promise<PreparedSetupSource>;
+/** Revalidate immediately before upload; only the immutable reviewed memory packet may leave the process. */
+export declare function verifySetupSource(directory: string, packet: PreparedSetupSource, signal?: AbortSignal): Promise<void>;