@c4roa0/agentpay-user 0.3.6 → 0.3.8

package/progress.md

@@ -1,20 +1,150 @@
 # AgentPay User progress
 
-## User 0.3.6 release candidate — 2026-11-10
+## 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.
+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
+
+Participant directory-local npm update to User 0.3.6 / Wallet 0.3.3 completed.
+Running versions, unlocked Wallet, two settled Orders, unchanged saved validity,
+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
+published in 0.3.7. Fresh installation and interrupted-update
+acceptance remain next for discussion; neither has started in this loop.
+
+
+## Cache details guidance — 2026-11-11
+
+Missing details IDs now show a short example before accessing local storage.
+List guidance explains that the namespace is part of the ID. Read-only details
+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.
+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.
+
+
+## Update preview clarity — 2026-11-11
+
+The confirmation screen now lists installed User and Wallet versions separately
+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. Published in 0.3.7; running-process
+versions remain the responsibility of status after update/restart.
+
+
+## User 0.3.6 published — 2026-11-10
 
 Pins published Wallet 0.3.3, retaining Protocol 0.14.3. Maintenance errors provide
 same-request guidance without automatic write retries. Package manifest, lockfile
-and update-pair metadata agree. Publication uses the matching v0.3.6 tag after
-independent installation and behavior checks; completion is not implied by this
-candidate record. No local data, Policy or service changes occur on publication.
+and update-pair metadata agree. Published through matching tag v0.3.6 after 391 behavior tests and independent
+installation/lifecycle checks. Public npm metadata and SHA-512 match the verified
+archive. No local data, Policy or service changes occur on publication.
 
 
 ## Maintenance guidance — 2026-11-10
 
 Added explicit maintenance guidance without automatic write retries or replacement
 purchases. Controlled HTTP/IPC tests verify that retry retains original request
-identifiers. This is source verification, not live financial acceptance. Changes
-have not been published to npm.
+identifiers. This is source verification, not live financial acceptance. These changes were subsequently published in 0.3.6; see the release record above.
 
 
 ## Acceptance bookkeeping — 2026-11-10

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/cache-management-cli.mjs

@@ -128,6 +128,11 @@ export async function runCacheManagement(
     }
   const usage =
     "Usage: agentpay cache [info | list [PAGE] [input|output] [--state STATE] [--request ID | --order ID] | details ID | export ID PATH | clean | settings [KEY VALUE]]\nAdd --offline only when managing stopped Runtime storage. Wallet unlock is not required.";
+  if(action === "details" && rest.length === 0){
+    write("Choose a Cache ID from agentpay cache list. Copy the whole ID, including any prefix such as result:.");
+    write("Example: agentpay cache details result:5aa18b50\nA unique short ID needs at least 8 hexadecimal characters.");
+    return 2;
+  }
   if (
     invalidFilter ||
     !["summary", "list", "details", "export", "clean", "settings"].includes(
@@ -192,7 +197,7 @@ export async function runCacheManagement(
           ...(rest[1] ? { purpose: rest[1] } : {}),
         });
       write(
-        `\n${r.total} entries · page ${page}\nDetails: agentpay cache details <Cache ID>`,
+        `\n${r.total} entries · page ${page}\nDetails: agentpay cache details <Cache ID>\nCopy the full ID including its prefix, or use a unique short ID (8+ hex characters).`,
       );
       if (!r.items.length)
         write("No saved results or attachments match this view.");
@@ -222,7 +227,32 @@ export async function runCacheManagement(
             .join("")}`,
         );
     } else if (action === "details") {
-      const r = await operate({ action, id: rest[0] });
+      let id=rest[0];
+      if(!/^(?:result:|runtime-result:0x)?[0-9a-f]{64}$/.test(id)){
+        if(!/^(?:result:|runtime-result:0x)?[0-9a-f]{8,63}$/.test(id)){
+          write('Use the Cache ID from agentpay cache list, or its first 8 or more hexadecimal characters.');
+          return 2;
+        }
+        // Resolve only read-only details. Bound enumeration; never guess from an
+        // incomplete list or turn a short display identifier into a cleanup key.
+        const matches=new Set();let offset=0,total;
+        do {
+          const page=await operate({action:'list',offset,limit:100});
+          if(page.total>1000 || total!==undefined&&page.total!==total || !page.items.length&&offset<page.total){
+            write('Use the full Cache ID; the cache is too large or changed during lookup.');return 2;
+          }
+          total=page.total;
+          for(const row of page.items){
+            const key=id.includes(':')?row.id:row.id.replace(/^(?:result:|runtime-result:0x)/,'');
+            if(key.startsWith(id))matches.add(row.id);
+          }
+          if(matches.size>1){write('More than one cache entry matches. Copy a longer or full Cache ID from agentpay cache list.');return 2;}
+          offset+=page.items.length;
+        }while(offset<total);
+        if(!matches.size){write('No cache entry matches. Run agentpay cache list and copy its Cache ID.');return 2;}
+        id=[...matches][0];
+      }
+      const r = await operate({ action, id });
       write(
         `${safe(r.filename)}\n  ${contentSize(r)} · ${r.state}\n  ${r.requestId ? "Request" : "Order"}: ${safe(r.requestId || r.orderId)}\n  File key: ${safe(r.fileKey)}\n  SHA-256: ${r.sha256 || "Not available"}\n  Updated: ${new Date(r.updatedAtMs).toLocaleString()}`,
       );

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.",