@c4roa0/agentpay-user 0.3.7 → 0.3.8

package/src/install-user.mjs

@@ -1,3 +1,4 @@
+import {withInstallationOperation, installationChildOptions} from './installation-operation.mjs';
 import { installationDirectory, importSetupFiles } from "./installation-paths.mjs";
 // SPDX-License-Identifier: MPL-2.0
 // This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
@@ -70,7 +71,10 @@ async function saveJson(path, value) {
     await unlink(temp).catch(() => {});
   }
 }
-export async function runInstall({
+export async function runInstall(options) {
+  return withInstallationOperation(() => installUnderLock(options));
+}
+async function installUnderLock({
   userDir,
   market,
   dataDir,
@@ -81,6 +85,7 @@ export async function runInstall({
   prepareOnly = false,
   beforePrepare,
   afterPrepare,
+  beforeApplySettings,
 }) {
   userDir = resolve(userDir);
 
@@ -100,17 +105,6 @@ export async function runInstall({
   const stateInfo = await lstat(stateDir);
   if (!stateInfo.isDirectory() || stateInfo.isSymbolicLink() || stateInfo.uid !== process.getuid() || stateInfo.mode & 0o077)
     throw Error('Installation state directory must be owner-held and private.');
-  const lockPath = join(stateDir, "install.lock");
-  let lock;
-  try {
-    lock = await open(lockPath, "wx", 0o600);
-  } catch (e) {
-    if (e.code === "EEXIST")
-      throw Error(
-        `Another installation may be running. Check ${lockPath} before removing a stale lock.`,
-      );
-    throw e;
-  }
   const logPath = join(stateDir, `install-${Date.now()}-${randomUUID()}.log`),
     statePath = join(stateDir, "state.json");
   let state = { version: 1 };
@@ -162,7 +156,7 @@ export async function runInstall({
     const inputs = sourceInstall ? await fingerprint(userDir, ['package.json', 'package-lock.json']) : null;
     if (sourceInstall && (state.userDependencies !== inputs || !initial.ok)) {
       write('1/2 Install the pinned User and Wallet dependencies. This may take a few minutes.');
-      await run('npm', ['ci'], {cwd:userDir, logPath});
+      await run('npm', ['ci', '--ignore-scripts'], {cwd:userDir, logPath});
       state.userDependencies = inputs;
     } else write('1/2 Check installed User and Wallet packages.');
     const checked = await checkLocalInstallation({
@@ -175,10 +169,10 @@ export async function runInstall({
       throw Error(`${failed.message}. ${failed.fix || ""}`);
     }
     await mkdir(privateDir, {recursive:true, mode:0o700});
-    await importSetupFiles(privateDir, userDir);
-    state.dataDir = privateDir;
-    await saveJson(statePath, state);
     if (prepareOnly) {
+      await importSetupFiles(privateDir, userDir);
+      state.dataDir = privateDir;
+      await saveJson(statePath, state);
       if (afterPrepare) await afterPrepare(preparationContext);
       return { completed: true, logPath };
     }
@@ -220,7 +214,16 @@ export async function runInstall({
       "./prepare-onboarding.mjs"
     );
     const config = validatePublicDeployment(JSON.parse(raw));
+    // Keep downloaded settings in memory until the serialized service switch is
+    // approved. A cancelled switch must not alter the other installation's data.
+    if (beforeApplySettings) {
+      const code = await beforeApplySettings();
+      if (code) return {completed:false,cancelled:true,exitCode:code,logPath};
+    }
+    await importSetupFiles(privateDir, userDir);
     await saveJson(join(privateDir, "user-deployment.json"), config);
+    state.dataDir = privateDir;
+    await saveJson(statePath, state);
     write(
       "User, Wallet and Market settings are ready. Continuing to setup.",
     );
@@ -235,9 +238,6 @@ export async function runInstall({
     error.messageDisplayed = true;
     error.logPath = logPath;
     throw error;
-  } finally {
-    await lock.close();
-    await unlink(lockPath);
   }
 }
 async function runCommand(command, args, { cwd, logPath }) {
@@ -246,7 +246,7 @@ async function runCommand(command, args, { cwd, logPath }) {
     await new Promise((resolve, reject) => {
       const child = spawn(command, args, {
         cwd,
-        env: {
+        ...installationChildOptions({env: {
           ...process.env,
           PATH:
             dirname(process.execPath) +
@@ -254,7 +254,7 @@ async function runCommand(command, args, { cwd, logPath }) {
             (process.env.PATH || ""),
           COREPACK_ENABLE_DOWNLOAD_PROMPT: "0",
         },
-        stdio: ["ignore", log.fd, log.fd],
+        stdio: ["ignore", log.fd, log.fd]}),
       });
       child.once("error", (e) =>
         reject(
@@ -263,7 +263,7 @@ async function runCommand(command, args, { cwd, logPath }) {
           ),
         ),
       );
-      child.once("exit", (code) =>
+      child.once("close", (code) =>
         code === 0
           ? resolve()
           : reject(

package/src/installation-binding.mjs

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MPL-2.0
+// Installation routing is local metadata, never Wallet or payment identity.
+import { constants } from 'node:fs';
+import { open, realpath, mkdir, link, unlink, lstat } from 'node:fs/promises';
+import { join, resolve, isAbsolute } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { installationDirectory } from './installation-paths.mjs';
+import { atomicWritePrivate } from './private-journal-files.mjs';
+
+async function location(userDir) {
+  const root = await realpath(userDir);
+  const directory = join(installationDirectory(), 'bindings');
+  const key = createHash('sha256').update(root).digest('hex');
+  return {root, directory, path: join(directory, key + '.json')};
+}
+export async function readInstallationBinding(userDir) {
+  let place;
+  try { place = await location(userDir); }
+  catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+  let handle;
+  try {
+    const directory = await lstat(place.directory);
+    if (!directory.isDirectory() || directory.isSymbolicLink() || directory.uid !== process.getuid() || directory.mode & 0o077)
+      throw Error('Installation bindings directory must be private and owned by you.');
+    handle = await open(place.path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const info = await handle.stat();
+    if (!info.isFile() || info.nlink !== 1 || info.uid !== process.getuid() || info.mode & 0o077 || info.size > 16384)
+      throw Error('Installation binding must be a private file owned by you.');
+    const value = JSON.parse(await handle.readFile('utf8'));
+    if (value.version !== 1 || value.installation !== place.root || typeof value.dataDir !== 'string' || !isAbsolute(value.dataDir) || value.dataDir.includes('\0'))
+      throw Error('Installation binding is invalid. Keep it for review.');
+    return value;
+  } catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+  finally { await handle?.close(); }
+}
+export async function rememberInstallationBinding(userDir, dataDir) {
+  const place = await location(userDir);
+  // Missing data is valid before setup. Existing paths use their canonical location.
+  const selected = await realpath(resolve(dataDir)).catch(e => {
+    if (e.code === 'ENOENT') return resolve(dataDir);
+    throw e;
+  });
+  const saved = await readInstallationBinding(userDir);
+  if (saved) {
+    if (saved.dataDir !== selected) throw Error('This installation uses another data folder. Explicit adoption is required before changing it.');
+    return saved;
+  }
+  await mkdir(place.directory, {recursive:true, mode:0o700});
+  const value = {version:1, installation:place.root, dataDir:selected};
+  const temporary = join(place.directory, '.binding-' + randomUUID());
+  try {
+    await atomicWritePrivate(temporary, JSON.stringify(value) + '\n');
+    // Publish without replacing a concurrently established binding.
+    try { await link(temporary, place.path); }
+    catch (e) { if (e.code !== 'EEXIST') throw e; }
+  } finally { await unlink(temporary).catch(e => { if (e.code !== 'ENOENT') throw e; }); }
+  const actual = await readInstallationBinding(userDir);
+  if (actual.dataDir !== selected) throw Error('Another command selected a different data folder. No binding was replaced.');
+  return actual;
+}
+
+export async function installationBindingPath(userDir) { return (await location(userDir)).path; }

package/src/installation-operation.mjs

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: MPL-2.0
+// Serialize installation writes and managed-service changes. Descriptor locks are
+// inherited by npm/repair children: killing the caller does not unlock a live writer.
+import {AsyncLocalStorage} from 'node:async_hooks';
+import {constants, fstatSync} from 'node:fs';
+import {open, mkdir, lstat, unlink, link} from 'node:fs/promises';
+import {join} from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {ensureInstallationDirectory} from './installation-paths.mjs';
+
+const context = new AsyncLocalStorage();
+export const installationLockMarker = 'agentpay.install-lock.v2\n';
+const marker = installationLockMarker;
+const fdVariable = 'AGENTPAY_INSTALLATION_LOCK_FD';
+const busy = () => Error('Another AgentPay installation or service change is running. Wait for it to finish, then retry.');
+function checkFile(info, allowLinks = false) {
+  if (!info.isFile() || (!allowLinks && info.nlink !== 1) || info.uid !== process.getuid() || info.mode & 0o077)
+    throw Error('Installation lock must be a private regular file owned by you.');
+}
+
+export async function withInstallationOperation(operation) {
+  const directory = await ensureInstallationDirectory();
+  const existing = context.getStore();
+  if (existing?.directory === directory) return operation();
+  await mkdir(directory,{recursive:true,mode:0o700});
+  const info = await lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || info.mode & 0o077)
+    throw Error('Installation state directory must be private and owned by you.');
+  let tryLock;
+  try { ({tryLock} = await import('fs-native-extensions')); }
+  catch { throw Error('Installation tools are missing. Reinstall the User npm package, or run npm ci in your User source folder, then retry.'); }
+  const path = join(directory,'service-selection.lock');
+  const file = await open(path,constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW,0o600);
+  let ownsMarker = false;
+  try {
+    const stat = await file.stat(); checkFile(stat);
+    const inherited = process.env[fdVariable];
+    if (inherited !== undefined) {
+      if (!/^\d+$/.test(inherited) || Number(inherited) < 3) throw Error('Invalid installation lock handoff.');
+      const fd = Number(inherited), held = fstatSync(fd); checkFile(held);
+      if (held.dev !== stat.dev || held.ino !== stat.ino || !tryLock(fd)) throw Error('Invalid installation lock handoff.');
+      // A separately opened descriptor must be excluded, proving the inherited
+      // descriptor really protects this file; an environment flag alone is not a bypass.
+      if (tryLock(file.fd)) throw Error('Installation lock handoff did not preserve exclusion.');
+      return await context.run({directory,fd},operation);
+    }
+    if (!tryLock(file.fd)) throw busy();
+    // Preserve interoperability with older installers. Only our recognizable v2
+    // marker can be reclaimed after acquiring the native lock. Unknown/empty old
+    // markers need operator review, never PID-age based deletion.
+    const legacyPath = join(directory,'install.lock');
+    const temporary = join(directory, 'install-marker-' + randomUUID());
+    let legacy;
+    try {
+      legacy = await open(temporary,'wx',0o600);
+      await legacy.writeFile(marker); await legacy.sync(); await legacy.close(); legacy=undefined;
+      await link(temporary,legacyPath);
+    } catch(error) {
+      await legacy?.close(); legacy = undefined;
+      if (error.code !== 'EEXIST') throw error;
+      legacy = await open(legacyPath,constants.O_RDONLY | constants.O_NOFOLLOW);
+      // A crash between link publication and temporary-name cleanup can leave
+      // two names for this marker. We only read/unlink it; the actual native
+      // lock file still requires exactly one link and provides exclusion.
+      const saved = await legacy.stat(); checkFile(saved, true);
+      if (saved.size !== Buffer.byteLength(marker) || await legacy.readFile('utf8') !== marker)
+        throw Error('An older installer lock exists. Keep it for review; automatic recovery cannot confirm whether its writer has stopped.');
+    } finally {
+      await legacy?.close();
+      await unlink(temporary).catch(error=>{if(error.code!=='ENOENT')throw error;});
+    }
+    ownsMarker = true;
+    return await context.run({directory,fd:file.fd},operation);
+  } finally {
+    // Do not unlock explicitly: inherited children may still hold the same open
+    // description. Production command runners wait for child close before returning.
+    try {
+      if (ownsMarker) await unlink(join(directory,'install.lock')).catch(e=>{if(e.code!=='ENOENT')throw e;});
+    } finally { await file.close(); }
+  }
+}
+
+// Only short-lived administration/writer children inherit the lock. Never pass it
+// to the Wallet/Runtime daemons, which would keep maintenance blocked indefinitely.
+export function installationChildOptions({env = process.env, stdio = ['ignore','pipe','pipe']} = {}) {
+  const held = context.getStore();
+  const clean = {...env}; delete clean[fdVariable];
+  if (!held) return {env:clean,stdio};
+  return {env:{...clean,[fdVariable]:String(stdio.length)},stdio:[...stdio,held.fd]};
+}
+
+// Wait for close even on timeout/error: returning on a timer while npm still writes
+// would release the caller's lock too early. Writer children retain the descriptor.
+export async function runInstallationCommand(file, args, {env = process.env, timeout = 120000, maxBuffer = 2 * 1024 * 1024, cwd} = {}) {
+  const {spawn} = await import('node:child_process');
+  return new Promise((resolve,reject) => {
+    const child = spawn(file,args,{cwd,...installationChildOptions({env})});
+    let stdout='',stderr='',failure,killTimer;
+    const stop = error => {
+      failure ||= error;
+      child.kill('SIGTERM');
+      killTimer ||= setTimeout(()=>child.kill('SIGKILL'),1000);
+    };
+    const timer = setTimeout(()=>stop(Error('Command timed out.')),timeout);
+    child.stdout.on('data',chunk=>{if(failure)return;stdout+=chunk;if(Buffer.byteLength(stdout)>maxBuffer)stop(Error('Command output exceeded its limit.'));});
+    child.stderr.on('data',chunk=>{if(failure)return;stderr+=chunk;if(Buffer.byteLength(stderr)>maxBuffer)stop(Error('Command output exceeded its limit.'));});
+    child.once('error',error=>{failure=error;});
+    child.once('close',(code,signal)=>{
+      clearTimeout(timer); clearTimeout(killTimer);
+      if(failure || code!==0) reject(Object.assign(failure || Error(`Command failed (${signal || code}).`),{stdout,stderr}));
+      else resolve({stdout,stderr});
+    });
+  });
+}

package/src/installation-paths.mjs

@@ -3,12 +3,61 @@
 // per-user state storage; explicit data-directory settings still select key/history data.
 import { homedir } from 'node:os';
 import { isAbsolute, join, dirname } from 'node:path';
-import { lstat, mkdir, copyFile, constants } from 'node:fs/promises';
+import { lstat, mkdir, copyFile, constants, link, unlink, realpath } from 'node:fs/promises';
+import {openSync,closeSync,fstatSync,readFileSync,lstatSync} from 'node:fs';
+import {randomUUID} from 'node:crypto';
+import {atomicWritePrivate} from './private-journal-files.mjs';
+export function stateLocationFile() {
+  return join(homedir(),'.local/state/agentpay/state-location.json');
+}
 export function installationDirectory() {
+  // A fixed, non-secret locator makes login services and Skills independent of
+  // shell-only XDG settings. XDG chooses the initial location, not a second instance.
+  let handle;
+  try {
+    const path=stateLocationFile(),parent=lstatSync(dirname(path));
+    if(!parent.isDirectory() || parent.isSymbolicLink() || parent.uid!==process.getuid() || parent.mode & 0o022)
+      throw Error('AgentPay state locator directory needs ownership review.');
+    handle=openSync(path,constants.O_RDONLY|constants.O_NOFOLLOW);
+    const st=fstatSync(handle);
+    if(!st.isFile() || st.uid!==process.getuid() || st.mode & 0o077 || st.size>16384)
+      throw Error('AgentPay state locator must be private and owned by you.');
+    const saved=JSON.parse(readFileSync(handle,'utf8'));
+    if(saved.version!==1 || typeof saved.directory!=='string' || !isAbsolute(saved.directory) || /[\x00-\x1f\x7f]/.test(saved.directory))
+      throw Error('Invalid AgentPay state locator. Preserve it for review.');
+    return saved.directory;
+  } catch(error) {if(error.code!=='ENOENT')throw error;}
+  finally {if(handle!==undefined)closeSync(handle);}
   const base = process.env.XDG_STATE_HOME || join(homedir(), '.local/state');
   if (!isAbsolute(base)) throw Error('XDG_STATE_HOME must be an absolute path.');
   return join(base, 'agentpay/user');
 }
+export async function ensureInstallationDirectory() {
+  const requested=installationDirectory();
+  await mkdir(requested,{recursive:true,mode:0o700});
+  const info=await lstat(requested);
+  if(!info.isDirectory() || info.isSymbolicLink() || info.uid!==process.getuid() || info.mode & 0o077)
+    throw Error('Installation state directory must be private and owned by you.');
+  const directory=await realpath(requested),path=stateLocationFile();
+  try {
+    await lstat(path);
+    if(installationDirectory()!==directory)
+      throw Error('Another command selected the AgentPay state directory. Retry using its saved location.');
+    return directory;
+  } catch(error) { if(error.code!=='ENOENT')throw error; }
+  await mkdir(dirname(path),{recursive:true,mode:0o700});
+  const parent=await lstat(dirname(path));
+  if(!parent.isDirectory() || parent.isSymbolicLink() || parent.uid!==process.getuid() || parent.mode & 0o022)
+    throw Error('AgentPay state locator directory needs ownership review.');
+  const temporary=path+'.'+randomUUID();
+  try {
+    await atomicWritePrivate(temporary,JSON.stringify({version:1,directory})+'\n');
+    try {await link(temporary,path);}catch(error){if(error.code!=='EEXIST')throw error;}
+  } finally {await unlink(temporary).catch(error=>{if(error.code!=='ENOENT')throw error;});}
+  if(installationDirectory()!==directory)
+    throw Error('Another command selected the AgentPay state directory. Retry using its saved location.');
+  return directory;
+}
 export function legacyInstallationDirectory(userDir) { return join(dirname(userDir), '.agentpay-install'); }
 export async function deploymentFilePath(dataDir, userDir, name) {
   if (!['anvil-onboarding.json', 'user-deployment.json'].includes(name)) throw Error('Invalid setup filename.');

package/src/invocation-store.mjs

@@ -367,7 +367,7 @@ export function createInvocationStore(path, serviceBinding = null) {
   });
 }
 
-function hashInvocationKey(value) {
+export function hashInvocationKey(value) {
   const normalized = String(value || "").trim();
   if (!/^[A-Za-z0-9._:-]{8,128}$/.test(normalized))
     throw coded(

package/src/local-data-directory.mjs

@@ -1,9 +1,11 @@
+import {withInstallationOperation} from './installation-operation.mjs';
+import { readInstallationBinding, rememberInstallationBinding } from "./installation-binding.mjs";
 import { installationDirectory, legacyInstallationDirectory } from "./installation-paths.mjs";
 // SPDX-License-Identifier: MPL-2.0
 // This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
 // If a copy was not distributed with this file, see https://mozilla.org/MPL/2.0/.
 import { constants } from "node:fs";
-import { lstat, mkdir, open, rename, unlink } from "node:fs/promises";
+import { lstat, mkdir, open, rename, unlink, realpath } from "node:fs/promises";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -65,13 +67,23 @@ export async function resolveUserDataDir({
   env = process.env,
   userDir = installedUserDir,
 } = {}) {
-  if (argument || env.AGENTPAY_USER_DATA_DIR)
-    return resolve(argument || env.AGENTPAY_USER_DATA_DIR);
+  const binding = await readInstallationBinding(userDir);
+  if (argument || env.AGENTPAY_USER_DATA_DIR) {
+    const selected = resolve(argument || env.AGENTPAY_USER_DATA_DIR);
+    const canonical = await realpath(selected).catch(e => { if (e.code === 'ENOENT') return selected; throw e; });
+    if (binding && canonical !== binding.dataDir)
+      throw Error('This installation is bound to another data folder. Use its configured folder; explicit adoption is required to change it.');
+    return selected;
+  }
+  if (binding) return binding.dataDir;
   const state = await readState(userDir);
   return state.dataDir || join(homedir(), ".local/share/agentpay/user");
 }
 // Uses the existing installer lock and preserves dependency/build checkpoints.
-export async function rememberUserDataDir({
+export async function rememberUserDataDir(options) {
+  return withInstallationOperation(() => rememberUnderLock(options));
+}
+async function rememberUnderLock({
   userDir = installedUserDir,
   dataDir,
 }) {
@@ -84,21 +96,11 @@ export async function rememberUserDataDir({
     throw Error(
       "Installation record directory must be private and owned by you.",
     );
-  const lockPath = join(directory, "install.lock");
-  let lock;
-  try {
-    lock = await open(lockPath, "wx", 0o600);
-  } catch (error) {
-    if (error.code === "EEXIST")
-      throw Error(
-        "Another installation may be running. Retry after it finishes.",
-      );
-    throw error;
-  }
   const temp = join(directory, `location-${randomUUID()}.tmp`);
   let file;
   try {
     const state = await readState(userDir);
+    await rememberInstallationBinding(userDir, dataDir);
     file = await open(temp, "wx", 0o600);
     await file.writeFile(
       JSON.stringify({ ...state, version: 1, dataDir: resolve(dataDir) }) +
@@ -111,7 +113,5 @@ export async function rememberUserDataDir({
   } finally {
     await file?.close();
     await unlink(temp).catch(() => {});
-    await lock.close();
-    await unlink(lockPath);
   }
 }

package/src/local-update.mjs

@@ -1,3 +1,5 @@
+import {withInstallationOperation, installationChildOptions} from './installation-operation.mjs';
+import {maintenanceServiceScope} from './service-selection.mjs';
 import { requireRunningSoftware } from "./software-versions.mjs";
 import { walletPackage } from "./wallet-package.mjs";
 // Apply installed packages. Preserve identity/history and startup preferences;
@@ -112,12 +114,12 @@ async function manage(action, { userDir, dataDir, logPath }) {
         [join(userDir, "scripts/autostart.mjs"), action],
         {
           shell: false,
-          env: { ...process.env, AGENTPAY_USER_DATA_DIR: dataDir },
-          stdio: ["ignore", file.fd, file.fd],
+          ...installationChildOptions({env: { ...process.env, AGENTPAY_USER_DATA_DIR: dataDir },
+          stdio: ["ignore", file.fd, file.fd]}),
         },
       );
       child.once("error", reject);
-      child.once("exit", (code) =>
+      child.once("close", (code) =>
         code === 0
           ? done()
           : reject(Error("Background service operation failed.")),
@@ -127,7 +129,11 @@ async function manage(action, { userDir, dataDir, logPath }) {
     await file.close();
   }
 }
-export async function applyLocalUpdate({
+export async function applyLocalUpdate(options = {}) {
+  try { return await withInstallationOperation(() => repairUnderLock(options)); }
+  catch(error) { (options.write || console.log)("Repair stopped. " + error.message); return 1; }
+}
+async function repairUnderLock({
   userDir = installedUserDir,
   dataDir,
   write = console.log,
@@ -143,13 +149,15 @@ export async function applyLocalUpdate({
   connection = ensureRuntimeConnection,
   prepare = runInstall,
   service = manage,
+  serviceScope = maintenanceServiceScope,
   wallet = localWalletAdmin,
   runtime = readRuntimeStatus,
   pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
 } = {}) {
   let phase = "preflight",
     logPath,
-    selected;
+    selected,
+    activeServices = true;
   try {
     write(
       "\n------------------------------------------------------------\n> Repair User and Wallet\n------------------------------------------------------------",
@@ -165,6 +173,8 @@ export async function applyLocalUpdate({
     const pair = await pairCheck(userDir);
     await checkDirectory(dataDir);
     await settings(dataDir);
+    const scope = await serviceScope({userDir,dataDir});
+    activeServices = scope.active;
     write(
       `1/3 Check local files · User ${pair.userVersion} / Wallet ${pair.walletVersion}`,
     );
@@ -186,12 +196,18 @@ export async function applyLocalUpdate({
           applied.inputs === selected.inputs &&
           applied.outputs === selected.outputs
         ) {
+          if (!scope.active) {
+            await connection({dataDir,write,refreshClientModule:true});
+            phase = "unchanged";
+            write("This installation is up to date and remains inactive. Running services were not changed.");
+            return false;
+          }
           let runningMatches = false;
           try {
             requireRunningSoftware(await wallet(dataDir, "status"), await runtime(dataDir), { ...pair, protocolVersion: pair.typesDependency });
             runningMatches = true;
           } catch { /* Keep repair available for old, stopped or unreported processes. */ }
-          if (runningMatches) {
+          if (runningMatches && scope.active) {
             await connection({ dataDir, write });
             phase = "unchanged";
             write("Local installation and running versions are up to date. Background services were not changed.");
@@ -205,7 +221,8 @@ export async function applyLocalUpdate({
             : "Installed program changes need to be applied.",
         );
         write(
-          "Wallet and Runtime will pause, verify installed files and restart. Wallet will need unlocking afterwards.",
+          scope.active ? "Wallet and Runtime will pause, verify installed files and restart. Wallet will need unlocking afterwards."
+            : "This inactive installation will be repaired. The running Wallet and Runtime will not change.",
         );
         if (!force) {
           while (true) {
@@ -234,6 +251,11 @@ export async function applyLocalUpdate({
           inputs: selected.inputs,
         };
         await context.saveState();
+        if (!scope.active) {
+          phase = "building";
+          write("2/3 Check this installation's packages. Active services are unchanged.");
+          return;
+        }
         await service("prepare-repair", { userDir, dataDir, logPath });
         phase = "stopping";
         write(
@@ -248,6 +270,13 @@ export async function applyLocalUpdate({
         if (built.inputs !== selected.inputs)
           throw Error("Installed files changed during repair.");
         await connection({ dataDir, write, refreshClientModule: true });
+        if (!scope.active) {
+          context.state.localUpdate = {status:"complete", ...built};
+          await context.saveState();
+          phase = "ready";
+          write("3/3 Inactive installation checked. It has not been started.");
+          return;
+        }
         phase = "starting";
         write("3/3 Start Wallet and Runtime.");
         await service("start", { userDir, dataDir, logPath });
@@ -288,20 +317,22 @@ export async function applyLocalUpdate({
     if (!result?.completed || phase !== "ready")
       throw Error("Repair did not finish.");
     write(
-      "\nRepair complete. Wallet and Runtime are running in the background.",
+      scope.active ? "\nRepair complete. Wallet and Runtime are running in the background."
+        : "\nRepair complete. This installation remains inactive; existing services were kept.",
     );
     write(
       "Keys, spending permission and Order records were kept. Login startup preference is unchanged.",
     );
     await officialTest({ userDir, dataDir, write });
-    write("Next: agentpay wallet unlock\nThen: agentpay status");
+    write(scope.active ? "Next: agentpay wallet unlock\nThen: agentpay status" : "To switch to this installation: agentpay service start");
     return 0;
   } catch (error) {
     if (phase === "preflight")
       write("Repair stopped before pausing services. " + error.message);
     else if (phase === "building")
       write(
-        "Repair could not finish. Wallet and Runtime remain stopped; your local data was kept.",
+        activeServices ? "Repair could not finish. Wallet and Runtime remain stopped; your local data was kept."
+          : "Repair could not finish. The active installation was not changed; your local data was kept.",
       );
     else
       write(

package/src/local-wallet-ipc.mjs

@@ -7,7 +7,7 @@ import { open } from "node:fs/promises";
 import { createConnection } from "node:net";
 import { join } from "node:path";
 import { randomBytes } from "node:crypto";
-export async function localWalletAdmin(dataDir, method, params = {}) {
+export async function localWalletAdmin(dataDir, method, params = {}, {timeoutMs = 30000} = {}) {
   await checkServiceDirectory(dataDir);
   const h = await open(
     join(dataDir, "wallet/admin.token"),
@@ -40,7 +40,7 @@ export async function localWalletAdmin(dataDir, method, params = {}) {
     };
     const timer = setTimeout(
       () => finish(Error("Wallet did not respond. Run agentpay status.")),
-      30000,
+      timeoutMs,
     );
     socket.setEncoding("utf8");
     socket.once("error", (e) =>