blun-king-cli 9.1.615 → 9.1.617

package/bin/launcher-runtime.js

@@ -39,6 +39,7 @@ const {
   writePrivateFile,
 } = require('./private-paths');
 const { parseProfileLaunchArgs, resolveSelectedProfile } = require('./profile-launch.cjs');
+const { createProfileHandoff, PROFILE_HANDOFF_READY, PROFILE_HANDOFF_EXIT } = require('./profile-handoff.cjs');
 
 const PKG = path.resolve(__dirname, '..');
 const PROFILE = parseProfileLaunchArgs(process.argv.slice(2), launcherModeFromArgv(process.argv));
@@ -153,7 +154,7 @@ function shouldDetachProtectedCore(options = {}) {
   return platform !== 'win32' || stdinIsTTY !== true;
 }
 
-function spawnProtectedCore(args, env, cwd) {
+function spawnProtectedCore(args, env, cwd, onProfileMessage) {
   const child = spawn(
     process.execPath,
     [path.join(PKG, 'bin', 'core-bootstrap.js'), ...args],
@@ -167,7 +168,8 @@ function spawnProtectedCore(args, env, cwd) {
   );
   let loadedSettled = false;
   let completedSettled = false;
-  let operatorSignal;
+  let operatorSignal;
+  let profileReady = false;
   let resolveLoaded;
   let resolveCompleted;
   const loadTimer = setTimeout(() => {
@@ -201,16 +203,29 @@ function spawnProtectedCore(args, env, cwd) {
     signalHandlers.set(signal, handler);
     process.once(signal, handler);
   }
-  child.on('message', (message) => {
-    if (message?.type !== CORE_LOADED_MESSAGE) return;
-    settleLoaded(true);
-    try {
-      child.disconnect();
-    } catch {}
+  child.on('message', (message) => {
+    if (message?.type !== CORE_LOADED_MESSAGE) {
+      if (completedSettled || !onProfileMessage) return;
+      if (message?.type === PROFILE_HANDOFF_READY && Object.keys(message).length === 1) {
+        profileReady = true;
+        return;
+      }
+      if (!loadedSettled) return;
+      const reply = onProfileMessage(message);
+      if (reply) {
+        try { child.send(reply, () => {}); } catch {}
+      }
+      return;
+    }
+    settleLoaded(true);
+    if (onProfileMessage) child.channel?.unref();
+    else {
+      try { child.disconnect(); } catch {}
+    }
   });
   child.once('error', (error) => settleCompleted({ error }));
   child.once('exit', (code, signal) => settleCompleted({ code, signal }));
-  return { child, completed, loaded };
+  return { child, completed, loaded, isProfileReady: () => profileReady };
 }
 
 async function runInformationalCore(args, env, cwd, releaseNotice) {
@@ -222,10 +237,14 @@ async function runInformationalCore(args, env, cwd, releaseNotice) {
   return Number.isInteger(result.code) ? result.code : exitCodeForChild(result, false);
 }
 
-async function superviseProtectedCore(args, env, cwd, releaseNotice) {
-  let noticeReleased = false;
-  for (;;) {
-    const core = spawnProtectedCore(args, env, cwd);
+async function superviseProtectedCore(args, env, cwd, releaseNotice, options = {}) {
+  let noticeReleased = false;
+  let rollback;
+  let recoveryAttempted = false;
+  for (;;) {
+    const handoff = options.prepareProfile
+      ? createProfileHandoff(env, target => runningTuiPid(target) !== null) : undefined;
+    const core = spawnProtectedCore(args, env, cwd, handoff && ((message) => handoff.prepare(message)));
     const loaded = await core.loaded;
     if (!noticeReleased) {
       noticeReleased = true;
@@ -236,12 +255,47 @@ async function superviseProtectedCore(args, env, cwd, releaseNotice) {
     const intentionalStop = consumeIntentionalStopMarker({
       homeDir: env.BLUN_HOME, childPid: core.child.pid, nowMs: Date.now(),
     });
-    recordRuntimeExit({
+    recordRuntimeExit({
       homeDir: env.BLUN_HOME, source: 'launcher', kind: result.error ? 'child-error' : 'child-exit',
       exitCode, signal: result.signal, phase: loaded ? 'runtime' : 'startup',
       cliVersion: env.BLUN_PUBLIC_PACKAGE_VERSION, profile: env.BLUN_PROFILE,
-      loaded, childPid: core.child.pid, error: result.error,
-    });
+      loaded, childPid: core.child.pid, error: result.error,
+    });
+    // A profile transition is committed only after the old process exits cleanly.
+    // Failed target startup restores the previous owner, never the previous PID.
+    if (rollback && (!loaded || !core.isProfileReady()) && !result.signal) {
+      ({ args, env } = rollback);
+      rollback = undefined;
+      continue;
+    }
+    if (loaded && core.isProfileReady()) {
+      rollback = undefined;
+      recoveryAttempted = false;
+    }
+    if (handoff && loaded && !intentionalStop && !result.error && !result.signal
+      && result.code === PROFILE_HANDOFF_EXIT) {
+      if (!handoff.hasPending()) return 1;
+      const sourceSessionId = handoff.getSourceSessionId();
+      const recoveryArgs = sourceSessionId === undefined ? ['-c'] : ['-r', sourceSessionId];
+      try {
+        const selected = handoff.commit();
+        const nextEnv = await options.prepareProfile(selected);
+        handoff.commit();
+        rollback = { args: recoveryArgs, env };
+        args = ['-c'];
+        env = { ...nextEnv, BLUN_PROFILE_HANDOFF: '1' };
+        continue;
+      } catch (error) {
+        recordRuntimeExit({ homeDir: env.BLUN_HOME, source: 'launcher', kind: 'profile-handoff-failure',
+          phase: 'startup', cliVersion: env.BLUN_PUBLIC_PACKAGE_VERSION, profile: env.BLUN_PROFILE,
+          exitCode: 1, error });
+        if (recoveryAttempted) return 1;
+        recoveryAttempted = true;
+        // Reopen the original owner when the selection became unavailable.
+        args = recoveryArgs;
+        continue;
+      }
+    }
     if (intentionalStop || !isAbnormalCoreExit(result, loaded)) {
       if (result.error) throw result.error;
       return exitCode;
@@ -272,7 +326,7 @@ function exitCodeForChild(result, loaded) {
   return 1;
 }
 
-function installTelegramForProfile(packageRoot, blunDir) {
+function installTelegramForProfile(packageRoot, blunDir) {
   installManagedTelegramPlugin({ packageRoot, blunDir });
   const channelsDir = path.join(blunDir, 'channels');
   const channelDir = path.join(channelsDir, 'telegram');
@@ -284,7 +338,37 @@ function installTelegramForProfile(packageRoot, blunDir) {
   } else {
     securePrivateFile(envFile);
   }
-}
+}
+
+function prepareProfileRuntime(blunDir, callerCwd, mode) {
+  ensurePrivateDirectory(blunDir);
+  const cfgFile = path.join(blunDir, 'config.toml');
+  if (fs.existsSync(cfgFile)) securePrivateFile(cfgFile);
+  const standardMcpNames = availableStandardToolNames({ packageRoot: PKG })
+    .filter((name) => name !== 'telegram');
+  seedStandardTools({ packageRoot: PKG, blunDir, names: standardMcpNames });
+  seedStandardDesignSkill({ packageRoot: PKG, blunDir });
+  installManagedAgentSpinePlugin({ packageRoot: PKG, blunDir });
+  if (mode === LAUNCHER_MODES.KING) installTelegramForProfile(PKG, blunDir);
+  return repairConfiguredNativeModules({
+    blunDir, callerCwd,
+    onRepairStart() {
+      process.stdout.write('BLUN richtet native Node.js-Module fuer die neue Laufzeit ein.\n');
+    },
+  });
+}
+
+async function withProfileRuntimeReservation(homeDir, work) {
+  const result = await tryAcquireUpdateLease({ packageRoot: homeDir, role: 'profile' });
+  if (!result.acquired) throw Object.assign(new Error(`PROFILE_RUNTIME_${result.reason.toUpperCase()}`),
+    { code: result.reason === 'busy' ? 'PROFILE_RUNTIME_BUSY' : 'PROFILE_RUNTIME_UNAVAILABLE' });
+  try {
+    result.lease.assertOwned();
+    const value = await work();
+    result.lease.assertOwned();
+    return value;
+  } finally { await result.lease.release(); }
+}
 
 function spawnManagedLauncher(binary, cwd) {
   return new Promise((resolve, reject) => {
@@ -511,51 +595,42 @@ async function runLauncher(options = {}) {
   // --- 2. Bestehende Konfiguration absichern -------------------------------
   // Ein frischer Start bleibt absichtlich ohne statischen Anbieter. /login
   // provisioniert King ueber den BLUN-OAuth-Server.
-    const cfgFile = path.join(blunDir, 'config.toml');
-    if (fs.existsSync(cfgFile)) securePrivateFile(cfgFile);
-    require('./verify-bundled-agent-sources.cjs').verifyBundledAgentSources(PKG);
+    require('./verify-bundled-agent-sources.cjs').verifyBundledAgentSources(PKG);
+    const nativeModules = mode === LAUNCHER_MODES.KING && isInteractiveKingStart(ARGS)
+      ? await withProfileRuntimeReservation(blunDir, () => prepareProfileRuntime(blunDir, callerCwd, mode))
+      : prepareProfileRuntime(blunDir, callerCwd, mode);
 
-    // --- 3. BLUN-Standard-MCPs additiv im Benutzerprofil einrichten ---------
-    const standardMcpNames = availableStandardToolNames({ packageRoot: PKG })
-      .filter((name) => name !== 'telegram');
-    seedStandardTools({
-      packageRoot: PKG,
-      blunDir,
-      names: standardMcpNames,
-    });
-
-  // --- 4. Eigenes BLUN-Grunddesign als einzigen Standard-Skill installieren
-    seedStandardDesignSkill({ packageRoot: PKG, blunDir });
-    installManagedAgentSpinePlugin({ packageRoot: PKG, blunDir });
-
-    // --- 5. Telegram-Plugin + Token-Vorlage (nur King) -----------------------
-    if (mode === LAUNCHER_MODES.KING) {
-      installTelegramForProfile(PKG, blunDir);
-    }
-
-    const nativeModules = repairConfiguredNativeModules({
-      blunDir,
-      callerCwd,
-      onRepairStart() {
-        process.stdout.write('BLUN richtet native Node.js-Module fuer die neue Laufzeit ein.\n');
-      },
-    });
     if (nativeModules.repaired.length > 0) {
       process.stdout.write('Native Node.js-Module sind wieder einsatzbereit.\n');
     }
 
-    // --- 6. Start -----------------------------------------------------------
+    // --- 6. Start -----------------------------------------------------------
     const env = createLauncherEnvironment(process.env, mode, readPackageVersion(), blunDir);
     env.BLUN_HOME = blunDir;
     if (PROFILE.name !== undefined) {
       env.BLUN_SHARED_HOME = getPrivatePaths().sharedHome;
       env.BLUN_PROFILE = PROFILE.name;
     }
+    const handoffOptions = mode === LAUNCHER_MODES.KING && isInteractiveKingStart(ARGS)
+      ? { prepareProfile: async (selected) => {
+        const target = selected.homeDir;
+        await withProfileRuntimeReservation(target, () => prepareProfileRuntime(target, callerCwd, mode));
+        const next = createLauncherEnvironment(process.env, mode, readPackageVersion(), target);
+        next.BLUN_HOME = target;
+        next.BLUN_SHARED_HOME = selected.sharedHome;
+        next.BLUN_PROFILE = selected.name;
+        delete next.BLUN_TELEGRAM_STATE_DIR;
+        delete next.BLUN_PLUGIN_ROOT;
+        return next;
+      } } : {};
+    if (handoffOptions.prepareProfile) env.BLUN_PROFILE_HANDOFF = '1';
+    else delete env.BLUN_PROFILE_HANDOFF;
     process.exitCode = await superviseProtectedCore(
       ARGS,
       env,
       callerCwd,
-      releaseNotice,
+      releaseNotice,
+      handoffOptions,
     );
   } finally {
     await releaseNotice();
@@ -563,6 +638,7 @@ async function runLauncher(options = {}) {
 }
 
 module.exports = {
+  withProfileRuntimeReservation,
   resolveLauncherPrivatePaths,
   isInteractiveKingStart,
   runningTuiPid,

package/bin/managed-plugin-selection.cjs

@@ -5,8 +5,10 @@ const path = require('node:path');
 const { ensurePrivateDirectory, securePrivateTree } = require('./private-paths');
 const SCHEMA = 'blun.managed-plugin-selection/v1';
 
-function snapshotPluginTree(root) {
-  const entries = [];
+function snapshotPluginTree(root, expectedEntries = null) {
+  const entries = [];
+  const expectedByPath = expectedEntries === null ? null
+    : new Map(expectedEntries.map(entry => [entry.path, entry]));
   const rootStat = fs.lstatSync(root);
   if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) return null;
   const visit = (directory, relativeDirectory = '') => {
@@ -14,19 +16,24 @@ function snapshotPluginTree(root) {
       .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0)) {
       const relativePath = path.join(relativeDirectory, entry.name);
       const absolutePath = path.join(directory, entry.name);
-      const stat = fs.lstatSync(absolutePath);
-      if (stat.isSymbolicLink()) return false;
-      if (stat.isDirectory()) {
+      const stat = fs.lstatSync(absolutePath);
+      if (stat.isSymbolicLink()) return false;
+      const expected = expectedByPath?.get(relativePath);
+      if (expectedByPath && !expected) return false;
+      if (stat.isDirectory()) {
+        if (expected && expected.kind !== 'directory') return false;
         entries.push({ kind: 'directory', path: relativePath });
         if (!visit(absolutePath, relativePath)) return false;
-      } else if (stat.isFile()) {
+      } else if (stat.isFile()) {
+        if (expected && (expected.kind !== 'file' || stat.size !== expected.content.length)) return false;
         entries.push({ kind: 'file', path: relativePath, content: fs.readFileSync(absolutePath) });
       } else return false;
     }
     return true;
   };
-  return visit(root) ? entries : null;
-}
+  if (!visit(root) || (expectedByPath && entries.length !== expectedByPath.size)) return null;
+  return entries;
+}
 
 function digestPluginEntries(entries) {
   if (entries === null) throw new Error('Invalid managed plugin tree');

package/bin/plugin-bootstrap.js

@@ -3,7 +3,13 @@
 const { randomUUID } = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
-const { selectedAgentSpineRoot, describeAgentSpineSelection, copySelectedAgentSpinePlugin } = require('./managed-plugin-selection.cjs');
+const {
+  selectedAgentSpineRoot,
+  describeAgentSpineSelection,
+  copySelectedAgentSpinePlugin,
+  snapshotPluginTree,
+  digestPluginEntries,
+} = require('./managed-plugin-selection.cjs');
 
 const {
   ensurePrivateDirectory,
@@ -88,20 +94,37 @@ function installManagedTelegramPlugin({ packageRoot, blunDir, now = new Date().t
 
   ensurePrivateDirectory(pluginsDir);
   if (fs.existsSync(installedFile)) securePrivateFile(installedFile);
-  const installed = readInstalledPlugins(installedFile);
-  const updatedInstalled = updatedInstalledPlugins(installed, pluginRoot, now);
-  ensurePrivateDirectory(managedDir);
-  const nonce = `${process.pid}-${randomUUID()}`;
-  const stagingRoot = path.join(managedDir, `.telegram-${nonce}.tmp`);
-  const backupRoot = path.join(managedDir, `.telegram-${nonce}.bak`);
-  let hadPreviousPlugin = false;
-  let installedNewPlugin = false;
-  try {
-    if (fs.existsSync(pluginRoot)) {
-      ensurePrivateDirectory(pluginRoot);
-      hadPreviousPlugin = true;
-    }
-    fs.cpSync(sourceRoot, stagingRoot, { recursive: true, force: true });
+  const installed = readInstalledPlugins(installedFile);
+  const updatedInstalled = updatedInstalledPlugins(installed, pluginRoot, now);
+  ensurePrivateDirectory(managedDir);
+  const expectedEntries = snapshotPluginTree(sourceRoot);
+  const expectedDigest = digestPluginEntries(expectedEntries);
+  let hadPreviousPlugin = false;
+  if (fs.existsSync(pluginRoot)) {
+    ensurePrivateDirectory(pluginRoot);
+    hadPreviousPlugin = true;
+    const existingEntries = snapshotPluginTree(pluginRoot, expectedEntries);
+    if (existingEntries !== null && digestPluginEntries(existingEntries) === expectedDigest) {
+      const previous = installed.plugins.find((plugin) => plugin.id === 'telegram');
+      const previousUpdate = typeof previous?.updatedAt === 'string' && previous.updatedAt.length > 0
+        ? previous.updatedAt : now;
+      const reusedInstalled = updatedInstalledPlugins(installed, pluginRoot, previousUpdate);
+      if (JSON.stringify(reusedInstalled) !== JSON.stringify(installed)) {
+        writeInstalledPlugins(installedFile, reusedInstalled);
+      }
+      return { installedFile, pluginRoot, reused: true };
+    }
+  }
+  const nonce = `${process.pid}-${randomUUID()}`;
+  const stagingRoot = path.join(managedDir, `.telegram-${nonce}.tmp`);
+  const backupRoot = path.join(managedDir, `.telegram-${nonce}.bak`);
+  let installedNewPlugin = false;
+  try {
+    fs.cpSync(sourceRoot, stagingRoot, { recursive: true, force: true });
+    const stagedEntries = snapshotPluginTree(stagingRoot, expectedEntries);
+    if (stagedEntries === null || digestPluginEntries(stagedEntries) !== expectedDigest) {
+      throw new Error('Telegram source changed during installation');
+    }
     if (hadPreviousPlugin) fs.renameSync(pluginRoot, backupRoot);
     try {
       fs.renameSync(stagingRoot, pluginRoot);
@@ -119,8 +142,8 @@ function installManagedTelegramPlugin({ packageRoot, blunDir, now = new Date().t
     fs.rmSync(stagingRoot, { recursive: true, force: true });
   }
 
-  return { installedFile, pluginRoot };
-}
+  return { installedFile, pluginRoot, reused: false };
+}
 
 function installManagedAgentSpinePlugin({ packageRoot, blunDir, now = new Date().toISOString() }) {
   const installedFile = path.join(blunDir, 'plugins', 'installed.json');

package/bin/private-paths.js

@@ -667,8 +667,16 @@ public static class BlunPrivateAclNative
             VerifyHandlePath(handle, fullTarget);
             HashSet<string> expectedSids = ExpectedSids(userSid);
             string owner = ValidateOwner(handle, expectedSids);
-            SetExactDacl(handle, userSid, true);
-            VerifyExactDacl(handle, userSid, true, owner);
+            // Avoid rewriting an exact directory DACL on every launcher start.
+            try
+            {
+                VerifyExactDacl(handle, userSid, true, owner);
+            }
+            catch (UnauthorizedAccessException)
+            {
+                SetExactDacl(handle, userSid, true);
+                VerifyExactDacl(handle, userSid, true, owner);
+            }
             VerifyHandlePath(handle, fullTarget);
         }
     }

package/bin/profile-handoff.cjs

@@ -0,0 +1,152 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+const { listExistingProfiles, resolveSelectedProfile } = require('./profile-launch.cjs');
+
+const PROFILE_HANDOFF_REQUEST = 'blun-profile-handoff-request';
+const PROFILE_HANDOFF_REPLY = 'blun-profile-handoff-reply';
+const PROFILE_HANDOFF_CANCEL = 'blun-profile-handoff-cancel';
+const PROFILE_HANDOFF_READY = 'blun-profile-handoff-ready';
+const PROFILE_HANDOFF_EXIT = 76;
+const REQUEST_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/u;
+const samePath = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+const unavailable = () => Object.assign(new Error('PROFILE_HANDOFF_UNAVAILABLE'), { code: 'PROFILE_HANDOFF_UNAVAILABLE' });
+
+function createProfileHandoff(env, isBusy = () => false) {
+  let pending;
+  const validate = (name) => {
+    if (typeof env.BLUN_HOME !== 'string' || !path.isAbsolute(env.BLUN_HOME)
+      || (env.BLUN_SHARED_HOME !== undefined && !path.isAbsolute(env.BLUN_SHARED_HOME))) throw unavailable();
+    const sharedHome = path.resolve(env.BLUN_SHARED_HOME || env.BLUN_HOME);
+    const homeDir = path.resolve(env.BLUN_HOME);
+    const current = env.BLUN_PROFILE;
+    if (current !== undefined) {
+      if (!env.BLUN_SHARED_HOME || path.basename(resolveSelectedProfile(sharedHome, current)) !== current
+        || !samePath(homeDir, resolveSelectedProfile(sharedHome, current))) throw unavailable();
+    } else if (!samePath(homeDir, sharedHome)) throw unavailable();
+    const names = listExistingProfiles(sharedHome);
+    if (typeof name !== 'string' || !names.includes(name) || name === current
+      || (current !== undefined && !names.includes(current))) throw unavailable();
+    const target = resolveSelectedProfile(sharedHome, name);
+    if (isBusy(target)) throw unavailable();
+    const identities = [sharedHome, path.join(sharedHome, 'profile'), homeDir, target]
+      .map(file => ({ file, stat: fs.lstatSync(file, { bigint: true }) }));
+    if (identities.some(({ stat }) => !stat.isDirectory() || stat.isSymbolicLink())) throw unavailable();
+    return { name, sharedHome, homeDir: target, identities };
+  };
+  return {
+    hasPending: () => pending !== undefined,
+    getSourceSessionId: () => pending?.sourceSessionId,
+    prepare(message) {
+      if (message?.type === PROFILE_HANDOFF_CANCEL && typeof message.requestId === 'string'
+        && REQUEST_ID.test(message.requestId) && Object.keys(message).sort().join(',') === 'requestId,type') {
+        if (pending?.requestId === message.requestId) pending = undefined;
+        return { type: PROFILE_HANDOFF_REPLY, requestId: message.requestId, status: 'cancelled' };
+      }
+      if (!message || message.type !== PROFILE_HANDOFF_REQUEST || typeof message.requestId !== 'string' || !REQUEST_ID.test(message.requestId)) return undefined;
+      const shape = Object.keys(message).sort().join(',');
+      if (shape !== 'name,requestId,type' && shape !== 'name,requestId,sourceSessionId,type') return undefined;
+      if (shape === 'name,requestId,sourceSessionId,type'
+        && (typeof message.sourceSessionId !== 'string' || !SESSION_ID.test(message.sourceSessionId))) return undefined;
+      let status = 'rejected';
+      try {
+        if (pending) {
+          if (pending.requestId === message.requestId && pending.name === message.name
+            && pending.sourceSessionId === message.sourceSessionId) status = 'prepared';
+        } else {
+          pending = { ...validate(message.name), requestId: message.requestId, sourceSessionId: message.sourceSessionId };
+          status = 'prepared';
+        }
+      } catch {}
+      return { type: PROFILE_HANDOFF_REPLY, requestId: message.requestId, status };
+    },
+    commit() {
+      try {
+        if (!pending) throw unavailable();
+        const fresh = validate(pending.name);
+        for (let index = 0; index < pending.identities.length; index++) {
+          const before = pending.identities[index];
+          const after = fresh.identities[index];
+          if (before.file !== after.file || before.stat.dev !== after.stat.dev || before.stat.ino !== after.stat.ino) throw unavailable();
+        }
+        return Object.freeze({ name: fresh.name, sharedHome: fresh.sharedHome, homeDir: fresh.homeDir,
+          ...(pending.sourceSessionId === undefined ? {} : { sourceSessionId: pending.sourceSessionId }) });
+      } catch {
+        throw unavailable();
+      }
+    },
+  };
+}
+
+function createProfileHandoffClient(channel = process) {
+  const enabled = channel.env?.BLUN_PROFILE_HANDOFF === '1';
+  let pending;
+  let disposed = false;
+  const available = () => !disposed && enabled && channel.connected === true
+    && typeof channel.send === 'function';
+  const cancel = () => {
+    const request = pending;
+    if (!request) return;
+    pending = undefined;
+    request.finish(false);
+    if (channel.connected === true) {
+      try { channel.send({ type: PROFILE_HANDOFF_CANCEL, requestId: request.id }, () => {}); } catch {}
+    }
+  };
+  return Object.freeze({
+    isPrepared: () => available() && pending?.prepared === true,
+    cancel,
+    dispose() { cancel(); disposed = true; },
+    /** @param {string} name @param {{ signal?: AbortSignal, timeoutMs?: number, sourceSessionId?: string }} [options] */
+    prepare(name, { signal, timeoutMs = 5000, sourceSessionId } = {}) {
+      try {
+        if (!available() || pending || signal?.aborted || typeof name !== 'string'
+          || path.basename(resolveSelectedProfile(path.parse(__dirname).root, name)) !== name
+          || !Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000
+          || (sourceSessionId !== undefined && (typeof sourceSessionId !== 'string' || !SESSION_ID.test(sourceSessionId)))) return Promise.resolve(false);
+      } catch { return Promise.resolve(false); }
+      return new Promise(resolve => {
+        const request = { id: randomUUID(), prepared: false, finish: undefined };
+        let settled = false;
+        let timer;
+        const aborted = () => cancel();
+        const disconnected = () => cancel();
+        const message = reply => {
+          if (pending !== request || reply?.type !== PROFILE_HANDOFF_REPLY || reply.requestId !== request.id
+            || Object.keys(reply).sort().join(',') !== 'requestId,status,type') return;
+          if (reply.status === 'prepared') request.finish(true);
+          else if (reply.status === 'rejected' || reply.status === 'cancelled') cancel();
+        };
+        request.finish = prepared => {
+          if (!prepared) signal?.removeEventListener('abort', aborted);
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          channel.removeListener('message', message);
+          channel.removeListener('disconnect', disconnected);
+          try { channel.channel?.unref(); } catch {}
+          request.prepared = prepared;
+          resolve(prepared);
+        };
+        pending = request;
+        channel.on('message', message);
+        channel.once('disconnect', disconnected);
+        signal?.addEventListener('abort', aborted, { once: true });
+        timer = setTimeout(aborted, timeoutMs);
+        try {
+          channel.channel?.ref();
+          channel.send({ type: PROFILE_HANDOFF_REQUEST, requestId: request.id, name,
+            ...(sourceSessionId === undefined ? {} : { sourceSessionId }) }, error => {
+            if (error && pending === request) cancel();
+          });
+        } catch { cancel(); }
+      });
+    },
+  });
+}
+
+module.exports = { createProfileHandoff, createProfileHandoffClient, PROFILE_HANDOFF_CANCEL, PROFILE_HANDOFF_REQUEST, PROFILE_HANDOFF_REPLY,
+  PROFILE_HANDOFF_READY, PROFILE_HANDOFF_EXIT };

package/bin/profile-launch.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
-const path = require('node:path');
+const path = require('node:path');
+const fs = require('node:fs');
 
 const PROFILE_NAME = /^[a-z0-9][a-z0-9_-]{0,31}$/u;
 const RESERVED = new Set(['doctor', 'export', 'help', 'login', 'mcp', 'server', 'tools', 'update', 'upgrade', 'version']);
@@ -35,8 +36,85 @@ function parseProfileLaunchArgs(args, mode) {
   return { args: remaining, name: undefined };
 }
 
-function resolveSelectedProfile(sharedHome, name, pathImpl = path) {
-  return pathImpl.join(sharedHome, 'profile', profileName(name));
-}
-
-module.exports = { parseProfileLaunchArgs, resolveSelectedProfile };
+function resolveSelectedProfile(sharedHome, name, pathImpl = path) {
+  return pathImpl.join(sharedHome, 'profile', profileName(name));
+}
+
+function catalogUnavailable() {
+  return Object.assign(new Error('PROFILE_CATALOG_UNAVAILABLE'), { code: 'PROFILE_CATALOG_UNAVAILABLE' });
+}
+
+function directoryIdentity(target, fsImpl) {
+  let stat;
+  try { stat = fsImpl.lstatSync(target, { bigint: true }); }
+  catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw catalogUnavailable();
+  return stat;
+}
+
+function homeIdentity(home, fsImpl) {
+  const root = path.parse(home).root;
+  let current = root;
+  let stat = directoryIdentity(current, fsImpl);
+  for (const part of home.slice(root.length).split(path.sep).filter(Boolean)) {
+    if (stat === undefined) return undefined;
+    current = path.join(current, part);
+    stat = directoryIdentity(current, fsImpl);
+  }
+  return stat;
+}
+
+function sameDirectory(before, after) {
+  return before !== undefined && after !== undefined && before.dev === after.dev && before.ino === after.ino;
+}
+
+/** Directory names only; selection must revalidate them before changing owner. */
+function listExistingProfiles(sharedHome, options = {}) {
+  const fsImpl = options.fsImpl || fs;
+  try {
+    if (typeof sharedHome !== 'string' || !path.isAbsolute(sharedHome)) throw catalogUnavailable();
+    const home = path.resolve(sharedHome);
+    if (process.platform === 'win32' && home.startsWith('\\\\')) throw catalogUnavailable();
+    const beforeHome = homeIdentity(home, fsImpl);
+    if (beforeHome === undefined) return [];
+    const profileRoot = path.join(home, 'profile');
+    const beforeProfiles = directoryIdentity(profileRoot, fsImpl);
+    if (beforeProfiles === undefined) {
+      if (!sameDirectory(beforeHome, homeIdentity(home, fsImpl))) throw catalogUnavailable();
+      return [];
+    }
+    const rows = [];
+    const dir = fsImpl.opendirSync(profileRoot);
+    try {
+      let count = 0;
+      for (let entry; (entry = dir.readSync()) !== null;) {
+        if (++count > 4096) throw catalogUnavailable();
+        const name = entry.name;
+        if (!PROFILE_NAME.test(name)) continue;
+        const target = resolveSelectedProfile(home, name);
+        let stat;
+        try { stat = fsImpl.lstatSync(target, { bigint: true }); }
+        catch (error) {
+          if (error.code === 'ENOENT') continue;
+          throw error;
+        }
+        if (stat.isDirectory() && !stat.isSymbolicLink()) rows.push({ name, target, stat });
+      }
+    } finally { dir.closeSync(); }
+    if (!sameDirectory(beforeHome, homeIdentity(home, fsImpl))
+      || !sameDirectory(beforeProfiles, directoryIdentity(profileRoot, fsImpl))) throw catalogUnavailable();
+    for (const row of rows) {
+      if (!sameDirectory(row.stat, directoryIdentity(row.target, fsImpl))) throw catalogUnavailable();
+    }
+    if (!sameDirectory(beforeHome, homeIdentity(home, fsImpl))
+      || !sameDirectory(beforeProfiles, directoryIdentity(profileRoot, fsImpl))) throw catalogUnavailable();
+    return rows.map(row => row.name).sort();
+  } catch {
+    throw catalogUnavailable();
+  }
+}
+
+module.exports = { parseProfileLaunchArgs, resolveSelectedProfile, listExistingProfiles };

package/bin/update-lease.js

@@ -34,7 +34,9 @@ function canonicalPackageIdentity(packageRoot, options = {}) {
 
 function deriveUpdateLeaseEndpoint(packageRoot, options = {}) {
   const platform = options.platform || process.platform;
-  const role = options.role === 'install'
+  const role = options.role === 'profile'
+    ? 'profile'
+    : options.role === 'install'
     ? 'install'
     : options.role === 'runtime'
       ? 'runtime'