@userreason/cli 0.2.0 → 0.2.1

package/dist/setup-executor.js

@@ -4,7 +4,9 @@ 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;
@@ -93,7 +95,8 @@ function validateJournal(data, identity, active = true) {
         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)) ||
+            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');
@@ -179,151 +182,169 @@ async function verified(directory, operation, runtime, receipt) {
     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 = {}) {
+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.');
-    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 });
+    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 });
                 }
-                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 });
+                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 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();
+                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;
                 }
-                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') {
+                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;
                 }
-                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 };
+                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.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.');
+                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.');
                     }
-                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);
+                    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 }));
             }
-            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 });
-        }
-    });
+        });
+    }
+    finally {
+        if (!sharedHeartbeat)
+            await heartbeat.stop();
+    }
 }

package/dist/setup-heartbeat.d.ts

@@ -0,0 +1,268 @@
+import type { BrowserSetupClient } from './setup.js';
+import type { SetupSessionView } from './setup-wire.js';
+/** Stop waiting when this run ends, including user-supplied preparations. */
+export declare function setupAbortable<T>(work: Promise<T>, signal?: AbortSignal): Promise<T>;
+/** One lease-aware heartbeat for the entire run, independent of its current stage. */
+export declare class SetupHeartbeat {
+    private client;
+    private options;
+    private session?;
+    private timer?;
+    private pending?;
+    private stopped;
+    private paused;
+    private failure?;
+    private lease?;
+    private readonly lifetime;
+    readonly signal: AbortSignal;
+    constructor(client: Pick<BrowserSetupClient, 'identity' | 'heartbeat'>, options?: {
+        signal?: AbortSignal;
+        heartbeatMs?: number;
+    });
+    observe(next: SetupSessionView): SetupSessionView;
+    get current(): ({
+        phase: "expired" | "cancelled" | "analyzing" | "configuring" | "awaiting_local_approval" | "applying" | "ready_for_recommendations" | "selecting_drafts" | "creating_drafts" | "agent_test" | "complete";
+        revision: string;
+        workspace_id: string | null;
+        site_id: string | null;
+        project_fingerprint: string;
+        choices: {
+            install_sdk: boolean;
+            install_skill: boolean;
+            footer_badge: boolean;
+        } & {};
+        capabilities: {
+            framework: string;
+            package_manager: string;
+            install_packages: boolean;
+            initialize_sdk: boolean;
+            install_skill: boolean;
+            insert_footer: boolean;
+            source_review: boolean;
+            sample_read: boolean;
+        } & {
+            onboarding_v2?: boolean | undefined;
+            project_name?: string | undefined;
+            launcher?: ({
+                wizard_version: string;
+                api_origin: string;
+            } & {
+                registry?: string | undefined;
+            }) | undefined;
+            terminal?: ({
+                platform: string;
+                app: string;
+            } & {}) | undefined;
+        };
+        local_plan: ({
+            project_fingerprint: string;
+            choices_digest: string;
+            effects: import("./setup-wire.js").SetupEffect[];
+        } & {
+            manual_steps?: ({
+                kind: "install_packages" | "initialize_sdk" | "install_skill" | "insert_footer";
+                code: string;
+            } & {})[] | undefined;
+        }) | null;
+        plan_digest: string | null;
+        commands: ({
+            operation_id: string;
+            sequence: number;
+            kind: "install_packages" | "initialize_sdk" | "install_skill" | "insert_footer";
+            expected_revision: string;
+            input: import("./setup-wire.js").SetupEffect;
+            input_digest: string;
+            approval_digest: string;
+            status: "approved" | "manual" | "cancelled" | "failed" | "outcome_unknown" | "prepared" | "leased" | "running" | "succeeded";
+            executor_generation: number | null;
+            lease_generation: number;
+            lease_expires_at: string | null;
+            result: ({
+                code: "cancelled" | "skipped" | "already_present" | "unsupported" | "operation_failed" | "verified" | "review_required" | "dependency_failed" | "outcome_unknown";
+            } & {
+                verified?: boolean | undefined;
+            }) | null;
+            result_digest: string | null;
+            created_at: string;
+            started_at: string | null;
+            finished_at: string | null;
+            updated_at: string;
+        } & {})[];
+        executor_generation: number;
+        connection: string;
+        heartbeat_at: string | null;
+        sample: {
+            status: string;
+            first_received_at: string | null;
+            latest_received_at: string | null;
+            latest_request_id: string | null;
+        } & {};
+        draft_outcomes: ({
+            candidate_id: string;
+            status: string;
+            prompt_id: string;
+            request_id: string;
+            revision: string | null;
+            code: "cancelled" | "skipped" | "already_present" | "unsupported" | "operation_failed" | "verified" | "review_required" | "dependency_failed" | "outcome_unknown" | null;
+        } & {})[];
+        bound_at: string;
+        last_activity_at: string;
+        idle_expires_at: string;
+        absolute_expires_at: string;
+        terminal_at: string | null;
+        schema_version: 1;
+        setup_id: string;
+    } & {
+        source?: ({
+            preparation_id: string;
+            status: string;
+            packet_digest: string;
+            provider_fingerprint: string;
+            authorized_at: string | null;
+            expires_at: string;
+            error_code: "operation_failed" | "planning_unavailable" | "planning_paused" | "planning_daily_budget" | "planning_allowance_exhausted" | "planning_provider_unavailable" | "planning_policy_changed" | "planning_consent_expired" | "planning_input_budget" | "planning_invalid_output" | "planning_timeout" | "source_changed" | "source_unavailable" | "recommendations_no_source" | null;
+        } & {
+            analysis_id?: string | undefined;
+            analysis_started_at?: string | undefined;
+            analysis_completed_at?: string | undefined;
+            deadline_at?: string | undefined;
+            timings?: ({} & {
+                extraction_ms?: number | undefined;
+                consolidation_ms?: number | undefined;
+                authoring_ms?: number | undefined;
+                total_ms?: number | undefined;
+            }) | undefined;
+        }) | null | undefined;
+        recommendation_digest?: string | null | undefined;
+        selected_candidates?: string[] | undefined;
+    }) | undefined;
+    setLease(lease: {
+        operation_id: string;
+        executor_generation: number;
+        lease_generation: number;
+    }): void;
+    latest(fallback: SetupSessionView): {
+        phase: "expired" | "cancelled" | "analyzing" | "configuring" | "awaiting_local_approval" | "applying" | "ready_for_recommendations" | "selecting_drafts" | "creating_drafts" | "agent_test" | "complete";
+        revision: string;
+        workspace_id: string | null;
+        site_id: string | null;
+        project_fingerprint: string;
+        choices: {
+            install_sdk: boolean;
+            install_skill: boolean;
+            footer_badge: boolean;
+        } & {};
+        capabilities: {
+            framework: string;
+            package_manager: string;
+            install_packages: boolean;
+            initialize_sdk: boolean;
+            install_skill: boolean;
+            insert_footer: boolean;
+            source_review: boolean;
+            sample_read: boolean;
+        } & {
+            onboarding_v2?: boolean | undefined;
+            project_name?: string | undefined;
+            launcher?: ({
+                wizard_version: string;
+                api_origin: string;
+            } & {
+                registry?: string | undefined;
+            }) | undefined;
+            terminal?: ({
+                platform: string;
+                app: string;
+            } & {}) | undefined;
+        };
+        local_plan: ({
+            project_fingerprint: string;
+            choices_digest: string;
+            effects: import("./setup-wire.js").SetupEffect[];
+        } & {
+            manual_steps?: ({
+                kind: "install_packages" | "initialize_sdk" | "install_skill" | "insert_footer";
+                code: string;
+            } & {})[] | undefined;
+        }) | null;
+        plan_digest: string | null;
+        commands: ({
+            operation_id: string;
+            sequence: number;
+            kind: "install_packages" | "initialize_sdk" | "install_skill" | "insert_footer";
+            expected_revision: string;
+            input: import("./setup-wire.js").SetupEffect;
+            input_digest: string;
+            approval_digest: string;
+            status: "approved" | "manual" | "cancelled" | "failed" | "outcome_unknown" | "prepared" | "leased" | "running" | "succeeded";
+            executor_generation: number | null;
+            lease_generation: number;
+            lease_expires_at: string | null;
+            result: ({
+                code: "cancelled" | "skipped" | "already_present" | "unsupported" | "operation_failed" | "verified" | "review_required" | "dependency_failed" | "outcome_unknown";
+            } & {
+                verified?: boolean | undefined;
+            }) | null;
+            result_digest: string | null;
+            created_at: string;
+            started_at: string | null;
+            finished_at: string | null;
+            updated_at: string;
+        } & {})[];
+        executor_generation: number;
+        connection: string;
+        heartbeat_at: string | null;
+        sample: {
+            status: string;
+            first_received_at: string | null;
+            latest_received_at: string | null;
+            latest_request_id: string | null;
+        } & {};
+        draft_outcomes: ({
+            candidate_id: string;
+            status: string;
+            prompt_id: string;
+            request_id: string;
+            revision: string | null;
+            code: "cancelled" | "skipped" | "already_present" | "unsupported" | "operation_failed" | "verified" | "review_required" | "dependency_failed" | "outcome_unknown" | null;
+        } & {})[];
+        bound_at: string;
+        last_activity_at: string;
+        idle_expires_at: string;
+        absolute_expires_at: string;
+        terminal_at: string | null;
+        schema_version: 1;
+        setup_id: string;
+    } & {
+        source?: ({
+            preparation_id: string;
+            status: string;
+            packet_digest: string;
+            provider_fingerprint: string;
+            authorized_at: string | null;
+            expires_at: string;
+            error_code: "operation_failed" | "planning_unavailable" | "planning_paused" | "planning_daily_budget" | "planning_allowance_exhausted" | "planning_provider_unavailable" | "planning_policy_changed" | "planning_consent_expired" | "planning_input_budget" | "planning_invalid_output" | "planning_timeout" | "source_changed" | "source_unavailable" | "recommendations_no_source" | null;
+        } & {
+            analysis_id?: string | undefined;
+            analysis_started_at?: string | undefined;
+            analysis_completed_at?: string | undefined;
+            deadline_at?: string | undefined;
+            timings?: ({} & {
+                extraction_ms?: number | undefined;
+                consolidation_ms?: number | undefined;
+                authoring_ms?: number | undefined;
+                total_ms?: number | undefined;
+            }) | undefined;
+        }) | null | undefined;
+        recommendation_digest?: string | null | undefined;
+        selected_candidates?: string[] | undefined;
+    };
+    check(): void;
+    private schedule;
+    pulse(): Promise<void>;
+    /** Finish the old lease's in-flight heartbeat before closing it in a report. */
+    duringReport<T>(operation: () => Promise<T>): Promise<T>;
+    stop(): Promise<void>;
+}
+/** Observe all responses; cancel outstanding reads/source work when the run ends. */
+export declare function observeSetupClient<T extends object>(client: T, heartbeat: SetupHeartbeat, signal?: AbortSignal): T;