@c4roa0/agentpay-user 0.3.1 → 0.3.3

package/AGENTS.md

@@ -135,3 +135,13 @@ load Protocol fixtures from the pinned public package, not a source checkout.
 Do not remove scripts merely because their name contains smoke or Anvil: some are
 current onboarding entries. Review callers first. Never weaken signer or payment
 boundaries to simplify tests. Keep source maps and behavioral evidence limits current.
+
+## Tag-triggered npm releases
+
+Package version `X.Y.Z` is released by pushing tag `vX.Y.Z` at the exact reviewed
+source commit. `.github/workflows/publish.yml` validates this match, verifies the
+package, publishes through OIDC and checks registry integrity. Pushing a release
+tag is a publication action and needs maintainer authorization; ordinary branch
+pushes do not publish. Never move an existing release tag. Verify registry state
+before rerunning a failed publication. The `npm-publish` environment must allow
+release tags (for example `v*`), not only the main branch.

package/README.md

@@ -15,7 +15,7 @@ Install User with the command below. It automatically installs the matching Wall
 and Protocol packages; you do not need to download two repositories:
 
 ```sh
-npm install --global @c4roa0/agentpay-user@0.3.1
+npm install --global @c4roa0/agentpay-user
 agentpay install --market https://YOUR_MARKET_ORIGIN
 ```
 
@@ -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,5 +1,35 @@
 # 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.
