@userreason/cli 0.2.0 → 0.2.1

package/dist/setup-heartbeat.js

@@ -0,0 +1,120 @@
+const terminal = new Set(['complete', 'cancelled', 'expired']);
+/** Stop waiting when this run ends, including user-supplied preparations. */
+export function setupAbortable(work, signal) {
+    if (!signal)
+        return work;
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener('abort', abort, { once: true });
+        work.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+    });
+}
+/** One lease-aware heartbeat for the entire run, independent of its current stage. */
+export class SetupHeartbeat {
+    client;
+    options;
+    session;
+    timer;
+    pending;
+    stopped = false;
+    paused = 0;
+    failure;
+    lease;
+    lifetime = new AbortController();
+    signal;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.options = options;
+        this.signal = AbortSignal.any([this.lifetime.signal, ...(options.signal ? [options.signal] : [])]);
+    }
+    observe(next) {
+        const current = this.session;
+        if (!current || BigInt(next.revision) >= BigInt(current.revision)) {
+            const heartbeat = current?.heartbeat_at && (!next.heartbeat_at || Date.parse(current.heartbeat_at) > Date.parse(next.heartbeat_at)) ? current.heartbeat_at : next.heartbeat_at;
+            this.session = { ...next, heartbeat_at: heartbeat };
+        }
+        if (terminal.has(this.session.phase) && !this.signal.aborted)
+            this.lifetime.abort(new Error('Setup ended'));
+        if (!this.stopped && !this.timer && !this.pending && !this.paused && !terminal.has(this.session.phase))
+            this.schedule(0);
+        return this.session;
+    }
+    get current() { return this.session; }
+    setLease(lease) { this.lease = lease; }
+    latest(fallback) { return this.observe(fallback); }
+    check() { this.options.signal?.throwIfAborted(); if (this.failure)
+        throw this.failure; }
+    schedule(delay = this.options.heartbeatMs ?? 10000) {
+        if (this.stopped || this.paused || !this.session || terminal.has(this.session.phase) || this.signal.aborted)
+            return;
+        this.timer = setTimeout(() => { this.timer = undefined; void this.pulse(); }, delay);
+    }
+    async pulse() {
+        if (this.pending)
+            return this.pending;
+        if (this.stopped || this.paused || this.signal.aborted || !this.session || terminal.has(this.session.phase))
+            return;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        const session = this.session;
+        this.pending = setupAbortable(this.client.heartbeat({ schema_version: 1, setup_id: this.client.identity.setup_id, executor_generation: session.executor_generation,
+            operation_id: this.lease?.operation_id ?? null, lease_generation: this.lease?.lease_generation ?? null }), this.signal)
+            .then(value => { this.observe(value); })
+            .catch(error => { if (!this.stopped && !this.options.signal?.aborted) {
+            this.failure = error;
+            this.lifetime.abort(error);
+        } })
+            .finally(() => { this.pending = undefined; this.schedule(); });
+        return this.pending;
+    }
+    /** Finish the old lease's in-flight heartbeat before closing it in a report. */
+    async duringReport(operation) {
+        this.paused++;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        try {
+            await this.pending;
+            this.lease = undefined;
+            return await operation();
+        }
+        finally {
+            this.paused--;
+            this.schedule();
+        }
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.lifetime.abort(new Error('Setup run ended'));
+        await this.pending;
+    }
+}
+/** Observe all responses; cancel outstanding reads/source work when the run ends. */
+export function observeSetupClient(client, heartbeat, signal) {
+    return new Proxy(client, { get(target, key, receiver) {
+            const value = Reflect.get(target, key, target);
+            if (typeof value !== 'function')
+                return value;
+            if (key === 'withSignal')
+                return value.bind(target);
+            return async (...args) => {
+                // Reports settle already-recorded effects, including a cancelled operation.
+                if (key !== 'report')
+                    signal?.throwIfAborted();
+                // Acknowledged mutations remain acknowledged if cancellation races their
+                // response. Reads and the long source upload can stop waiting immediately.
+                const requestSignal = ['poll', 'discovery', 'sourceInfo', 'sourceUpload'].includes(String(key)) ? signal : undefined;
+                const result = await setupAbortable(Reflect.apply(value, target, args), requestSignal);
+                const view = result && typeof result === 'object' && 'session' in result ? result.session : result;
+                if (view && typeof view === 'object' && 'phase' in view && 'revision' in view && typeof view.phase === 'string' && typeof view.revision === 'string')
+                    heartbeat.observe(view);
+                return result;
+            };
+        } });
+}

