@userreason/cli 0.1.1 → 0.2.1

package/dist/recommended-surveys.js

@@ -0,0 +1,201 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, open, rename, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { configDirectory } from "./config.js";
+import { sourceHash, verifyFirstSurveySource, } from "./first-survey-source.js";
+import { prepareFirstSurveyLocally, } from "./first-survey-preparation.js";
+const record = (v) => v && typeof v === "object" && !Array.isArray(v)
+    ? v
+    : {};
+/** One optional selection; all drafts stay unpublished and match no audience. */
+export async function recommendedSurveys(client, root, workspace, site, ui, options = {}) {
+    if (!options.sourceConsent)
+        return { state: "skipped" };
+    if (!ui.chooseMany)
+        throw Error("Survey selection requires a checkbox interface");
+    const scope = {
+        api: client.config.apiUrl,
+        workspace_id: workspace,
+        site_id: site,
+    };
+    const scopeKey = sourceHash(JSON.stringify([root, scope]));
+    const dir = join(configDirectory(), "recommended-surveys");
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const path = join(dir, scopeKey + ".json");
+    const lock = await open(path + ".lock", "wx", 0o600);
+    const preparation = options.preparation ?? prepareFirstSurveyLocally(root);
+    let state = {
+        version: 1,
+        scope: scopeKey,
+        expires: Date.now() + 7 * 86400000,
+        candidates: [],
+        sources: [],
+        receipts: {},
+    };
+    const save = async () => {
+        const tmp = path + "." + randomUUID() + ".tmp";
+        await writeFile(tmp, JSON.stringify(state), { flag: "wx", mode: 0o600 });
+        await rename(tmp, path);
+    };
+    const check = () => ui.signal?.throwIfAborted();
+    try {
+        try {
+            const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                if ((await file.stat()).size > 128000)
+                    throw Error("Invalid recommendation cache");
+                const old = JSON.parse(await file.readFile("utf8"));
+                if (old.version !== 1 || old.scope !== scopeKey)
+                    throw Error("Recommendation scope changed");
+                if (old.expires > Date.now())
+                    state = old;
+            }
+            finally {
+                await file.close();
+            }
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                throw e;
+        }
+        check();
+        // A previous selected save can be retried without changing its definitions or IDs.
+        if (!state.selected) {
+            if (state.candidates.length) {
+                try {
+                    await verifyFirstSurveySource(root, state.sources);
+                }
+                catch {
+                    state.candidates = [];
+                    state.sources = [];
+                }
+            }
+            if (!state.candidates.length) {
+                const generate = async () => {
+                    const preview = await preparation.take(ui.signal);
+                    if (!preview.evidence.length)
+                        throw Error("No product source available");
+                    const metadata = record(await client.request("/onboarding/v1/planning/describe", { schema_version: 1, session_id: randomUUID(), scope }, ui.signal));
+                    if (!record(metadata.recommendations).version)
+                        throw Error("Development recommendation pipeline is unavailable");
+                    await verifyFirstSurveySource(root, preview.evidence);
+                    const response = record(await client.request("/onboarding/v1/planning/analyze", {
+                        schema_version: 1,
+                        session_id: randomUUID(),
+                        request_id: randomUUID(),
+                        scope,
+                        packages: preview.packages,
+                        capabilities: [
+                            ...preview.capabilities,
+                            "recommended_surveys:v1",
+                        ],
+                        evidence: preview.evidence,
+                        previous_plan_digest: null,
+                        limits: {
+                            input_tokens: 12000,
+                            output_tokens: 4000,
+                            deadline_ms: 40000,
+                        },
+                        consent: {
+                            packet_digest: sourceHash(JSON.stringify(preview.evidence)),
+                            destination: metadata.destination,
+                            configuration_fingerprint: metadata.configuration_fingerprint,
+                            policy_version: "first-survey-v1",
+                            authorized_at: new Date().toISOString(),
+                            git_authorized: false,
+                        },
+                    }, ui.signal));
+                    await verifyFirstSurveySource(root, preview.evidence);
+                    const candidates = record(response.result).candidates;
+                    if (!Array.isArray(candidates))
+                        throw Error("Invalid recommendations");
+                    state.candidates = candidates.slice(0, 3);
+                    state.sources = preview.evidence.map(({ path, file_hash }) => ({
+                        path,
+                        file_hash,
+                    }));
+                    await save();
+                };
+                try {
+                    if (ui.loading)
+                        await ui.loading("Finding recommended surveys", generate);
+                    else
+                        await generate();
+                }
+                catch (error) {
+                    check();
+                    ui.show("Recommendations are unavailable right now. Setup is complete; rerun the wizard to try again.");
+                    return {
+                        state: "unavailable",
+                        error: error instanceof Error ? error.message : "unavailable",
+                    };
+                }
+            }
+            if (!state.candidates.length) {
+                ui.show("No supported survey recommendations yet. Setup is complete.");
+                return { state: "empty" };
+            }
+            ui.show("Select surveys to get started. We’ll create drafts in your workspace. Nothing will be published.");
+            const selected = await ui.chooseMany("Recommended surveys", state.candidates.map((c) => ({
+                value: c.id,
+                label: `${String(c.definition.name)} — ${c.question}`,
+                hint: `${c.opportunity.claim} Delivery can be configured later.`,
+            })), []);
+            check();
+            if (!selected.length)
+                return { state: "skipped" };
+            if (new Set(selected).size !== selected.length ||
+                selected.some((id) => !state.candidates.some((c) => c.id === id)))
+                throw Error("Invalid survey selection");
+            await verifyFirstSurveySource(root, state.sources);
+            // Validate all selected drafts before writing any of them.
+            for (const id of selected) {
+                const c = state.candidates.find((c) => c.id === id);
+                const validation = record(await client.read("prompts.validate", {
+                    workspaceId: workspace,
+                    siteId: site,
+                    definition: c.definition,
+                }));
+                if (validation.valid !== true)
+                    throw Error("A recommended draft did not validate");
+            }
+            state.selected = selected;
+            for (const id of selected)
+                state.receipts[id] = {
+                    prompt: randomUUID(),
+                    request: randomUUID(),
+                    definition: state.candidates.find((c) => c.id === id).definition,
+                };
+            await save();
+        }
+        let count = 0;
+        for (const id of state.selected) {
+            check();
+            const receipt = state.receipts[id];
+            if (!receipt)
+                throw Error("Missing draft receipt");
+            if (!receipt.result) {
+                receipt.result = await client.promptCommand({
+                    workspaceId: workspace,
+                    siteId: site,
+                    action: "create",
+                    promptId: receipt.prompt,
+                    requestId: receipt.request,
+                    definition: receipt.definition,
+                });
+                await save();
+            }
+            const saved = record(receipt.result), link = record(saved.links).edit;
+            ui.show(`Draft saved: ${String(receipt.definition.name)}${typeof link === "string" ? `\n${link}` : ""}`);
+            count++;
+        }
+        ui.show(`${count} survey draft${count === 1 ? "" : "s"} saved. Nothing was published.`);
+        return { state: "saved", count, receipts: state.receipts };
+    }
+    finally {
+        preparation.cancel();
+        await lock.close();
+        await unlink(path + ".lock");
+    }
+}

