@userreason/cli 0.1.1 → 0.2.1

package/dist/setup-runner.js

@@ -0,0 +1,191 @@
+import { randomUUID } from 'node:crypto';
+import { realpath } from 'node:fs/promises';
+import { BrowserSetupUnavailable } from './setup.js';
+import { runSetupExecutor } from './setup-executor.js';
+import { prepareSetupSource, restoreSetupSource, verifySetupSource } from './setup-source.js';
+import { SetupError, withSetupProjectLock } from './setup-store.js';
+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) {
+    options.signal?.throwIfAborted();
+    if (options.sleep)
+        return options.sleep(milliseconds).then(() => options.signal?.throwIfAborted());
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { options.signal?.removeEventListener('abort', abort); resolve(); }, milliseconds);
+        function abort() { clearTimeout(timer); reject(options.signal?.reason); }
+        options.signal?.addEventListener('abort', abort, { once: true });
+    });
+}
+/** 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;
+    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);
+                        }
+                        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.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');
+                            }
+                        }
+                        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());
+                    }
+                }
+                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

@@ -0,0 +1,32 @@
+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;
+        snapshot_id: string;
+        files: {
+            path: string;
+            file_hash: string;
+            excerpt_hash: string;
+            bytes: number;
+            start_line: number;
+            end_line: number;
+        }[];
+        omitted_files: number;
+        truncated: boolean;
+        git_included: false;
+    };
+    packages: {
+        name: string;
+        version: string;
+    }[];
+    evidence: LocalEvidence[];
+}
+/** Reuse the bounded application collector without Git, provider calls or local packet persistence. */
+export declare function prepareSetupSource(directory: string, preparationId?: string, signal?: AbortSignal, 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, 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

@@ -0,0 +1,48 @@
+import { randomUUID } from 'node:crypto';
+import { collectFirstSurveySource, verifyFirstSurveySource } from './first-survey-source.js';
+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, expanded = false) {
+    signal?.throwIfAborted();
+    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, 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,
+                bytes: Buffer.byteLength(item.excerpt), start_line: item.start_line, end_line: item.end_line })),
+            omitted_files: preview.omitted.length, truncated: preview.truncated, git_included: false,
+        },
+    };
+    // The shared public decoder enforces the actual UTF-8 wire budget, including
+    // JSON escaping; the collector's estimate is deliberately not authorization.
+    parseSetupSourceManifest(prepared.manifest);
+    parseSetupSourceUploadInput({ schema_version: 1, setup_id: preparationId, preparation_id: preparationId,
+        project_fingerprint: '0'.repeat(64), evidence });
+    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, 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;
+}
+/** Revalidate immediately before upload; only the immutable reviewed memory packet may leave the process. */
+export async function verifySetupSource(directory, packet, signal) {
+    signal?.throwIfAborted();
+    if (packet.preparation_id !== packet.manifest.snapshot_id || setupDigest({ evidence: packet.evidence, packages: packet.packages }) !== packet.manifest.packet_digest)
+        throw new SetupError('setup_source_changed', 'The prepared source packet changed. Review a new packet before analysis.');
+    try {
+        await verifyFirstSurveySource(directory, packet.evidence);
+    }
+    catch {
+        throw new SetupError('setup_source_changed', 'Application files changed. Review a new source packet before analysis.');
+    }
+    await restoreSetupSource(directory, packet, signal, packet.expanded);
+    signal?.throwIfAborted();
+}

package/dist/setup-store.d.ts

