@msvesper/vesper-link 0.1.4 → 0.1.6

package/LICENSE.md

@@ -1,44 +1,44 @@
-# Vesper Link End User License Agreement (EULA)
-
-**Copyright (c) 2026 VSWork. All Rights Reserved.**
-
-## 1. Grant of License
-
-This End User License Agreement ("Agreement") grants you ("User") a limited, non-exclusive, non-transferable, revocable license to install and use Vesper Link ("Software") for personal or internal business purposes, subject to the terms below.
-
-## 2. Restrictions
-
-You may NOT:
-- Copy, modify, adapt, translate, or create derivative works of the Software
-- Reverse engineer, decompile, disassemble, or attempt to derive the source code
-- Redistribute, sublicense, rent, lease, or lend the Software to any third party
-- Remove or alter any proprietary notices, labels, or marks on the Software
-- Use the Software for any unlawful purpose or in violation of any applicable laws
-
-## 3. Intellectual Property
-
-The Software, including all copies, modifications, and derivative works, is the exclusive property of VSWork and is protected by copyright and other intellectual property laws. This Agreement does not grant you any ownership rights to the Software.
-
-## 4. No Warranty
-
-THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU.
-
-## 5. Limitation of Liability
-
-IN NO EVENT SHALL VSWORK BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, LOSS OF DATA, BUSINESS INTERRUPTION, OR LOSS OF PROFITS) ARISING OUT OF OR IN CONNECTION WITH THIS AGREEMENT OR THE USE OF THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
-
-## 6. Termination
-
-This license is effective until terminated. Your rights under this license will terminate automatically without notice if you fail to comply with any of its terms. Upon termination, you must destroy all copies of the Software in your possession.
-
-## 7. Governing Law
-
-This Agreement shall be governed by and construed in accordance with the laws of the jurisdiction in which VSWork operates, without regard to its conflict of law provisions.
-
-## 8. Entire Agreement
-
-This Agreement constitutes the entire agreement between you and VSWork regarding the Software and supersedes all prior agreements and understandings, whether written or oral.
-
----
-
-By installing or using this Software, you acknowledge that you have read, understood, and agree to be bound by the terms of this Agreement.
+# Vesper Link End User License Agreement (EULA)
+
+**Copyright (c) 2026 VSWork. All Rights Reserved.**
+
+## 1. Grant of License
+
+This End User License Agreement ("Agreement") grants you ("User") a limited, non-exclusive, non-transferable, revocable license to install and use Vesper Link ("Software") for personal or internal business purposes, subject to the terms below.
+
+## 2. Restrictions
+
+You may NOT:
+- Copy, modify, adapt, translate, or create derivative works of the Software
+- Reverse engineer, decompile, disassemble, or attempt to derive the source code
+- Redistribute, sublicense, rent, lease, or lend the Software to any third party
+- Remove or alter any proprietary notices, labels, or marks on the Software
+- Use the Software for any unlawful purpose or in violation of any applicable laws
+
+## 3. Intellectual Property
+
+The Software, including all copies, modifications, and derivative works, is the exclusive property of VSWork and is protected by copyright and other intellectual property laws. This Agreement does not grant you any ownership rights to the Software.
+
+## 4. No Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU.
+
+## 5. Limitation of Liability
+
+IN NO EVENT SHALL VSWORK BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, LOSS OF DATA, BUSINESS INTERRUPTION, OR LOSS OF PROFITS) ARISING OUT OF OR IN CONNECTION WITH THIS AGREEMENT OR THE USE OF THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+## 6. Termination
+
+This license is effective until terminated. Your rights under this license will terminate automatically without notice if you fail to comply with any of its terms. Upon termination, you must destroy all copies of the Software in your possession.
+
+## 7. Governing Law
+
+This Agreement shall be governed by and construed in accordance with the laws of the jurisdiction in which VSWork operates, without regard to its conflict of law provisions.
+
+## 8. Entire Agreement
+
+This Agreement constitutes the entire agreement between you and VSWork regarding the Software and supersedes all prior agreements and understandings, whether written or oral.
+
+---
+
+By installing or using this Software, you acknowledge that you have read, understood, and agree to be bound by the terms of this Agreement.

package/README.md