+- [x] Verify first tag-triggered OIDC run 42491753287 and registry archive integrity.
+
+## Official package 1.2.1 — 2026-11-08
+
+- [x] Review actual published bytes, update the built-in official pin and verify fixed-download checks. Real Market fixed-version download/install repeated successfully in an isolated directory.
+- [x] Inspect this participant installation’s prior-version official tests: saved 1.2.0 record is acknowledged; retained unchanged. This does not assert every user has completed old tests.
+- [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.
+- [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
+
+- [x] Request the official ZIP by the built-in SHA-256; reject unavailable/substituted versions without fallback.
+- [x] Complete fixed-download regression/type checks and publication/deletion review; the separate Market schema-fixture issue was resolved in its later regression.
+- [ ] After Market API/Web/nginx support is live, publish the next User version (not 0.3.1 again) and verify old pinned ZIP download and participant upgrade.
+
+
 ## Running-version release loop — 2026-11-07
 
 - [x] Verify User 0.3.0 public-registry publication; Trusted Publisher configured.
@@ -7,7 +37,8 @@
 - [x] Add process-start software reporting and status/repair mismatch handling; isolated checks passed.
 - [x] Wallet 0.3.1 published through the configured workflow; public npm version/dependencies verified.
 - [x] Pin User 0.3.1 to published Wallet 0.3.1; pairing metadata/lockfile and standalone archive verification complete.
-- [ ] Publish matching User release; validate User OIDC and real published-version update/restart.
+- [x] Publish User 0.3.1; verify public npm/latest and successful Wallet/User OIDC runs.
+- [ ] Verify real published-version update/restart on the participant installation.
 
 
 ## npm update follow-up — 2026-11-07
@@ -25,11 +56,12 @@
 - [x] Review step 2: guard normal packing against missing/stale builds, correct public-interface docs and verify a standalone TypeScript consumer.
 - [x] Step 3: migrate User to Wallet npm dependency and `agentpay` entry; remove sibling/build assumptions; isolated tarball/process acceptance passed.
 - [x] Step 4a: exact installed-package checks, service-path/client relocation, installer lock, recovery-safe preparation and explicit uninstall modes.
-- [ ] Step 4b: running-daemon version/interface negotiation and participant upgrade/interruption acceptance.
+- [x] Step 4b implementation: installed/running version and interface checks.
+- [ ] Step 4b acceptance: participant upgrade/interruption recovery (same gate as the running-version loop above).
 - [ ] Step 5: publish Wallet then User via OIDC; verify registry installs and update Market guides.
   - [x] Wallet 0.3.0 first Token publication; registry integrity/latest and fresh public install/CLI/IPC verified.
-  - [x] Owner configured Wallet npm Trusted Publisher (pending validation).
-  - [ ] Validate Wallet and User OIDC with later reviewed releases. Both 0.3.0 packages are published; Market guide updates remain pending.
+  - [x] Owner configured Wallet npm Trusted Publisher; validated by 0.3.1 publication.
+  - [x] Wallet and User OIDC validated by 0.3.1 releases; Market guide updates remain pending.
 - [ ] Step 6: participant setup/upgrade/restart/uninstall and official Anvil paid acceptance.
 
 
@@ -58,7 +90,7 @@
 ## Independent distribution (next development loop)
 
 - [ ] Define the supported Wallet client/IPC boundary and source/build/running compatibility requirements.
-- [ ] Replace exact version pairing with reviewed compatibility checks; preserve keys, Policies and recovery.
+- [ ] Optional later: widen exact reviewed dependency pairs only with a verified compatibility matrix; preserve keys, Policies and recovery.
 - [ ] Optional later: combined ZIP/platform assets after primary npm installation acceptance.
 - [ ] Verify fresh Git/ZIP installation and missing/incompatible/stale version recovery; update Market guidance.
 

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/doc/runbooks/npm-publication.md

@@ -1,56 +1,62 @@
 # Publish User to npm
 
-This publishes the User CLI and Runtime, with its exact reviewed Wallet dependency.
-It does not deploy platform services or alter participant keys, Policies or Orders.
+Push a reviewed `vX.Y.Z` tag to publish `@c4roa0/agentpay-user` through GitHub
+Actions. The tag must match `package.json`. Ordinary branch pushes do not publish.
+Keep `update-pair.json`, the lockfile and the reviewed Wallet dependency aligned.
+Publish the required Wallet version before releasing User.
 
-## Verify a release
+## One-time setup
 
-From a clean reviewed source checkout, using Node 22.22.3 or newer:
+In GitHub **Settings → Environments → npm-publish**, allow deployment from tags
+matching `v*`. A rule allowing only the `main` branch will block tag releases.
+Keep required reviewer approval if desired. Restrict creation, update and deletion
+of release tags to maintainers through repository rules.
 
-```sh
-npm ci --ignore-scripts
-npm test
-node scripts/test-package.mjs artifacts/npm
-```
+On npm, configure this package's Trusted Publisher:
+
+| Field | Value |
+| --- | --- |
+| Publisher | GitHub Actions |
+| Organization/user | `c4rO-0` |
+| Repository | `agentpay-user` |
+| Workflow filename | `publish.yml` |
+| Environment name | `npm-publish` |
+| Allowed action | Direct publishing |
 
-Review the package inventory and README. The archive check installs the package in
-an isolated directory, checks the public command and starts disposable Wallet/Runtime
-processes. It never uses a participant's private data. Keep the exact verified archive
-for publication; do not rebuild it between verification and upload.
+Existing matching npm trust settings need no change. The first successful OIDC
+publication validates a pending connection; a local token upload does not.
+No stored npm token is needed by this workflow.
 
-## First publication
+## Release a version
 
-Authenticate as the package maintainer, then publish the verified archive:
+1. Update `package.json` and the changelog. Review code, documentation, dependencies
+   and package contents; complete the repository's verification steps.
+2. Commit and push the reviewed source to main, including the tag-triggered workflow.
+3. Create an annotated tag at that exact commit and push it. Replace `X.Y.Z` and
+   `REVIEWED_COMMIT` below with the release version and reviewed commit:
 
 ```sh
-npm publish artifacts/npm/c4roa0-agentpay-user-0.3.0.tgz --access public --ignore-scripts --registry=https://registry.npmjs.org/
-node scripts/verify-npm-release.mjs artifacts/npm/c4roa0-agentpay-user-0.3.0.tgz 0.3.0
+git tag -a vX.Y.Z REVIEWED_COMMIT -m "Release X.Y.Z"
+git push origin vX.Y.Z
 ```
 
-Never commit or share a publishing Token. If npm stages the first release, approve
-it on npm before verifying. A timeout is not proof of failure: check the registry
-before retrying publication. Published version numbers cannot be reused.
-
-## GitHub Trusted Publisher
+Pushing the tag starts **Publish User to npm** automatically. There is no version
+input or separate Run workflow step. If the environment requires approval, approve
+that deployment in GitHub. The workflow checks the tag against the manifest before
+building, runs the existing verification gates, tests/packs the archive, publishes
+with OIDC and checks public registry integrity. It builds the tagged source, even
+if main advances. No production service or participant Wallet is upgraded.
 
-Create the GitHub environment `npm-publish` and restrict its deployment branch to
-`main`. Add maintainer approval if desired. In the npm package's Trusted Publisher
-settings, select GitHub Actions and enter:
+## Verify or recover a publication
 
-| Field | Value |
-| --- | --- |
-| Organization/user | `c4rO-0` |
-| Repository | `agentpay-user` |
-| Workflow filename | `publish.yml` |
-| Environment name | `npm-publish` |
-| Allowed action | Direct publishing |
+Check the run's **Verify public registry integrity** result and the package version
+on npm. Record the tag, source commit and result in progress. Do not claim success
+from tag creation alone. Actual OIDC validation requires the GitHub run.
 
-Run **Publish User to npm** on `main` with a new reviewed package version matching
-`package.json` and `update-pair.json`. It tests, packs, verifies, publishes that exact
-archive through OIDC, and compares registry integrity. No stored npm Token is needed.
-The first successful OIDC release validates the connection; the initial Token upload
-does not. Afterwards, disable bypass-2FA tokens and retire unused publishing tokens.
-See [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/).
+If a run fails before upload, investigate before rerunning. If source needs a fix,
+use a new version/tag; never move an existing release tag. If upload may have
+succeeded, check registry state and archive integrity before rerunning; npm versions
+are immutable and an already-published version must not be uploaded again.
 
-Publication is not real-network or participant upgrade acceptance. Record the exact
-source revision and verification outcome; test the published installation separately.
+Publication is not participant upgrade acceptance, cross-platform verification or
+real-funds approval.

package/doc/runbooks/official-test-package.md

@@ -9,9 +9,24 @@ hash reported by the same server that supplies the ZIP.
 
 This pin applies only to the maintained onboarding test. Generic Runtime calls and
 ordinary Skill installation do not require the random service or this package.
-The current pin is the reviewed random Skill 1.2.0 private rehearsal package;
+The current pin is the reviewed random Skill 1.2.1 private rehearsal package;
 it includes its service reference. It is not a production-network release.
 
+## Download a fixed Market version
+
+Setup and repair derive `/skills/bundles/:serviceId/versions/:sha256/metadata`
+from the saved Market source, using User's built-in ZIP hash. They download the matching
+fixed ZIP on the same origin and retain any `/market` ingress prefix. They no longer
+require Market's current release to match the User release. The ZIP is still hashed
+before parsing or saving; metadata cannot override the pin.
+
+Market must retain the approved historical version and permit its public download.
+If it is absent, withdrawn or no longer approved under current checks, preparation
+stops with an unavailable message. No current-version or Provider-hosted fallback is
+used. Existing local packages, requests and spending permission are unchanged.
+This client change requires the Market fixed-version API rollout before distributing
+the next User release; User 0.3.1 and earlier do not use this endpoint.
+
 ## Before publishing a User update
 
 1. Check whether the maintained official Skill has a new published version.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@c4roa0/agentpay-user",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "dependencies": {
-    "ethers": "^6.17.0",
-    "fs-native-extensions": "1.5.3",
     "@c4roa0/agentpay-protocol": "0.14.3",
-    "@c4roa0/agentpay-wallet": "0.3.1"
+    "@c4roa0/agentpay-wallet": "0.3.2",
+    "ethers": "^6.17.0",
+    "fs-native-extensions": "1.5.3"
   },
   "scripts": {
     "start": "node src/index.mjs",

package/progress.md

@@ -1,6 +1,147 @@
 # AgentPay User progress
 
-## User 0.3.1 paired release preparation — 2026-11-08
+## 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,
+lockfile and update-pair metadata agree. This release includes fixed-version
+Market downloads and the reviewed official Skill 1.2.1 pin. Historical notes
+below describe earlier candidate pairings. Publish through tag `v0.3.2` after
+final suite and standalone archive checks; no automatic new purchase is authorized.
+
+## Tag-triggered publication — 2026-11-08
+
+Wallet, Protocol and User release workflows now run on pushed `vX.Y.Z` tags.
+Each validates its package version, runs existing verification, publishes with
+OIDC and checks registry integrity. Branch pushes do not publish. No tag was
+pushed or npm version published for this workflow change. Owner confirmed `v*` tags allowed in the GitHub
+`npm-publish` environment; npm trust fields remain unchanged. YAML/shell checks and six executable tag/version guard cases passed
+per repository (matching version, mismatch, branch, prerelease, leading zero and
+newline rejection). Actual GitHub/OIDC execution remains pending.
+
+## Official 1.2.1 payment reconciled / User 0.3.2 candidate — 2026-11-08
+
+Participant confirmed Market Order visibility. Independent fixed-block chain reads,
+receipts and token transfers match Settlement's finalized release record: paid
+0.7 rUSDC, seller 0.665, platform fee 0.035, no refund, empty Vault. Funding,
+delivery and release events occur once for the verified Order. No further payment.
+This is private Anvil acceptance, not real-network or production approval.
+User 0.3.2 candidate includes fixed-version downloads and the reviewed official
+1.2.1 ZIP pin. Its preliminary package check used Wallet 0.3.1 and Protocol 0.14.3.
+The maintainer requested Wallet 0.3.2 review/publication first; after registry
+verification, update User’s exact dependency and reverify the final package.
+Candidate publication and real npm update acceptance remain pending.
+
+## Official Skill 1.2.1 participant payment passed — 2026-11-08
+
+Operator ran normal wallet unlock and payment-test commands after source repair.
+The guide quoted a maximum 0.7 rUSDC and 10-minute service limit; the operator
+explicitly confirmed. It reported delivery verification, saved-result verification
+and receipt acknowledgement, then completed successfully. This is private Anvil
+end-to-end participant evidence. The quoted maximum is not independently reconciled
+actual charge; payout/refund terminal chain evidence has not been checked here.
+User remains the 0.3.1-labelled source candidate, not a new published npm release.
+Next: website Order visibility and read-only Settlement/chain reconciliation before
+release closeout. Do not rerun a completed payment test just to inspect the result.
+
+## Participant repair completed — 2026-11-08
+
+Operator ran the normal source repair entry. Official Skill 1.2.1 passed the
+built-in hash check and was installed. Wallet and Runtime restarted; Wallet is
+locked as expected. Saved Policy and Market connection remain present, and local
+history reports two settled Orders plus one archived record. No purchase occurred.
+This is source-candidate repair acceptance, not publication of a new npm version.
+Next operator step unlocks Wallet and invokes the normal payment test; explicit
+current-price confirmation remains required before creating a paid Order.
+
+## Official fixed-download acceptance — 2026-11-08
+
+The normal prepareOfficialTestUpdate entry downloaded 1.2.1 twice from the running
+Market fixed-version API into an isolated directory, verified the built-in hash,
+installed successfully and preserved an existing prior-record fixture byte-for-byte.
+The first diagnostic read assumed a flat archive; it was corrected to read the saved
+publisher ZIP through User's parser. No product installation defect was found.
+17 targeted pin/download/update/payment-orchestration/prefix checks passed.
+This proves download/install behavior, not paid invocation. No participant services
+or Wallet data changed. Source repair and explicit payment acceptance are next;
+the candidate is not yet a new npm release.
+
+## Official test pin 1.2.1 prepared — 2026-11-08
+
+Reviewed the actual Provider ZIP and confirmed it matches the published fixed Market
+download: 4373 bytes, SHA-256
+`20633b314c66166f94dc6e7d7eb5bce54ab5901fb1ed314a04ea3fd49ca8a9a4`.
+The official-test pin now selects 1.2.1; generic Runtime routing is unchanged.
+The package checker and 14 controlled pin/download/update/payment-orchestration
+checks passed. The payment fixture now follows the selected version instead of
+hardcoding 1.2.0. No real payment, service restart or npm release was performed.
+Before participant testing, check for unfinished tests from the previous version:
+records are retained, but the payment-test entry selects a version-specific record.
+Do not treat a new-version test as recovery of an old purchase.
+
+
+## Development dependency verification — 2026-11-08
+
+Reinstalled dependencies from the unchanged lockfile after a stale local installation
+could not resolve the already-declared Protocol package. Fixed-download/update/prefix
+checks pass 8/8; the cross-repository publication/download/User preview regression
+passes 27/27. No dependency pins, services or user data changed. This is controlled
+verification, not a new npm release or live payment acceptance.
+
+
+## Fixed historical Skill downloads — 2026-11-08
+
+Development adds SHA-256-fixed Market metadata/ZIP routes over retained releases,
+a derived per-listing lookup, website forwarding and User official-test pin selection.
+Current publication replacement no longer changes the requested ZIP. Hidden/deleted
+listings, takedown, stale approval and damaged files remain unavailable. Historical
+internal-version ZIP routes now also respect listing visibility. No DB migration,
+Provider download dependency, service restart or payment was performed.
+Deploy Market API/Web and the nginx route allowlist first, then release the updated User; current published User
+0.3.1 does not use the new fixed-version endpoint. Verification: User 33 targeted checks, Web 7 proxy checks, Deploy 8 route/build checks
+and both Market/Web typechecks passed. Market publication regression: 69/70 passed;
+the remaining pre-existing schema fixture fails with WALLET_MAPPING_SCHEMA_INVALID.
+Controlled scanner/DB fixtures and local HTTP were used; no live database, nginx
+rollout or participant acceptance is claimed.
+
+## User 0.3.1 paired release published — 2026-11-08
 
 Public npm now contains Wallet 0.3.1 with Protocol 0.14.3. User 0.3.1 pins that
 published Wallet exactly; pairing metadata and lockfile are updated together.
@@ -8,10 +149,19 @@ This release adds actual installed Protocol verification and running-version che
 for status/repair. Prior release-gate notes below describe earlier checkpoints.
 User 0.3.1 passed 378 behavioral tests and standalone npm archive installation,
 including real Wallet/Runtime restart and matching running-version reports.
-User 0.3.1 publication and real published-version upgrade acceptance remain pending.
+User 0.3.1 is public and npm `latest`, with Wallet 0.3.1 and Protocol 0.14.3.
+[User OIDC publication](https://github.com/c4rO-0/agentpay-user/actions/runs/42440841342)
+passed from `46796ea`; [Wallet OIDC publication](https://github.com/c4rO-0/agentpay-wallet/actions/runs/42440112081)
+passed from `7e4d4fa`. Registry metadata was independently checked.
+Real published-version upgrade/restart acceptance remains pending.
 No participant services, keys, Policies or Orders are changed by package verification.
 
-## Installed dependency verification / paired release — 2026-11-08
+## Historical checkpoints — superseded by the current release status above
+
+The dated entries below preserve evidence and earlier decisions. Their pending
+release labels are historical; use current TODO for remaining work.
+
+### Installed dependency verification / paired release — 2026-11-08
 
 User now checks the actual Protocol package resolved from User and Wallet separately,
 including nested npm copies. Process reports use resolved installed versions, not

package/scripts/install-skill-bundle.mjs

@@ -7,7 +7,7 @@ import {
   verifyOfficialTestBytes,
   verifyOfficialTestDigest,
 } from "../src/official-test-package.mjs";
-import { marketDownloadUrl } from "../src/market-download-url.mjs";
+import { marketDownloadUrl, marketVersionMetadataUrl } from "../src/market-download-url.mjs";
 import { resolve } from "node:path";
 import {
   inspectInstalledBundle,
@@ -42,7 +42,7 @@ if (
 }
 if (mode === "--prepare-official-test" && !marketMode)
   throw Error("OFFICIAL_TEST_MARKET_REQUIRED");
-const url = new URL(source);
+const url = official ? marketVersionMetadataUrl(source, digest) : new URL(source);
 if (
   url.username ||
   url.password ||
@@ -62,6 +62,8 @@ if (marketMode) {
     redirect: "error",
     signal: AbortSignal.timeout(5000),
   });
+  if (official && [404, 410].includes(r.status))
+    throw Error("This official test version is unavailable in Market. Check for a reviewed User update or contact support; no replacement was selected.");
   if (!r.ok) throw new Error(`MARKET_BUNDLE_METADATA_HTTP_${r.status}`);
   const body = await r.json();
   metadata = body.result;
@@ -78,7 +80,7 @@ if (marketMode) {
     !metadata.publisherId ||
     typeof metadata.marketServiceId !== "string" ||
     metadata.marketDownloadPath !==
-      `/skills/bundles/${encodeURIComponent(metadata.marketServiceId)}/download`
+      marketDownloadUrl(url, metadata.marketServiceId).pathname.replace(/^\/market(?=\/skills\/)/, "")
   )
     throw new Error("MARKET_BUNDLE_METADATA_INVALID");
   downloadUrl = marketDownloadUrl(url, metadata.marketServiceId);

package/src/market-download-url.mjs

@@ -1,21 +1,26 @@
 // 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/.
-// Preserve the approved metadata URL's ingress prefix; metadata cannot select a host.
+// The configured origin/prefix owns the download location; metadata cannot change it.
+function metadataLocation(value) {
+  const url = new URL(value);
+  const match = /^(|\/market)\/skills\/bundles\/([^/]+)(?:\/versions\/([a-f0-9]{64}))?\/metadata$/.exec(url.pathname);
+  if (url.username || url.password || url.search || url.hash || !match)
+    throw Error('MARKET_METADATA_PATH_MISMATCH');
+  return { url, prefix: match[1], service: match[2], digest: match[3] };
+}
+
+export function marketVersionMetadataUrl(source, digest) {
+  const location = metadataLocation(source);
+  if (!/^[a-f0-9]{64}$/.test(digest) || location.digest && location.digest !== digest)
+    throw Error('MARKET_PACKAGE_VERSION_MISMATCH');
+  location.url.pathname = `${location.prefix}/skills/bundles/${location.service}/versions/${digest}/metadata`;
+  return location.url;
+}
+
 export function marketDownloadUrl(metadataUrl, serviceId) {
-  const url = new URL(metadataUrl);
-  const suffix = `/skills/bundles/${encodeURIComponent(serviceId)}/metadata`;
-  if (
-    url.username ||
-    url.password ||
-    url.search ||
-    url.hash ||
-    !url.pathname.endsWith(suffix)
-  )
-    throw Error("MARKET_METADATA_PATH_MISMATCH");
-  const prefix = url.pathname.slice(0, -suffix.length);
-  if (!["", "/market"].includes(prefix))
-    throw Error("MARKET_METADATA_PREFIX_INVALID");
-  url.pathname = prefix + suffix.replace(/\/metadata$/, "/download");
+  const {url, service} = metadataLocation(metadataUrl);
+  if (service !== encodeURIComponent(serviceId)) throw Error('MARKET_METADATA_PATH_MISMATCH');
+  url.pathname = url.pathname.replace(/\/metadata$/, '/download');
   return url;
 }

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/official-test-package.mjs

@@ -8,8 +8,8 @@ import { createHash } from "node:crypto";
 // This belongs to the official onboarding test, never generic Runtime routing.
 export const OFFICIAL_TEST_PACKAGE = Object.freeze({
   name: "agentpay-random",
-  version: "1.2.0",
-  sha256: "aa366fc2e747b5b444786d542b0a412a505e58ea15252ac1a792b99079084146",
+  version: "1.2.1",
+  sha256: "20633b314c66166f94dc6e7d7eb5bce54ab5901fb1ed314a04ea3fd49ca8a9a4",
 });
 const mismatch = () =>
   Object.assign(

package/src/official-test-update.mjs

@@ -10,7 +10,7 @@ import {
   verifyOfficialTestBytes,
   verifyOfficialTestDigest,
 } from "./official-test-package.mjs";
-import { marketDownloadUrl } from "./market-download-url.mjs";
+import { marketDownloadUrl, marketVersionMetadataUrl } from "./market-download-url.mjs";
 
 async function localJson(path) {
   let handle;
@@ -48,6 +48,8 @@ async function download(fetchImpl, address, max) {
     redirect: "error",
     signal: AbortSignal.timeout(10000),
   });
+  if ([404, 410].includes(response.status))
+    throw Object.assign(Error("Official test version unavailable"), {code: "OFFICIAL_TEST_VERSION_UNAVAILABLE"});
   if (!response.ok || !response.body) throw Error("Market request failed");
   let length = 0;
   const chunks = [];
@@ -99,13 +101,7 @@ export async function prepareOfficialTestUpdate({
       );
       return { status: "unconfigured" };
     }
-    const metadataUrl = url(source);
-    if (
-      !/^\/(?:market\/)?skills\/bundles\/[^/]+\/metadata$/.test(
-        metadataUrl.pathname,
-      )
-    )
-      throw Error("Invalid package metadata path");
+    const metadataUrl = marketVersionMetadataUrl(url(source), OFFICIAL_TEST_PACKAGE.sha256);
     const body = JSON.parse(
       (await download(fetchImpl, metadataUrl, 65536)).toString("utf8"),
     );
@@ -150,6 +146,8 @@ export async function prepareOfficialTestUpdate({
       write(
         "Not updated: the published ZIP does not match this User release. Check for a reviewed User update; do not bypass the file check.",
       );
+    else if (error.code === "OFFICIAL_TEST_VERSION_UNAVAILABLE")
+      write("This official test version is unavailable in Market. Check for a reviewed User update or contact support; no replacement package was selected.");
     else
       write(
         "Could not prepare the official test Skill. Check your Market connection and retry agentpay repair.",

package/update-pair.json

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