@c4roa0/agentpay-user 0.3.7 → 0.3.8

package/progress.md

@@ -1,12 +1,99 @@
 # AgentPay User progress
 
-## User 0.3.7 release preparation — 2026-11-11
+## Real two-installation switch passed — 2026-11-12
+
+Actual user-systemd switching A → B → A passed using source and folder-local npm
+candidate installations with separate data. Cancellation preserved A's process;
+repeated B start preserved its process. B authenticated status passed. Original
+A key/Policy hashes were unchanged, and its existing Orders/Market connection
+remained visible. A is restored with both services running and startup enabled;
+Wallet is locked. Source dependencies now match Wallet 0.3.3 / Protocol 0.14.3;
+old dependencies and inactive B are retained privately. No payment or authorization.
+The initial harness rejected an expected nonzero status for B's unconfigured Wallet;
+corrected full execution passed. This does not establish fresh guided install,
+desktop login/reboot or funded recovery. [Evidence](doc/records/dual-install-systemd-2026-11-12.md).
+
+## Service command recovery — 2026-11-12
+
+Service-manager failure recovery is now stage-aware: complete exact target unit
+files are checkpointed before reload/start/stop, so command failure permits retry
+or repair. Older incomplete journals recover only after all target units match;
+partial/conflicting units remain blocked. Sixteen selection checks passed, including
+actual autostart subprocesses with a controlled systemctl executable. No real
+systemd service or transaction was changed (2026-11-12).
+
+## Sequential review fixes — 2026-11-11
+
+Shared-data installation switching now relocates the client module only after
+switch confirmation and stopped-service/listener checks. It accepts the previous
+managed installation path or the already-relocated current path; unrelated paths
+remain blocked. Retrying `service start` completes interrupted preparation without
+requiring repair first. Keys, authorization and request records are unchanged.
+Twelve selection tests and both connection/preparation test files passed with
+real temporary storage/native locks and simulated service management. Real systemd
+acceptance is still pending.
+
+Default availability now requires authenticated Wallet/Runtime readiness and
+matching running versions; locked Wallets are accepted. Startup preferences and
+preparation preserve existing availability, removal closes it, and readiness failure
+leaves maintenance retryable. Login startup verifies both services under the selection
+lock and checks the selected program/data identity. Transport fixtures and lifecycle
+regressions passed; actual systemd acceptance remains pending.
+
+Installation now stages downloaded settings in memory, confirms activation under
+the shared operation lock, then writes settings and binds the installation. Cancel
+preserves the previous deployment. A private per-user state locator preserves the
+initial XDG location across shells, background services and candidate Skill loaders;
+changing XDG does not create another ownership/maintenance lock namespace.
+Isolated installation, transport, process-lock and update/uninstall regressions passed.
+Next: overall review and real two-install systemd acceptance before release.
+systemd is a Linux backend, not the definition of installation identity.
+macOS background startup remains deferred until a test machine is available.
+
+## Multiple installations, one active Runtime — 2026-11-11
+
+Working-tree implementation now includes canonical installation/data bindings,
+reuse/new/cancel selection, confirmed service switching, single Runtime lifetime
+ownership, default Skill routing and protection for newly recorded request scopes.
+Agent template 0.1.2 / example Skill 1.2.2 remain unpublished candidates; User still
+pins official Skill 1.2.1. Historical request ownership is now indexed during
+confirmed switches; original files and authorization remain unchanged.
+[Design and remaining acceptance](doc/plans/local-instances-and-install-recovery.md).
+
+Installation, update, repair, uninstall, service switching and address maintenance
+now share one operation lock. Inactive update/repair preserves the selected services;
+shared active program/data paths require explicit switching. Short-lived writers and
+administration children inherit the lock, while daemons do not. Recognizable v2 locks
+recover after writers exit; old unknown locks remain blocked for review. Interrupted
+updates retain the confirmed target and finish repair even when npm already installed
+that version. Uninstall rechecks the confirmed scope and supports partial-unit retry.
+
+77 combined targeted checks passed, followed by the marker-publication recovery
+check and its process-lock regressions. These cover process interruption/inheritance, temporary
+storage and controlled npm/service interfaces. A separate offline npm install verified
+Wallet 0.3.3, Protocol 0.14.3 and native-lock loading with hooks disabled. The working
+checkout's older dependencies were not replaced. [Evidence and limits](doc/records/installation-maintenance-2026-11-11.md).
+
+Historical routing now preserves known IDs and refuses missing/conflicting original
+selection. Unclassified older history does not prevent startup, but blocks automatic
+replacement calls from another installation; explicit force remains a new purchase.
+35 focused checks passed with controlled HTTP/service fixtures.
+
+Remaining: complete two-install public-entry and
+real systemd switch/login acceptance; release coordination and participant rehearsal.
+Unknown occupied ports still conservatively block uninstall. No live service, key,
+Policy, Order, payment, migration, commit or publication changed in this loop.
+
+## User 0.3.7 published — 2026-11-11
 
 Patch release includes installed/target Wallet version preview and clearer Cache ID
 help with unique short-ID lookup for read-only details. Wallet remains pinned to
 0.3.3 and Protocol to 0.14.3. Manifest, lockfile and update-pair versions are aligned.
