@c4roa0/agentpay-user 0.3.6 → 0.3.8

package/src/npm-update.mjs

@@ -1,17 +1,19 @@
+import {atomicWritePrivate, assertPrivateFile} from './private-journal-files.mjs';
+import {withInstallationOperation, runInstallationCommand} from './installation-operation.mjs';
+import {maintenanceServiceScope} from './service-selection.mjs';
 // SPDX-License-Identifier: MPL-2.0
 // Update real global or project npm installations. Source checkouts/npm links are never
 // overwritten. npm selects User; User's exact dependencies select Wallet/Protocol.
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import { access, appendFile, copyFile, chmod, lstat, mkdir, mkdtemp, open, readFile, realpath, rm, unlink } from 'node:fs/promises';
+import { access, appendFile, copyFile, chmod, lstat, mkdir, mkdtemp, readFile, realpath, rm, unlink } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
-import { randomUUID } from 'node:crypto';
+import { randomUUID, createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
 import { createInterface } from 'node:readline/promises';
 import { installedUserDir, resolveUserDataDir, rememberUserDataDir } from './local-data-directory.mjs';
 import { installationDirectory } from './installation-paths.mjs';
 import { prepareOfficialTestUpdate } from './official-test-update.mjs';
-const execute = promisify(execFile);
+const execute = runInstallationCommand;
 const name = '@c4roa0/agentpay-user';
 const stable = value => typeof value === 'string' && /^\d+\.\d+\.\d+$/.test(value);
 function newer(next, current) {
@@ -64,15 +66,20 @@ async function installationTarget(userDir, npm) {
     flags:['--global=false','--workspaces=false','--save-exact',save,'--include=dev','--include=optional']};
 }
 
-export async function updateFromNpm({
+export async function updateFromNpm(options = {}) {
+  try { return await withInstallationOperation(() => updateUnderLock(options)); }
+  catch(error) { (options.write || console.log)("Update stopped. " + error.message); return 1; }
+}
+async function updateUnderLock({
   userDir = installedUserDir, dataDir, force = false, write = console.log,
   ask = askConfirmation,
   npm = (args, options) => command('npm', args, options),
   service = (action, options) => command(process.execPath, [join(userDir,'scripts/autostart.mjs'), action], options),
   repair = options => command(process.execPath, [join(userDir,'scripts/repair.mjs'), '-f'], options),
   officialTest = prepareOfficialTestUpdate,
+  serviceScope = maintenanceServiceScope,
 } = {}) {
-  let lock, lockPath, logPath, installing = false;
+  let logPath, installing = false;
   try {
     userDir = resolve(userDir);
     const current = JSON.parse(await readFile(join(userDir, 'package.json'), 'utf8'));
@@ -80,20 +87,62 @@ export async function updateFromNpm({
     write('Checking for a User update…');
     const target = await installationTarget(userDir, npm);
     await access(dirname(target.directory), constants.W_OK);
-    const metadata = JSON.parse(await npm(['view',name + '@latest','--json'], {cwd:target.prefix}));
+    const progressPath = join(installationDirectory(), 'update-' + createHash('sha256').update(userDir).digest('hex') + '.json');
+    let pending;
+    try {
+      await assertPrivateFile(progressPath);
+      if ((await lstat(progressPath)).size > 16384) throw Error('Invalid update recovery record.');
+      pending = JSON.parse(await readFile(progressPath,'utf8'));
+      if (pending.version !== 1 || pending.installation !== userDir || !stable(pending.targetVersion) ||
+          !stable(pending.walletVersion) || !stable(pending.protocolVersion) || !isAbsolute(pending.dataDir))
+        throw Error('Invalid update recovery record. Keep it for review.');
+    } catch(error) { if(error.code !== 'ENOENT') throw error; }
+    dataDir ??= await resolveUserDataDir({userDir});
+    if (pending && pending.dataDir !== dataDir) throw Error('The interrupted update belongs to another data folder. Keep its recovery record for review.');
+    const scope = await serviceScope({userDir,dataDir});
+    if (pending && current.version === pending.targetVersion) {
+      installing = true;
+      if (current.dependencies?.['@c4roa0/agentpay-wallet'] !== pending.walletVersion ||
+          current.dependencies?.['@c4roa0/agentpay-protocol'] !== pending.protocolVersion)
+        throw Error('The interrupted update has mismatched dependencies. Reinstall the confirmed User version, then retry.');
+      write('Continuing the interrupted update. Checking installed packages and service settings.');
+      const configured = await lstat(join(dataDir,'runtime/local-services.json')).then(s=>s.isFile(),e=>{if(e.code==='ENOENT')return false;throw e;});
+      if (configured) {
+        const output = await repair({env:{...process.env,AGENTPAY_USER_DATA_DIR:dataDir},cwd:target.prefix,timeout:600000});
+        if(output)write(output);
+      } else await officialTest({userDir,dataDir,write});
+      await unlink(progressPath);
+      write(`User ${current.version} update completed. No paid test was started.`);
+      return 0;
+    }
+    if(pending && newer(current.version,pending.targetVersion))
+      throw Error('Installed User is newer than the interrupted update. Keep the recovery record for review; no downgrade was attempted.');
+    const metadata = JSON.parse(await npm(['view',name + '@' + (pending?.targetVersion || 'latest'),'--json'], {cwd:target.prefix}));
     if (metadata.name !== name || !stable(metadata.version) ||
         !stable(metadata.dependencies?.['@c4roa0/agentpay-wallet']) ||
         !stable(metadata.dependencies?.['@c4roa0/agentpay-protocol']))
       throw Error('The published User release does not declare reviewed package versions.');
-    dataDir ??= await resolveUserDataDir({userDir});
+    if (pending && (metadata.version !== pending.targetVersion || metadata.dependencies["@c4roa0/agentpay-wallet"] !== pending.walletVersion || metadata.dependencies["@c4roa0/agentpay-protocol"] !== pending.protocolVersion))
+      throw Error("The published package differs from the interrupted update. No program files were changed.");
     if (!newer(metadata.version,current.version)) {
       write(`User ${current.version} is current. Checking the official test Skill.`);
       await officialTest({userDir,dataDir,write});
       return 0;
     }
-    write(`User ${current.version} → ${metadata.version} · Wallet ${metadata.dependencies['@c4roa0/agentpay-wallet']}`);
+    // Read the installed dependency, not the version requested by User's manifest.
+    // Missing/broken packages must not prevent npm from repairing the installation.
+    let walletVersion;
+    try {
+      const file = createRequire(join(userDir,'package.json')).resolve('@c4roa0/agentpay-wallet/package.json');
+      const wallet = JSON.parse(await readFile(file,'utf8'));
+      if(wallet.name === '@c4roa0/agentpay-wallet' && stable(wallet.version)) walletVersion = wallet.version;
+    } catch {}
+    const targetWallet = metadata.dependencies['@c4roa0/agentpay-wallet'];
+    write('Installed packages → update target');
+    write(`User    ${current.version} → ${metadata.version}`);
+    write(`Wallet  ${walletVersion === targetWallet ? `${walletVersion} (unchanged)` : `${walletVersion || 'not confirmed'} → ${targetWallet}`}`);
     write(`Installation folder: ${target.prefix}`);
-    write('Background services will pause. Keys, permissions, Orders and cache are kept.');
+    write(scope.active ? 'Background services will pause. Keys, permissions, Orders and cache are kept.' : 'This installation is inactive. The running Wallet and Runtime will not change.');
     if (!force && (await ask("Type 'confirm' to update, or 'q' to cancel")).trim().toLowerCase() !== 'confirm') {
       write('Update cancelled. Nothing was changed.'); return 0;
     }
@@ -102,8 +151,6 @@ export async function updateFromNpm({
     const stateDir = installationDirectory();
     await mkdir(stateDir,{recursive:true,mode:0o700});
     logPath = join(stateDir, `update-${Date.now()}-${randomUUID()}.log`);
-    lockPath = join(stateDir,'install.lock');
-    lock = await open(lockPath,'wx',0o600);
     const rechecked = JSON.parse(await readFile(join(userDir,'package.json'),'utf8'));
     if (rechecked.version !== current.version || rechecked.name !== name)
       throw Error('Program files changed while reviewing the update. Run agentpay update again.');
@@ -132,8 +179,13 @@ export async function updateFromNpm({
     let configured = false;
     try { configured = (await lstat(join(dataDir,'runtime/local-services.json'))).isFile(); }
     catch(e) { if(e.code !== 'ENOENT') throw e; }
+    // Record the confirmed version before stopping or replacing anything. A retry
+    // must finish repair even when npm already installed the target version.
+    await atomicWritePrivate(progressPath, JSON.stringify({version:1,installation:userDir,dataDir,
+      targetVersion:metadata.version,walletVersion:metadata.dependencies['@c4roa0/agentpay-wallet'],
+      protocolVersion:metadata.dependencies['@c4roa0/agentpay-protocol']}) + '\n');
     // All imports used by this updater are loaded before npm replaces its files.
-    if (configured) await service('stop',options);
+    if (configured && scope.active) await service('stop',options);
     installing = true;
     write('2/3 Install User and its matching Wallet. This may take a few minutes.');
     await npm(args,options);
@@ -142,11 +194,8 @@ export async function updateFromNpm({
        installed.dependencies?.['@c4roa0/agentpay-wallet'] !== metadata.dependencies['@c4roa0/agentpay-wallet'] ||
        installed.dependencies?.['@c4roa0/agentpay-protocol'] !== metadata.dependencies['@c4roa0/agentpay-protocol'])
       throw Error('The installed version does not match the confirmed update.');
-    // Release before the new version's repair acquires the same lock. Another
-    // operation may win that lock; repair then refuses safely and can be retried.
-    await lock.close(); lock = null; await unlink(lockPath); lockPath = null;
     if (configured) {
-      write('3/3 Restore services and verify the official test Skill.');
+      write(scope.active ? '3/3 Restore services and verify the official test Skill.' : '3/3 Verify the inactive installation and official test Skill.');
       // A fresh Node process loads the NEW repair/client/official digest, not old imports.
       const output = await repair(options);
       if(output) write(output);
@@ -154,6 +203,7 @@ export async function updateFromNpm({
       write('3/3 Program files are ready. Local setup has not been configured.');
       write('Next: agentpay install --market YOUR_MARKET_URL');
     }
+    await unlink(progressPath);
     write(`User ${metadata.version} installed. No paid test was started.`);
     return 0;
   } catch(error) {
@@ -162,7 +212,5 @@ export async function updateFromNpm({
       : 'Update stopped before replacing program files. ' + (error.code === 'EEXIST' ? 'Another installation is running.' : error.message));
     if(logPath) write('Log: ' + logPath);
     return 1;
-  } finally {
-    if(lock) { await lock.close(); await unlink(lockPath); }
   }
 }

package/src/platform-endpoints.mjs

@@ -1,3 +1,4 @@
+import {withInstallationOperation,runInstallationCommand} from './installation-operation.mjs';
 // SPDX-License-Identifier: MPL-2.0
 // Deliberate transport changes only. Never replace a Policy, request, or result.
 import {open,mkdir,lstat,rename,unlink,readFile} from 'node:fs/promises';
@@ -5,8 +6,6 @@ import {constants} from 'node:fs';
 import {join,dirname} from 'node:path';
 import {homedir} from 'node:os';
 import {randomUUID} from 'node:crypto';
-import {execFile} from 'node:child_process';
-import {promisify} from 'node:util';
 import {installedUserDir} from './local-data-directory.mjs';
 import {deploymentFilePath,installationDirectory} from './installation-paths.mjs';
 import {readPrivateJson,deploymentChanges} from './deployment-status.mjs';
@@ -18,7 +17,7 @@ import {settlementProfileBlocker} from './readiness-profile.mjs';
 import {readRuntimeStatus} from './runtime-status.mjs';
 import {readSettlementAddresses} from './settlement-address-history.mjs';
 
-const execute=promisify(execFile);
+const execute=runInstallationCommand;
 const normalize=value=>new URL(value).href.replace(/\/+$/,'');
 const same=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
 const pendingPath=dir=>join(dir,'runtime/endpoint-update.pending.json');
@@ -102,12 +101,11 @@ export async function preparePlatformEndpoints({dataDir,origin,scope,userDir=ins
  if(!metadata.response.ok||!metadata.result?.ok||!/^[a-f0-9]{64}$/.test(metadata.result.result?.sha256||''))
   throw Error('The new package address could not be checked. Current addresses are kept.');
  if(!changed)return {changed:false,apply:async()=>{}};
- return {changed:true,urls,async apply({write=console.log,manage=runtimeControl,stateDir=installationDirectory(),saveConnection=async()=>{}}={}){
+ return {changed:true,urls,async apply(options={}){return withInstallationOperation(()=>applyAddresses(options));}};
+ async function applyAddresses({write=console.log,manage=runtimeControl,stateDir=installationDirectory(),saveConnection=async()=>{}}={}){
   await mkdir(stateDir,{recursive:true,mode:0o700});
   const stat=await lstat(stateDir);
   if(!stat.isDirectory()||stat.isSymbolicLink()||stat.uid!==process.getuid()||(stat.mode&0o077))throw Error('Unsafe installation state directory.');
-  const lockPath=join(stateDir,'install.lock');let lock;
-  try{lock=await open(lockPath,'wx',0o600);}catch(e){if(e.code==='EEXIST')throw Error('Another setup or update is running. Retry market connect when it finishes.');throw e;}
   let updating=false;
   try{
    if(!same(await readPrivateJson(join(dataDir,'market-connection.json')),connectionBefore)||!same(await readPrivateJson(join(dataDir,'wallet/policy.json')),policy)||!same(await readServiceSettings(dataDir),settings)||!same(await readPrivateJson(publicPath),previousPublic)||!same(await readPrivateJson(await deploymentFilePath(dataDir,userDir,'anvil-onboarding.json')),setup))
@@ -133,6 +131,5 @@ export async function preparePlatformEndpoints({dataDir,origin,scope,userDir=ins
    await unlink(pendingPath(dataDir));
    write('Platform addresses updated. Your Wallet, permission and Order records were kept.');
   }catch(e){throw Error('Address update did not finish.\n'+e.message+'\n'+(updating?'Some connection settings may already be saved. Wallet keys, Policies and Orders were kept.':'No connection addresses were changed.')+'\nNext: agentpay market connect --market '+origin);}
-  finally{await lock.close();await unlink(lockPath);}
- }};
+ }
 }

package/src/runtime-client.mjs

@@ -1,3 +1,5 @@
+import { readFileSync, lstatSync } from "node:fs";
+import { installationDirectory } from "./installation-paths.mjs";
 // Shared Skill transport and recovery. Resolve local credentials privately; endpoint
 // changes must not replace the original purchase identity or bypass retained checkpoints.
 // SPDX-License-Identifier: MPL-2.0
@@ -38,6 +40,17 @@ export class RuntimeClientError extends Error {
 }
 const fail = (code, message) => new RuntimeClientError(code, message);
 export function userDataDirectory(env = process.env) {
+  if (!env.AGENTPAY_USER_DATA_DIR) {
+    const path=join(installationDirectory(),'active-services.json');
+    try {
+      const st=lstatSync(path);
+      if (!st.isFile() || st.isSymbolicLink() || st.uid!==process.getuid() || st.mode & 0o077 || st.size>32768) throw Error('Unsafe default Runtime selection.');
+      const selection=JSON.parse(readFileSync(path,'utf8'));
+      if (selection.version!==1 || selection.phase!=='selected' || typeof selection.target?.dataDir!=='string' || !isAbsolute(selection.target.dataDir))
+        throw Error('The default Runtime is unavailable. Start the selected installation before using a Skill.');
+      return selection.target.dataDir;
+    } catch(e) {if(e.code!=='ENOENT')throw e;}
+  }
   return resolve(
     env.AGENTPAY_USER_DATA_DIR || join(homedir(), ".local/share/agentpay/user"),
   );
@@ -852,7 +865,7 @@ export async function selectInvocation(
   connection,
   service,
   input,
-  { force = false, requestId } = {},
+  { force = false, requestId, knownRequestIds } = {},
 ) {
   if (force && requestId !== undefined)
     throw fail(
@@ -871,9 +884,13 @@ export async function selectInvocation(
         );
       const id =
         requestId || (!force ? state.currentId || state.pending[0] : undefined);
-      const checkpoint = id
-        ? await prepareInvocation(connection, service, input, id)
-        : await prepareInvocation(connection, service, input);
+      if (!force && knownRequestIds?.length && (!id || !knownRequestIds.includes(id)))
+        throw fail("REQUEST_HISTORY_REVIEW_REQUIRED",
+          "The original request selection is missing or conflicting. Use --resume with the saved request ID in the original installation; do not start a replacement purchase.");
+      const retained = id && (state.currentId === id || state.pending.includes(id) || knownRequestIds?.includes(id));
+      const checkpoint = retained
+        ? await resumeInvocation(connection, service, id, input)
+        : await prepareInvocation(connection, service, input, id);
       if (!state.pending.includes(checkpoint.requestId)) {
         const cached = await cachedResult(connection, checkpoint);
         if (!cached) state.pending.push(checkpoint.requestId);

package/src/runtime-connection-settings.mjs

@@ -12,7 +12,7 @@ import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
 import { readServiceSettings } from "./local-services.mjs";
 
-export async function ensureRuntimeConnection({ dataDir, write = () => {}, refreshClientModule = false, checkOnly = false }) {
+export async function ensureRuntimeConnection({ dataDir, write = () => {}, refreshClientModule = false, previousClientModule, checkOnly = false }) {
   const settings = await readServiceSettings(dataDir);
   const directory = join(dataDir, "runtime"),
     path = join(directory, "connection.json");
@@ -45,6 +45,7 @@ export async function ensureRuntimeConnection({ dataDir, write = () => {}, refre
         throw Error("conflict");
       if (saved.clientModule !== expected.clientModule) {
         if (!refreshClientModule || typeof saved.clientModule !== 'string' || !isAbsolute(saved.clientModule) || !saved.clientModule.endsWith('/src/runtime-client.mjs')) throw Error('conflict');
+        if (previousClientModule !== undefined && saved.clientModule !== previousClientModule) throw Error('conflict');
         // Explicit repair after stopping services can relocate trusted client code.
         // URL, credential, request identities and authorization remain unchanged.
         if (!checkOnly) {

package/src/runtime-owner.mjs

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: MPL-2.0
+// A descriptor lock prevents different product entry points from running two
+// Runtimes for the same OS user, even when their ports and data folders differ.
+import { constants } from 'node:fs';
+import { open, mkdir, lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ensureInstallationDirectory } from './installation-paths.mjs';
+export async function acquireRuntimeOwner() {
+  const directory=await ensureInstallationDirectory();
+  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('Runtime ownership directory must be private and owned by you.');
+  const handle=await open(join(directory,'runtime-owner.lock'),constants.O_CREAT|constants.O_RDWR|constants.O_NOFOLLOW,0o600);
+  try {
+    const info=await handle.stat();
+    if(!info.isFile() || info.nlink!==1 || info.uid!==process.getuid() || info.mode & 0o077) throw Error('Unsafe Runtime ownership lock.');
+    const {tryLock}=await import('fs-native-extensions');
+    if(!tryLock(handle.fd)) throw Error('Another AgentPay Runtime is running. Switch installations through agentpay service start; do not start a second Runtime.');
+    return handle;
+  } catch(e) { await handle.close(); throw e; }
+}

package/src/runtime-selection-ready.mjs

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MPL-2.0
+import {readFile,realpath} from 'node:fs/promises';
+import {join} from 'node:path';
+import {installationDirectory} from './installation-paths.mjs';
+import {assertPrivateFile,atomicWritePrivate} from './private-journal-files.mjs';
+import {fileURLToPath} from 'node:url';
+import {waitForServiceReadiness} from './service-readiness.mjs';
+import {withClientRequestLock} from './client-request-lock.mjs';
+// Called after bind. Login startup may revive a stopped selection, but must never
+// overwrite an unfinished switch or select a different data directory.
+export async function publishRuntimeReady(dataDir, {verifyReady = waitForServiceReadiness} = {}) {
+ const state=installationDirectory(),path=join(state,'active-services.json');
+ const userDir=await realpath(fileURLToPath(new URL('..',import.meta.url)));
+ for (let attempt=0;attempt<60;attempt++) {
+ try {return await withClientRequestLock(join(state,'service-selection.lock'),async()=>{
+  let selected;
+  try {await assertPrivateFile(path);selected=JSON.parse(await readFile(path,'utf8'));}
+  catch(e){if(e.code==='ENOENT')return;throw e;}
+  if(selected.version!==1 || selected.target?.dataDir!==dataDir || selected.target?.userDir!==userDir || !['stopped','selected'].includes(selected.phase))return;
+  // Recheck after acquiring the transition lock; an earlier probe could become
+  // stale while a concurrent stop/switch runs. Login also verifies both services.
+  await verifyReady(dataDir);
+  await atomicWritePrivate(path,JSON.stringify({...selected,phase:'selected'})+'\n');
+ });} catch(error) {
+  if(error.code!=='REQUEST_BUSY' || attempt===59)throw error;
+  await new Promise(resolve=>setTimeout(resolve,300));
+ }
+ }
+}

package/src/service-readiness.mjs

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MPL-2.0
+// Authenticated local status, not an open port or systemctl's start result,
+// establishes readiness. A locked Wallet and unfinished Order checks are normal.
+import {localWalletAdmin} from './local-wallet-ipc.mjs';
+import {readRuntimeStatus} from './runtime-status.mjs';
+import {requireRunningSoftware} from './software-versions.mjs';
+
+export async function waitForServiceReadiness(dataDir, {
+  wallet = dir => localWalletAdmin(dir, 'status', {}, {timeoutMs:2500}),
+  runtime = readRuntimeStatus,
+  timeoutMs = 15000,
+  pause = ms => new Promise(resolve => setTimeout(resolve, ms)),
+} = {}) {
+  const deadline = Date.now() + timeoutMs;
+  do {
+    try {
+      const [w,r] = await Promise.all([wallet(dataDir), runtime(dataDir)]);
+      if (typeof w?.locked !== 'boolean' || r?.role !== 'user-runtime')
+        throw Error('Invalid local service response.');
+      requireRunningSoftware(w,r);
+      return;
+    } catch (error) {
+      if (error.code === 'RUNNING_VERSION_UNVERIFIED') throw error;
+      if (Date.now() >= deadline) break;
+      await pause(300);
+    }
+  } while (Date.now() < deadline);
+  throw Error('Wallet and Runtime readiness could not be confirmed. Default Skill access stays paused. Run agentpay status, then retry agentpay service start.');
+}

package/src/service-selection.mjs

@@ -0,0 +1,189 @@
+import {importHistoricalRequests} from './default-request-owner.mjs';
+// SPDX-License-Identifier: MPL-2.0
+// One managed service pair per OS user. A switch never changes Wallet identity.
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { autostartFiles, units } from './autostart-files.mjs';
+import { installationDirectory } from './installation-paths.mjs';
+import { withInstallationOperation } from './installation-operation.mjs';
+import { readServiceSettings, listenerPresent } from './local-services.mjs';
+import { atomicWritePrivate } from './private-journal-files.mjs';
+import { ensureRuntimeConnection } from './runtime-connection-settings.mjs';
+import { waitForServiceReadiness } from './service-readiness.mjs';
+
+export async function installedServiceSelection(unitDir = join(homedir(), '.config/systemd/user'), recovery, {allowPartial = false} = {}) {
+  let identity;
+  let count = 0;
+  for (const name of units) {
+    const path = join(unitDir,name);
+    let info;
+    try { info = await lstat(path); } catch (e) { if (e.code === 'ENOENT') continue; throw e; }
+    if (!info.isFile() || info.isSymbolicLink() || info.uid !== process.getuid() || info.mode & 0o022)
+      throw Error('Existing service files need ownership review before switching.');
+    const body = await readFile(path,'utf8');
+    const line = body.split('\n').find(s => s.startsWith('ExecStart='));
+    const args = [...(line || '').matchAll(/"(?:\\.|[^"\\])*"/g)].map(([s]) => JSON.parse(s).replaceAll('%%','%').replaceAll('$$','$'));
+    const suffix = name.includes('reminder') ? '/scripts/login-notify.mjs' : '/scripts/local-service.mjs';
+    if (!args[1]?.endsWith(suffix) || !args[2]) throw Error('Unrecognized startup file. No service was changed.');
+    const found = {node:args[0], userDir:args[1].slice(0,-suffix.length), dataDir:args[2]};
+    const recoverable = recovery && [recovery.previous,recovery.target].filter(Boolean).some(value=>autostartFiles(value)[name]===body);
+    if ((recovery && !recoverable) || autostartFiles(found)[name] !== body || (!recoverable && identity && JSON.stringify(found) !== JSON.stringify(identity)))
+      throw Error('Startup files belong to conflicting configurations. No service was changed.');
+    identity = found; count++;
+  }
+  if (!recovery && !allowPartial && count && count !== units.length) throw Error('Startup files are incomplete. Repair the original installation before switching.');
+  return recovery ? (recovery.previous || recovery.target) : identity;
+}
+
+// Full, exact target units distinguish a failed service command from interrupted
+// file replacement. Never infer completion from only one surviving unit.
+async function targetUnitsPrepared(unitDir, target) {
+  try {
+    const found = await installedServiceSelection(unitDir);
+    return Boolean(found && ['node','userDir','dataDir'].every(key => found[key] === target?.[key]));
+  } catch { return false; }
+}
+
+// The caller holds this lock through unit replacement and start/stop. No prompts
+// can grant approval to a different target while the current transition writes.
+export async function withServiceSelection({target, action, ask, write = console.log, ctl, unitDir, operation, verifyReady = waitForServiceReadiness}) {
+  return withServiceLifecycleLock(async () => {
+    const canonical = path => realpath(path).catch(error=>{if(error.code==='ENOENT')return resolve(path);throw error;});
+    target = {...target,userDir:await canonical(target.userDir),dataDir:await canonical(target.dataDir)};
+    const state = installationDirectory();
+    const journalPath = join(state,'active-services.json');
+    let recovery, savedSelection;
+    try {
+      const st=await lstat(journalPath);
+      if (!st.isFile() || st.isSymbolicLink() || st.uid!==process.getuid() || st.mode & 0o077 || st.size>32768) throw Error('Unsafe service transition record.');
+      const saved=JSON.parse(await readFile(journalPath,'utf8'));
+      savedSelection=saved;
+      if (saved.version!==1) throw Error('Invalid service transition record.');
+      if (['stopping','preparing'].includes(saved.phase)) {
+        if (!saved.target || await canonical(saved.target.dataDir)!==target.dataDir || await canonical(saved.target.userDir)!==target.userDir) throw Error('A switch was interrupted. Retry from the originally selected installation before choosing another one.');
+        recovery=saved;
+      }
+    } catch(e) { if(e.code!=='ENOENT')throw e; }
+    if (recovery && await targetUnitsPrepared(unitDir,recovery.target)) {
+      // Also recover journals written before the explicit units-prepared checkpoint.
+      await atomicWritePrivate(journalPath,JSON.stringify({version:1,phase:'stopped',target:recovery.target,startupChoice:recovery.startupChoice})+'\n');
+      savedSelection={...recovery,phase:'stopped'};
+      recovery=undefined;
+    }
+    const previous = await installedServiceSelection(unitDir,recovery);
+    if (action === 'status') return operation({previous,switched:false});
+    if (recovery && !['start','restart','activate-setup'].includes(action))
+      throw Error('A service switch is unfinished. Retry agentpay service start before changing startup preferences.');
+    let startupChoice=recovery?.startupChoice || (savedSelection?.target?.dataDir===target.dataDir ? savedSelection.startupChoice : undefined);
+    const different = previous && (previous.dataDir !== target.dataDir || previous.userDir !== target.userDir);
+    if (different) {
+      if (!['start','restart','activate-setup'].includes(action))
+        throw Error('Another installation owns the background services. Run service start from this installation to switch explicitly.');
+      write('\nSwitch AgentPay installation');
+      write('Current data: ' + previous.dataDir);
+      write('Selected data: ' + target.dataDir);
+      write('Wallet and Runtime will stop. Keys, permissions and Order records stay in their own folders.');
+      if (!ask || String(await ask("Type 'confirm' to switch, or 'q' to cancel")).trim().toLowerCase() !== 'confirm') {
+        write('Switch cancelled. Existing services were kept.');
+        return {cancelled:true};
+      }
+      if (!startupChoice) {
+        const states=await Promise.all(units.slice(0,2).map(async name=>String((await ctl('show',name,'--property=UnitFileState','--value')).stdout || '').trim()));
+        if (states.every(s=>s==='enabled')) startupChoice='enabled';
+        else if (states.every(s=>s==='disabled')) startupChoice='disabled';
+      }
+      await atomicWritePrivate(join(state,'active-services.json'),JSON.stringify({version:1,phase:'stopping',previous,target,startupChoice})+'\n');
+      await ctl('stop',...units);
+      // is-active returning nonzero alone is not evidence of a successful stop:
+      // inspect explicit ActiveState values, including failed/inactive only.
+      for (const name of units) {
+        const result = await ctl('show',name,'--property=ActiveState','--value');
+        if (!['inactive','failed'].includes(String(result.stdout || '').trim()))
+          throw Error('Previous services have not stopped. The selected installation was not started.');
+      }
+    }
+    if (different) {
+      const settings = await readServiceSettings(previous.dataDir);
+      if (await listenerPresent(join(previous.dataDir,'wallet/wallet.sock')) ||
+          await listenerPresent({host:'127.0.0.1',port:Number(new URL(settings.runtimeUrl).port)}))
+        throw Error('An original Wallet or Runtime listener is still running. Stop it before switching; no new service was started.');
+    }
+    if (different) {
+      for (const dataDir of new Set([previous.dataDir,target.dataDir])) {
+        const history = await importHistoricalRequests(dataDir);
+        if (history?.unclassified)
+          write('Some older requests need review. Their original files are kept; automatic replacement purchases are blocked.');
+      }
+    }
+    const journal = join(state,'active-services.json');
+    const starts = ['start','restart'].includes(action);
+    const preservesRunning = !different && !recovery && !['stop','remove'].includes(action) &&
+      savedSelection?.phase === 'selected' && savedSelection.target?.dataDir === target.dataDir &&
+      savedSelection.target?.userDir === target.userDir;
+    // Preference-only operations must not revive a stopped default connection.
+    if (starts || different || recovery || ['stop','remove'].includes(action))
+      await atomicWritePrivate(journal,JSON.stringify({version:1,phase:'preparing',previous,target,startupChoice})+'\n');
+    // Reusing data across program installations moves only the client locator.
+    // Consent and stopped-listener checks above must precede this write. On retry
+    // the locator may already point here; unrelated paths still require review.
+    if (different && previous.dataDir === target.dataDir) {
+      await ensureRuntimeConnection({
+        dataDir:target.dataDir, write, refreshClientModule:true,
+        previousClientModule:join(previous.userDir,'src/runtime-client.mjs'),
+      });
+    }
+    // Exact old unit bodies may be replaced only inside this confirmed transition.
+    const unitsPrepared = async () => {
+      if (!await targetUnitsPrepared(unitDir,target))
+        throw Error('Service files are incomplete. Retry agentpay service start from this installation.');
+      // "stopped" closes the default route; it is not a claim about process state.
+      // Persist before invoking systemctl so a crash/timeout still permits repair.
+      await atomicWritePrivate(journal,JSON.stringify({version:1,phase:'stopped',target,startupChoice})+'\n');
+    };
+    const result = await operation({previous, switched:Boolean(different), unitsPrepared});
+    if (starts) {
+      write('Checking Wallet and Runtime readiness…');
+      try { await verifyReady(target.dataDir); }
+      catch (error) {
+        // Unit installation completed. Keep the default closed, but allow repair
+        // or a later start instead of stranding it in a unit-write transition.
+        await atomicWritePrivate(journal,JSON.stringify({version:1,phase:'stopped',target,startupChoice})+'\n');
+        throw error;
+      }
+    }
+    if(action==='enable')startupChoice='enabled';
+    if(action==='disable' || action==='remove')startupChoice='disabled';
+    const phase = starts || preservesRunning ? 'selected' : 'stopped';
+    await atomicWritePrivate(journal,JSON.stringify({version:1,phase,target,startupChoice})+'\n');
+    return result;
+  });
+}
+
+// Uninstall shares the service transition lock. Keep confirmation outside this
+// section, then re-read the selected scope before making destructive changes.
+export async function withServiceLifecycleLock(operation) {
+  return withInstallationOperation(operation);
+}
+
+// Called while holding the installation-operation lock. Maintenance of an inactive
+// program tree must never claim the fixed service pair or rewrite active data.
+export async function maintenanceServiceScope({userDir,dataDir,unitDir}) {
+  const canonical = async path => realpath(path).catch(error=>{if(error.code==='ENOENT')return resolve(path);throw error;});
+  userDir = await canonical(userDir); dataDir = await canonical(dataDir);
+  let saved;
+  try {
+    const path=join(installationDirectory(),'active-services.json');
+    const {assertPrivateFile}=await import('./private-journal-files.mjs');
+    await assertPrivateFile(path); saved=JSON.parse(await readFile(path,'utf8'));
+    if(saved.version!==1)throw Error('Unrecognized service selection. Keep it for review.');
+    if(['stopping','preparing'].includes(saved.phase) && !await targetUnitsPrepared(unitDir,saved.target))
+      throw Error('A service switch is unfinished. Retry service start from its selected installation before maintenance.');
+  } catch(error) {if(error.code!=='ENOENT')throw error;}
+  const owner=await installedServiceSelection(unitDir) || saved?.target;
+  if(!owner)return {active:true}; // Existing single-install setup/repair behavior.
+  if(await canonical(owner.userDir)===userDir && await canonical(owner.dataDir)===dataDir)return {active:true};
+  if(await canonical(owner.userDir)===userDir || await canonical(owner.dataDir)===dataDir)
+    throw Error('Another service selection shares these program or data files. Switch explicitly before repairing or updating this installation.');
+  return {active:false};
+}

package/src/setup-autostart.mjs

@@ -1,3 +1,5 @@
+import { installationDirectory } from "./installation-paths.mjs";
+import { assertPrivateFile } from "./private-journal-files.mjs";
 import { walletCliPath } from "./wallet-package.mjs";
 // SPDX-License-Identifier: MPL-2.0
 // This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
@@ -14,7 +16,6 @@ import {
 } from "./local-services.mjs";
 const execute = promisify(execFile);
 const userDir = fileURLToPath(new URL("..", import.meta.url));
-const walletCli = walletCliPath();
 async function ctl(...args) {
   return execute("systemctl", ["--user", ...args], {
     timeout: 10000,
@@ -83,7 +84,7 @@ async function ownership(dataDir, settings) {
     } catch {}
     const expected =
       role === "wallet"
-        ? [process.execPath, walletCli, "serve", join(dataDir, "wallet")]
+        ? [process.execPath, walletCliPath(), "serve", join(dataDir, "wallet")]
         : [process.execPath, join(userDir, "src/index.mjs")];
     if (
       !(await guideOwnsProcess({
@@ -143,6 +144,15 @@ export async function finishLocalSetup({
       settlementUrl: config.settlementUrl,
     });
     const settings = await readSettings(dataDir);
+    const selectionPath=join(installationDirectory(),'active-services.json');
+    try {
+      await assertPrivateFile(selectionPath);
+      const selection=JSON.parse(await readFile(selectionPath,'utf8'));
+      if (selection.target?.dataDir===dataDir && ['enabled','disabled'].includes(selection.startupChoice)) {
+        settings.startupChoice=selection.startupChoice;
+        await save({dataDir,...settings});
+      }
+    } catch(e) { if(e.code!=='ENOENT')throw e; }
     await available();
     if (!(await owns(dataDir, settings))) {
       write(

package/src/setup-service-selection.mjs

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MPL-2.0
+// Manual setup remains available when the OS has no user service manager.
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { installedServiceSelection } from './service-selection.mjs';
+import {installationChildOptions} from './installation-operation.mjs';
+export async function activateSetup({dataDir, platform=process.platform,
+  available=()=>promisify(execFile)('systemctl',['--user','show-environment'],{timeout:10000}),
+  inspect=installedServiceSelection, write=console.log,
+  launch=()=>new Promise((resolve,reject)=>{
+    const child=spawn(process.execPath,[fileURLToPath(new URL('../scripts/autostart.mjs',import.meta.url)),'activate-setup'],{
+      ...installationChildOptions({stdio:['inherit','inherit','inherit'],env:{...process.env,AGENTPAY_USER_DATA_DIR:dataDir}})
+    });
+    child.once('error',reject);child.once('close',code=>resolve(code ?? 1));
+  })}={}) {
+  let managed=platform==='linux';
+  if (managed) { try {await available();} catch {managed=false;} }
+  if (!managed) {
+    if (await inspect()) throw Error('Existing background service files were found, but the user service manager is unavailable. Restore it before switching installations.');
+    write('User service manager unavailable. Continuing with manual setup; login startup is not enabled.');
+    return 0;
+  }
+  return launch();
+}