@c4roa0/agentpay-user 0.3.2 → 0.3.3

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,16 @@
 # User TODO
 
+## 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.
+- [ ] Publish a follow-up version and 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 +19,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 |

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

@@ -0,0 +1,28 @@
+# 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.

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/package.json

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

package/progress.md

@@ -1,5 +1,43 @@
 # AgentPay User progress
 
+## 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/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/update-pair.json

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