-Publication and registry verification are pending; no local participant service or
-private data is changed by preparing the release.
+393 behavior tests passed from an isolated lockfile installation; standalone npm
+archive installation and process lifecycle passed. Tag v0.3.7 points to source
+3d31297dd3baedbd798f51e86c5fa8a1e474bb4a. GitHub run 42976422954 succeeded;
+public registry SHA-512 matches the tested archive and latest is 0.3.7. No local
+participant service or private data was changed by publication.
 
 
 ## Existing client update accepted — 2026-11-11
@@ -17,7 +104,7 @@ startup/Market connection and retained available result cache were observed.
 Participant confirmed both original Orders remain visible on Market. The older
 missing result predates this update. No new payment or Policy was created.
 [Evidence and limits](doc/records/npm-update-participant-2026-11-11.md). Update-preview and Cache ID guidance fixes are
-verified in source, not yet published. Fresh installation and interrupted-update
+published in 0.3.7. Fresh installation and interrupted-update
 acceptance remain next for discussion; neither has started in this loop.
 
 
@@ -29,7 +116,7 @@ accept a unique prefix with at least eight hexadecimal characters; ambiguous,
 missing or incomplete bounded lookups require a full ID. Export and cleanup keep
 their existing exact-identity rules. All 19 targeted cache/CLI regressions passed
 with isolated process tests outside the restricted sandbox; no live cache changed.
-Source only, pending publication. There is no input: ID namespace: inputs use the
+Included in published 0.3.7. There is no input: ID namespace: inputs use the
 attachment ID shown by list, while results can use result: or runtime-result:0x.
 
 
@@ -40,7 +127,7 @@ from update targets. Wallet is read from the installed dependency, not inferred
 from User's requested dependency. Unchanged versions are explicit; unreadable or
 missing Wallet metadata shows “not confirmed” without blocking the normal repair
 through npm. Controlled update tests cover all three cases and cancellation without
-service/install mutation. This source change is not yet published; running-process
+service/install mutation. Published in 0.3.7; running-process
 versions remain the responsibility of status after update/restart.
 
 

package/scripts/autostart.mjs

@@ -2,8 +2,10 @@
 // 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 { withServiceSelection } from "../src/service-selection.mjs";
+import { createInterface } from "node:readline/promises";
 import { randomUUID } from "node:crypto";
-import { execFileSync } from "node:child_process";
+import {runInstallationCommand,withInstallationOperation} from "../src/installation-operation.mjs";
 import { lstat, mkdir, readFile, writeFile, unlink, rename } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -22,15 +24,17 @@ import {
   saveServiceSettings,
 } from "../src/local-services.mjs";
 import { ensureLocalServices } from "../src/prepare-local-services.mjs";
