@c4roa0/agentpay-user 0.3.2 → 0.3.4

package/README.md

@@ -33,6 +33,24 @@ normally live in `~/.local/share/agentpay/user`; an existing custom data directo
 is retained. Installation checkpoints use `~/.local/state/agentpay/user` (or
 `$XDG_STATE_HOME/agentpay/user`). Upgrading program files does not erase either.
 
+## Install in a folder instead
+
+For a directory-owned installation, choose a program folder:
+
+```sh
+mkdir agentpay-local
+cd agentpay-local
+npm install @c4roa0/agentpay-user
+./node_modules/.bin/agentpay help
+```
+
+Use `./node_modules/.bin/agentpay` instead of `agentpay` in the commands below.
+`update` updates this installation and its project lockfile; it does not install
+User globally. For an existing Wallet, use `repair` to refresh the background
+services against this installation. Private data stays in its existing directory.
+Before deleting the program folder, run `uninstall` to remove managed services;
+private data is kept unless you explicitly choose `--delete-data`.
+
 ## After setup
 
 ```sh
@@ -44,7 +62,7 @@ agentpay market connect
 
 Linux background services use your systemd user session. Wallet starts locked after
 a restart. `agentpay service help` explains startup, stop and logs; `agentpay help` lists
-all groups. Global npm installations use `agentpay update` to review and install a
+all groups. npm installations use `agentpay update` to review and install a
 new User version with its matching Wallet and official test Skill. Source checkouts
 update their files, run `npm ci`, then `agentpay repair`. [Commands](doc/runbooks/commands.md) · [Updates](doc/runbooks/local-update.md)
 · [Backup and restore](doc/runbooks/wallet-identity.md).

package/doc/README.md

@@ -1,5 +1,7 @@
 # User documentation
 
+- [Directory npm update verification](records/local-npm-update-2026-11-08.md): real package update and preflight boundary.
+
 ## Start by role
 
 | Reader | Start here |

package/doc/TODO.md

@@ -1,10 +1,25 @@
 # User TODO
 
+## Existing Market address update
+
+- [x] Reauthenticate and verify original account, Wallet tuple and Policy connection before replacing an address.
+- [x] Verify unchanged deployment; preserve RPC, key, Policy, history/cache and original cancellation IDs.
+- [x] Apply under installer lock, restart managed Runtime, retain retry marker and show incomplete update in status.
+- [x] Full regression (387 checks), followed by targeted reconnect-boundary/transaction checks.
+- [ ] Publish a reviewed version and verify the existing participant installation against HTTPS.
+
+## Directory npm update, then HTTPS
+
+- [x] Support directory-local npm update without replacing source/link installs.
+- [x] Verify real npm directory upgrade and isolated preflight; nine regression checks passed.
+- [x] Publish 0.3.3 via v0.3.3 and independently verify registry archive/dependency pins.
+- [ ] Verify participant directory install/update.
+
 ## Tag-triggered publication
 
 - [x] Use matching `vX.Y.Z` tags for npm publication; retain verification gates.
 - [x] Owner confirmed release tags allowed in the GitHub `npm-publish` environment.
-- [ ] Verify the first tag-triggered OIDC publication and registry integrity.
+- [x] Verify first tag-triggered OIDC run 42491753287 and registry archive integrity.
 
 ## Official package 1.2.1 — 2026-11-08
 
@@ -13,7 +28,8 @@
 - [x] Load the reviewed User source update and run the normal 1.2.1 payment test with explicit user consent; terminal delivery/result/ack completed.
 - [x] Verify website visibility and independently reconcile Settlement/chain outcome; prepare User 0.3.2 candidate.
 - [x] Pin the verified public Wallet 0.3.2; align package/lockfile/update-pair.
-- [ ] Publish User 0.3.2 through OIDC and verify registry artifact; then accept a real npm update.
+- [x] Publish User 0.3.2 through tag-triggered OIDC; verify public registry archive.
+- [ ] Accept a real participant npm update/restart.
 
 
 ## Fixed Skill download loop — 2026-11-08

package/doc/architecture.md

@@ -30,6 +30,7 @@ name change. Independent-version compatibility remains a separate planned featur
 | Area | Main files | Responsibility |
 | --- | --- | --- |
 | CLI | `run`, `scripts/agentpay-cli.mjs`, `src/user-cli.mjs` | Node discovery, grouped commands and help |
+| npm update | `npm-update.mjs` | Detect global/direct-project installation, isolate npm preflight, pin the reviewed release and repair services without changing private data |
 | Install / repair | `install-user.mjs`, `install-and-setup.mjs`, `install-preflight.mjs`, `local-update.mjs` | Dependency/build preparation, checkpoints, downloaded settings and safe restart |
 | Setup | `guided-setup.mjs`, `user-setup-guide.mjs`, `anvil-onboarding.mjs` | Terminal sequence and saved-step continuation; explicit signer mode |
 | Permission | `policy-terminal-guide.mjs`, `safe-policy-plan.mjs`, `renew-policy.mjs`, `policy-operations.mjs`, `policy-migration.mjs` | Drafts, approved operations and verified local binding |
@@ -97,3 +98,20 @@ required for the local test suite.
 Tests use public interfaces and controlled remote responses. The explicit fault
 loader only instruments a spawned test Runtime; production startup contains no
 crash-test switch. See [test guide](https://github.com/c4rO-0/agentpay-user/blob/main/test/README.md) for evidence limits.
+
+## Explicit platform address changes
+
+`connect-market.mjs` reauthenticates at the user-selected origin and checks the
+original account, Wallet tuple and exact Policy connection ID. Public configuration
+is not a Market identity proof. `platform-endpoints.mjs` compares saved deployment
+and bound Policy with the new configuration, probes Settlement's existing public
+readiness projection, then changes only transport URLs after consent. No new API
+or platform identity key is introduced.
+
+The shared installer lock serializes the local apply step. Only the managed Runtime
+unit is stopped; its listener must be gone before writes. Private atomic files and
+a pending marker allow retry after interruption. Wallet and Order files are never
+rewritten. `settlement-address-history.mjs` preserves exact directed, Policy-scoped
+address mappings so cancellation retries retain their immutable original IDs.
+Runtime recovery observations remain tagged by source and are rechecked instead of
+being relabelled. The pending marker is surfaced by status.

package/doc/records/local-npm-update-2026-11-08.md

@@ -0,0 +1,32 @@
+# Directory npm update verification — 2026-11-08
+
+The updater accepts a direct registry dependency in a project installation as well
+as a global installation. The owning folder comes from the running package, not
+the terminal working directory. Source/link, custom-source and transitive installs
+remain outside automatic updates. Confirmation, exact release pinning, private-data
+retention and the existing service repair flow remain in effect.
+
+Nine controlled regression checks passed, covering global/local update, cancellation,
+forced confirmation, failures, concurrent changes and unsupported install layouts.
+A real-npm check installed public User 0.3.1 into a temporary project, ran the changed
+updater against public 0.3.2 and verified program, manifest and lockfile versions.
+Private-record fixture bytes were preserved. Service stop/repair hooks were controlled;
+this is not participant process recovery or paid acceptance.
+
+npm 10.9.8 dry-run changed node_modules/.package-lock.json without replacing program
+files. The subsequent install could report up to date while leaving old code.
+Lock-related flags did not reliably prevent this. Preflight now uses a disposable
+prefix with privately copied project npm settings for consistent registry selection,
+removed afterward. The real check confirms the existing hidden lockfile stays on
+the old version after preflight. No participant keys, services or payments were used.
+
+Follow-up publication and participant directory-update acceptance remain pending.
+
+User 0.3.3 release preparation (2026-11-09): all 383 behavior checks and standalone
+archive installation with isolated Wallet/Runtime process checks passed. Wallet
+0.3.2, Protocol 0.14.3 and official package pin are unchanged. Publication and
+participant acceptance remain separate gates.
+
+Publication verified on 2026-11-09: tag v0.3.3 at c5f3be1, GitHub run
+42567636609. Public npm archive matches the final local release archive byte for
+byte; provenance metadata is present. Participant acceptance remains pending.

package/doc/runbooks/commands.md

@@ -2,7 +2,8 @@
 
 Use `agentpay` after installing the package or linking a source checkout with
 `npm link`. From a source folder, `./run` is the same entry; it uses Node on PATH
-or `AGENTPAY_NODE`.
+or `AGENTPAY_NODE`. For a folder-local npm install, use
+`./node_modules/.bin/agentpay`; its `update` stays in that installation folder.
 
 ```sh
 agentpay help