@@ -0,0 +1,37 @@
+export declare class SetupError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export type StoredSetup = {
+    schema_version: 1;
+    setup_id: string;
+    api_url: string;
+    project_fingerprint: string;
+    created_at: string;
+    expires_at: string;
+} & ({
+    state: 'pending';
+    ticket: string;
+    verifier: string;
+} | {
+    state: 'connected';
+    access_token: string;
+});
+/** A root identity, not uploaded source or a pathname in the remote setup record. */
+export declare function setupProjectFingerprint(directory: string): Promise<string>;
+export declare function parseStoredSetup(value: unknown): StoredSetup;
+/** Lazy, bounded retention cleanup; unrelated files, links and locks are left alone. */
+export declare function pruneSetupSessions(now?: number): Promise<{
+    scanned: number;
+    removed: number;
+}>;
+/** Setup capabilities never enter the general CLI credential store or project source. */
+export declare function saveSetupSession(value: StoredSetup): Promise<void>;
+export declare function loadSetupSession(origin: string, setupId: string, directory: string, now?: number): Promise<StoredSetup>;
+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>;
+/** Recover only after a crashed process is proven gone; never steals a live lock. */
+export declare function recoverSetupProjectLock(directory: string): Promise<boolean>;
+/** 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

@@ -0,0 +1,266 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, opendir, readFile, realpath, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { configDirectory } from './config.js';
+import { apiUrl, object, uuid } from './contracts.js';
+export class SetupError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** A root identity, not uploaded source or a pathname in the remote setup record. */
+export async function setupProjectFingerprint(directory) {
+    return createHash('sha256').update(await realpath(directory)).digest('hex');
+}
+export function parseStoredSetup(value) {
+    const data = object(value, 'stored setup');
+    const common = ['schema_version', 'setup_id', 'api_url', 'project_fingerprint', 'created_at', 'expires_at', 'state'];
+    const fields = data.state === 'pending' ? ['ticket', 'verifier'] : data.state === 'connected' ? ['access_token'] : [];
+    if (!fields.length || Object.keys(data).some(key => ![...common, ...fields].includes(key)) ||
+        [...common, ...fields].some(key => !(key in data)) || data.schema_version !== 1 ||
+        typeof data.api_url !== 'string' || apiUrl(data.api_url) !== data.api_url ||
+        typeof data.setup_id !== 'string' || uuid(data.setup_id) !== data.setup_id ||
+        typeof data.project_fingerprint !== 'string' || !/^[a-f0-9]{64}$/.test(data.project_fingerprint) ||
+        typeof data.created_at !== 'string' || typeof data.expires_at !== 'string' ||
+        !Number.isFinite(Date.parse(data.created_at)) || !Number.isFinite(Date.parse(data.expires_at)) ||
+        Date.parse(data.expires_at) <= Date.parse(data.created_at) ||
+        Date.parse(data.expires_at) - Date.parse(data.created_at) > (data.state === 'pending' ? 901_000 : 7_201_000) ||
+        fields.some(key => typeof data[key] !== 'string' || !data[key].length || data[key].length > 16_384) ||
+        (data.state === 'pending' && !/^[a-f0-9]{64}$/.test(data.verifier)) ||
+        (data.state === 'connected' && !/^ur-setup\.v1\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(data.access_token))) {
+        throw new SetupError('invalid_setup_session', 'Invalid local setup session. Start a new setup; ordinary CLI credentials are unchanged.');
+    }
+    return data;
+}
+function storePath(origin, setupId) {
+    const key = createHash('sha256').update(`${apiUrl(origin)}\n${uuid(setupId)}`).digest('hex');
+    return join(configDirectory(), 'setup-v1', `${key}.json`);
+}
+const retentionMs = 7 * 24 * 60 * 60 * 1000;
+const pruneBatch = 128;
+/** Read through one bounded file handle, never through a symbolic link. */
+async function readSetupRecord(path) {
+    const before = await lstat(path);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > 65_536)
+        throw new Error('invalid setup file');
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const info = await file.stat();
+        if (!info.isFile() || info.ino !== before.ino || info.dev !== before.dev || info.size > 65_536)
+            throw new Error('changed setup file');
+        const buffer = Buffer.alloc(65_537);
+        let size = 0;
+        while (size < buffer.length) {
+            const part = await file.read(buffer, size, buffer.length - size, size);
+            if (!part.bytesRead)
+                break;
+            size += part.bytesRead;
+        }
+        if (size > 65_536)
+            throw new Error('oversized setup file');
+        return { data: parseStoredSetup(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, size)))), info };
+    }
+    finally {
+        await file.close();
+    }
+}
+async function removeSameRecord(path, info) {
+    try {
+        const current = await lstat(path);
+        if (!current.isFile() || current.isSymbolicLink() || current.ino !== info.ino || current.dev !== info.dev)
+            return false;
+        await rm(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Lazy, bounded retention cleanup; unrelated files, links and locks are left alone. */
+export async function pruneSetupSessions(now = Date.now()) {
+    if (!Number.isFinite(now))
+        return { scanned: 0, removed: 0 };
+    let directory;
+    try {
+        const path = join(configDirectory(), 'setup-v1'), info = await lstat(path);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            return { scanned: 0, removed: 0 };
+        directory = await opendir(path);
+    }
+    catch {
+        return { scanned: 0, removed: 0 };
+    }
+    let scanned = 0, removed = 0;
+    try {
+        for await (const entry of directory) {
+            if (++scanned > pruneBatch) {
+                scanned = pruneBatch;
+                break;
+            }
+            if (!entry.isFile() || !/^[a-f0-9]{64}\.json$/.test(entry.name))
+                continue;
+            const path = join(configDirectory(), 'setup-v1', entry.name);
+            try {
+                const { data, info } = await readSetupRecord(path);
+                if (storePath(data.api_url, data.setup_id) !== path || Date.parse(data.created_at) > now - retentionMs)
+                    continue;
+                if (await removeSameRecord(path, info))
+                    removed++;
+            }
+            catch { /* Unknown/corrupt files are not ours to erase. */ }
+        }
+    }
+    catch { /* Cleanup is best effort and never prevents a new setup. */ }
+    return { scanned, removed };
+}
+/** Setup capabilities never enter the general CLI credential store or project source. */
+export async function saveSetupSession(value) {
+    const data = parseStoredSetup(value), path = storePath(data.api_url, data.setup_id);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        const directory = join(configDirectory(), 'setup-v1');
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new SetupError('setup_store_failed', 'The setup store must be a regular private directory, not a symbolic link.');
+        await pruneSetupSessions();
+        const file = await open(temporary, 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(data) + '\n');
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, path);
+    }
+    catch (error) {
+        if (error instanceof SetupError)
+            throw error;
+        throw new SetupError('setup_store_failed', 'Unable to save the private setup session outside the project. Check local configuration-directory access.');
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => { });
+    }
+}
+export async function loadSetupSession(origin, setupId, directory, now = Date.now()) {
+    let data;
+    let info;
+    const path = storePath(origin, setupId);
+    try {
+        const parent = await lstat(join(configDirectory(), 'setup-v1'));
+        if (!parent.isDirectory() || parent.isSymbolicLink())
+            throw new Error('invalid setup directory');
+        ({ data, info } = await readSetupRecord(path));
+    }
+    catch (error) {
+        if (error instanceof SetupError)
+            throw error;
+        throw new SetupError('setup_session_unavailable', 'No valid local setup session for this API and ID. Resume from the original project or start a new setup.');
+    }
+    if (data.api_url !== apiUrl(origin) || data.setup_id !== setupId || data.project_fingerprint !== await setupProjectFingerprint(directory))
+        throw new SetupError('setup_binding_mismatch', 'The setup session belongs to another API or project. Use the original project and API.');
+    if (Date.parse(data.expires_at) <= now) {
+        await removeSameRecord(path, info);
+        throw new SetupError('setup_expired', 'This setup session expired. Start a new setup; saved drafts and completed local work are retained.');
+    }
+    return data;
+}
+export async function clearSetupSession(origin, setupId) {
+    await rm(storePath(origin, setupId), { force: true });
+}
+/** Create one private level at a time; never traverse a replaced setup ancestor. */
+export async function setupPrivateDirectory(...parts) {
+    let path = configDirectory();
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    for (const part of ['', 'setup-v1', ...parts]) {
+        if (part) {
+            path = join(path, part);
+            await mkdir(path, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
+                throw error; });
+        }
+        const info = await lstat(path);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new SetupError('setup_store_failed', 'A private setup directory was replaced by a link.');
+    }
+    return path;
+}
+/** 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`);
+    let info;
+    try {
+        info = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1 || info.size > 1024)
+        throw new SetupError('setup_lock_failed', 'The project lock needs manual review.');
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const now = await file.stat();
+        if (now.ino !== info.ino || now.dev !== info.dev)
+            throw new Error('changed lock');
+        const value = JSON.parse(await file.readFile('utf8'));
+        if (!Number.isInteger(value.pid) || value.pid < 1 || typeof value.owner !== 'string')
+            throw new Error('invalid lock');
+        try {
+            process.kill(value.pid, 0);
+            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')
+                throw error;
+        }
+        return removeSameRecord(path, info);
+    }
+    finally {
+        await file.close();
+    }
+}
+/** 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');
+    const path = join(locks, `${fingerprint}.lock`), owner = randomUUID();
+    let file;
+    try {
+        file = await open(path, 'wx', 0o600);
+    }
+    catch (error) {
+        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 {
+        await file.writeFile(JSON.stringify({ owner, pid: process.pid, created_at: new Date().toISOString() }));
+        await file.sync();
+        return await operation();
+    }
+    finally {
+        await file.close();
+        try {
+            if (JSON.parse(await readFile(path, 'utf8')).owner === owner)
+                await removeSameRecord(path, lockInfo);
+        }
+        catch { /* Never delete a replacement lock or mask the operation's result. */ }
+    }
+}