-const ctl = (...args) =>
-  execFileSync("systemctl", ["--user", ...args], {
-    stdio: "inherit",
-    timeout: 30000,
-  });
+const ctl = async (...args) => {
+  const result = await runInstallationCommand("systemctl", ["--user", ...args], {timeout:30000});
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  return result;
+};
 try {
   const [action, ...args] = process.argv.slice(2);
   if (
     ![
+      "activate-setup",
       "prepare",
       "prepare-repair",
       "enable",
@@ -53,13 +57,21 @@ try {
     );
   const dataDir = await resolveUserDataDir();
   if (action === "configure") {
-    await saveServiceSettings({
+    await withInstallationOperation(() => saveServiceSettings({
       dataDir,
       runtimeUrl: args[0],
       settlementUrl: args[1],
-    });
+    }));
     console.log("Local startup settings saved. No service was started.");
   } else {
+    const selectionResult = await withServiceSelection({
+      target:{node:process.execPath,userDir:installedUserDir,dataDir}, action,
+      ctl:(...args) => runInstallationCommand('systemctl',['--user',...args],{timeout:30000}),
+      ask:process.stdin.isTTY ? async message => {
+        const terminal = createInterface({input:process.stdin,output:process.stdout});
+        try { return await terminal.question(message + '\n> '); } finally { terminal.close(); }
+      } : undefined,
+      operation:async ({previous,switched,unitsPrepared}) => {
     const files = autostartFiles({
       node: process.execPath,
       userDir: installedUserDir,
@@ -68,7 +80,7 @@ try {
     const config = join(homedir(), ".config"),
       unitDir = join(config, "systemd/user");
     for (const directory of [config, join(config, "systemd"), unitDir]) {
-      if (["enable", "prepare", "prepare-repair"].includes(action))
+      if (["enable", "prepare", "prepare-repair", "start", "restart", "activate-setup"].includes(action))
         await mkdir(directory, { mode: 0o700 }).catch((e) => {
           if (e.code !== "EEXIST") throw e;
         });
@@ -96,7 +108,7 @@ try {
           info.isSymbolicLink() ||
           info.uid !== process.getuid() ||
           info.mode & 0o022 ||
-          !isManagedUnit(await readFile(path, "utf8"), name, dataDir)
+          !(isManagedUnit(await readFile(path, "utf8"), name, dataDir) || (switched && previous && autostartFiles(previous)[name] === await readFile(path,"utf8")))
         )
           throw Error(
             "An existing startup file belongs to another configuration. Preserve it and review before switching.",
@@ -106,21 +118,27 @@ try {
       }
     }
     if (action === "status") {
-      ctl("status", "--no-pager", ...runtimeUnits);
+      await ctl("status", "--no-pager", ...runtimeUnits);
       console.log(
         "The login reminder runs once per graphical session; it can be inactive outside a desktop login.",
       );
     } else if (["start", "restart", "stop"].includes(action)) {
-      if (action !== "stop") await readServiceSettings(dataDir);
-      for (const { path } of paths) await lstat(path);
-      ctl(action, ...(action !== "stop" ? runtimeUnits : units));
-      console.log(
-        action !== "stop"
-          ? `${action === "restart" ? "Restart" : "Start"} requested through systemd. This does not confirm readiness.\nNext: agentpay status`
-          : "Stop requested through systemd. Login startup and saved Wallet data are unchanged.\nNext: agentpay status",
+      if (action !== 'stop') {
+      await ensureLocalServices({dataDir});
+      for (const {path,body} of paths) {
+        const temporary = path + '.' + randomUUID();
+        try { await writeFile(temporary,body,{flag:'wx',mode:0o600}); await rename(temporary,path); }
+        finally { await unlink(temporary).catch(e=>{if(e.code!=='ENOENT')throw e;}); }
+      }
+      }
+      await unitsPrepared();
+      if (action !== 'stop') await ctl('daemon-reload');
+      await ctl(action, ...(action !== "stop" ? runtimeUnits : units));
+      if (action === 'stop') console.log(
+        'Stop requested through systemd. Login startup and saved Wallet data are unchanged.\nNext: agentpay status',
       );
-    } else if (["enable", "prepare", "prepare-repair"].includes(action)) {
-      await ensureLocalServices({ dataDir, connectionOptions: action === "prepare-repair" ? { refreshClientModule: true, checkOnly: true } : {} });
+    } else if (["enable", "prepare", "prepare-repair", "activate-setup"].includes(action)) {
+      if (action !== "activate-setup") await ensureLocalServices({ dataDir, connectionOptions: action === "prepare-repair" ? { refreshClientModule: true, checkOnly: true } : {} });
       // No --now: avoid replacing a Wallet currently owned by terminal setup/system services.
       for (const { path, body } of paths)
         try {
@@ -133,9 +151,9 @@ try {
             await rename(temporary,path);
           } finally { await unlink(temporary).catch(e => { if(e.code !== 'ENOENT') throw e; }); }
         }
-      ctl("daemon-reload");
+      await ctl("daemon-reload");
       if (action === "enable") {
-        ctl("enable", ...units);
+        await ctl("enable", ...units);
         await saveServiceSettings({
           dataDir,
           ...(await readServiceSettings(dataDir)),
@@ -150,7 +168,7 @@ try {
         );
     } else if (action === "disable") {
       await readServiceSettings(dataDir);
-      ctl("disable", ...units);
+      await ctl("disable", ...units);
       await saveServiceSettings({
         dataDir,
         ...(await readServiceSettings(dataDir)),
@@ -165,16 +183,21 @@ try {
         ...(await readServiceSettings(dataDir)),
         startupChoice: "disabled",
       });
-      ctl("disable", "--now", ...units);
+      await ctl("disable", "--now", ...units);
       for (const { path } of paths)
         await unlink(path).catch((e) => {
           if (e.code !== "ENOENT") throw e;
         });
-      ctl("daemon-reload");
+      await ctl("daemon-reload");
       console.log(
         "Automatic startup and its reminder removed. Wallet data, Policy and request history are kept.",
       );
     }
+      }});
+    if (selectionResult?.cancelled) process.exitCode = 2;
+    else if (['start','restart'].includes(action)) console.log(
+      'Wallet and Runtime are ready. Default Skill access is available.\nNext: agentpay status',
+    );
   }
 } catch (error) {
   console.error(
@@ -182,5 +205,8 @@ try {
       ? error.message
       : "The systemd command failed; some service changes may already have applied. Wallet keys and request history were kept. Run agentpay status before retrying.",
   );
+  if (process.argv[2] === 'stop') console.error('Retry: agentpay service stop');
+  else if (['start','restart'].includes(process.argv[2]))
+    console.error('Check: agentpay status\nRetry: agentpay service start');
   process.exitCode = 1;
 }

package/scripts/install-user.mjs

@@ -3,7 +3,8 @@
 // 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 { fileURLToPath } from "node:url";
-import { resolveUserDataDir } from "../src/local-data-directory.mjs";
+import { selectInstallationData } from "../src/install-selection.mjs";
+import { createInterface } from "node:readline/promises";
 import { installAndSetup } from "../src/install-and-setup.mjs";
 try {
   const args = process.argv.slice(2);
@@ -13,10 +14,16 @@ try {
     throw Error(
       "Run Install in an interactive terminal so setup can continue.",
     );
-  process.exitCode = await installAndSetup({
+  const userDir = fileURLToPath(new URL("..", import.meta.url));
+  const terminal = createInterface({input:process.stdin,output:process.stdout});
+  let selection;
+  try { selection = await selectInstallationData({userDir,ask:message=>terminal.question(message+'\n> ')}); }
+  finally { terminal.close(); }
+  if (!selection) console.log('Installation cancelled. Existing services were kept.');
+  else process.exitCode = await installAndSetup({
     userDir: fileURLToPath(new URL("..", import.meta.url)),
     market: args[1],
-    dataDir: await resolveUserDataDir(),
+    dataDir: selection.dataDir,
   });
 } catch (error) {
   if (!error.messageDisplayed) console.error(error.message);

package/scripts/local-service.mjs

@@ -31,7 +31,7 @@ try {
       ? walletCliPath()
       : join(userDir, "src/index.mjs");
   const env = Object.fromEntries(
-    ["HOME", "PATH", "LANG", "LC_ALL", "TZ", "TMPDIR"]
+    ["HOME", "PATH", "LANG", "LC_ALL", "TZ", "TMPDIR", "XDG_STATE_HOME"]
       .filter((k) => process.env[k])
       .map((k) => [k, process.env[k]]),
   );

package/scripts/user-setup.mjs

@@ -28,6 +28,10 @@ try {
       "../src/local-data-directory.mjs"
     );
     const { runGuidedEntry } = await import("../src/guided-setup.mjs");
+    const dataDir = await resolveUserDataDir({argument:args[1]});
+    const { activateSetup } = await import('../src/setup-service-selection.mjs');
+    const activation = await activateSetup({dataDir});
+    if (activation) process.exit(activation);
     process.exit(
       await runGuidedEntry({
         userDir: fileURLToPath(new URL("..", import.meta.url)),

package/src/default-request-owner.mjs

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: MPL-2.0
+// A local routing index, not payment authority. Preserve old records in place;
+// only service/input hashes and originating data folders enter this index.
+import {constants} from 'node:fs';
+import {mkdir,open,readdir,lstat,realpath} from 'node:fs/promises';
+import {join,resolve,isAbsolute} from 'node:path';
+import {createHash} from 'node:crypto';
+import {hashPrivateRequest} from '@c4roa0/agentpay-protocol';
+import {installationDirectory} from './installation-paths.mjs';
+import {atomicWritePrivate} from './private-journal-files.mjs';
+import {withInstallationOperation} from './installation-operation.mjs';
+import {hashInvocationKey} from './invocation-store.mjs';
+import {parseServiceReference} from './service-reference.mjs';
+
+const digest = value => createHash('sha256').update(value).digest('hex');
+const scopeKey = (service,requestHash) => digest(JSON.stringify([service.skillId,service.profileHash,requestHash]));
+const codeError = (code,message) => Object.assign(Error(message),{code});
+const requestIdPattern = /^[A-Za-z0-9._:-]{16,128}$/;
+const review = () => codeError('REQUEST_HISTORY_REVIEW_REQUIRED','Original request history could not be identified safely. Keep the old data folder and inspect agentpay orders list; no replacement purchase was started.');
+const canonical = path => realpath(path).catch(error=>{if(error.code==='ENOENT')return resolve(path);throw error;});
+async function privateDirectory(path) {
+  try {
+    const info=await lstat(path);
+    if(!info.isDirectory() || info.isSymbolicLink() || info.uid!==process.getuid() || info.mode & 0o077)throw review();
+    return true;
+  }catch(error){if(error.code==='ENOENT')return false;throw error;}
+}
+async function json(path,max=2*1048576) {
+  let file;
+  try {
+    file=await open(path,constants.O_RDONLY|constants.O_NOFOLLOW);
+    const info=await file.stat();
+    if(!info.isFile() || info.uid!==process.getuid() || info.mode & 0o077 || info.size>max)throw review();
+    const value=JSON.parse(await file.readFile('utf8'));
+    if(value===null)throw review();
+    return value;
+  }catch(error){if(error.code==='ENOENT')return null;throw review();}
+  finally{await file?.close();}
+}
+async function indexDirectory() {
+  const directory=join(installationDirectory(),'request-owners');
+  await mkdir(directory,{recursive:true,mode:0o700});await privateDirectory(directory);
+  return directory;
+}
+function validOwner(saved) {
+  if(saved && (saved.version!==1 || typeof saved.dataDir!=='string' || !isAbsolute(saved.dataDir) ||
+    (saved.requestIds!==undefined && (!Array.isArray(saved.requestIds) || saved.requestIds.some(id=>!requestIdPattern.test(id)))) ||
+    (saved.conflicts!==undefined && (!Array.isArray(saved.conflicts) || saved.conflicts.some(path=>typeof path!=='string' || !isAbsolute(path))))))throw review();
+}
+async function recordHistory(directory,key,dataDir,requestIds=[]) {
+  const path=join(directory,key+'.json'),saved=await json(path,32768);validOwner(saved);
+  // Explicit force is a deliberate later purchase, not a migration decision.
+  if(saved?.deliberate && saved.dataDir!==dataDir)return;
+  if(saved?.dataDir===dataDir) {
+    const ids=[...new Set([...(saved.requestIds || []),...requestIds])];
+    if(ids.length)await atomicWritePrivate(path,JSON.stringify({...saved,requestIds:ids})+'\n');
+    return;
+  }
+  const conflicts=saved ? [...new Set([...(saved.conflicts || []),saved.dataDir,dataDir])] : undefined;
+  await atomicWritePrivate(path,JSON.stringify(saved ? {...saved,conflicts} : {version:1,dataDir,...(requestIds.length?{requestIds}: {})})+'\n');
+}
+
+// Called with services stopped during a confirmed switch. Scan only these known
+// private stores, once per switch, never arbitrary folders or remote services.
+export async function importHistoricalRequests(dataDir) {
+  return withInstallationOperation(async()=>{
+    dataDir=await canonical(dataDir);
+    try { return await scanHistoricalRequests(dataDir); }
+    catch {
+      // Incomplete old history must not prevent Runtime startup. Retain a
+      // conservative routing barrier; never turn unreadable records into new calls.
+      const directory=await indexDirectory();
+      await recordHistory(directory,'unclassified',dataDir);
+      return {indexed:0,unclassified:true,reviewRequired:true};
+    }
+  });
+}
+async function scanHistoricalRequests(dataDir) {
+    if(!await privateDirectory(dataDir))return;
+    const runtime=join(dataDir,'runtime');if(!await privateDirectory(runtime))return;
+    const directory=await indexDirectory(),keys=new Map(),clientRequests=new Map();
+    let bytes=0,count=0;
+    for(const kind of ['client-requests','client-pending']) {
+      const parent=join(runtime,kind);if(!await privateDirectory(parent))continue;
+      const names=await readdir(parent);
+      if(names.length>20000 || (kind==='client-pending' && names.some(name=>name.endsWith('.lock'))))throw review();
+      for(const name of names) {
+        if(!/^[a-f0-9]{64}\.json$/.test(name))continue;
+        const path=join(parent,name),info=await lstat(path);bytes+=info.size;
+        if(++count>20000 || bytes>64*1048576)throw review();
+        const saved=await json(path);if(!saved)throw review();
+        let service,input,ids;
+        if(kind==='client-requests') {
+          if(saved.version!=='agentpay.runtime-client-request.v1' || !requestIdPattern.test(saved.requestId || ''))throw review();
+          service=parseServiceReference(saved.service);input=saved.input?.request;ids=[saved.requestId];
+          clientRequests.set(hashInvocationKey(saved.requestId),{requestHash:hashPrivateRequest(saved.preparedRequest===undefined ? input : saved.preparedRequest),serviceKey:scopeKey(service,hashPrivateRequest(saved.preparedRequest===undefined ? input : saved.preparedRequest))});
+        }else {
+          if(!['agentpay.runtime-client-pending.v1','agentpay.runtime-client-pending.v2'].includes(saved.version) || !saved.binding?.service)throw review();
+          // Pending records intentionally omit the business adapter. The full
+          // checkpoint remains the authority for resume; only scope IDs are used here.
+          service=saved.binding.service;input=saved.binding.input;
+          if(!Array.isArray(saved.pending))throw review();
+          ids=[...saved.pending,...(saved.currentId ? [saved.currentId]:[])];
+          if(ids.some(id=>!requestIdPattern.test(id)))throw review();
+          if(!/^0x[a-fA-F0-9]{64}$/.test(service.skillId || '') || !/^0x[a-fA-F0-9]{64}$/.test(service.profileHash || ''))throw review();
+        }
+        const key=scopeKey(service,hashPrivateRequest(input));
+        keys.set(key,[...new Set([...(keys.get(key) || []),...ids])]);
+      }
+    }
+    const history=await json(join(runtime,'invocations.json'),32*1048576);
+    let unclassified=false;
+    if(history) {
+      if(history.version!=='agentpay.user-invocations.v1' || !history.invocations || typeof history.invocations!=='object' || Array.isArray(history.invocations))throw review();
+      for(const [id,entry] of Object.entries(history.invocations)) {
+        if(!/^0x[a-f0-9]{64}$/.test(entry?.requestHash || '') || entry.invocationId!==id)throw review();
+        // Runtime-only records cannot prove the caller's original input (a Skill
+        // may prepare/upload files first). Do not guess a cross-installation match.
+        const client=clientRequests.get(id);
+        let linked=false;
+        if(client && client.requestHash===entry.requestHash) {
+          try {
+            const binding=JSON.parse(entry.serviceBinding);
+            linked=binding.version==='agentpay.runtime-service.v1' &&
+              scopeKey(parseServiceReference(binding.reference),entry.requestHash)===client.serviceKey;
+          }catch { /* Old or incomplete service identity stays unclassified. */ }
+        }
+        if(!linked)unclassified=true;
+      }
+    }
+    for(const [key,ids] of keys)await recordHistory(directory,key,dataDir,ids);
+    if(unclassified)await recordHistory(directory,'unclassified',dataDir);
+    return {indexed:keys.size,unclassified};
+}
+
+// Keep ownership selection and local request creation in one maintenance section.
+// Network/payment calls run after it, always against the pinned original connection.
+export async function withDefaultRequest({service,input,dataDir,force=false},operation) {
+  return withInstallationOperation(async()=>{
+    dataDir=await canonical(dataDir);
+    const directory=await indexDirectory();
+    const path=join(directory,scopeKey(service,hashPrivateRequest(input.request))+'.json');
+    const saved=await json(path,32768);validOwner(saved);
+    const unknown=await json(join(directory,'unclassified.json'),32768);validOwner(unknown);
+    if(!force && !(saved?.deliberate && saved.dataDir===dataDir) && (unknown?.conflicts || (unknown && unknown.dataDir!==dataDir)))
+      throw codeError('REQUEST_HISTORY_REVIEW_REQUIRED','Another installation has older requests whose original input cannot be identified. Review them in the original installation. Use --force only if you deliberately want a new purchase.');
+    if(!force && saved?.conflicts)
+      throw codeError('ORIGINAL_REQUEST_AMBIGUOUS','Several local installations contain this request. Return to the intended installation and use --resume with its saved request ID. No new purchase was started.');
+    if(!force && saved && saved.dataDir!==dataDir)
+      throw codeError('ORIGINAL_INSTALLATION_REQUIRED','This input was used by another local Wallet. Return to that installation to recover it. Use --force only for a deliberate new purchase.');
+    const next = !saved || force ? {version:1,dataDir,...(force?{deliberate:true}:{})} : saved;
+    if(!saved || force)await atomicWritePrivate(path,JSON.stringify(next)+'\n');
+    const result = await operation(!force ? next.requestIds : undefined);
+    if(result?.requestId) {
+      if(!requestIdPattern.test(result.requestId))throw review();
+      await atomicWritePrivate(path,JSON.stringify({...next,requestIds:[...new Set([...(next.requestIds || []),result.requestId])]})+'\n');
+    }
+    return result;
+  });
+}
+export async function claimDefaultRequest(options) {
+  return withDefaultRequest(options,async()=>{});
+}

package/src/index.mjs

@@ -1,3 +1,5 @@
+import { publishRuntimeReady } from "./runtime-selection-ready.mjs";
+import { acquireRuntimeOwner } from "./runtime-owner.mjs";
 import { runtimeSoftware } from "./software-versions.mjs";
 // Authenticated local invocation engine. Preserve durable request/payment checkpoints before
 // network calls; startup reconciliation observes history without creating replacement purchases.
@@ -15,6 +17,7 @@ import {
 import { serviceUrl } from "./service-url.mjs";
 import { createRuntimeRecovery } from "./runtime-recovery.mjs";
 import { constants } from "node:fs";
+import { dirname } from "node:path";
 import { open } from "node:fs/promises";
 import { assertOrderCanContinue } from "./order-closure.mjs";
 import { invocationResults } from "./invocation-result.mjs";
@@ -37,6 +40,9 @@ import { fetchJsonWithTimeout } from "./transport.mjs";
 import { readFinalizationDisclosure } from "./finalization-disclosure.mjs";
 import { walletIpcError } from "./wallet-ipc-error.mjs";
 
+// Retain the FileHandle for the entire server lifetime; process exit releases it.
+const runtimeOwner = await acquireRuntimeOwner();
+process.once('exit', () => { void runtimeOwner; });
 const host = String(process.env.AGENTPAY_USER_HOST || "127.0.0.1").trim();
 if (!["127.0.0.1", "localhost", "::1"].includes(host))
   throw Error("User Runtime must listen on loopback");
@@ -785,6 +791,9 @@ const server = createServer(async (req, res) => {
 });
 
 server.listen(port, host, () => {
+  void publishRuntimeReady(dirname(dirname(callerCredentialFile))).catch(error=>{
+    console.error('Default Runtime connection could not be refreshed:',error.message);
+  });
   process.stdout.write(
     `${JSON.stringify({
       ready: true,

package/src/install-and-setup.mjs

@@ -5,6 +5,7 @@ import { rememberUserDataDir } from "./local-data-directory.mjs";
 import { spawn } from "node:child_process";
 import { join } from "node:path";
 import { runInstall } from "./install-user.mjs";
+import { activateSetup } from './setup-service-selection.mjs';
 
 export async function installAndSetup({
   userDir,
@@ -13,9 +14,13 @@ export async function installAndSetup({
   install = runInstall,
   start = startGuide,
   remember = rememberUserDataDir,
+  activate = activateSetup,
   write = console.log,
 }) {
-  const result = await install({ userDir, market, dataDir, write });
+  const result = await install({ userDir, market, dataDir, write,
+    beforeApplySettings: () => activate({dataDir,write}),
+  });
+  if (result?.cancelled) return result.exitCode;
   if (!result?.completed)
     throw Error(
       "Installation did not complete. Run the same Install command to resume.",

package/src/install-selection.mjs

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MPL-2.0
+// Choose storage before dependencies or services are changed. Selection itself
+// never creates a Wallet, copies a key, or activates another installation.
+import { lstat, mkdir } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { readInstallationBinding } from './installation-binding.mjs';
+import { resolveUserDataDir } from './local-data-directory.mjs';
+
+export async function selectInstallationData({userDir, ask, write = console.log, env = process.env}) {
+  const binding = await readInstallationBinding(userDir);
+  if (binding) {
+    if (env.AGENTPAY_USER_DATA_DIR && resolve(env.AGENTPAY_USER_DATA_DIR) !== binding.dataDir)
+      throw Error('This installation already uses another data folder. Remove the conflicting AGENTPAY_USER_DATA_DIR setting before installing.');
+    return {dataDir:binding.dataDir, requiresActivation:true};
+  }
+  const existing = await resolveUserDataDir({userDir, env});
+  const info = await lstat(existing).catch(e => { if (e.code === 'ENOENT') return null; throw e; });
+  if (!info) return {dataDir:existing, requiresActivation:true};
+  if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || info.mode & 0o077)
+    throw Error('The existing User data folder needs ownership and permission review. No installation was changed.');
+  write('\nExisting AgentPay data');
+  write(existing);
+  write('Use it to keep your Wallet and Orders, or create separate data for this installation.');
+  while (true) {
+    const choice = String(await ask("Enter 'reuse', 'new', or 'q' to cancel")).trim().toLowerCase();
+    if (choice === 'q') return null;
+    if (choice === 'reuse') {
+      // Activation belongs to the serialized service-switch flow, not storage choice.
+      write('Existing Wallet and Order data will be kept. This does not switch running services.');
+      return {dataDir:existing, requiresActivation:true, selection:'reuse'};
+    }
+    if (choice === 'new') {
+      const dataDir = join(dirname(existing), 'user-' + randomUUID());
+      await mkdir(dataDir, {mode:0o700});
+      write('Separate data folder: ' + dataDir);
+      return {dataDir, requiresActivation:true, selection:'new'};
+    }
+    write("Choose 'reuse' to keep the existing data, 'new' for a separate Wallet setup, or 'q'.");
+  }
+}