package/doc/runbooks/local-update.md

@@ -8,18 +8,35 @@ For a global npm installation:
 agentpay update
 ```
 
+For an npm installation inside a project folder, run its own command:
+
+```sh
+./node_modules/.bin/agentpay update
+```
+
+Directory-local update support starts with User 0.3.3. For an older directory
+installation, run `npm install --save-exact @c4roa0/agentpay-user@0.3.3` in its
+original program folder, then `./node_modules/.bin/agentpay repair`. Future versions
+can be installed with the command above. Keep your private data directory.
+
+Both forms update the installation that owns the command, regardless of the
+terminal's working directory. Directory installs update their direct User dependency
+and package lockfile in that folder, with an exact version; global installs keep
+their global prefix. The confirmation shows the target folder. User must be a direct
+registry dependency, not a transitive dependency or a linked/custom-source package.
+
 It checks the published User version and shows its exact Wallet dependency. Confirm
 to continue, or cancel without changing services. `agentpay update -f` skips only
-this confirmation. The updater checks requirements, stops configured services,
+this confirmation. The updater checks requirements in a temporary installation directory, stops configured services,
 installs the confirmed version and invokes the new version's repair to refresh
 services and verify its pinned official test Skill. No paid test runs automatically.
 Other installed Skills and original requests are kept. Wallet needs unlocking after
 restart. A current User version still checks the official test Skill.
 
-Only genuine global npm installations are updated. A source checkout or `npm link`
+Only genuine npm installations are updated. A source checkout or `npm link`
 is refused rather than overwritten: update User's files, run `npm ci`, then
-`agentpay repair`. The first User 0.3.0 release establishes the package baseline; a later real
-registry upgrade still needs participant acceptance. The updater uses npm's configured registry, checks
+`agentpay repair`. Directory update has controlled real-npm verification; participant upgrade acceptance
+remains separate. The updater uses npm's configured registry, checks
 Node engine requirements and disables package installation hooks; releases must
 ship usable runtime artifacts. It never independently selects the newest Wallet.
 

package/doc/runbooks/market-connection.md

@@ -16,6 +16,39 @@ Review the account and nickname, then type `confirm`. Use `details` to inspect t
 Safe, network and Policy. Open Market → Account to view your Wallets and Orders.
 A separate browser login may be needed; terminal sign-in does not create browser cookies.
 
+## Change the address of the same Market
+
+In a version containing the address-update feature, run:
+
+```sh
+agentpay market connect --market https://YOUR_NEW_MARKET_ADDRESS
+```
+
+For a folder installation, use `./node_modules/.bin/agentpay` instead of `agentpay`.
+Sign in again at the address you trust. User checks that the account ID and the
+original Wallet/Policy connection are still present. The existing nickname is
+reused. It also checks the network, contracts and Settlement deployment before
+showing the new platform addresses for confirmation.
+
+Confirm to update the saved Market address and, if changed, the Settlement and
+package download addresses. Runtime pauses briefly and restarts; Wallet remains
+unlocked. Keys, Policy, Orders, input/output caches, startup preference and the
+participant's RPC address stay unchanged. No paid test runs automatically.
+
+A different account, missing original connection or changed contracts stops the
+address update. This is a deliberate address change, not automatic discovery or
+cryptographic proof of server identity. Check the website address yourself; the
+terminal never forwards a previously saved login token to the new address.
+
+If interrupted, repeat the same command with the same address. `status` reports
+an incomplete update until it finishes. If a killed process leaves an installation
+lock, confirm no installer is running before following the lock-review guidance;
+User does not break an unknown live lock automatically. Existing cancellation requests keep their
+original IDs; recovery checks refresh observations from the new Settlement.
+Keep any old SSH tunnels until the update succeeds and `status` confirms operation.
+This feature requires User 0.3.4 or newer. Updating software does not change
+your saved addresses; run the command above to review the change.
+
 ## Wallet identity and Policy access
 
 A Wallet is identified by network + Module + Safe + execution address. Its nickname

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4roa0/agentpay-user",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "type": "module",
   "dependencies": {
     "@c4roa0/agentpay-protocol": "0.14.3",

package/progress.md

@@ -1,5 +1,77 @@
 # AgentPay User progress
 
+## User 0.3.4 release candidate — 2026-11-09
+
+Release the explicit Market address update with unchanged Wallet 0.3.2 and
+Protocol 0.14.3 pins. No participant data or running services are changed by
+publication. Independent npm archive installation and real isolated local-service
+startup passed; all 388 release regressions passed. Tag publication, registry verification and participant migration
+are separate gates; participant acceptance remains pending.
+
+
+## Explicit Market address update — 2026-11-09
+
+Approved reduced scope: reuse login, Wallet list and public deployment interfaces;
+no Market identity key or new backend endpoint. User-selected address changes must
+match the original account/Wallet/Policy connection and deployment. Consent updates
+transport URLs, restarts only managed Runtime and preserves key/Policy/Orders/cache.
+Policy-scoped aliases retain cancellation IDs; interrupted apply has a retry marker
+and status guidance. Controlled address/connection/cancellation/status checks pass;
+387 full regression checks passed; subsequent reconnect-boundary/transaction
+changes passed targeted checks. npm publication and participant acceptance remain
+pending. Only explicit origin changes or interrupted updates enter this path;
+ordinary reconnect/renewal does not acquire new configuration dependencies.
+No participant settings have been modified.
+
+## User 0.3.3 published — 2026-11-09
+
+Tag v0.3.3 identifies c5f3be1. GitHub run 42567636609 passed behavior, standalone
+archive and OIDC publication steps. Independent public-registry verification
+confirmed exact Wallet 0.3.2 / Protocol 0.14.3 dependencies, provenance metadata
+and byte-identical archive (SHA-256
+aa231297a4690117850f5d50414d89ad0da86b29c29d03947383c23bfa62a833).
+Participant directory-update acceptance remains pending. Existing directory installs
+older than 0.3.3 need one npm install of 0.3.3 and repair before using local update.
+HTTPS endpoint migration is not included.
+
+## User 0.3.3 release candidate — 2026-11-09
+
+Release directory-local npm updates, keeping exact Wallet 0.3.2 and Protocol
+0.14.3 dependencies and the reviewed official test package unchanged. No endpoint
+migration, Policy or saved request rewrite is included. All 383 local behavior tests and independent archive installation/process checks
+passed. Tag-triggered publication and registry verification remain pending.
+
+## HTTPS endpoint migration — 2026-11-09
+
+HTTPS migration inventory: existing setup rejects URL differences; local service settings, Market receipt origin/session, recovery observations and cancellation intents need coordinated handling. Public configuration publication does not migrate existing users. Keep original requests/Policies and current tunnels until an explicit local migration is implemented and verified.
+
+## Directory npm update — 2026-11-08
+
+Update now supports a direct registry dependency under a project node_modules as
+well as a global installation. It derives the owning project from the running
+package, pins the confirmed version, preserves the dependency section, updates the
+local lockfile and uses the existing stop/repair/private-data flow. Source/link,
+custom-source and transitive installs are refused before changing services.
+Nine updater regression checks passed. A real public-npm 0.3.1 → 0.3.2 upgrade
+in a disposable project verified program/manifest/lockfile agreement and preserved
+private-record fixtures; service hooks were controlled, not participant processes.
+This exposed npm dry-run rewriting the hidden installed-tree lockfile. Preflight
+now runs in a disposable prefix with private project npm settings, removed afterward.
+See [verification](doc/records/local-npm-update-2026-11-08.md).
+User 0.3.3 is the release candidate for this fix; publication verification is pending.
+
+## User 0.3.2 tag publication verified — 2026-11-08
+
+Tag `v0.3.2` points to `890171b`; GitHub push-triggered OIDC run
+[42491753287](https://github.com/c4rO-0/agentpay-user/actions/runs/42491753287)
+completed successfully, including registry integrity verification. Public npm latest
+is 0.3.2, pins Wallet 0.3.2 / Protocol 0.14.3 and includes provenance. Independently
+downloaded registry bytes exactly match the locally tested archive (SHA-256
+`e6bb2f1199e510850313c004055afeb3ba45afc07035697c1d37af14ebcf1489`).
+All 380 existing tests and the independent package's real Wallet/Runtime restart
+check passed. Participant npm update/restart acceptance remains the next step;
+publication did not modify any participant services or create a paid Order.
+
 ## User 0.3.2 release pairing — 2026-11-08
 
 Candidate now pins the verified public Wallet 0.3.2 with Protocol 0.14.3; package,

package/src/connect-market.mjs

@@ -13,6 +13,7 @@ import { checkServiceDirectory } from "./local-services.mjs";
 import { localWalletAdmin } from "./local-wallet-ipc.mjs";
 import { repairMarketWallet } from "./repair-market-wallet.mjs";
 import { controlWallet } from "./wallet-control.mjs";
+import { preparePlatformEndpoints } from "./platform-endpoints.mjs";
 import { fetchJsonWithTimeout } from "./transport.mjs";
 export function marketOrigin(value) {
   const u = new URL(value);
@@ -129,6 +130,7 @@ export async function connectMarket(
     save = saveConnection,
     repair = repairMarketWallet,
     unlock = controlWallet,
+    prepareEndpoints = preparePlatformEndpoints,
   } = {},
 ) {
   let token, origin, completion;
@@ -194,6 +196,8 @@ export async function connectMarket(
       return 0;
     }
     origin = marketOrigin(answer.trim() || previous?.marketOrigin);
+    write("Checking Market and platform addresses…");
+    const changingOrigin = !!previous?.marketOrigin && marketOrigin(previous.marketOrigin) !== origin;
     const call = async (path, body, auth = true) => {
       const { response, result } = await fetchJson(
         origin + "/market" + path,
@@ -244,6 +248,8 @@ export async function connectMarket(
     token = signedIn.sessionToken;
     if (typeof token !== "string" || !token || !signedIn.developer?.id)
       throw Error("Market returned an invalid sign-in response.");
+    if (changingOrigin && previous.accountId !== signedIn.developer.id)
+      throw Error("This is not your saved Market account. The previous connection and addresses were kept.");
     write(
       "\n------------------------------------------------------------\n2/3 Name your Wallet\n------------------------------------------------------------",
     );
@@ -257,6 +263,19 @@ export async function connectMarket(
           String(w[key]).toLowerCase() === scope[key].toLowerCase(),
       ),
     );
+    // These authenticated record checks detect accidental cross-Market moves.
+    // They are not a cryptographic server identity; the user chooses the URL.
+    const originalConnectionMatches = !!previous?.connection?.id && !!existing &&
+      ["network", "module", "safe", "delegate"].every(key =>
+        typeof previous.connection[key] === "string" &&
+        previous.connection[key].toLowerCase() === String(existing[key]).toLowerCase()) &&
+      existing.policies?.some(p => p.id === previous.connection.id &&
+        String(p.policyId).toLowerCase() === String(previous.connection.policyId).toLowerCase());
+    if (changingOrigin && !originalConnectionMatches)
+      throw Error("Your original Wallet connection was not found at this address. The previous connection and addresses were kept.");
+    const endpoints = previous ? await prepareEndpoints({dataDir,origin,scope,fetchJson,changingOrigin}) : {changed:false,apply:async()=>{}};
+    if (endpoints.changed && (previous?.accountId !== signedIn.developer.id || !originalConnectionMatches))
+      throw Error("Platform addresses changed, but your original account and Wallet connection could not be confirmed. Current addresses were kept.");
     if (existing) write(`Using your Wallet name: ${existing.label}`);
     else
       write(
@@ -307,6 +326,10 @@ export async function connectMarket(
         write(
           "View this Wallet’s Orders and request help on Market. No spending permission is added.",
         );
+        if (endpoints.changed) write(`Also update platform addresses:
+Settlement: ${endpoints.urls.settlementUrl}
+Downloads: ${endpoints.urls.marketBundleMetadataUrl}
+Runtime will restart; your spending permission stays the same.`);
         while (true) {
           const choice = (
             await ask(
@@ -345,17 +368,24 @@ export async function connectMarket(
           throw Error("Connection execution address differs from this Wallet.");
         if (result.connection.label !== label)
           throw Error("Connection nickname differs. Check Market Settings.");
-        try {
-          await save(dataDir, {
-            version: 1,
-            marketOrigin: origin,
-            accountId: signedIn.developer.id,
-            connection: result.connection,
-          });
-        } catch {
-          write(
-            "Market connected this Wallet, but the local shortcut could not be saved. Use --market URL next time.",
-          );
+        if (changingOrigin && previous.connection.policyId === scope.policyId &&
+            result.connection.id !== previous.connection.id)
+          throw Error("Market returned a different connection record. The previous local connection was kept.");
+        const saveConnected = () => save(dataDir, {
+          version: 1,
+          marketOrigin: origin,
+          accountId: signedIn.developer.id,
+          connection: result.connection,
+        });
+        if (endpoints.changed) {
+          await endpoints.apply({write,saveConnection:saveConnected});
+        } else {
+          try { await saveConnected(); }
+          catch {
+            if (changingOrigin)
+              throw Error("The updated Market connection could not be saved. Retry the same command.");
+            write("Market connected this Wallet, but the local shortcut could not be saved. Use --market URL next time.");
+          }
         }
         completion = `\nWallet connected: ${label}\nView this Wallet’s Orders in Market → Account → My Orders.\nManage or disconnect it in Market Settings. This guide has finished.`;
         return 0;

package/src/npm-update.mjs

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: MPL-2.0
-// Update only a real global npm installation. Source checkouts/npm links are never
+// 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, lstat, mkdir, open, readFile, realpath, unlink } from 'node:fs/promises';
+import { access, appendFile, copyFile, chmod, lstat, mkdir, mkdtemp, open, readFile, realpath, rm, unlink } from 'node:fs/promises';
 import { constants } from 'node:fs';
-import { dirname, isAbsolute, join } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { createInterface } from 'node:readline/promises';
 import { installedUserDir, resolveUserDataDir, rememberUserDataDir } from './local-data-directory.mjs';
@@ -35,6 +35,35 @@ async function askConfirmation(message) {
   const terminal = createInterface({ input:process.stdin, output:process.stdout });
   try { return await terminal.question(message + '\n> '); } finally { terminal.close(); }
 }
+// Resolve the installed package, not the terminal's working directory. A project
+// update must name a direct dependency; never promote a transitive package or
+// replace a linked source checkout as a side effect of updating User.
+async function installationTarget(userDir, npm) {
+  const root = await npm(['root', '--global']);
+  if (!isAbsolute(root)) throw Error('npm installation paths could not be verified.');
+  const globalPath = join(root, name);
+  const info = await lstat(globalPath).catch(e => { if (e.code !== 'ENOENT') throw e; return null; });
+  if (info?.isDirectory() && !info.isSymbolicLink() && await realpath(globalPath) === await realpath(userDir)) {
+    const prefix = await npm(['prefix', '--global']);
+    if (!isAbsolute(prefix)) throw Error('npm installation paths could not be verified.');
+    return {prefix, flags:['--global'], directory:globalPath};
+  }
+  const scope = dirname(userDir), modules = dirname(scope), prefix = dirname(modules);
+  if (basename(userDir) !== 'agentpay-user' || basename(scope) !== '@c4roa0' || basename(modules) !== 'node_modules' ||
+      !(await lstat(userDir)).isDirectory() || (await lstat(userDir)).isSymbolicLink())
+    throw Error('This is a source checkout or linked installation. Update its files, run npm ci, then agentpay repair.');
+  const project = JSON.parse(await readFile(join(prefix,'package.json'),'utf8'));
+  const sections = ['dependencies','devDependencies','optionalDependencies'].filter(key => Object.hasOwn(project[key] || {}, name));
+  if (sections.length !== 1 || typeof project[sections[0]][name] !== 'string')
+    throw Error('User must be a direct npm dependency of this folder. Install it in a dedicated folder before using update.');
+  const spec = project[sections[0]][name];
+  if (/[:/\\]/.test(spec) || spec.startsWith('.'))
+    throw Error('This dependency uses a custom source. Update that source explicitly, then run agentpay repair.');
+  const save = {dependencies:'--save-prod',devDependencies:'--save-dev',optionalDependencies:'--save-optional'}[sections[0]];
+  return {prefix, directory:userDir, section:sections[0], spec,
+    flags:['--global=false','--workspaces=false','--save-exact',save,'--include=dev','--include=optional']};
+}
+
 export async function updateFromNpm({
   userDir = installedUserDir, dataDir, force = false, write = console.log,
   ask = askConfirmation,
@@ -45,17 +74,13 @@ export async function updateFromNpm({
 } = {}) {
   let lock, lockPath, logPath, installing = false;
   try {
+    userDir = resolve(userDir);
     const current = JSON.parse(await readFile(join(userDir, 'package.json'), 'utf8'));
     if (current.name !== name || !stable(current.version)) throw Error('Unrecognized User installation.');
     write('Checking for a User update…');
-    const root = await npm(['root','--global']), prefix = await npm(['prefix','--global']);
-    if (!isAbsolute(root) || !isAbsolute(prefix)) throw Error('npm installation paths could not be verified.');
-    const globalPath = join(root, name);
-    const globalInfo = await lstat(globalPath).catch(e => { if(e.code !== 'ENOENT') throw e; return null; });
-    if (!globalInfo || globalInfo.isSymbolicLink() || await realpath(globalPath) !== await realpath(userDir))
-      throw Error('This is a source checkout or linked installation. Update its files, run npm ci, then agentpay repair.');
-    await access(dirname(globalPath), constants.W_OK);
-    const metadata = JSON.parse(await npm(['view',name + '@latest','--global','--json']));
+    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}));
     if (metadata.name !== name || !stable(metadata.version) ||
         !stable(metadata.dependencies?.['@c4roa0/agentpay-wallet']) ||
         !stable(metadata.dependencies?.['@c4roa0/agentpay-protocol']))
@@ -67,6 +92,7 @@ export async function updateFromNpm({
       return 0;
     }
     write(`User ${current.version} → ${metadata.version} · Wallet ${metadata.dependencies['@c4roa0/agentpay-wallet']}`);
+    write(`Installation folder: ${target.prefix}`);
     write('Background services will pause. Keys, permissions, Orders and cache are kept.');
     if (!force && (await ask("Type 'confirm' to update, or 'q' to cancel")).trim().toLowerCase() !== 'confirm') {
       write('Update cancelled. Nothing was changed.'); return 0;
@@ -81,12 +107,28 @@ export async function updateFromNpm({
     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.');
+    if (target.section) {
+      const project = JSON.parse(await readFile(join(target.prefix,'package.json'),'utf8'));
+      if (project[target.section]?.[name] !== target.spec)
+        throw Error('The project dependency changed while reviewing the update. Run agentpay update again.');
+    }
     const env = {...process.env,AGENTPAY_USER_DATA_DIR:dataDir};
-    const options = {logPath,env,cwd:stateDir,timeout:600000};
+    const options = {logPath,env,cwd:target.prefix,timeout:600000};
     const spec = name + '@' + metadata.version;
-    const args = ['install','--global','--prefix',prefix,'--engine-strict','--ignore-scripts','--no-audit','--no-fund',spec];
+    const args = ['install',...target.flags,'--prefix',target.prefix,'--engine-strict','--ignore-scripts','--no-audit','--no-fund',spec];
     write('1/3 Check the update requirements.');
-    await npm([...args,'--dry-run'],options);
+    // npm dry-run may rewrite its hidden installed-tree lockfile. Preflight in
+    // a disposable prefix, never the live installation. Carry project npm settings
+    // privately so registry/auth selection remains consistent with the real install.
+    const preflight = await mkdtemp(join(stateDir,'update-check-'));
+    try {
+      await copyFile(join(target.prefix,'.npmrc'),join(preflight,'.npmrc')).then(
+        () => chmod(join(preflight,'.npmrc'),0o600),
+        error => { if(error.code !== 'ENOENT') throw error; });
+      await npm(['install','--global=false','--prefix',preflight,'--engine-strict',
+        '--ignore-scripts','--no-audit','--no-fund',spec,'--dry-run'],
+        {...options,cwd:preflight});
+    } finally { await rm(preflight,{recursive:true,force:true}); }
     let configured = false;
     try { configured = (await lstat(join(dataDir,'runtime/local-services.json'))).isFile(); }
     catch(e) { if(e.code !== 'ENOENT') throw e; }

package/src/order-cancellation.mjs

@@ -1,6 +1,7 @@
 // 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 { sameSettlementAddress } from "./settlement-address-history.mjs";
 import { isUnpaidExpiry } from "./order-closure.mjs";
 import { randomBytes, createHash } from "node:crypto";
 import { constants } from "node:fs";
@@ -109,7 +110,7 @@ async function readIntent(ctx) {
     !B32.test(intent.cancellationId || "") ||
     intent.orderId !== ctx.orderId ||
     intent.policyId !== ctx.policyId ||
-    intent.settlementUrl !== ctx.settlementUrl ||
+    !(await sameSettlementAddress(ctx.dataDir,intent.settlementUrl,ctx.settlementUrl,ctx.policyId)) ||
     !Number.isSafeInteger(intent.createdAtMs) ||
     intent.createdAtMs < 0
   )

package/src/platform-endpoints.mjs

@@ -0,0 +1,129 @@
+// 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';
+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';
+import {validatePublicDeployment} from './prepare-onboarding.mjs';
+import {readServiceSettings,checkServiceDirectory,listenerPresent} from './local-services.mjs';
+import {isManagedUnit} from './autostart-files.mjs';
+import {fetchJsonWithTimeout} from './transport.mjs';
+import {settlementProfileBlocker} from './readiness-profile.mjs';
+import {readRuntimeStatus} from './runtime-status.mjs';
+import {readSettlementAddresses} from './settlement-address-history.mjs';
+
+const execute=promisify(execFile);
+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');
+const aliasesPath=dir=>join(dir,'runtime/settlement-addresses.json');
+
+async function durableJson(path,value){
+ const temp=path+'.'+randomUUID()+'.tmp';let file;
+ try{
+  file=await open(temp,'wx',0o600);await file.writeFile(JSON.stringify(value)+'\n');await file.sync();await file.close();file=null;
+  await rename(temp,path);
+  const directory=await open(dirname(path),constants.O_RDONLY|constants.O_DIRECTORY|constants.O_NOFOLLOW);
+  try{await directory.sync();}finally{await directory.close();}
+ }finally{await file?.close();await unlink(temp).catch(e=>{if(e.code!=='ENOENT')throw e;});}
+}
+
+
+async function runtimeControl(action,{dataDir,settings}){
+ if(process.platform!=='linux')throw Error('Automatic address updates currently require managed Linux services. Keep your saved settings.');
+ const unit='agentpay-local-runtime.service',path=join(homedir(),'.config/systemd/user',unit);
+ const stat=await lstat(path);
+ if(!stat.isFile()||stat.isSymbolicLink()||stat.uid!==process.getuid()||(stat.mode&0o022)||!isManagedUnit(await readFile(path,'utf8'),unit,dataDir))
+  throw Error('Runtime is not managed by this User installation. Run agentpay repair before updating addresses.');
+ const ctl=async args=>(await execute('systemctl',['--user',...args],{timeout:45000,maxBuffer:16384})).stdout.trim();
+ if(await ctl(['show',unit,'--property=FragmentPath','--value'])!==path||await ctl(['show',unit,'--property=DropInPaths','--value']))
+  throw Error('Runtime service settings need review before updating addresses.');
+ await ctl([action,unit]);
+ if(action==='stop'){
+  const url=new URL(settings.runtimeUrl);
+  if(await listenerPresent({host:url.hostname,port:Number(url.port)}))throw Error('Runtime is still running. No connection settings were changed.');
+ }else{
+  for(let i=0;i<30;i++){
+   try{await readRuntimeStatus(dataDir);return;}catch{await new Promise(r=>setTimeout(r,500));}
+  }
+  throw Error('Runtime did not become ready. Retry agentpay market connect with the same Market address.');
+ }
+}
+
+export async function preparePlatformEndpoints({dataDir,origin,scope,userDir=installedUserDir,fetchJson=fetchJsonWithTimeout,changingOrigin=false}){
+ await checkServiceDirectory(dataDir);
+ const pending=await readPrivateJson(pendingPath(dataDir));
+ // Ordinary reconnect/renewal keeps its existing behavior. Only a deliberately
+ // changed origin or an interrupted update owns transport changes.
+ if(!changingOrigin&&!pending)return {changed:false,apply:async()=>{}};
+ const setup=await readPrivateJson(await deploymentFilePath(dataDir,userDir,'anvil-onboarding.json'));
+ if(!setup)throw Error('Local setup settings are missing. Run agentpay setup before connecting Market.');
+ const policy=await readPrivateJson(join(dataDir,'wallet/policy.json'));
+ if(!policy||policy.policyId?.toLowerCase()!==scope.policyId?.toLowerCase()||policy.safe?.toLowerCase()!==scope.safe?.toLowerCase()||`eip155:${policy.chainId}`!==scope.network||policy.module?.toLowerCase()!==scope.module?.toLowerCase())
+  throw Error('Wallet authorization changed. Run agentpay market connect again.');
+ const connectionBefore=await readPrivateJson(join(dataDir,'market-connection.json'));
+ if(pending&&(pending.version!==1||pending.origin!==origin||pending.policyId!==policy.policyId))
+  throw Error('Finish the pending address update with the same Policy. Retry: agentpay market connect --market '+pending.origin);
+ const {response,result}=await fetchJson(origin+'/market/web/onboarding/user-config',{method:'GET'},15000);
+ if(!response.ok)throw Error('Market settings could not be checked. Your current addresses are kept.');
+ const proposed=validatePublicDeployment(result);
+ const settings=await readServiceSettings(dataDir);
+ const urls={settlementUrl:proposed.settlementUrl,marketBundleMetadataUrl:proposed.marketBundleMetadataUrl};
+ const changed=Object.keys(urls).some(key=>normalize(setup[key])!==normalize(urls[key]))||normalize(settings.settlementUrl)!==normalize(urls.settlementUrl)||!!pending;
+ // RPC is participant-owned: a different local tunnel must never be overwritten.
+ // A Market connection alone is not authority to rotate contracts or test packages.
+ const publicPath=await deploymentFilePath(dataDir,userDir,'user-deployment.json');
+ const previousPublic=await readPrivateJson(publicPath);
+ if(!changed&&!changingOrigin)return {changed:false,apply:async()=>{}};
+ if(deploymentChanges(policy,proposed).length||deploymentChanges(setup,proposed).length||setup.mode!==proposed.mode||setup.tokenDecimals!==proposed.tokenDecimals||setup.tokenSymbol!==proposed.tokenSymbol)
+  throw Error('This Market uses different network or contract settings. Address update stopped; your current Policy and Orders are kept.');
+
+ // Query an unknown service to inspect deployment identity without depending on
+ // a particular Provider being online, or granting it an Order.
+ const query=new URL(normalize(urls.settlementUrl)+'/agentpay/purchase-readiness');
+ query.searchParams.set('skillId','0x'+'0'.repeat(64));query.searchParams.set('profileHash','0x'+'0'.repeat(64));
+ const readiness=await fetchJson(query.href,{method:'GET'},15000);
+ if(!readiness.response.ok||!readiness.result?.ok||settlementProfileBlocker(policy,readiness.result.result?.settlementProfile))
+  throw Error('The new Settlement address does not match this Wallet deployment. Current addresses are kept.');
+ const metadata=await fetchJson(urls.marketBundleMetadataUrl,{method:'GET'},15000);
+ 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()=>{}}={}){
+  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;}
+  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))
+    throw Error('Local settings changed during connection. Retry market connect; no addresses were changed.');
+   const aliases=await readSettlementAddresses(dataDir);
+   const entry={from:normalize(settings.settlementUrl),to:normalize(urls.settlementUrl),policyId:policy.policyId};
+   if(entry.from!==entry.to&&!aliases.entries.some(e=>same(e,entry))){
+    if(aliases.entries.length>=256)throw Error('Settlement address history needs review.');
+    aliases.entries.push(entry);
+   }
+   write('Updating platform addresses. Runtime will pause briefly; Wallet stays unlocked.');
+   // A durable marker makes interruptions retryable even after settings are written.
+   // Write the alias before the new active address; never mutate cancellation IDs.
+   await durableJson(pendingPath(dataDir),{version:1,origin,policyId:policy.policyId});
+   await saveConnection();
+   await manage('stop',{dataDir,settings});
+   await durableJson(aliasesPath(dataDir),aliases);
+   if(previousPublic)await durableJson(join(dataDir,'user-deployment.json'),{...previousPublic,...urls});
+   await durableJson(join(dataDir,'anvil-onboarding.json'),{...setup,...urls});
+   await durableJson(join(dataDir,'runtime/local-services.json'),{...settings,settlementUrl:normalize(urls.settlementUrl)});
+   await manage('start',{dataDir,settings:{...settings,settlementUrl:normalize(urls.settlementUrl)}});
+   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. Run agentpay market connect --market '+origin+' again. '+e.message);}
+  finally{await lock.close();await unlink(lockPath);}
+ }};
+}

package/src/settlement-address-history.mjs

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: MPL-2.0
+// Local aliases acknowledge an explicitly confirmed address change, not extra
+// authority. Cancellation IDs and Policy scopes remain unchanged.
+import {join} from 'node:path';
+import {readPrivateFile} from './runtime-client.mjs';
+const normalize=value=>{
+ const u=new URL(value);
+ if(u.username||u.password||u.search||u.hash||!(u.protocol==='https:'||u.protocol==='http:'&&['localhost','127.0.0.1','[::1]'].includes(u.hostname)))throw Error('Invalid saved Settlement address.');
+ return u.href.replace(/\/+$/,'');
+};
+export async function readSettlementAddresses(dataDir){
+ let saved;
+ try{saved=JSON.parse(await readPrivateFile(join(dataDir,'runtime/settlement-addresses.json'),65536));}
+ catch(e){if(e.code==='ENOENT')return {version:1,entries:[]};throw e;}
+ if(saved?.version!==1||!Array.isArray(saved.entries)||saved.entries.length>256)throw Error('Invalid saved Settlement address history.');
+ for(const e of saved.entries){
+  if(!e||Object.keys(e).sort().join(',')!=='from,policyId,to'||!/^0x[a-fA-F0-9]{64}$/.test(e.policyId)||normalize(e.from)!==e.from||normalize(e.to)!==e.to)throw Error('Invalid saved Settlement address history.');
+ }
+ return saved;
+}
+export async function sameSettlementAddress(dataDir,from,to,policyId){
+ if(normalize(from)===normalize(to))return true;
+ const saved=await readSettlementAddresses(dataDir),seen=new Set([normalize(from)]);
+ for(let i=0;i<saved.entries.length;i++)for(const entry of saved.entries){
+  if(entry.policyId.toLowerCase()===policyId.toLowerCase()&&seen.has(entry.from))seen.add(entry.to);
+ }
+ return seen.has(normalize(to));
+}

package/src/status-panel.mjs

@@ -118,6 +118,16 @@ export async function readMarketStatus(dataDir) {
       await h?.close();
     }
   }
+  const endpointUpdate = await saved("runtime/endpoint-update.pending.json");
+  if (endpointUpdate) {
+    let origin;
+    try {
+      const url = new URL(endpointUpdate.origin);
+      if (url.origin === endpointUpdate.origin &&
+          (url.protocol === "https:" || url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname))) origin = url.origin;
+    } catch {}
+    return {state:"address_pending", ...(origin ? {origin} : {})};
+  }
   const receipt = await saved("market-connection.json");
   if (!receipt) return { state: "none" };
   const policy = await saved("wallet/policy.json"),
@@ -409,7 +419,7 @@ export function renderStatusPanel(
     next =
       "Keep services running. Check progress in the original Agent conversation. If continuing a supported request, keep its original identifier; never create a replacement purchase.";
   }
-  const marketPending = ["pending", "unknown"].includes(model.market?.state);
+  const marketPending = ["pending", "unknown", "address_pending"].includes(model.market?.state);
   if (marketPending && level === "ok") {
     title =
       model.market.state === "pending"
@@ -420,6 +430,12 @@ export function renderStatusPanel(
       "Website access to this Policy is not confirmed. Local payments are unaffected.";
     next = "agentpay market connect";
   }
+  if (model.market?.state === "address_pending") {
+    title = "Platform address update incomplete";
+    level = "wait";
+    detail = "Retry your Market connection to finish updating addresses. Original Order records are kept.";
+    next = "agentpay market connect" + (model.market.origin ? " --market " + model.market.origin : "");
+  }
   const divider = "-".repeat(Math.min(60, width));
   const lines = [
     "",
@@ -524,7 +540,9 @@ export function renderStatusPanel(
       lines.push("", "> Market");
       const state = model.market.state;
       lines.push(
-        state === "saved"
+        state === "address_pending"
+          ? `  ${badge("wait")} Platform address update incomplete`
+          : state === "saved"
           ? `  ${badge("ok")} Current Policy connection saved locally`
           : state === "none"
             ? "  Not connected from this installation"

package/update-pair.json

@@ -1,6 +1,6 @@
 {
   "format": "agentpay.local-update-pair.v1",
-  "userVersion": "0.3.2",
+  "userVersion": "0.3.4",
   "walletVersion": "0.3.2",
   "typesDependency": "0.14.3"
 }