@msvesper/vesper-link 0.1.4

package/dist/sync.js

@@ -0,0 +1,247 @@
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ClaudeCollector, CodexCollector, CopilotCollector } from './collectors/index.js';
+import { readConfig } from './config.js';
+import { getHealth, postManifest, putContent, SystemicUploadError, TaskUploadError } from './http-client.js';
+import { readInstalledState } from './installation.js';
+import { acquireSyncLock, SyncAlreadyRunningError } from './lock.js';
+import { readPendingMarkers, removePendingMarker } from './pending.js';
+import { resolveLinkPaths } from './paths.js';
+import { isStableForUpload, selectQueueItems } from './queue.js';
+import { fingerprintStableSource, LocalTaskError, assertSourceUnchanged } from './source.js';
+import { clearSyncState, readSessionStates, readSyncState, writeSessionState, writeSyncState } from './state.js';
+import { SCHEMA_VERSION } from './contracts.js';
+import { stableSessionKey } from './session.js';
+import { acquireRemoteTransport } from './transport.js';
+const MISSING_SOURCE_RETRY_MS = 7 * 24 * 60 * 60 * 1000;
+function createState(item) {
+    const candidate = item.candidate;
+    return {
+        schemaVersion: 1,
+        provider: candidate.provider,
+        format: candidate.format,
+        formatVersion: candidate.formatVersion,
+        providerSessionId: candidate.providerSessionId,
+        transcriptPath: candidate.transcriptPath,
+        projectKey: candidate.projectKey,
+        cwdUri: candidate.cwdUri,
+        sourceCreatedAt: candidate.sourceCreatedAt,
+        sourceUpdatedAt: candidate.sourceUpdatedAt,
+        lastSeenSize: candidate.size,
+        lastSeenMtimeMs: candidate.mtimeMs,
+        requiresStability: candidate.discovery === 'scan' && candidate.archived !== true,
+        status: 'pending',
+    };
+}
+function errorDetails(error) {
+    if (error instanceof TaskUploadError || error instanceof SystemicUploadError || error instanceof LocalTaskError) {
+        return { code: error.code, message: error.message };
+    }
+    if (error.code === 'ENOENT') {
+        return { code: 'missing_source', message: String(error) };
+    }
+    return { code: 'unexpected_error', message: String(error) };
+}
+function isPermanentTaskFailure(code) {
+    return ['file_too_large', 'manifest_too_large', 'invalid_manifest', 'unsupported_provider'].includes(code);
+}
+export async function runSyncOnce(options = {}) {
+    const paths = options.paths ?? resolveLinkPaths();
+    const nowMs = options.nowMs ?? Date.now();
+    const summary = { discovered: 0, queued: 0, uploaded: 0, unchanged: 0, failed: 0, collectorIssues: [] };
+    let release;
+    try {
+        release = await acquireSyncLock(paths.lockPath);
+    }
+    catch (error) {
+        if (error instanceof SyncAlreadyRunningError) {
+            summary.alreadyRunning = true;
+            return summary;
+        }
+        throw error;
+    }
+    try {
+        if ((await readInstalledState(paths))?.paused) {
+            summary.stoppedBy = 'paused';
+            return summary;
+        }
+        const syncState = await readSyncState(paths.syncStatePath);
+        if (syncState.retryAfterUntil && Date.parse(syncState.retryAfterUntil) > nowMs) {
+            summary.stoppedBy = 'rate_limited';
+            return summary;
+        }
+        if (syncState.retryAfterUntil) {
+            await clearSyncState(paths.syncStatePath);
+        }
+        const config = await readConfig(paths.configPath);
+        const transport = options.acquireTransport
+            ? await options.acquireTransport(paths, config.host)
+            : await acquireRemoteTransport({ paths, hostUrl: config.host });
+        const remoteHost = transport.hostUrl;
+        const remoteFetch = transport.fetch;
+        try {
+            const states = await readSessionStates(paths.sessionsDir);
+            let health;
+            try {
+                health = await getHealth(remoteHost, remoteFetch);
+            }
+            catch (error) {
+                if (error instanceof SystemicUploadError && error.code === 'rate_limited' && error.retryAfterUntil) {
+                    await writeSyncState(paths.syncStatePath, { schemaVersion: 1, retryAfterUntil: error.retryAfterUntil });
+                    summary.stoppedBy = error.code;
+                    return summary;
+                }
+                throw error;
+            }
+            if (!health.archiveReady) {
+                summary.stoppedBy = 'archive_unavailable';
+                return summary;
+            }
+            const context = {
+                nowMs,
+                claudeProjectsDir: paths.claudeProjectsDir,
+                copilotSessionsDir: paths.copilotSessionsDir,
+                codexHome: paths.codexHome,
+                reportIssue: (issue) => summary.collectorIssues.push(issue),
+            };
+            const collectors = [new ClaudeCollector(), new CopilotCollector(), new CodexCollector()];
+            const scanned = (await Promise.all(collectors.map((collector) => collector.collect(context)))).flat();
+            const markers = await readPendingMarkers(paths.pendingDir);
+            summary.discovered = scanned.length + markers.length;
+            const queue = await selectQueueItems({ markers, scanned, states, nowMs });
+            summary.queued = queue.length;
+            let consecutiveSystemicFailures = 0;
+            for (const item of queue) {
+                const key = stableSessionKey(item.candidate.provider, item.candidate.providerSessionId);
+                const state = states.get(key) ?? createState(item);
+                state.transcriptPath = item.candidate.transcriptPath;
+                state.format = item.candidate.format;
+                state.formatVersion = item.candidate.formatVersion;
+                state.projectKey = item.candidate.projectKey ?? state.projectKey;
+                state.cwdUri = item.candidate.cwdUri;
+                state.sourceUpdatedAt = item.candidate.sourceUpdatedAt;
+                state.lastSeenSize = item.candidate.size;
+                state.lastSeenMtimeMs = item.candidate.mtimeMs;
+                if (item.markerPath) {
+                    state.requiresStability = false;
+                }
+                else if (item.candidate.discovery === 'scan') {
+                    state.requiresStability = item.candidate.archived !== true;
+                }
+                const markerIsNewerThanLastAttempt = item.markerQueuedAt !== undefined
+                    && Date.parse(item.markerQueuedAt) > Date.parse(state.lastError?.at ?? state.missingSince ?? '');
+                if (markerIsNewerThanLastAttempt) {
+                    delete state.missingSince;
+                }
+                try {
+                    const fingerprint = await fingerprintStableSource(item.candidate.transcriptPath);
+                    if (!isStableForUpload(item.candidate, fingerprint.mtimeMs, nowMs)) {
+                        continue;
+                    }
+                    const sourceUpdatedAt = new Date(fingerprint.mtimeMs).toISOString();
+                    state.sourceUpdatedAt = sourceUpdatedAt;
+                    const manifest = {
+                        schemaVersion: SCHEMA_VERSION,
+                        provider: item.candidate.provider,
+                        format: item.candidate.format,
+                        formatVersion: item.candidate.formatVersion,
+                        providerSessionId: item.candidate.providerSessionId,
+                        projectKey: state.projectKey,
+                        cwdUri: item.candidate.cwdUri,
+                        sourceTranscriptUri: pathToFileURL(path.resolve(item.candidate.transcriptPath)).href,
+                        sourceCreatedAt: item.candidate.sourceCreatedAt,
+                        sourceUpdatedAt,
+                        byteLength: fingerprint.size,
+                        sha256: fingerprint.sha256,
+                    };
+                    const posted = await postManifest(remoteHost, manifest, remoteFetch);
+                    if (posted.uploadStatus !== 'needs_content' && posted.uploadStatus !== 'already_archived') {
+                        throw new SystemicUploadError('malformed_response', `Unexpected manifest upload status: ${posted.uploadStatus}`);
+                    }
+                    if ((posted.uploadStatus === 'needs_content' && posted.currentSha256 === fingerprint.sha256)
+                        || (posted.uploadStatus === 'already_archived' && posted.currentSha256 !== fingerprint.sha256)) {
+                        throw new SystemicUploadError('malformed_response', 'Manifest response SHA does not match the source');
+                    }
+                    let finalResponse = posted;
+                    if (posted.uploadStatus !== 'already_archived') {
+                        await assertSourceUnchanged(item.candidate.transcriptPath, fingerprint);
+                        finalResponse = await putContent({
+                            host: remoteHost,
+                            transcriptId: posted.transcriptId,
+                            filePath: item.candidate.transcriptPath,
+                            byteLength: fingerprint.size,
+                            fetchImpl: remoteFetch,
+                        });
+                        await assertSourceUnchanged(item.candidate.transcriptPath, fingerprint);
+                    }
+                    if (!['archived', 'updated', 'already_archived'].includes(finalResponse.uploadStatus)) {
+                        throw new SystemicUploadError('unexpected_upload_status', finalResponse.uploadStatus);
+                    }
+                    if (finalResponse.currentSha256 !== fingerprint.sha256) {
+                        throw new SystemicUploadError('malformed_response', 'Archive response SHA does not match the source');
+                    }
+                    state.status = 'uploaded';
+                    state.lastUploadedSha256 = fingerprint.sha256;
+                    state.lastUploadedAt = new Date(nowMs).toISOString();
+                    state.lastSeenSize = fingerprint.size;
+                    state.lastSeenMtimeMs = fingerprint.mtimeMs;
+                    delete state.pendingReason;
+                    delete state.missingSince;
+                    delete state.lastError;
+                    await writeSessionState(paths.sessionsDir, state);
+                    if (item.markerPath) {
+                        await removePendingMarker(item.markerPath);
+                    }
+                    if (finalResponse.uploadStatus === 'already_archived') {
+                        summary.unchanged += 1;
+                    }
+                    else {
+                        summary.uploaded += 1;
+                    }
+                    consecutiveSystemicFailures = 0;
+                }
+                catch (error) {
+                    const details = errorDetails(error);
+                    if (details.code === 'missing_source') {
+                        state.missingSince ??= new Date(nowMs).toISOString();
+                    }
+                    else {
+                        delete state.missingSince;
+                    }
+                    const missingExpired = state.missingSince !== undefined
+                        && nowMs - Date.parse(state.missingSince) >= MISSING_SOURCE_RETRY_MS;
+                    const permanentTaskFailure = (error instanceof TaskUploadError || error instanceof LocalTaskError)
+                        && isPermanentTaskFailure(details.code);
+                    state.status = (permanentTaskFailure || missingExpired) ? 'failed' : 'pending';
+                    state.pendingReason = details.code;
+                    state.lastError = { ...details, at: new Date(nowMs).toISOString() };
+                    await writeSessionState(paths.sessionsDir, state);
+                    if (error instanceof SystemicUploadError && error.code === 'rate_limited' && error.retryAfterUntil) {
+                        await writeSyncState(paths.syncStatePath, { schemaVersion: 1, retryAfterUntil: error.retryAfterUntil });
+                    }
+                    summary.failed += 1;
+                    if (error instanceof TaskUploadError || error instanceof LocalTaskError
+                        || error.code === 'ENOENT') {
+                        continue;
+                    }
+                    consecutiveSystemicFailures += 1;
+                    if (error instanceof SystemicUploadError && error.code !== 'internal_error') {
+                        summary.stoppedBy = error.code;
+                        break;
+                    }
+                    if (consecutiveSystemicFailures >= 3) {
+                        summary.stoppedBy = details.code;
+                        break;
+                    }
+                }
+            }
+            return summary;
+        }
+        finally {
+            await transport.release();
+        }
+    }
+    finally {
+        await release();
+    }
+}