package/dist/setup-runner.d.ts

@@ -3,12 +3,14 @@ import { type SetupExecutorOptions, type SetupExecutorRuntime } from './setup-ex
 import { type PreparedSetupSource } from './setup-source.js';
 import { type SetupSessionView } from './setup-wire.js';
 export interface BrowserSetupRunnerOptions extends SetupExecutorOptions {
+    automaticSetup?: boolean;
+    preparedSource?: Promise<PreparedSetupSource | null>;
     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'>;
+export type BrowserSetupRunnerClient = Pick<BrowserSetupClient, 'identity' | 'poll' | 'plan' | 'claim' | 'startCommand' | 'report' | 'heartbeat' | 'reconcile' | 'discovery' | 'sourceInfo' | 'sourcePlan' | 'sourceUpload'> & Partial<Pick<BrowserSetupClient, 'withSignal'>>;
 /** 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

@@ -4,6 +4,7 @@ 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';
+import { SetupHeartbeat, observeSetupClient, setupAbortable } from './setup-heartbeat.js';
 const terminal = new Set(['complete', 'cancelled', 'expired']);
 const localPhases = new Set(['configuring', 'awaiting_local_approval', 'applying']);
 function pause(milliseconds, options) {
@@ -16,127 +17,175 @@ function pause(milliseconds, options) {
         options.signal?.addEventListener('abort', abort, { once: true });
     });
 }
+/** Start repository analysis as soon as the authenticated setup is bound. It
+ * intentionally does not hold the installation lock while a provider works. */
+async function prepareEarly(client, directory, options) {
+    const scope = { schema_version: 1, setup_id: client.identity.setup_id };
+    try {
+        let session = await client.poll();
+        if (session.source || !(await client.discovery()).browser_setup.source_analysis)
+            return;
+        const packet = options.preparedSource ? await setupAbortable(options.preparedSource, options.signal) ?? await prepareSetupSource(directory, randomUUID(), options.signal, true) : await prepareSetupSource(directory, randomUUID(), options.signal, true);
+        let conflicts = 0;
+        while (true) {
+            session = await client.poll();
+            if (session.source || terminal.has(session.phase))
+                return;
+            try {
+                session = await client.sourcePlan({ ...scope, request_id: packet.preparation_id, expected_revision: session.revision, manifest: packet.manifest, packages: packet.packages });
+                break;
+            }
+            catch (error) {
+                if (!(error instanceof SetupError) || error.code !== 'revision_conflict' || ++conflicts >= 5)
+                    throw error;
+            }
+        }
+        if (session.source?.status !== 'approved' || session.source.preparation_id !== packet.preparation_id)
+            return;
+        await verifySetupSource(directory, packet, options.signal);
+        options.onSession?.(session);
+        await client.sourceUpload({ ...scope, preparation_id: packet.preparation_id, project_fingerprint: client.identity.project_fingerprint, evidence: packet.evidence });
+    }
+    catch (error) {
+        options.signal?.throwIfAborted();
+        options.onSourceIssue?.(error instanceof SetupError ? error.code : 'source_unavailable');
+    }
+}
 /** 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);
+    const lifetime = new AbortController();
+    const runSignal = AbortSignal.any([lifetime.signal, ...(options.signal ? [options.signal] : [])]);
+    const base = client.withSignal?.(runSignal) ?? client;
+    const heartbeat = new SetupHeartbeat(base, { ...options, signal: runSignal });
+    client = observeSetupClient(base.withSignal?.(heartbeat.signal) ?? base, heartbeat, heartbeat.signal);
+    const suppliedSignal = options.signal;
+    options = { ...options, signal: heartbeat.signal };
     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;
+    const early = options.automaticSetup ? prepareEarly(client, directory, options) : Promise.resolve();
+    void early.catch(() => { }); // Cleanup awaits it; never leave an unhandled background rejection.
+    try {
+        while (true) {
+            let session;
+            session = await runSetupExecutor(client, directory, runtime, options, heartbeat);
+            await early;
+            if (options.automaticSetup)
+                session = await client.poll();
+            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;
+                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;
+                }
+                try {
+                    while (true) {
+                        heartbeat.check();
+                        session = heartbeat.latest(session);
+                        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);
                         }
-                        catch (error) {
-                            options.signal?.throwIfAborted();
-                            failedPreparationRevision = session.revision;
-                            issue(error instanceof SetupError ? error.code : 'source_unavailable');
+                        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();
                         }
-                    }
-                    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 }));
+                        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.automaticSetup);
+                                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');
+                            }
                         }
-                        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.
+                        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.automaticSetup);
+                                options.onSourcePrepared?.(packet);
+                                await verifySetupSource(directory, packet, options.signal);
+                                heartbeat.check();
+                                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());
                     }
-                    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;
+                finally {
+                    packet = undefined;
+                }
+            });
+            if (!localPhases.has(result.phase) || options.maxPolls !== undefined)
+                return result;
+        }
+    }
+    catch (error) {
+        const current = heartbeat.current;
+        if (!suppliedSignal?.aborted && current && terminal.has(current.phase))
+            return current;
+        throw error;
+    }
+    finally {
+        lifetime.abort(new Error('Setup run ended'));
+        await Promise.allSettled([early, heartbeat.stop()]);
     }
 }

package/dist/setup-source.d.ts

@@ -1,6 +1,7 @@
 import { type LocalEvidence } from './first-survey-source.js';
 /** One memory-only packet. The wire manifest contains hashes/ranges, never source text. */
 export interface PreparedSetupSource {
+    expanded?: boolean;
     preparation_id: string;
     manifest: {
         packet_digest: string;
@@ -24,8 +25,8 @@ export interface PreparedSetupSource {
     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>;
+export declare function prepareSetupSource(directory: string, preparationId?: string, signal?: AbortSignal, expanded?: boolean): 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>;
+export declare function restoreSetupSource(directory: string, approved: Pick<PreparedSetupSource, 'preparation_id' | 'manifest' | 'packages'>, signal?: AbortSignal, expanded?: boolean): 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>;

package/dist/setup-source.js

@@ -4,13 +4,13 @@ import { setupDigest } from './setup-files.js';
 import { SetupError } from './setup-store.js';
 import { parseSetupSourceManifest, parseSetupSourceUploadInput } from './setup-wire.js';
 /** Reuse the bounded application collector without Git, provider calls or local packet persistence. */
-export async function prepareSetupSource(directory, preparationId = randomUUID(), signal) {
+export async function prepareSetupSource(directory, preparationId = randomUUID(), signal, expanded = false) {
     signal?.throwIfAborted();
-    const preview = await collectFirstSurveySource({ root: directory, snapshotId: preparationId, recommendations: true, signal });
+    const preview = await collectFirstSurveySource({ root: directory, snapshotId: preparationId, recommendations: true, benchmark: expanded, signal });
     await verifyFirstSurveySource(directory, preview.evidence);
     const evidence = preview.evidence, packages = preview.packages;
     const prepared = {
-        preparation_id: preparationId, evidence, packages,
+        preparation_id: preparationId, evidence, packages, expanded,
         manifest: {
             packet_digest: setupDigest({ evidence, packages }), snapshot_id: preparationId,
             files: evidence.map(item => ({ path: item.path, file_hash: item.file_hash, excerpt_hash: item.excerpt_hash,
@@ -26,8 +26,8 @@ export async function prepareSetupSource(directory, preparationId = randomUUID()
     return prepared;
 }
 /** An approved preparation is rebuilt with its original snapshot ID; no raw source needs a receipt. */
-export async function restoreSetupSource(directory, approved, signal) {
-    const prepared = await prepareSetupSource(directory, approved.preparation_id, signal);
+export async function restoreSetupSource(directory, approved, signal, expanded) {
+    const prepared = await prepareSetupSource(directory, approved.preparation_id, signal, expanded ?? approved.manifest.files.reduce((n, file) => n + file.bytes, 0) > 10000);
     if (setupDigest(prepared.manifest) !== setupDigest(approved.manifest) || setupDigest(prepared.packages) !== setupDigest(approved.packages))
         throw new SetupError('setup_source_changed', 'Application source or installed package metadata changed. Review a new source packet in the browser before analysis.');
     return prepared;
@@ -43,6 +43,6 @@ export async function verifySetupSource(directory, packet, signal) {
     catch {
         throw new SetupError('setup_source_changed', 'Application files changed. Review a new source packet before analysis.');
     }
-    await restoreSetupSource(directory, packet, signal);
+    await restoreSetupSource(directory, packet, signal, packet.expanded);
     signal?.throwIfAborted();
 }

package/dist/setup-store.d.ts

@@ -31,7 +31,7 @@ export declare function loadSetupSession(origin: string, setupId: string, direct
 export declare function clearSetupSession(origin: string, setupId: string): Promise<void>;
 /** Create one private level at a time; never traverse a replaced setup ancestor. */
 export declare function setupPrivateDirectory(...parts: string[]): Promise<string>;
-/** Explicit recovery only after a crashed process is proven gone; never steals a live lock. */
+/** Recover only after a crashed process is proven gone; never steals a live lock. */
 export declare function recoverSetupProjectLock(directory: string): Promise<boolean>;
-/** Fail closed on an existing lock. A stale process requires reconciliation, not a timed takeover. */
+/** Recover a proven-dead owner, then acquire exclusively. Live/unknown owners stay protected. */
 export declare function withSetupProjectLock<T>(directory: string, operation: () => Promise<T>): Promise<T>;

package/dist/setup-store.js

@@ -188,7 +188,7 @@ export async function setupPrivateDirectory(...parts) {
     }
     return path;
 }
-/** Explicit recovery only after a crashed process is proven gone; never steals a live lock. */
+/** Recover only after a crashed process is proven gone; never steals a live lock. */
 export async function recoverSetupProjectLock(directory) {
     const locks = await setupPrivateDirectory('project-locks');
     const path = join(locks, `${await setupProjectFingerprint(directory)}.lock`);
@@ -213,7 +213,7 @@ export async function recoverSetupProjectLock(directory) {
             throw new Error('invalid lock');
         try {
             process.kill(value.pid, 0);
-            throw new SetupError('setup_project_locked', 'The project lock owner is still running.');
+            throw new SetupError('setup_project_locked', `Another wizard is still running for this project (PID ${value.pid}). Return to its terminal and finish or stop that run before retrying.`);
         }
         catch (error) {
             if (error.code !== 'ESRCH')
@@ -225,7 +225,7 @@ export async function recoverSetupProjectLock(directory) {
         await file.close();
     }
 }
-/** Fail closed on an existing lock. A stale process requires reconciliation, not a timed takeover. */
+/** Recover a proven-dead owner, then acquire exclusively. Live/unknown owners stay protected. */
 export async function withSetupProjectLock(directory, operation) {
     const fingerprint = await setupProjectFingerprint(directory);
     const locks = await setupPrivateDirectory('project-locks');
@@ -235,9 +235,19 @@ export async function withSetupProjectLock(directory, operation) {
         file = await open(path, 'wx', 0o600);
     }
     catch (error) {
-        if (error.code === 'EEXIST')
-            throw new SetupError('setup_project_locked', 'Another setup owns this project. Reconcile its local results before retrying; an expired server lease does not release this lock.');
-        throw new SetupError('setup_lock_failed', 'Unable to lock this project for setup. Check local configuration-directory access.');
+        if (error.code !== 'EEXIST')
+            throw new SetupError('setup_lock_failed', 'Unable to lock this project for setup. Check local configuration-directory access.');
+        try {
+            await recoverSetupProjectLock(directory);
+            file = await open(path, 'wx', 0o600);
+        }
+        catch (recoveryError) {
+            if (recoveryError instanceof SetupError)
+                throw recoveryError;
+            if (recoveryError.code === 'EEXIST')
+                throw new SetupError('setup_project_locked', 'Another wizard acquired this project. Return to its terminal and finish or stop that run before retrying.');
+            throw new SetupError('setup_lock_failed', 'The existing project lock could not be verified safely. No lock or installation receipt was removed.');
+        }
     }
     const lockInfo = await file.stat();
     try {