package/dist/setup-diagnostics.d.ts

@@ -0,0 +1,2 @@
+/** Bounded, local-only diagnostics. Never include these in setup API requests. */
+export declare function sanitizeSetupDiagnostic(value: string, secrets?: string[]): string;

package/dist/setup-diagnostics.js

@@ -0,0 +1,26 @@
+/** Bounded, local-only diagnostics. Never include these in setup API requests. */
+export function sanitizeSetupDiagnostic(value, secrets = []) {
+    let text = value.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
+    const environmentSecrets = Object.entries(process.env)
+        .filter(([key, value]) => /token|secret|password|api[_-]?key|authorization/i.test(key) && value && value.length >= 4)
+        .map(([, value]) => value);
+    for (const secret of [...secrets, ...environmentSecrets].filter(value => value.length >= 4).sort((a, b) => b.length - a.length))
+        text = text.split(secret).join('[redacted]');
+    text = text.replace(/\b(Bearer|Basic)\s+[^\s]+/gi, '$1 [redacted]');
+    text = text.replace(/((?:_authToken|_password|password|access_token|refresh_token|api_key|authorization)\s*[:=]\s*)[^\s]+/gi, '$1[redacted]');
+    text = text.replace(/\b(?:gh[pousr]_[A-Za-z0-9_]+|github_pat_[A-Za-z0-9_]+|npm_[A-Za-z0-9]+|sk-[A-Za-z0-9_-]{16,})\b/g, '[redacted]');
+    text = text.replace(/https?:\/\/[^\s<>"']+/g, value => {
+        try {
+            const url = new URL(value);
+            url.username = '';
+            url.password = '';
+            url.search = '';
+            url.hash = '';
+            return url.toString();
+        }
+        catch {
+            return '[invalid URL]';
+        }
+    });
+    return text.trim().slice(0, 8000);
+}

package/dist/setup-executor.d.ts