package/dist/setup-terminal.d.ts

@@ -0,0 +1,3 @@
+import type { SetupCapabilities } from './setup-wire.js';
+/** Fixed labels only. No process names, environment values, paths or shell are uploaded. */
+export declare function detectSetupTerminal(platform?: NodeJS.Platform, environment?: NodeJS.ProcessEnv): NonNullable<SetupCapabilities['terminal']>;

package/dist/setup-terminal.js

@@ -0,0 +1,6 @@
+/** Fixed labels only. No process names, environment values, paths or shell are uploaded. */
+export function detectSetupTerminal(platform = process.platform, environment = process.env) {
+    const detectedPlatform = platform === 'darwin' ? 'macos' : platform === 'win32' ? 'windows' : platform === 'linux' ? 'linux' : 'other';
+    const known = { Apple_Terminal: 'apple_terminal', iTerm: 'iterm2', 'iTerm.app': 'iterm2', vscode: 'vscode', cursor: 'cursor', WarpTerminal: 'warp', ghostty: 'ghostty', WezTerm: 'wezterm', Alacritty: 'alacritty', kitty: 'kitty' };
+    return { platform: detectedPlatform, app: known[environment.TERM_PROGRAM ?? ''] ?? (platform === 'win32' && environment.WT_SESSION ? 'windows_terminal' : 'generic') };
+}