package/dist/transport.d.ts

@@ -0,0 +1,27 @@
+import { type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { type CompanionInfo } from './companion.js';
+import type { LinkPaths } from './paths.js';
+export interface RemoteTransport {
+    readonly hostUrl: string;
+    readonly identity: {
+        tailnetName: string;
+        nodeName: string;
+        ipv4: string;
+    };
+    readonly fetch: typeof fetch;
+    release(): Promise<void>;
+}
+export interface AcquireTransportOptions {
+    paths: LinkPaths;
+    hostUrl: string;
+    fetchImpl?: typeof fetch;
+    resolveCompanion?: () => Promise<CompanionInfo>;
+    requiredCompanion?: CompanionInfo;
+    probeCompanion?: (companion: CompanionInfo, environment: NodeJS.ProcessEnv) => Promise<void>;
+    spawnChild?: (executable: string, args: string[], env: NodeJS.ProcessEnv) => ChildProcessWithoutNullStreams;
+    onNeedsLogin?: (url: string) => void;
+    bootstrapAuthKey?: string;
+    startTimeoutMs?: number;
+}
+export declare function consumeBootstrapAuthKey(explicitAuthKey: string | undefined, environment?: NodeJS.ProcessEnv): string | undefined;
+export declare function acquireRemoteTransport(options: AcquireTransportOptions): Promise<RemoteTransport>;

package/dist/transport.js

@@ -0,0 +1,400 @@
+import * as fs from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { isIPv4 } from 'node:net';
+import * as http from 'node:http';
+import { Readable } from 'node:stream';
+import { assertCompanionProtocol, VESPER_NET_PROTOCOL_VERSION, resolveCompanion } from './companion.js';
+const START_TIMEOUT_MS = 10 * 60_000;
+const ATTACH_TIMEOUT_MS = 2_000;
+const POLL_INTERVAL_MS = 100;
+const MAX_CONTROL_BYTES = 64 * 1024;
+const LOCAL_SECRET_HEADER = 'x-vesper-transport-secret';
+const KEEPALIVE_MS = 10_000;
+const PROXY_ENVIRONMENT_KEYS = new Set([
+    'http_proxy', 'https_proxy', 'all_proxy', 'no_proxy',
+]);
+const AUTH_KEY_ENVIRONMENT_KEYS = new Set([
+    'vesper_ts_authkey', 'ts_authkey', 'ts_auth_key',
+]);
+const AUTH_KEY_PATTERN = /^tskey-auth-[A-Za-z0-9_-]{16,512}$/;
+function directLoopbackFetch(input, init = {}) {
+    const inputRequest = input instanceof Request ? input : undefined;
+    const url = new URL(inputRequest?.url ?? input.toString());
+    if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1') {
+        return Promise.reject(new Error(`Direct transport client rejected non-loopback URL: ${url.origin}`));
+    }
+    const headers = new Headers(inputRequest?.headers);
+    if (init.headers) {
+        new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+    }
+    const method = init.method ?? inputRequest?.method ?? 'GET';
+    const body = init.body ?? inputRequest?.body;
+    const signal = init.signal ?? inputRequest?.signal;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finishReject = (error) => {
+            if (!settled) {
+                settled = true;
+                reject(error);
+            }
+        };
+        const request = http.request({
+            protocol: 'http:', hostname: '127.0.0.1', port: Number(url.port),
+            path: `${url.pathname}${url.search}`, method, headers: Object.fromEntries(headers),
+            agent: false,
+        }, (response) => {
+            const chunks = [];
+            response.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+            response.once('error', finishReject);
+            response.once('end', () => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                const responseHeaders = new Headers();
+                for (const [key, value] of Object.entries(response.headers)) {
+                    for (const item of Array.isArray(value) ? value : value === undefined ? [] : [value]) {
+                        responseHeaders.append(key, String(item));
+                    }
+                }
+                resolve(new Response(Buffer.concat(chunks), {
+                    status: response.statusCode ?? 500, statusText: response.statusMessage, headers: responseHeaders,
+                }));
+            });
+        });
+        request.once('error', finishReject);
+        const abort = () => {
+            request.destroy(new DOMException('The operation was aborted', 'AbortError'));
+        };
+        if (signal?.aborted) {
+            abort();
+            return;
+        }
+        signal?.addEventListener('abort', abort, { once: true });
+        request.once('close', () => signal?.removeEventListener('abort', abort));
+        if (body === undefined || body === null) {
+            request.end();
+        }
+        else if (typeof body === 'string' || Buffer.isBuffer(body) || body instanceof Uint8Array) {
+            request.end(body);
+        }
+        else if (typeof body.pipe === 'function') {
+            body.pipe(request);
+        }
+        else {
+            Readable.fromWeb(body).pipe(request);
+        }
+    });
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function validLoopbackEndpoint(value) {
+    if (typeof value !== 'string') {
+        return false;
+    }
+    try {
+        const url = new URL(value);
+        return url.protocol === 'http:' && url.hostname === '127.0.0.1' && url.port !== ''
+            && url.pathname === '/' && url.search === '' && url.hash === '';
+    }
+    catch {
+        return false;
+    }
+}
+function parseRendezvous(value) {
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+    const candidate = value;
+    if (candidate.protocolVersion !== VESPER_NET_PROTOCOL_VERSION
+        || !Number.isSafeInteger(candidate.pid) || candidate.pid <= 0
+        || !validLoopbackEndpoint(candidate.endpoint)
+        || typeof candidate.secret !== 'string' || candidate.secret.length < 32) {
+        return null;
+    }
+    return candidate;
+}
+async function readRendezvous(filePath) {
+    try {
+        const stat = await fs.stat(filePath);
+        if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0) {
+            throw new Error('Transport rendezvous permissions are not user-private');
+        }
+        const parsed = parseRendezvous(JSON.parse(await fs.readFile(filePath, 'utf8')));
+        if (!parsed) {
+            throw new Error('Transport rendezvous is malformed or has an unsupported protocol');
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+async function attach(paths, hostUrl, fetchImpl, requiredExecutablePath) {
+    let rendezvous;
+    try {
+        rendezvous = await readRendezvous(paths.transportRendezvousPath);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('Transport rendezvous is malformed')) {
+            return null;
+        }
+        throw error;
+    }
+    if (!rendezvous || !isAlive(rendezvous.pid)) {
+        return null;
+    }
+    const requestLease = async (inspectOnly) => {
+        try {
+            const operation = inspectOnly ? 'identity' : 'lease';
+            return await fetchImpl(`${rendezvous.endpoint}/__vesper_transport/${operation}`, {
+                headers: { [LOCAL_SECRET_HEADER]: rendezvous.secret },
+                signal: AbortSignal.timeout(ATTACH_TIMEOUT_MS),
+            });
+        }
+        catch {
+            return null;
+        }
+    };
+    const readLease = async (inspectOnly) => {
+        const response = await requestLease(inspectOnly);
+        if (!response?.ok) {
+            return null;
+        }
+        return await response.json();
+    };
+    let lease = await readLease(requiredExecutablePath !== undefined);
+    if (!lease) {
+        return null;
+    }
+    function validateLease(candidate) {
+        if (candidate.protocolVersion !== VESPER_NET_PROTOCOL_VERSION || candidate.hostUrl !== hostUrl
+            || typeof candidate.tailnetName !== 'string' || !candidate.tailnetName
+            || typeof candidate.nodeName !== 'string' || !candidate.nodeName
+            || typeof candidate.ipv4 !== 'string' || !isIPv4(candidate.ipv4)
+            || typeof candidate.executablePath !== 'string' || !candidate.executablePath) {
+            throw new Error('Running vesper-net transport targets a different host or protocol');
+        }
+    }
+    validateLease(lease);
+    if (requiredExecutablePath) {
+        const reportedExecutablePath = lease.executablePath;
+        const actualExecutablePath = await fs.realpath(reportedExecutablePath).catch(() => reportedExecutablePath);
+        const sameExecutable = process.platform === 'win32'
+            ? actualExecutablePath.toLowerCase() === requiredExecutablePath.toLowerCase()
+            : actualExecutablePath === requiredExecutablePath;
+        if (!sameExecutable) {
+            return null;
+        }
+        lease = await readLease(false);
+        if (!lease) {
+            return null;
+        }
+        validateLease(lease);
+    }
+    const transportFetch = async (input, init) => {
+        const remote = input instanceof Request ? new URL(input.url) : new URL(input.toString());
+        if (remote.origin !== new URL(hostUrl).origin) {
+            throw new Error(`Remote Memory request escaped configured host: ${remote.origin}`);
+        }
+        const local = new URL(`${remote.pathname}${remote.search}`, rendezvous.endpoint);
+        const headers = new Headers(input instanceof Request ? input.headers : undefined);
+        if (init?.headers) {
+            new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+        }
+        headers.set(LOCAL_SECRET_HEADER, rendezvous.secret);
+        return fetchImpl(local, { ...init, headers });
+    };
+    const keepalive = setInterval(() => {
+        void fetchImpl(`${rendezvous.endpoint}/__vesper_transport/lease`, {
+            headers: { [LOCAL_SECRET_HEADER]: rendezvous.secret },
+            signal: AbortSignal.timeout(ATTACH_TIMEOUT_MS),
+        }).catch(() => undefined);
+    }, KEEPALIVE_MS);
+    keepalive.unref();
+    let released = false;
+    return {
+        ownerPid: rendezvous.pid,
+        transport: {
+            hostUrl,
+            identity: { tailnetName: lease.tailnetName, nodeName: lease.nodeName, ipv4: lease.ipv4 },
+            fetch: transportFetch,
+            async release() {
+                if (!released) {
+                    released = true;
+                    clearInterval(keepalive);
+                }
+            },
+        },
+    };
+}
+function defaultSpawn(executable, args, env) {
+    return spawn(executable, args, {
+        env, detached: true, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+}
+function companionEnvironment(environment, bootstrapAuthKey) {
+    const filtered = Object.fromEntries(Object.entries(environment).filter(([key]) => {
+        const normalized = key.toLowerCase();
+        return !PROXY_ENVIRONMENT_KEYS.has(normalized) && !AUTH_KEY_ENVIRONMENT_KEYS.has(normalized);
+    }));
+    if (bootstrapAuthKey !== undefined) {
+        filtered.VESPER_TS_AUTHKEY = bootstrapAuthKey;
+    }
+    return filtered;
+}
+function protocolProbeEnvironment(environment) {
+    const filtered = companionEnvironment(environment);
+    return filtered;
+}
+export function consumeBootstrapAuthKey(explicitAuthKey, environment = process.env) {
+    let inheritedAuthKey;
+    for (const alias of AUTH_KEY_ENVIRONMENT_KEYS) {
+        for (const [key, value] of Object.entries(environment)) {
+            if (key.toLowerCase() === alias) {
+                inheritedAuthKey ??= value || undefined;
+                delete environment[key];
+            }
+        }
+    }
+    return explicitAuthKey ?? inheritedAuthKey;
+}
+function validateHostUrl(hostUrl) {
+    const url = new URL(hostUrl);
+    if (url.protocol !== 'http:' || !isIPv4(url.hostname) || url.port !== '11723'
+        || url.pathname !== '/' || url.search !== '' || url.hash !== '') {
+        throw new Error('Transport host must be the configured http://<Tailscale IPv4>:11723 origin');
+    }
+    const octets = url.hostname.split('.').map(Number);
+    if (octets[0] !== 100 || octets[1] < 64 || octets[1] > 127) {
+        throw new Error('Transport host must use Tailscale IPv4 range 100.64.0.0/10');
+    }
+}
+export async function acquireRemoteTransport(options) {
+    const bootstrapAuthKey = consumeBootstrapAuthKey(options.bootstrapAuthKey);
+    validateHostUrl(options.hostUrl);
+    if (bootstrapAuthKey !== undefined && !AUTH_KEY_PATTERN.test(bootstrapAuthKey)) {
+        throw new Error('Tailscale bootstrap auth key is malformed');
+    }
+    const fetchImpl = options.fetchImpl ?? directLoopbackFetch;
+    let companion = options.requiredCompanion;
+    if (companion) {
+        await (options.probeCompanion ?? assertCompanionProtocol)(companion, protocolProbeEnvironment(process.env));
+    }
+    const requiredExecutablePath = companion
+        ? await fs.realpath(companion.executable).catch(() => companion.executable)
+        : undefined;
+    const existing = await attach(options.paths, options.hostUrl, fetchImpl, requiredExecutablePath);
+    if (existing) {
+        return existing.transport;
+    }
+    // Package selection and lockstep version validation must fail before any
+    // transport state, identity directory, or rendezvous mutation.
+    companion ??= await (options.resolveCompanion ?? (() => resolveCompanion()))();
+    if (!options.requiredCompanion) {
+        await (options.probeCompanion ?? assertCompanionProtocol)(companion, protocolProbeEnvironment(process.env));
+    }
+    const deadline = Date.now() + (options.startTimeoutMs ?? START_TIMEOUT_MS);
+    const args = [
+        '--mode', 'transport', '--state-dir', options.paths.tsnetDir, '--hostname', 'vesper-link',
+        '--host-url', options.hostUrl, '--rendezvous', options.paths.transportRendezvousPath,
+        '--lock', options.paths.transportLockPath, '--idle-timeout', '30s',
+    ];
+    const child = (options.spawnChild ?? defaultSpawn)(companion.executable, args, companionEnvironment(process.env, bootstrapAuthKey));
+    child.stdin.end();
+    let controlBuffer = '';
+    let fatalMessage;
+    child.once('error', (error) => { fatalMessage = `spawn failed: ${error.message}`; });
+    child.once('exit', (code, signal) => {
+        fatalMessage ??= `exited before ready (code=${code ?? 'none'}, signal=${signal ?? 'none'})`;
+    });
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+        controlBuffer += chunk;
+        if (Buffer.byteLength(controlBuffer, 'utf8') > MAX_CONTROL_BYTES) {
+            fatalMessage = 'vesper-net control stream exceeded its limit';
+            child.kill('SIGTERM');
+            return;
+        }
+        let lineEnd;
+        while ((lineEnd = controlBuffer.indexOf('\n')) >= 0) {
+            const line = controlBuffer.slice(0, lineEnd).trim();
+            controlBuffer = controlBuffer.slice(lineEnd + 1);
+            if (!line) {
+                continue;
+            }
+            try {
+                const event = JSON.parse(line);
+                if (event.protocolVersion !== VESPER_NET_PROTOCOL_VERSION) {
+                    fatalMessage = 'vesper-net protocol mismatch';
+                    child.kill('SIGTERM');
+                }
+                else if (event.type === 'needs_login' && typeof event.loginUrl === 'string') {
+                    if (bootstrapAuthKey !== undefined) {
+                        fatalMessage = 'automatic enrollment key was not accepted; copy a fresh Memory Link command';
+                        child.kill('SIGTERM');
+                    }
+                    else {
+                        options.onNeedsLogin?.(event.loginUrl);
+                    }
+                }
+                else if (event.type === 'ready' && typeof event.tailnetName === 'string'
+                    && typeof event.nodeName === 'string' && typeof event.ipv4 === 'string') {
+                    // Rendezvous attachment below is the authoritative transport-ready signal.
+                }
+                else if (event.type === 'fatal' && typeof event.message === 'string') {
+                    fatalMessage = event.message;
+                    child.kill('SIGTERM');
+                }
+                else {
+                    fatalMessage = 'vesper-net emitted an unknown or malformed control event';
+                    child.kill('SIGTERM');
+                }
+            }
+            catch {
+                fatalMessage = 'vesper-net emitted malformed control JSON';
+                child.kill('SIGTERM');
+            }
+        }
+    });
+    // Never persist helper stderr. Drain it to prevent a blocked pipe.
+    child.stderr.resume();
+    while (Date.now() < deadline) {
+        let attached;
+        try {
+            attached = await attach(options.paths, options.hostUrl, fetchImpl, requiredExecutablePath);
+        }
+        catch (error) {
+            child.kill('SIGTERM');
+            throw error;
+        }
+        if (attached) {
+            if (attached.ownerPid === child.pid) {
+                child.unref();
+                child.stdout.unref?.();
+                child.stderr.unref?.();
+            }
+            else {
+                child.kill('SIGTERM');
+            }
+            return attached.transport;
+        }
+        if (fatalMessage) {
+            child.kill('SIGTERM');
+            throw new Error(`vesper-net transport failed: ${fatalMessage}`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+    child.kill('SIGTERM');
+    throw new Error('Timed out waiting for vesper-net transport');
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VESPER_LINK_VERSION = "0.1.4";

package/dist/version.js

@@ -0,0 +1 @@
+export const VESPER_LINK_VERSION = '0.1.4';