@@ -0,0 +1,42 @@
+import { type BrowserSetupClient } from './setup.js';
+import { type SetupLocalPlan, type SetupEffect, type SetupSessionView } from './setup-wire.js';
+import { SetupHeartbeat } from './setup-heartbeat.js';
+import { type SetupLocalFile } from './setup-files.js';
+export interface PreparedSetupOperation {
+    effect: SetupEffect;
+    files: SetupLocalFile[];
+    guards?: {
+        path: string;
+        before_hash: string | null;
+    }[];
+}
+export interface PreparedSetupPlan {
+    wire: SetupLocalPlan;
+    operations: PreparedSetupOperation[];
+}
+export interface SetupExecutorRuntime {
+    prepare(session: SetupSessionView): Promise<PreparedSetupPlan>;
+    /** Only a locally prepared allowlisted operation is passed here, never a server script. */
+    apply(operation: PreparedSetupOperation, signal: AbortSignal): Promise<'verified' | 'already_present'>;
+    /** Installed package versions require a runtime check in addition to file hashes. */
+    verify?(operation: PreparedSetupOperation): Promise<boolean>;
+}
+export interface SetupExecutorOptions {
+    signal?: AbortSignal;
+    pollMs?: number;
+    heartbeatMs?: number;
+    maxPolls?: number;
+    sleep?: (ms: number) => Promise<void>;
+    onSession?: (session: SetupSessionView) => void;
+    /** Sanitized local detail, retained in the private journal, never sent to the API. */
+    onOperationError?: (failure: {
+        kind: SetupEffect['kind'];
+        message: string;
+        receiptPath: string;
+    }) => void;
+}
+export type SetupExecutorClient = Pick<BrowserSetupClient, 'identity' | 'poll' | 'plan' | 'claim' | 'startCommand' | 'report' | 'heartbeat' | 'reconcile'>;
+/** Bounded local cleanup never restores authority or follows an unknown file/link. */
+export declare function pruneSetupExecutionReceipts(now?: number): Promise<number>;
+/** Runs only after browser approval. Durable intents precede effects and durable outcomes precede reports. */
+export declare function runSetupExecutor(client: SetupExecutorClient, directory: string, runtime: SetupExecutorRuntime, options?: SetupExecutorOptions, sharedHeartbeat?: SetupHeartbeat): Promise<SetupSessionView>;

package/dist/setup-executor.js

@@ -0,0 +1,350 @@
+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 { SetupHeartbeat, observeSetupClient, setupAbortable } from './setup-heartbeat.js';
+import { readSetupFile, setupDigest, setupHash, verifySetupFiles } from './setup-files.js';
+import { sanitizeSetupDiagnostic } from './setup-diagnostics.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', 'diagnostic', 'outputs', 'request_id'].includes(key)) ||
+            (receipt.diagnostic !== undefined && (typeof receipt.diagnostic !== 'string' || receipt.diagnostic.length > 8000)) ||
+            !/^[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 = {}, sharedHeartbeat) {
+    if (await setupProjectFingerprint(directory) !== client.identity.project_fingerprint)
+        throw new SetupError('setup_binding_mismatch', 'This executor belongs to another project.');
+    const heartbeat = sharedHeartbeat ?? new SetupHeartbeat(client, options);
+    client = observeSetupClient(client, heartbeat, options.signal);
+    try {
+        return await withSetupProjectLock(directory, async () => {
+            const path = await journalPath(client), journal = await loadJournal(path, client);
+            const shownErrors = new Set();
+            const showError = (id, receipt) => {
+                if (!receipt.diagnostic || shownErrors.has(id))
+                    return;
+                const operation = journal.plan?.operations.find(item => setupDigest(item.effect) === receipt.input_digest);
+                if (!operation)
+                    return;
+                shownErrors.add(id);
+                try {
+                    options.onOperationError?.({ kind: operation.effect.kind, message: sanitizeSetupDiagnostic(receipt.diagnostic), receiptPath: path });
+                }
+                catch { /* A display callback cannot prevent the durable result report. */ }
+            };
+            for (const [id, receipt] of Object.entries(journal.receipts))
+                showError(id, receipt);
+            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) {
+                heartbeat.check();
+                session = heartbeat.latest(session);
+                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) {
+                        await heartbeat.pulse();
+                        heartbeat.check();
+                        session = heartbeat.latest(session);
+                        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 setupAbortable(runtime.prepare(session), heartbeat.signal));
+                        journal.target_digest = targetDigest;
+                        journal.plan_request_id = randomUUID();
+                        await saveJournal(path, journal);
+                    }
+                    try {
+                        session = await client.plan({ ...scope, request_id: journal.plan_request_id, expected_revision: session.revision, plan: journal.plan.wire });
+                    }
+                    catch (error) {
+                        if (!(error instanceof SetupError) || error.code !== 'revision_conflict')
+                            throw error;
+                        session = await client.poll();
+                    }
+                    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') {
+                    await heartbeat.pulse();
+                    heartbeat.check();
+                    session = heartbeat.latest(session);
+                    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, diagnostic: receipt?.diagnostic, 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);
+                heartbeat.setLease(lease);
+                session = await client.startCommand(lease);
+                receipt.stage = 'running';
+                await saveJournal(path, journal);
+                const operationSignal = heartbeat.signal;
+                try {
+                    operationSignal.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, operationSignal);
+                    operationSignal.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: operationSignal.aborted ? 'outcome_unknown' : error instanceof SetupError && error.code === 'setup_files_changed' ? 'review_required' : 'operation_failed' } };
+                    receipt.diagnostic = sanitizeSetupDiagnostic(error instanceof Error ? error.message : 'Local operation failed without an error message.');
+                }
+                receipt.stage = 'settled';
+                journal.claim_request_id = randomUUID();
+                await saveJournal(path, journal);
+                showError(command.operation_id, receipt);
+                // A lost report is retried from its saved receipt on resume; the effect is never rerun.
+                session = await heartbeat.duringReport(() => client.report({ ...lease, ...receipt.outcome }));
+            }
+        });
+    }
+    finally {
+        if (!sharedHeartbeat)
+            await heartbeat.stop();
+    }
+}

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