@@ -1,26 +1,45 @@
-# vesper-link
-
-**Vesper Memory Link — One Memory across all your devices.**
-
-`vesper-link` connects a supported Windows or Linux device to Vesper Memory. It can:
-
-- Sync completed Claude Code, GitHub Copilot CLI, and OpenAI Codex sessions to your Vesper Host.
-- Let full-access devices search and add Vesper Memory through MCP.
-
-## Connect a Device
-
-On the Windows device running Vesper, open **Memory Links** and copy a connection command. Run it on the device you want to connect; no global installation is required.
-
-Node.js 20 or later is required. V1 supports Windows x64 and Linux x64.
-
-## Manage the Connection
-
-```bash
-npx --yes @msvesper/vesper-link@0.1.4 status
-npx --yes @msvesper/vesper-link@0.1.4 pause
-npx --yes @msvesper/vesper-link@0.1.4 resume
-npx --yes @msvesper/vesper-link@0.1.4 doctor
-npx --yes @msvesper/vesper-link@0.1.4 uninstall
-```
-
-Session transcripts are sent to the Vesper Host selected during setup and retained there. They are not uploaded to a Vesper-operated cloud service. Uninstalling the connection does not delete the original transcripts or Memory already saved on the Host.
+# vesper-link
+
+**Vesper Memory Link — One Memory across all your devices.**
+
+`vesper-link` connects a supported Windows or Linux device to Vesper Memory. It can:
+
+- Sync completed Claude Code, GitHub Copilot CLI, VS Code Copilot Chat, and OpenAI Codex sessions to your Vesper Host.
+- Let full-access devices search and add Vesper Memory through MCP.
+
+## Connect a Device
+
+On the Windows device running Vesper, open **Memory Links** and copy a connection command. Run it on the device you want to connect; no global installation is required.
+
+The Remote must already have Node.js 20+ and npm 9+. V1 supports Windows x64 and Linux x64.
+
+Linux also requires the `crontab` command for periodic session sync. Install it before running the copied command, then ensure the service is running:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install cron
+sudo systemctl enable --now cron
+
+# Fedora/RHEL
+sudo dnf install cronie
+sudo systemctl enable --now crond
+```
+
+Vesper Link does not use `sudo` or install operating-system packages for you.
+
+VS Code Copilot Chat transcripts are discovered from local VS Code workspace storage and from VS Code Server storage on Remote SSH hosts. On Windows this includes `%APPDATA%\Code\User\workspaceStorage` and the default `%USERPROFILE%\.vscode-server\data\User\workspaceStorage`; on Linux it includes `~/.config/Code/User/workspaceStorage` and `~/.vscode-server/data/User/workspaceStorage`. `VSCODE_AGENT_FOLDER` is honored when set. Vesper Link reads the per-session `GitHub.copilot-chat/transcripts/*.jsonl` files, not Copilot's global `session-store.db`.
+
+## Manage the Connection
+
+```bash
+npx --yes @msvesper/vesper-link@host-v1 upgrade
+npx --yes @msvesper/vesper-link@host-v1 status
+npx --yes @msvesper/vesper-link@host-v1 pause
+npx --yes @msvesper/vesper-link@host-v1 resume
+npx --yes @msvesper/vesper-link@host-v1 doctor
+npx --yes @msvesper/vesper-link@host-v1 uninstall
+```
+
+`upgrade` reads the existing Host and access role from `~/.vesper-link/`, replaces the managed runtime and integrations transactionally, and preserves the Remote identity and queued work. It accepts no Host or auth key. If the existing installation, configuration, or Tailscale identity is missing or inconsistent, it stops without relinking. Resume a paused Link before upgrading.
+
+Session transcripts are sent to the Vesper Host selected during setup and retained there. They are not uploaded to a Vesper-operated cloud service. Uninstalling the connection does not delete the original transcripts or Memory already saved on the Host.

package/dist/cli.js

@@ -1,17 +1,18 @@
 #!/usr/bin/env node
-import { writeConfig } from './config.js';
+import * as fs from 'node:fs/promises';
+import { readConfig, writeConfig } from './config.js';
 import { getDoctorReport, getStatusReport } from './diagnostics.js';
 import { resolveHookReport } from './hook-report.js';
 import { pauseIntegrations, resetRemoteIdentity, resumeIntegrations, uninstallIntegrations } from './installation.js';
 import { parseInstallArguments } from './install-args.js';
-import { installVesperLink } from './installer.js';
+import { installVesperLink, upgradeVesperLink } from './installer.js';
 import { runMemoryMcp } from './memory-mcp.js';
 import { appendSyncLog } from './operational-log.js';
 import { writePendingMarker } from './pending.js';
 import { resolveLinkPaths } from './paths.js';
 import { runSyncOnce } from './sync.js';
 import { VESPER_LINK_VERSION } from './version.js';
-const USAGE = 'Usage: vesper-link <configure|report-session|sync-once|scheduled-sync|mcp|install|pause|resume|uninstall|reset-identity|status|doctor>';
+const USAGE = 'Usage: vesper-link <configure|report-session|sync-once|scheduled-sync|mcp|install|upgrade|pause|resume|uninstall|reset-identity|status|doctor>';
 function flags(args) {
     const result = new Map();
     for (let index = 0; index < args.length; index += 1) {
@@ -51,7 +52,15 @@ async function main() {
         if (!host) {
             throw new Error('Usage: vesper-link configure --host <url>');
         }
-        const config = await writeConfig(paths.configPath, host);
+        const existing = await fs.access(paths.configPath)
+            .then(() => readConfig(paths.configPath))
+            .catch((error) => {
+            if (error.code === 'ENOENT') {
+                return undefined;
+            }
+            throw error;
+        });
+        const config = await writeConfig(paths.configPath, host, process.env.VSCODE_AGENT_FOLDER ?? existing?.vscodeAgentFolder);
         process.stdout.write(`${JSON.stringify(config)}\n`);
         return;
     }
@@ -116,6 +125,17 @@ async function main() {
         })}\n`);
         return;
     }
+    if (command === 'upgrade') {
+        if (args.length > 0) {
+            throw new Error('Usage: vesper-link upgrade');
+        }
+        const result = await upgradeVesperLink({ paths });
+        process.stdout.write(`${JSON.stringify({
+            upgraded: true, runtimeVersion: result.state.runtime.version,
+            sourceTrust: result.state.sourceTrust, firstSyncStarted: result.firstSyncStarted,
+        })}\n`);
+        return;
+    }
     if (command === 'uninstall') {
         process.stdout.write(`${JSON.stringify({ removed: await uninstallIntegrations(paths) })}\n`);
         return;

package/dist/collectors/copilot.js

@@ -16,6 +16,42 @@ function parseYamlScalars(text) {
     }
     return values;
 }
+async function readVscodeWorkspace(workspaceDir, context) {
+    try {
+        const workspace = JSON.parse(await fs.readFile(path.join(workspaceDir, 'workspace.json'), 'utf8'));
+        const cwdUri = typeof workspace.folder === 'string'
+            ? workspace.folder
+            : typeof workspace.workspace === 'string' ? workspace.workspace : undefined;
+        if (!cwdUri) {
+            return {};
+        }
+        let projectPath = cwdUri;
+        try {
+            projectPath = decodeURIComponent(new URL(cwdUri).pathname).replace(/^\/([A-Za-z]:\/)/, '$1');
+        }
+        catch {
+            // Keep the opaque location for project grouping when it is not a valid URL.
+        }
+        return { cwdUri, projectKey: pathToProjectKey(projectPath) };
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            context.reportIssue?.({ provider: 'github-copilot', code: 'workspace_metadata_unreadable', message: String(error) });
+        }
+        return {};
+    }
+}
+function preferNewest(candidates) {
+    const byId = new Map();
+    for (const candidate of candidates) {
+        const current = byId.get(candidate.providerSessionId);
+        if (!current || candidate.mtimeMs > current.mtimeMs
+            || (candidate.mtimeMs === current.mtimeMs && candidate.transcriptPath < current.transcriptPath)) {
+            byId.set(candidate.providerSessionId, candidate);
+        }
+    }
+    return [...byId.values()];
+}
 export class CopilotCollector {
     async collect(context) {
         const files = await walkFiles(context.copilotSessionsDir, (filePath) => path.basename(filePath) === 'events.jsonl');
@@ -59,6 +95,51 @@ export class CopilotCollector {
                 context.reportIssue?.({ provider: 'github-copilot', code: 'source_unreadable', message: String(error) });
             }
         }
-        return candidates;
+        for (const workspaceStorageDir of context.copilotVscodeWorkspaceStorageDirs) {
+            let workspaces;
+            try {
+                workspaces = await fs.readdir(workspaceStorageDir, { withFileTypes: true });
+            }
+            catch (error) {
+                if (['ENOENT', 'EACCES', 'EPERM'].includes(String(error.code))) {
+                    continue;
+                }
+                throw error;
+            }
+            for (const workspace of workspaces) {
+                if (!workspace.isDirectory()) {
+                    continue;
+                }
+                const workspaceDir = path.join(workspaceStorageDir, workspace.name);
+                const transcriptDir = path.join(workspaceDir, 'GitHub.copilot-chat', 'transcripts');
+                const transcripts = await walkFiles(transcriptDir, (filePath) => path.extname(filePath).toLowerCase() === '.jsonl');
+                if (transcripts.length === 0) {
+                    continue;
+                }
+                const metadata = await readVscodeWorkspace(workspaceDir, context);
+                for (const transcriptPath of transcripts) {
+                    try {
+                        const stat = await fs.stat(transcriptPath);
+                        candidates.push({
+                            provider: 'github-copilot',
+                            format: 'github-copilot-events-jsonl',
+                            formatVersion: 'observed-v1',
+                            providerSessionId: 'vscode:' + path.basename(transcriptPath, path.extname(transcriptPath)),
+                            transcriptPath,
+                            ...metadata,
+                            sourceCreatedAt: stat.birthtime.toISOString(),
+                            sourceUpdatedAt: stat.mtime.toISOString(),
+                            size: stat.size,
+                            mtimeMs: stat.mtimeMs,
+                            discovery: 'scan',
+                        });
+                    }
+                    catch (error) {
+                        context.reportIssue?.({ provider: 'github-copilot', code: 'source_unreadable', message: String(error) });
+                    }
+                }
+            }
+        }
+        return preferNewest(candidates);
     }
 }

package/dist/collectors/types.d.ts

@@ -3,6 +3,7 @@ export interface CollectorContext {
     nowMs: number;
     claudeProjectsDir: string;
     copilotSessionsDir: string;
+    copilotVscodeWorkspaceStorageDirs: string[];
     codexHome: string;
     reportIssue?: (issue: CollectorIssue) => void;
 }

package/dist/config.d.ts

@@ -1,7 +1,9 @@
 export interface LinkConfig {
     schemaVersion: 1;
     host: string;
+    vscodeAgentFolder?: string;
 }
+export declare function normalizeVscodeAgentFolder(value: string | undefined): string | undefined;
 export declare function normalizeHost(value: string): string;
 export declare function readConfig(configPath: string): Promise<LinkConfig>;
-export declare function writeConfig(configPath: string, host: string): Promise<LinkConfig>;
+export declare function writeConfig(configPath: string, host: string, vscodeAgentFolder?: string): Promise<LinkConfig>;

package/dist/config.js

@@ -1,5 +1,16 @@
 import { isIPv4 } from 'node:net';
+import * as path from 'node:path';
 import { readJsonFile, writeJsonAtomic } from './atomic-json.js';
+export function normalizeVscodeAgentFolder(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const normalized = path.normalize(value).replace(/[\\/]+$/, '');
+    if (!normalized || !path.isAbsolute(normalized) || normalized === path.parse(normalized).root) {
+        throw new Error('VSCODE_AGENT_FOLDER must be an absolute non-root path');
+    }
+    return normalized;
+}
 function isTailscaleIpv4(hostname) {
     if (!isIPv4(hostname)) {
         return false;
@@ -32,10 +43,20 @@ export async function readConfig(configPath) {
     if (!config || config.schemaVersion !== 1 || typeof config.host !== 'string') {
         throw new Error(`Missing or invalid config at ${configPath}; run vesper-link configure --host <url>`);
     }
-    return { schemaVersion: 1, host: normalizeHost(config.host) };
+    if (config.vscodeAgentFolder !== undefined && typeof config.vscodeAgentFolder !== 'string') {
+        throw new Error(`Invalid VSCODE_AGENT_FOLDER in config at ${configPath}`);
+    }
+    return {
+        schemaVersion: 1,
+        host: normalizeHost(config.host),
+        vscodeAgentFolder: normalizeVscodeAgentFolder(config.vscodeAgentFolder),
+    };
 }
-export async function writeConfig(configPath, host) {
-    const config = { schemaVersion: 1, host: normalizeHost(host) };
+export async function writeConfig(configPath, host, vscodeAgentFolder) {
+    const config = {
+        schemaVersion: 1, host: normalizeHost(host),
+        vscodeAgentFolder: normalizeVscodeAgentFolder(vscodeAgentFolder),
+    };
     await writeJsonAtomic(configPath, config);
     return config;
 }

package/dist/installation.d.ts

@@ -51,6 +51,7 @@ export declare function installManagedRuntime(options: {
     now?: Date;
     postInstallDoctor?: () => Promise<void>;
     faults?: InstallFaults;
+    vscodeAgentFolder?: string;
 }): Promise<InstalledState>;
 export declare function uninstallIntegrations(paths: LinkPaths, runner?: ProcessRunner, probeProcess?: (pid: number) => 'alive' | 'absent' | 'unknown'): Promise<boolean>;
 export declare function pauseIntegrations(paths: LinkPaths, runner?: ProcessRunner): Promise<boolean>;

package/dist/installation.js

@@ -2,6 +2,7 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { readJsonFile, writeJsonAtomic } from './atomic-json.js';
+import { normalizeVscodeAgentFolder } from './config.js';
 import { stableLauncherSource } from './managed-runtime.js';
 import { acquireSyncLock } from './lock.js';
 import { NodeProcessRunner } from './process-runner.js';
@@ -150,6 +151,14 @@ async function prepareInstall(options) {
             JSON.parse(snapshot.content.toString('utf8'));
         }
     }
+    let previousAgentFolder;
+    if (config.existed) {
+        const previousConfig = JSON.parse(config.content.toString('utf8'));
+        if (typeof previousConfig.vscodeAgentFolder === 'string') {
+            previousAgentFolder = previousConfig.vscodeAgentFolder;
+        }
+    }
+    const vscodeAgentFolder = normalizeVscodeAgentFolder(options.vscodeAgentFolder ?? previousAgentFolder);
     const installationId = previous?.installationId ?? randomUUID();
     const minuteOffset = previous?.minuteOffset ?? stableMinuteOffset(options.paths.homeDir);
     const scheduler = await prepareScheduler({
@@ -174,6 +183,7 @@ async function prepareInstall(options) {
                 ...(previous?.createdProviderFiles ?? []),
                 ...providerFiles.filter((snapshot) => !snapshot.existed).map((snapshot) => snapshot.filePath),
             ])],
+        vscodeAgentFolder,
     };
 }
 export async function installManagedRuntime(options) {
@@ -185,6 +195,7 @@ export async function installManagedRuntime(options) {
         paths: options.paths, runtime: options.runtime, host: options.host,
         sourceTrust: options.capabilities.sourceTrust, providers: options.providers,
         nodePath, platform, runner, now,
+        vscodeAgentFolder: options.vscodeAgentFolder,
     });
     const installationId = prepared.installationId;
     const pointer = {
@@ -196,7 +207,9 @@ export async function installManagedRuntime(options) {
         await ensureLauncher(options.paths);
         await writeJsonAtomic(options.paths.currentPath, pointer);
         await options.faults?.afterStep?.('current');
-        await writeJsonAtomic(options.paths.configPath, { schemaVersion: 1, host: options.host });
+        await writeJsonAtomic(options.paths.configPath, {
+            schemaVersion: 1, host: options.host, vscodeAgentFolder: prepared.vscodeAgentFolder,
+        });
         await options.faults?.afterStep?.('config');
         providersApplied = true;
         const integrations = await applyProviderIntegrations({

package/dist/installer.d.ts

@@ -38,6 +38,8 @@ export interface InstallerDependencies {
         onNeedsLogin?: (url: string) => void;
         requiredCompanion?: ManagedRuntime['companion'];
         bootstrapAuthKey?: string;
+        failIfLoginRequired?: boolean;
+        replaceExistingTransport?: boolean;
     }): Promise<RemoteTransport>;
     getHealth: typeof getHealth;
     getCapabilities: typeof getCapabilities;
@@ -56,4 +58,10 @@ export declare function installVesperLink(options: {
     pollIntervalMs?: number;
     signal?: AbortSignal;
     dependencies?: InstallerDependencies;
+    requireExistingIdentity?: boolean;
+}): Promise<InstallResult>;
+export declare function upgradeVesperLink(options: {
+    paths: LinkPaths;
+    runner?: ProcessRunner;
+    dependencies?: InstallerDependencies;
 }): Promise<InstallResult>;

package/dist/installer.js

@@ -1,8 +1,8 @@
 import * as fs from 'node:fs/promises';
 import { spawn } from 'node:child_process';
-import { normalizeHost } from './config.js';
+import { normalizeHost, readConfig } from './config.js';
 import { getCapabilities, getHealth, SystemicUploadError } from './http-client.js';
-import { installManagedRuntime } from './installation.js';
+import { installManagedRuntime, readInstalledState } from './installation.js';
 import { acquireSyncLock } from './lock.js';
 import { prepareManagedRuntime, validateInstallPrerequisites, validateManagedRuntime, } from './managed-runtime.js';
 import { NodeProcessRunner } from './process-runner.js';
@@ -58,6 +58,9 @@ export async function installVesperLink(options) {
     let bootstrapAuthKey = consumeBootstrapAuthKey(options.bootstrapAuthKey);
     options.bootstrapAuthKey = undefined;
     const automaticEnrollment = bootstrapAuthKey !== undefined;
+    if (options.requireExistingIdentity && automaticEnrollment) {
+        throw new Error('upgrade does not accept a Tailscale auth key');
+    }
     const host = normalizeHost(options.host);
     const companion = await dependencies.validatePrerequisites({ hostUrl: host, runner });
     const releaseCandidateLock = await acquireSyncLock(options.paths.lockPath);
@@ -72,13 +75,17 @@ export async function installVesperLink(options) {
     const progress = {
         schemaVersion: 1, state: 'enrolling', host, expectedRole: options.expectedRole, updatedAt: new Date().toISOString(),
     };
-    await writeProgress(options.paths, progress);
+    if (!options.requireExistingIdentity) {
+        await writeProgress(options.paths, progress);
+    }
     let transport;
     try {
         transport = await dependencies.acquireTransport({
             paths: options.paths, hostUrl: host,
             requiredCompanion: runtime.companion,
             bootstrapAuthKey,
+            failIfLoginRequired: options.requireExistingIdentity,
+            replaceExistingTransport: options.requireExistingIdentity,
             onNeedsLogin: (url) => {
                 options.onNeedsLogin?.(url);
             },
@@ -102,6 +109,9 @@ export async function installVesperLink(options) {
                 if (!(error instanceof SystemicUploadError) || error.httpStatus !== 403) {
                     throw error;
                 }
+                if (options.requireExistingIdentity) {
+                    throw new Error('The existing Tailscale identity is no longer authorized; upgrade stopped without relinking');
+                }
                 if (automaticEnrollment) {
                     throw new AutomaticEnrollmentConflictError(progress);
                 }
@@ -144,6 +154,7 @@ export async function installVesperLink(options) {
         await dependencies.validateRuntime(runtime);
         const candidateTransport = await dependencies.acquireTransport({
             paths: options.paths, hostUrl: host, requiredCompanion: runtime.companion,
+            failIfLoginRequired: options.requireExistingIdentity,
         });
         try {
             const [candidateHealth, candidateCapabilities] = await Promise.all([
@@ -160,10 +171,12 @@ export async function installVesperLink(options) {
         }
         installed = await dependencies.installManaged({
             paths: options.paths, runtime, host, capabilities, runner,
+            vscodeAgentFolder: process.env.VSCODE_AGENT_FOLDER,
             postInstallDoctor: async () => {
                 await dependencies.validateRuntime(runtime);
                 const postTransport = await dependencies.acquireTransport({
                     paths: options.paths, hostUrl: host, requiredCompanion: runtime.companion,
+                    failIfLoginRequired: options.requireExistingIdentity,
                 });
                 try {
                     const [health, currentCapabilities] = await Promise.all([
@@ -190,6 +203,37 @@ export async function installVesperLink(options) {
     await dependencies.triggerFirstSync(options.paths);
     return { state: installed, firstSyncStarted: true };
 }
+export async function upgradeVesperLink(options) {
+    const inheritedAuthKey = consumeBootstrapAuthKey(undefined);
+    if (inheritedAuthKey !== undefined) {
+        throw new Error('upgrade does not accept a Tailscale auth key');
+    }
+    const installed = await readInstalledState(options.paths);
+    if (!installed) {
+        throw new Error('No existing Vesper Link installation; use a Host-generated install command first');
+    }
+    if (installed.paused) {
+        throw new Error('Vesper Link is paused; resume it before upgrading');
+    }
+    const config = await readConfig(options.paths.configPath);
+    if (installed.host !== config.host) {
+        throw new Error('Installed Host does not match Vesper Link config; refusing to guess during upgrade');
+    }
+    const identityEntries = await fs.readdir(options.paths.tsnetDir).catch((error) => {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    });
+    if (identityEntries.length === 0) {
+        throw new Error('No existing Tailscale identity; upgrade stopped without relinking');
+    }
+    return installVesperLink({
+        paths: options.paths, host: config.host, expectedRole: installed.sourceTrust,
+        runner: options.runner, dependencies: options.dependencies, requireExistingIdentity: true,
+        pollAuthorization: false,
+    });
+}
 async function waitForPoll(milliseconds, signal) {
     if (signal?.aborted) {
         throw signal.reason ?? new Error('Installation cancelled');

package/dist/managed-runtime.js

@@ -4,6 +4,7 @@ import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { assertCompanionProtocol, resolveCompanion } from './companion.js';
 import { NodeProcessRunner } from './process-runner.js';
+import { validateLinuxSchedulerPrerequisite } from './scheduler.js';
 async function metadata(filePath) {
     return JSON.parse(await fs.readFile(filePath, 'utf8'));
 }
@@ -34,21 +35,21 @@ async function copyDirectory(source, destination) {
     await fs.cp(source, destination, { recursive: true, force: false, errorOnExist: true });
 }
 export function stableLauncherSource() {
-    return `#!/usr/bin/env node
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-const stateDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const current = JSON.parse(await fs.readFile(path.join(stateDir, 'current.json'), 'utf8'));
-if (current.schemaVersion !== 1 || typeof current.runtimePath !== 'string') {
-  throw new Error('vesper-link current runtime pointer is malformed');
-}
-const runtimeRoot = path.join(stateDir, 'runtime');
-const relative = path.relative(runtimeRoot, current.runtimePath);
-if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
-  throw new Error('vesper-link current runtime escaped the managed runtime root');
-}
-await import(pathToFileURL(path.join(current.runtimePath, 'package', 'dist', 'cli.js')).href);
+    return `#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+const stateDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const current = JSON.parse(await fs.readFile(path.join(stateDir, 'current.json'), 'utf8'));
+if (current.schemaVersion !== 1 || typeof current.runtimePath !== 'string') {
+  throw new Error('vesper-link current runtime pointer is malformed');
+}
+const runtimeRoot = path.join(stateDir, 'runtime');
+const relative = path.relative(runtimeRoot, current.runtimePath);
+if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+  throw new Error('vesper-link current runtime escaped the managed runtime root');
+}
+await import(pathToFileURL(path.join(current.runtimePath, 'package', 'dist', 'cli.js')).href);
 `;
 }
 export async function validateInstallPrerequisites(options) {
@@ -70,6 +71,9 @@ export async function validateInstallPrerequisites(options) {
     if (npm.code !== 0 || majorVersion(npm.stdout.trim()) < 9) {
         throw new Error(`A working npm 9 or newer is required: ${npm.stderr.trim() || npm.stdout.trim()}`);
     }
+    if (platform === 'linux') {
+        await validateLinuxSchedulerPrerequisite(runner);
+    }
     const companion = await (options.resolveSourceCompanion ?? (() => resolveCompanion(platform, architecture)))();
     await (options.probeCompanion ?? assertCompanionProtocol)(companion, protocolProbeEnvironment(process.env));
     return companion;

package/dist/paths.d.ts

@@ -18,6 +18,8 @@ export interface LinkPaths {
     logsDir: string;
     claudeProjectsDir: string;
     copilotSessionsDir: string;
+    copilotVscodeWorkspaceStorageDirs: string[];
     codexHome: string;
 }
-export declare function resolveLinkPaths(environment?: NodeJS.ProcessEnv): LinkPaths;
+export declare function vscodeAgentWorkspaceStorageDir(agentFolder: string): string;
+export declare function resolveLinkPaths(environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): LinkPaths;

package/dist/paths.js

@@ -1,6 +1,9 @@
 import * as os from 'node:os';
 import * as path from 'node:path';
-export function resolveLinkPaths(environment = process.env) {
+export function vscodeAgentWorkspaceStorageDir(agentFolder) {
+    return path.join(agentFolder, 'data', 'User', 'workspaceStorage');
+}
+export function resolveLinkPaths(environment = process.env, platform = process.platform) {
     const homeDir = environment.HOME || environment.USERPROFILE || os.homedir();
     const rawStateDir = path.normalize(environment.VESPER_LINK_HOME || path.join(homeDir, '.vesper-link'));
     const root = path.parse(rawStateDir).root;
@@ -9,6 +12,23 @@ export function resolveLinkPaths(environment = process.env) {
     }
     const stateDir = rawStateDir.replace(/[\\/]+$/, '');
     const codexHome = environment.CODEX_HOME || path.join(homeDir, '.codex');
+    const appData = environment.APPDATA || path.join(homeDir, 'AppData', 'Roaming');
+    const localWorkspaceStorageDirs = platform === 'win32'
+        ? [
+            path.join(appData, 'Code', 'User', 'workspaceStorage'),
+            path.join(appData, 'Code - Insiders', 'User', 'workspaceStorage'),
+        ]
+        : [
+            path.join(homeDir, '.config', 'Code', 'User', 'workspaceStorage'),
+            path.join(homeDir, '.config', 'Code - Insiders', 'User', 'workspaceStorage'),
+        ];
+    const agentRoots = environment.VSCODE_AGENT_FOLDER
+        ? [environment.VSCODE_AGENT_FOLDER]
+        : [path.join(homeDir, '.vscode-server'), path.join(homeDir, '.vscode-server-insiders')];
+    const copilotVscodeWorkspaceStorageDirs = [
+        ...localWorkspaceStorageDirs,
+        ...agentRoots.map(vscodeAgentWorkspaceStorageDir),
+    ];
     return {
         homeDir,
         stateDir,
@@ -31,6 +51,7 @@ export function resolveLinkPaths(environment = process.env) {
         logsDir: path.join(stateDir, 'logs'),
         claudeProjectsDir: path.join(homeDir, '.claude', 'projects'),
         copilotSessionsDir: path.join(homeDir, '.copilot', 'session-state'),
+        copilotVscodeWorkspaceStorageDirs,
         codexHome,
     };
 }

package/dist/scheduler.d.ts

@@ -22,6 +22,7 @@ export type SchedulerSnapshot = {
     content: string;
 };
 export declare function stableMinuteOffset(homeDir: string, machineName?: string): number;
+export declare function validateLinuxSchedulerPrerequisite(runner: ProcessRunner): Promise<void>;
 export declare function prepareScheduler(options: {
     platform?: NodeJS.Platform;
     runner?: ProcessRunner;

package/dist/scheduler.js

@@ -14,12 +14,31 @@ function shellQuote(value) {
 function ownerToken(installationId) {
     return '--owner ' + installationId;
 }
+async function runCron(runner, args, input) {
+    const environment = { ...process.env, LC_ALL: 'C', LANG: 'C' };
+    try {
+        return await runner.run('crontab', args, input, environment);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT') {
+            throw new Error('Linux requires the crontab command for periodic session sync.\n'
+                + 'Ubuntu/Debian: sudo apt-get install cron\n'
+                + 'Fedora/RHEL: sudo dnf install cronie\n'
+                + 'Ensure the cron service is running, then rerun this command.');
+        }
+        if (code === 'EACCES') {
+            throw new Error('Cannot execute crontab. Check that the crontab executable has execute permission and is not on a filesystem '
+                + 'mounted with noexec, then rerun this command.');
+        }
+        throw error;
+    }
+}
 export function stableMinuteOffset(homeDir, machineName = os.hostname()) {
     return Number.parseInt(createHash('sha256').update(machineName).update('\0').update(homeDir).digest('hex').slice(0, 8), 16) % 60;
 }
 async function readCron(runner) {
-    const environment = { ...process.env, LC_ALL: 'C', LANG: 'C' };
-    const result = await runner.run('crontab', ['-l'], undefined, environment);
+    const result = await runCron(runner, ['-l']);
     if (result.code === 0) {
         return result.stdout;
     }
@@ -33,12 +52,14 @@ function withoutOwnedCron(content) {
     return content.split(/\r?\n/).filter((line) => !line.trimEnd().endsWith(CRON_MARKER)).join('\n');
 }
 async function writeCron(runner, content) {
-    const environment = { ...process.env, LC_ALL: 'C', LANG: 'C' };
-    const result = await runner.run('crontab', ['-'], content, environment);
+    const result = await runCron(runner, ['-'], content);
     if (result.code !== 0) {
         throw new Error('Cannot update user crontab: ' + result.stderr.trim());
     }
 }
+export async function validateLinuxSchedulerPrerequisite(runner) {
+    await readCron(runner);
+}
 async function queryWindowsTask(runner, name) {
     return runner.run('schtasks.exe', ['/Query', '/TN', name, '/XML']);
 }

package/dist/sync.js

@@ -6,7 +6,7 @@ import { getHealth, postManifest, putContent, SystemicUploadError, TaskUploadErr
 import { readInstalledState } from './installation.js';
 import { acquireSyncLock, SyncAlreadyRunningError } from './lock.js';
 import { readPendingMarkers, removePendingMarker } from './pending.js';
-import { resolveLinkPaths } from './paths.js';
+import { resolveLinkPaths, vscodeAgentWorkspaceStorageDir } 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';
@@ -101,6 +101,10 @@ export async function runSyncOnce(options = {}) {
                 nowMs,
                 claudeProjectsDir: paths.claudeProjectsDir,
                 copilotSessionsDir: paths.copilotSessionsDir,
+                copilotVscodeWorkspaceStorageDirs: [...new Set([
+                        ...paths.copilotVscodeWorkspaceStorageDirs,
+                        ...(config.vscodeAgentFolder ? [vscodeAgentWorkspaceStorageDir(config.vscodeAgentFolder)] : []),
+                    ])],
                 codexHome: paths.codexHome,
                 reportIssue: (issue) => summary.collectorIssues.push(issue),
             };

package/dist/transport.d.ts

@@ -20,8 +20,14 @@ export interface AcquireTransportOptions {
     probeCompanion?: (companion: CompanionInfo, environment: NodeJS.ProcessEnv) => Promise<void>;
     spawnChild?: (executable: string, args: string[], env: NodeJS.ProcessEnv) => ChildProcessWithoutNullStreams;
     onNeedsLogin?: (url: string) => void;
+    failIfLoginRequired?: boolean;
+    replaceExistingTransport?: boolean;
     bootstrapAuthKey?: string;
     startTimeoutMs?: number;
+    handoffTimeoutMs?: number;
+    terminateProcess?: (pid: number) => void;
+    isProcessAlive?: (pid: number) => boolean;
+    restartPriorTransport?: (executable: string, args: string[], env: NodeJS.ProcessEnv) => void;
 }
 export declare function consumeBootstrapAuthKey(explicitAuthKey: string | undefined, environment?: NodeJS.ProcessEnv): string | undefined;
 export declare function acquireRemoteTransport(options: AcquireTransportOptions): Promise<RemoteTransport>;

package/dist/transport.js

@@ -2,6 +2,7 @@ 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 * as path from 'node:path';
 import { Readable } from 'node:stream';
 import { assertCompanionProtocol, VESPER_NET_PROTOCOL_VERSION, resolveCompanion } from './companion.js';
 const START_TIMEOUT_MS = 10 * 60_000;
@@ -9,7 +10,9 @@ 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 EXPECTED_OWNER_PID_HEADER = 'x-vesper-expected-owner-pid';
 const KEEPALIVE_MS = 10_000;
+const HANDOFF_TIMEOUT_MS = 10_000;
 const PROXY_ENVIRONMENT_KEYS = new Set([
     'http_proxy', 'https_proxy', 'all_proxy', 'no_proxy',
 ]);
@@ -17,6 +20,8 @@ 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}$/;
+const TRANSPORT_SECRET_ENVIRONMENT_KEY = 'VESPER_TRANSPORT_SECRET';
+const TRANSPORT_SECRET_PATTERN = /^[0-9a-fA-F]{64}$/;
 function directLoopbackFetch(input, init = {}) {
     const inputRequest = input instanceof Request ? input : undefined;
     const url = new URL(inputRequest?.url ?? input.toString());
@@ -140,7 +145,16 @@ async function readRendezvous(filePath) {
         throw error;
     }
 }
-async function attach(paths, hostUrl, fetchImpl, requiredExecutablePath) {
+function validateLease(candidate, hostUrl) {
+    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');
+    }
+}
+async function inspectTransport(paths, hostUrl, fetchImpl, renewLease) {
     let rendezvous;
     try {
         rendezvous = await readRendezvous(paths.transportRendezvousPath);
@@ -154,54 +168,49 @@ async function attach(paths, hostUrl, fetchImpl, requiredExecutablePath) {
     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) {
+    let response;
+    try {
+        response = await fetchImpl(`${rendezvous.endpoint}/__vesper_transport/${renewLease ? 'lease' : 'identity'}`, {
+            headers: { [LOCAL_SECRET_HEADER]: rendezvous.secret },
+            signal: AbortSignal.timeout(ATTACH_TIMEOUT_MS),
+        });
+    }
+    catch {
         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');
-        }
+    if (!response.ok) {
+        return null;
+    }
+    const lease = await response.json();
+    validateLease(lease, hostUrl);
+    return { rendezvous, lease };
+}
+function sameExecutable(left, right) {
+    return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+async function canonicalExecutable(executable) {
+    return fs.realpath(executable).catch(() => path.resolve(executable));
+}
+async function attach(paths, hostUrl, fetchImpl, requiredExecutablePath) {
+    let inspected = await inspectTransport(paths, hostUrl, fetchImpl, requiredExecutablePath === undefined);
+    if (!inspected) {
+        return null;
     }
-    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) {
+        const actualExecutablePath = await canonicalExecutable(inspected.lease.executablePath);
+        if (!sameExecutable(actualExecutablePath, requiredExecutablePath)) {
+            return null;
+        }
+        inspected = await inspectTransport(paths, hostUrl, fetchImpl, true);
+        if (!inspected) {
             return null;
         }
-        lease = await readLease(false);
-        if (!lease) {
+        const renewedExecutablePath = await canonicalExecutable(inspected.lease.executablePath);
+        if (!sameExecutable(renewedExecutablePath, requiredExecutablePath)) {
             return null;
         }
-        validateLease(lease);
     }
+    const { rendezvous, lease } = inspected;
     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) {
@@ -238,6 +247,122 @@ async function attach(paths, hostUrl, fetchImpl, requiredExecutablePath) {
         },
     };
 }
+function isManagedRuntimeExecutable(paths, executable) {
+    const relative = path.relative(path.resolve(paths.runtimeDir), path.resolve(executable));
+    const executableName = path.basename(executable).toLowerCase();
+    return relative !== '' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)
+        && (executableName === 'vesper-net' || executableName === 'vesper-net.exe')
+        && relative.split(path.sep).includes('node_modules');
+}
+async function prepareTransportHandoff(options, fetchImpl, requiredExecutablePath) {
+    const inspected = await inspectTransport(options.paths, options.hostUrl, fetchImpl, false);
+    if (!inspected) {
+        return undefined;
+    }
+    const oldExecutablePath = await canonicalExecutable(inspected.lease.executablePath);
+    if (sameExecutable(oldExecutablePath, requiredExecutablePath)) {
+        return undefined;
+    }
+    if (!isManagedRuntimeExecutable(options.paths, oldExecutablePath)) {
+        throw new Error(`Refusing to replace vesper-net transport outside the managed runtime: ${oldExecutablePath}`);
+    }
+    return { inspected, oldExecutablePath };
+}
+async function stopTransportForHandoff(options, fetchImpl, handoff) {
+    const { inspected, oldExecutablePath } = handoff;
+    const oldPid = inspected.rendezvous.pid;
+    const processIsAlive = options.isProcessAlive ?? isAlive;
+    if (inspected.lease.supportsShutdown === true) {
+        let response;
+        try {
+            response = await fetchImpl(`${inspected.rendezvous.endpoint}/__vesper_transport/shutdown`, {
+                method: 'POST', headers: {
+                    [LOCAL_SECRET_HEADER]: inspected.rendezvous.secret,
+                    [EXPECTED_OWNER_PID_HEADER]: String(oldPid),
+                },
+                signal: AbortSignal.timeout(ATTACH_TIMEOUT_MS),
+            });
+        }
+        catch {
+            throw new Error(`Failed to gracefully stop prior vesper-net transport (pid=${oldPid})`);
+        }
+        if (response.status === 409) {
+            // The inspected owner has already yielded the inherited listener.
+            return;
+        }
+        if (!response.ok) {
+            throw new Error(`Failed to gracefully stop prior vesper-net transport (pid=${oldPid})`);
+        }
+        if (await waitForProcessExit(oldPid, options.handoffTimeoutMs ?? HANDOFF_TIMEOUT_MS, processIsAlive)) {
+            return;
+        }
+        throw new Error(`Timed out stopping prior vesper-net transport (pid=${oldPid})`);
+    }
+    const revalidated = await inspectTransport(options.paths, options.hostUrl, fetchImpl, false);
+    if (!revalidated) {
+        throw new Error(`Timed out stopping prior vesper-net transport (pid=${oldPid})`);
+    }
+    const revalidatedExecutablePath = await canonicalExecutable(revalidated.lease.executablePath);
+    if (revalidated.rendezvous.pid !== oldPid
+        || revalidated.rendezvous.endpoint !== inspected.rendezvous.endpoint
+        || revalidated.rendezvous.secret !== inspected.rendezvous.secret
+        || !sameExecutable(revalidatedExecutablePath, oldExecutablePath)
+        || !isManagedRuntimeExecutable(options.paths, revalidatedExecutablePath)) {
+        throw new Error('vesper-net transport changed ownership during upgrade handoff');
+    }
+    (options.terminateProcess ?? ((pid) => process.kill(pid, 'SIGTERM')))(oldPid);
+    if (!await waitForProcessExit(oldPid, options.handoffTimeoutMs ?? HANDOFF_TIMEOUT_MS, processIsAlive)) {
+        throw new Error(`Timed out stopping prior vesper-net transport (pid=${oldPid})`);
+    }
+}
+async function evictUnexpectedTransportOwner(options, fetchImpl, requiredExecutablePath) {
+    const inspected = await inspectTransport(options.paths, options.hostUrl, fetchImpl, false);
+    if (!inspected) {
+        return;
+    }
+    const executablePath = await canonicalExecutable(inspected.lease.executablePath);
+    if (sameExecutable(executablePath, requiredExecutablePath)) {
+        return;
+    }
+    if (!isManagedRuntimeExecutable(options.paths, executablePath)) {
+        throw new Error(`Refusing to replace vesper-net transport outside the managed runtime: ${executablePath}`);
+    }
+    await stopTransportForHandoff(options, fetchImpl, { inspected, oldExecutablePath: executablePath });
+}
+async function waitForProcessExit(pid, timeoutMs, processIsAlive) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!processIsAlive(pid)) {
+            return true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+    return !processIsAlive(pid);
+}
+function defaultRestartPriorTransport(executable, args, env) {
+    const child = spawn(executable, args, { env, detached: true, windowsHide: true, stdio: 'ignore' });
+    child.unref();
+}
+async function restartPriorTransport(options, handoff, args, error) {
+    if (handoff) {
+        try {
+            const oldPid = handoff.inspected.rendezvous.pid;
+            const processIsAlive = options.isProcessAlive ?? isAlive;
+            if (processIsAlive(oldPid) && !await waitForProcessExit(oldPid, options.handoffTimeoutMs ?? HANDOFF_TIMEOUT_MS, processIsAlive)) {
+                throw new Error(`Prior vesper-net transport is still exiting (pid=${oldPid})`);
+            }
+            (options.restartPriorTransport ?? defaultRestartPriorTransport)(handoff.oldExecutablePath, args, companionEnvironment(process.env));
+        }
+        catch (recoveryError) {
+            throw new AggregateError([error, recoveryError], 'vesper-net candidate failed and prior transport restart failed');
+        }
+    }
+    throw error;
+}
+async function failAfterHandoff(options, handoff, baseArgs, child, error) {
+    child.kill('SIGTERM');
+    return restartPriorTransport(options, handoff, baseArgs, error);
+}
 function defaultSpawn(executable, args, env) {
     return spawn(executable, args, {
         env, detached: true, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
@@ -246,7 +371,8 @@ function defaultSpawn(executable, args, env) {
 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);
+        return !PROXY_ENVIRONMENT_KEYS.has(normalized) && !AUTH_KEY_ENVIRONMENT_KEYS.has(normalized)
+            && normalized !== TRANSPORT_SECRET_ENVIRONMENT_KEY.toLowerCase();
     }));
     if (bootstrapAuthKey !== undefined) {
         filtered.VESPER_TS_AUTHKEY = bootstrapAuthKey;
@@ -292,7 +418,7 @@ export async function acquireRemoteTransport(options) {
         await (options.probeCompanion ?? assertCompanionProtocol)(companion, protocolProbeEnvironment(process.env));
     }
     const requiredExecutablePath = companion
-        ? await fs.realpath(companion.executable).catch(() => companion.executable)
+        ? await canonicalExecutable(companion.executable)
         : undefined;
     const existing = await attach(options.paths, options.hostUrl, fetchImpl, requiredExecutablePath);
     if (existing) {
@@ -304,16 +430,30 @@ export async function acquireRemoteTransport(options) {
     if (!options.requiredCompanion) {
         await (options.probeCompanion ?? assertCompanionProtocol)(companion, protocolProbeEnvironment(process.env));
     }
-    const deadline = Date.now() + (options.startTimeoutMs ?? START_TIMEOUT_MS);
-    const args = [
+    const handoff = options.replaceExistingTransport && requiredExecutablePath
+        ? await prepareTransportHandoff(options, fetchImpl, requiredExecutablePath)
+        : undefined;
+    if (handoff && !TRANSPORT_SECRET_PATTERN.test(handoff.inspected.rendezvous.secret)) {
+        throw new Error('Running vesper-net transport has a malformed handoff secret');
+    }
+    const baseArgs = [
         '--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));
+    const candidateArgs = handoff
+        ? [...baseArgs, '--transport-listen', new URL(handoff.inspected.rendezvous.endpoint).host]
+        : baseArgs;
+    const candidateEnvironment = companionEnvironment(process.env, bootstrapAuthKey);
+    if (handoff) {
+        candidateEnvironment[TRANSPORT_SECRET_ENVIRONMENT_KEY] = handoff.inspected.rendezvous.secret;
+    }
+    const child = (options.spawnChild ?? defaultSpawn)(companion.executable, candidateArgs, candidateEnvironment);
     child.stdin.end();
     let controlBuffer = '';
     let fatalMessage;
+    let waitingForOwner = false;
+    let ownerAcquired = false;
     child.once('error', (error) => { fatalMessage = `spawn failed: ${error.message}`; });
     child.once('exit', (code, signal) => {
         fatalMessage ??= `exited before ready (code=${code ?? 'none'}, signal=${signal ?? 'none'})`;
@@ -339,11 +479,21 @@ export async function acquireRemoteTransport(options) {
                     fatalMessage = 'vesper-net protocol mismatch';
                     child.kill('SIGTERM');
                 }
+                else if (event.type === 'waiting_for_owner') {
+                    waitingForOwner = true;
+                }
+                else if (event.type === 'owner_acquired') {
+                    ownerAcquired = true;
+                }
                 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 if (options.failIfLoginRequired) {
+                        fatalMessage = 'the existing Tailscale identity is unavailable; upgrade stopped without relinking';
+                        child.kill('SIGTERM');
+                    }
                     else {
                         options.onNeedsLogin?.(event.loginUrl);
                     }
@@ -369,14 +519,43 @@ export async function acquireRemoteTransport(options) {
     });
     // Never persist helper stderr. Drain it to prevent a blocked pipe.
     child.stderr.resume();
+    const deadline = Date.now() + (options.startTimeoutMs ?? START_TIMEOUT_MS);
+    let handoffNeedsRecovery = false;
+    if (handoff) {
+        // Wait until the candidate confirms it has contended on the owner lock.
+        // This closes the stop/start gap where an old runtime could otherwise win.
+        while (!waitingForOwner && !ownerAcquired && !fatalMessage && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+        }
+        if (fatalMessage) {
+            child.kill('SIGTERM');
+            return restartPriorTransport(options, undefined, baseArgs, new Error(`vesper-net transport failed: ${fatalMessage}`));
+        }
+        if (!waitingForOwner && !ownerAcquired) {
+            child.kill('SIGTERM');
+            return restartPriorTransport(options, undefined, baseArgs, new Error('Timed out waiting for vesper-net candidate to queue for transport ownership'));
+        }
+        if (waitingForOwner) {
+            try {
+                await stopTransportForHandoff(options, fetchImpl, handoff);
+            }
+            catch (error) {
+                child.kill('SIGTERM');
+                throw error;
+            }
+        }
+        handoffNeedsRecovery = true;
+    }
     while (Date.now() < deadline) {
         let attached;
         try {
+            if (handoff && requiredExecutablePath) {
+                await evictUnexpectedTransportOwner(options, fetchImpl, requiredExecutablePath);
+            }
             attached = await attach(options.paths, options.hostUrl, fetchImpl, requiredExecutablePath);
         }
         catch (error) {
-            child.kill('SIGTERM');
-            throw error;
+            return failAfterHandoff(options, handoffNeedsRecovery ? handoff : undefined, baseArgs, child, error);
         }
         if (attached) {
             if (attached.ownerPid === child.pid) {
@@ -390,11 +569,11 @@ export async function acquireRemoteTransport(options) {
             return attached.transport;
         }
         if (fatalMessage) {
-            child.kill('SIGTERM');
-            throw new Error(`vesper-net transport failed: ${fatalMessage}`);
+            const error = new Error(`vesper-net transport failed: ${fatalMessage}`);
+            return failAfterHandoff(options, handoffNeedsRecovery ? handoff : undefined, baseArgs, child, error);
         }
         await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
     }
-    child.kill('SIGTERM');
-    throw new Error('Timed out waiting for vesper-net transport');
+    const error = new Error('Timed out waiting for vesper-net transport');
+    return failAfterHandoff(options, handoffNeedsRecovery ? handoff : undefined, baseArgs, child, error);
 }

package/dist/version.d.ts

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

package/dist/version.js

@@ -1 +1 @@
-export const VESPER_LINK_VERSION = '0.1.4';
+export const VESPER_LINK_VERSION = '0.1.6';

package/package.json

@@ -1,39 +1,39 @@
-{
-  "name": "@msvesper/vesper-link",
-  "version": "0.1.4",
-  "description": "Connect agent sessions and tools to Vesper Memory",
-  "type": "module",
-  "bin": {
-    "vesper-link": "dist/cli.js"
-  },
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "README.md",
-    "LICENSE.md"
-  ],
-  "scripts": {
-    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "npm run clean && tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && vitest run",
-    "pack-check": "npm run build && npm pack --dry-run",
-    "prepack": "npm run build"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "license": "SEE LICENSE IN LICENSE.md",
-  "publishConfig": {
-    "access": "public"
-  },
-  "optionalDependencies": {
-    "@msvesper/vesper-net-linux-x64": "0.1.4",
-    "@msvesper/vesper-net-win32-x64": "0.1.4"
-  },
-  "devDependencies": {
-    "@types/node": "^22.15.0",
-    "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
-  }
-}
+{
+  "name": "@msvesper/vesper-link",
+  "version": "0.1.6",
+  "description": "Connect agent sessions and tools to Vesper Memory",
+  "type": "module",
+  "bin": {
+    "vesper-link": "dist/cli.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && vitest run",
+    "pack-check": "npm run build && npm pack --dry-run",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "publishConfig": {
+    "access": "public"
+  },
+  "optionalDependencies": {
+    "@msvesper/vesper-net-linux-x64": "0.1.6",
+    "@msvesper/vesper-net-win32-x64": "0.1.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  }
+}