@c4roa0/agentpay-user 0.3.0 → 0.3.1

package/README.md

@@ -8,13 +8,14 @@ User is the Agent/Skill runtime, not a Provider server or a general-purpose wall
 It retains request identity and local results so interruptions can be recovered
 without silently creating a replacement purchase.
 
-## Install
+## Install with npm
 
-Use Linux with Node.js 22.22.3 or newer and npm. Install User; its reviewed Wallet
-and Protocol dependencies are included automatically:
+On Linux, prepare Node.js 22.22.3 or newer, npm and your AgentPay Market address.
+Install User with the command below. It automatically installs the matching Wallet
+and Protocol packages; you do not need to download two repositories:
 
 ```sh
-npm install --global @c4roa0/agentpay-user@0.3.0
+npm install --global @c4roa0/agentpay-user@0.3.1
 agentpay install --market https://YOUR_MARKET_ORIGIN
 ```
 
@@ -22,19 +23,6 @@ Replace the Market URL with your platform's address. Use a user-owned Node/npm
 installation with Node and npm's executable directory on PATH. No Wallet checkout,
 Corepack, pnpm or TypeScript build is needed.
 
-For contributors or source ZIP users:
-
-```sh
-git clone https://github.com/c4rO-0/agentpay-user.git user
-cd user
-npm ci
-npm link
-agentpay help
-```
-
-`npm link` exposes the command from your checkout. Without linking, `./run` (or
-`sh run`) provides the same commands; `AGENTPAY_NODE` can select your Node executable.
-
 Install verifies dependencies, downloads public settings and continues setup.
 You choose the Safe and spending limits, then approve with its owner wallet.
 The optional official payment test asks before spending. Never enter an owner
@@ -63,6 +51,19 @@ update their files, run `npm ci`, then `agentpay repair`. [Commands](doc/runbook
 
 ## Develop or integrate
 
+For contributors or source ZIP users:
+
+```sh
+git clone https://github.com/c4rO-0/agentpay-user.git user
+cd user
+npm ci
+npm link
+agentpay help
+```
+
+`npm link` exposes the command from your checkout. Without linking, `./run` (or
+`sh run`) provides the same commands; `AGENTPAY_NODE` can select your Node executable.
+
 - [Developer guide](doc/develope.md): independent checkout, focused tests and evidence limits.
 - [Architecture](doc/architecture.md): source map and recovery/authorization boundaries.
 - [Skill author guide](doc/runbooks/runtime-skill-client.md): call the shared Runtime client.

package/doc/TODO.md

@@ -1,5 +1,15 @@
 # User TODO
 
+## Running-version release loop — 2026-11-07
+
+- [x] Verify User 0.3.0 public-registry publication; Trusted Publisher configured.
+- [x] Verify actual installed Protocol versions from both consumer resolution paths.
+- [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.
+
+
 ## npm update follow-up — 2026-11-07
 
 - [x] Implement confirmed `agentpay update [-f]`, exact User target and matching Wallet; invoke new repair and pinned official Skill check.
@@ -19,7 +29,7 @@
 - [ ] 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 OIDC with a later reviewed release. User publication and Market guide updates remain pending.
+  - [ ] Validate Wallet and User OIDC with later reviewed releases. Both 0.3.0 packages are published; Market guide updates remain pending.
 - [ ] Step 6: participant setup/upgrade/restart/uninstall and official Anvil paid acceptance.
 
 

package/doc/architecture.md

@@ -18,7 +18,7 @@ logic or platform storage. No Settlement checkout or database access is required
 ## Shared Protocol dependency
 
 User and Wallet pin `@c4roa0/agentpay-protocol@0.14.3` from npm. Their lockfiles
-record integrity. The current repair gate still checks the exact repository versions
+record integrity. The current repair gate still checks the exact package versions
 and shared Protocol dependency in `update-pair.json`; `typesDependency` is the
 retained v1 field name for that npm version. It is not a compatibility range.
 Installation/repair fingerprints cover manifests and lockfiles rather than a vendor
@@ -85,8 +85,11 @@ verification before binding. A lost response resumes the original plan.
 ## External dependencies and development boundary
 
 User resolves the installed Wallet package through public client, local-administration
-and CLI exports. Exact reviewed dependency versions are checked; independent
-running-process compatibility negotiation remains planned. User imports ethers from its own
+and CLI exports. `wallet-package.mjs` verifies the exact reviewed pair;
+`protocol-package.mjs` resolves each consumer's actual Protocol installation, including
+nested npm dependencies. `software-versions.mjs` compares process-start reports with
+the installed pair during status/repair. User 0.3.1 pins Wallet 0.3.1 for these checks; broader compatibility ranges remain deferred.
+User imports ethers from its own
 declared dependency. The pinned public Protocol package provides types, hashes and
 fixtures. No Agent, Protocol source checkout or private platform repository is
 required for the local test suite.

package/doc/plans/user-wallet-distribution.md

@@ -9,8 +9,8 @@ Repositories, processes and releases remain separate; Node is still required.
 Ordinary users install `@c4roa0/agentpay-user` and run `agentpay setup`. User installs
 its reviewed Wallet dependency; both consume public Protocol. No sibling source
 folders, pnpm or local TypeScript build are required for the published User path.
-Wallet remains independently installable. Git checkouts are for contributors; the User 0.3.0 candidate now uses the same
-public Wallet package. User npm publication remains a separate release step.
+Wallet remains independently installable. Git checkouts are for contributors; the User 0.3.0 release uses the public Wallet package. User 0.3.1 pairs with
+Wallet 0.3.1 for running-version verification; publication remains a separate release step.
 Combined ZIPs and platform binaries are optional later work, not a release prerequisite.
 
 npm installation only installs program files. Key creation, background-service

package/doc/reference/npm-integration-verification.md

@@ -65,3 +65,39 @@ The existing official-package tests cover pinned digest rejection and preservati
 The updater follows npm's [install](https://docs.npmjs.com/cli/v11/commands/npm-install/)
 and [view](https://docs.npmjs.com/cli/v11/commands/npm-view/) command interfaces.
 A released-version registry upgrade and participant recovery still need acceptance.
+
+## Running-process reporting follow-up — 2026-11-07
+
+User 0.3.0 first publication was verified against the public registry. User and Wallet
+Trusted Publishers are configured; first OIDC validation is still pending.
+
+The next candidate checks process-start package/interface/Protocol metadata during
+status and repair. User regressions: 378 passed; Wallet behavioral suite: 30 passed.
+Wallet tarball consumption passed real CLI/IPC checks. A disposable User install with
+a local Wallet 0.3.1 archive and temporary test-only dependency pin passed real process
+startup/restart and key preservation. Missing/mismatched reports prevent repair from
+recording success. No Policy, Order or participant service was changed.
+
+These results do not establish a published-version upgrade: publish Wallet 0.3.1,
+then update User's exact pin, lockfile and pairing metadata and verify its final archive.
+The repository still pins public Wallet 0.3.0 until that release exists.
+
+## Actual installed Protocol verification — 2026-11-08
+
+Preflight checks resolved package versions from both User and Wallet, including a
+nested Wallet dependency. A mismatched copy is rejected even if both consumer
+manifests declare the expected version. Process reporting records the resolved
+version at startup. Wallet's 30 tests and standalone archive CLI/IPC checks passed;
+User's final 378-test suite passed after updating a dependency-less test fixture.
+This is local compatibility verification, not a guarantee against altered package files.
+Wallet candidate `7e4d4fa` is pushed; OIDC publication and User exact pin/lockfile
+update remain the release gate.
+
+## User 0.3.1 final pairing — 2026-11-08
+
+User 0.3.1 pins public Wallet 0.3.1 and Protocol 0.14.3. Lockfile integrity came from
+the public registry; no local file dependency or sibling checkout is required.
+The complete suite passed (378 tests). The npm archive installed independently,
+exposed `agentpay`, and started/restarted real disposable Wallet/Runtime processes
+with matching software reports while preserving the key and starting Wallet locked.
+Publication via GitHub OIDC and participant upgrade remain separate pending steps.

package/doc/runbooks/commands.md

@@ -87,3 +87,17 @@ independently query the chain. If querying fails, the command labels the last
 local record and its saved check time. A successful query does not rewrite local
 history; Runtime maintains its own recovery observations. Use
 `agentpay orders details ID` for the saved local record.
+
+## Running-version checks (User 0.3.1)
+
+`agentpay status` compares the installed User/Wallet pair with the versions reported
+by the running processes. A mismatch leads to `agentpay repair`; missing reporting
+requires a paired package update first. Repair only records success after both
+processes report the expected package, local reporting interface and Protocol versions.
+These checks do not change Policy validity, Order identity or payment permissions.
+User 0.3.1 installs the required Wallet 0.3.1 dependency automatically.
+
+Protocol reporting reads the installed package resolved by that process, rather than
+copying its dependency declaration. User preflight checks both User's and Wallet's
+resolved copies against the reviewed exact version, including nested dependencies.
+Package version checks establish compatibility metadata, not file-integrity attestation.

package/package.json

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

package/progress.md

@@ -1,12 +1,44 @@
 # AgentPay User progress
 
-## User 0.3.0 first publication prepared — 2026-11-07
-
-Owner authorized the first npm publication. The package's private gate is removed;
-README now describes the npm entry and exact Wallet dependency. GitHub `publish.yml`
-uses the `npm-publish` environment and OIDC for subsequent releases. Initial Token
-upload, public-registry verification and Trusted Publisher validation are pending.
-No published-success claim is made by the prepared package or workflow.
+## User 0.3.1 paired release preparation — 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.
+This release adds actual installed Protocol verification and running-version checks
+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.
+No participant services, keys, Policies or Orders are changed by package verification.
+
+## 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
+just dependency declarations. Wallet 0.3.1 candidate passed behavioral and independent
+package checks and is pushed as `7e4d4fa`; its OIDC publication is the next operator step.
+User remains pinned to public Wallet 0.3.0 until the new registry release exists;
+then update its exact dependency, lockfile and pairing metadata together. User changes
+remain unreleased. No participant service, key, Policy or Order was changed.
+
+## User 0.3.0 published; running-version checks in development — 2026-11-07
+
+`@c4roa0/agentpay-user@0.3.0` was published from User `86ee8e7`.
+Public registry version/latest and archive integrity matched the verified artifact.
+User and Wallet Trusted Publishers are configured; first OIDC releases remain pending.
+Earlier candidate sections below are historical, not current publication status.
+
+Wallet 0.3.1 candidate reports process-start software metadata. User status and repair
+compare running package/interface/Protocol versions against the installed pair.
+Missing reporting is unknown, never proof of compatibility. Policy format/version,
+identity and transaction authority are unchanged. Wallet behavioral tests (30) and installed-package IPC checks passed. User full
+regressions (378) passed, followed by final status checks and an isolated candidate
+Wallet/User process restart test. The candidate pair used a temporary test-only pin.
+
+Release gate: publish verified Wallet 0.3.1 first, then update User's exact Wallet pin,
+lockfile and pairing metadata and verify the combined package before publishing User.
+Current User still pins published Wallet 0.3.0; these development changes are not yet
+an installable verified release pair. No participant services/data were changed.
 
 
 ## npm update and migration review fixes — 2026-11-07

package/src/index.mjs

@@ -1,3 +1,4 @@
+import { runtimeSoftware } from "./software-versions.mjs";
 // Authenticated local invocation engine. Preserve durable request/payment checkpoints before
 // network calls; startup reconciliation observes history without creating replacement purchases.
 // SPDX-License-Identifier: MPL-2.0
@@ -127,6 +128,7 @@ const server = createServer(async (req, res) => {
       ok: true,
       result: {
         role: "user-runtime",
+        software: runtimeSoftware,
         capabilities: ["agentpay.runtime-call.v1"],
         walletTransport: "unix",
       },
@@ -144,7 +146,7 @@ const server = createServer(async (req, res) => {
     void recovery.refresh();
     return json(res, 200, {
       ok: true,
-      result: { role: "user-runtime", ...recovery.status() },
+      result: { role: "user-runtime", software: runtimeSoftware, ...recovery.status() },
     });
   }
   if (

package/src/local-update.mjs

@@ -1,3 +1,4 @@
+import { requireRunningSoftware } from "./software-versions.mjs";
 import { walletPackage } from "./wallet-package.mjs";
 // Apply installed packages. Preserve identity/history and startup preferences;
 // preparation failure must not enable a mismatched Wallet/Runtime pair.
@@ -185,12 +186,18 @@ export async function applyLocalUpdate({
           applied.inputs === selected.inputs &&
           applied.outputs === selected.outputs
         ) {
-          await connection({ dataDir, write });
-          phase = "unchanged";
-          write(
-            "Local installation is already up to date. Background services were not changed.",
-          );
-          return false;
+          let runningMatches = false;
+          try {
+            requireRunningSoftware(await wallet(dataDir, "status"), await runtime(dataDir), { ...pair, protocolVersion: pair.typesDependency });
+            runningMatches = true;
+          } catch { /* Keep repair available for old, stopped or unreported processes. */ }
+          if (runningMatches) {
+            await connection({ dataDir, write });
+            phase = "unchanged";
+            write("Local installation and running versions are up to date. Background services were not changed.");
+            return false;
+          }
+          write("Running versions need verification. Repair will restart the paired services.");
         }
         write(
           applied?.status === "pending"
@@ -257,10 +264,12 @@ export async function applyLocalUpdate({
               runtime(dataDir),
             ]);
             if (typeof w.locked === "boolean" && r.role === "user-runtime") {
+              requireRunningSoftware(w, r, { ...pair, protocolVersion: pair.typesDependency });
               ready = true;
               break;
             }
-          } catch {
+          } catch (error) {
+            if (error.code === "RUNNING_VERSION_UNVERIFIED") throw error;
             /* Startup can take a moment; final failure is reported below. */
           }
           await pause(500);
@@ -298,6 +307,7 @@ export async function applyLocalUpdate({
       write(
         "Service changes could not be confirmed. Check agentpay status and agentpay service logs runtime before retrying.",
       );
+    if (error.code === "RUNNING_VERSION_UNVERIFIED") write(error.message);
     const log = error.logPath || logPath;
     if (log) write("Details: " + log);
     write("After resolving the problem, run agentpay repair again.");

package/src/protocol-package.mjs

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MPL-2.0
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+// Resolve from each consumer independently: npm may install a nested Protocol copy.
+// The public schema export works even when package.json is not publicly exported.
+export function installedProtocol(consumerManifest) {
+  const require = createRequire(consumerManifest);
+  let directory = dirname(require.resolve('@c4roa0/agentpay-protocol/schema'));
+  for (;;) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(directory, 'package.json'), 'utf8'));
+      if (pkg.name !== '@c4roa0/agentpay-protocol' || !/^\d+\.\d+\.\d+$/.test(pkg.version)) {
+        throw Error('Installed Protocol package identity is invalid.');
+      }
+      return pkg.version;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    const parent = dirname(directory);
+    if (parent === directory) throw Error('Installed Protocol package metadata is missing.');
+    directory = parent;
+  }
+}

package/src/software-versions.mjs

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: MPL-2.0
+import { installedProtocol } from './protocol-package.mjs';
+import { fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
+
+// Capture once: installed files may be replaced while this process still runs.
+// This local compatibility report is not attestation or payment authority.
+const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+export const runtimeSoftware = Object.freeze({
+  name: '@c4roa0/agentpay-user',
+  version: manifest.version,
+  interfaceVersion: 1,
+  protocolVersion: installedProtocol(fileURLToPath(new URL('../package.json', import.meta.url))),
+});
+
+export function assessRunningSoftware(wallet, runtime, expected = {
+  userVersion: manifest.version,
+  walletVersion: manifest.dependencies['@c4roa0/agentpay-wallet'],
+  protocolVersion: manifest.dependencies['@c4roa0/agentpay-protocol'],
+}) {
+  const components = [
+    ['Wallet', wallet?.software, '@c4roa0/agentpay-wallet', expected.walletVersion],
+    ['Runtime', runtime?.software, '@c4roa0/agentpay-user', expected.userVersion],
+  ];
+  return components.map(([label, reported, name, version]) => {
+    if (!reported) return { label, state: 'unreported', expected: version };
+    const matches = reported.name === name && reported.version === version &&
+      reported.interfaceVersion === 1 && reported.protocolVersion === expected.protocolVersion;
+    return {
+      label, state: matches ? 'matched' : 'mismatch', expected: version,
+      running: typeof reported.version === 'string' && /^\d+\.\d+\.\d+$/.test(reported.version)
+        ? reported.version : 'unknown',
+    };
+  });
+}
+
+export function requireRunningSoftware(wallet, runtime, expected) {
+  const checks = assessRunningSoftware(wallet, runtime, expected);
+  const bad = checks.find(check => check.state !== 'matched');
+  if (bad) {
+    const reason = bad.state === 'unreported' ? 'does not report its running version' :
+      `does not match the installed package/interface (${bad.expected})`;
+    throw Object.assign(Error(`${bad.label} ${reason}. Update the paired packages and run agentpay repair.`), {
+      code: 'RUNNING_VERSION_UNVERIFIED',
+    });
+  }
+  return checks;
+}

package/src/status-panel.mjs

@@ -1,3 +1,4 @@
+import { assessRunningSoftware } from "./software-versions.mjs";
 import { walletCliPath } from "./wallet-package.mjs";
 // SPDX-License-Identifier: MPL-2.0
 // This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
@@ -172,6 +173,7 @@ export async function collectLocalStatus() {
   const value = (i) =>
     results[i].status === "fulfilled" ? results[i].value : null;
   return {
+    software: assessRunningSoftware(value(0), value(3)),
     deployment: value(6) || { state: "unknown" },
     market: value(5) || { state: "unknown" },
     authorization: value(4),
@@ -325,6 +327,13 @@ export function renderStatusPanel(
     detail =
       "Runtime is running. Order checks will continue when Wallet is available.";
     next = stopped(ws) ? "agentpay service start" : "agentpay service logs wallet";
+  } else if (model.software?.some(x => x.state !== "matched")) {
+    title = "Running software needs checking";
+    level = "wait";
+    detail = "Installed files and running processes have not been verified as a matching pair. Your original Orders are kept.";
+    next = model.software.some(x => x.state === "unreported")
+      ? "agentpay update (source checkout: update the paired packages, then agentpay repair)"
+      : "agentpay repair";
   } else if (w.policyRenewalPending) {
     title = "Spending permission renewal incomplete";
     level = "wait";
@@ -422,6 +431,11 @@ export function renderStatusPanel(
     "",
   ];
   if (!model.configurationError) {
+    if (model.software) {
+      lines.push("> Software");
+      for (const item of model.software) lines.push(`  ${badge(item.state === "matched" ? "ok" : "wait", 6)}  ${item.label.padEnd(8)}  ${item.state === "matched" ? item.running : item.state === "unreported" ? "Running version not reported" : item.running === item.expected ? "Package interface mismatch" : `Running ${item.running} · installed ${item.expected}`}`);
+      lines.push("");
+    }
     lines.push("> Services");
     const row = (label, text, state) =>
       lines.push(`  ${badge(state, 6)}  ${label.padEnd(8)}  ${text}`);

package/src/wallet-package.mjs

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: MPL-2.0
 // Resolve public Wallet entries from this User installation, never a sibling checkout.
+import { installedProtocol } from './protocol-package.mjs';
 import { createRequire } from 'node:module';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
@@ -17,6 +18,11 @@ export function walletPackage(userDir = userPackageDirectory) {
       manifest.dependencies?.['@c4roa0/agentpay-protocol'] !== user.dependencies?.['@c4roa0/agentpay-protocol']) {
     throw Error('Installed Wallet does not match this User version. Reinstall the reviewed User version, then run agentpay repair. Your private data is unchanged.');
   }
+  const expectedProtocol = user.dependencies['@c4roa0/agentpay-protocol'];
+  if (installedProtocol(join(userDir, 'package.json')) !== expectedProtocol ||
+      installedProtocol(manifestPath) !== expectedProtocol) {
+    throw Error('Installed Protocol does not match the reviewed User/Wallet pair. Reinstall this User version and its dependencies; private data is unchanged.');
+  }
   return { directory: dirname(manifestPath), manifest, cli: require.resolve('@c4roa0/agentpay-wallet/cli') };
 }
 export function walletCliPath(userDir) { return walletPackage(userDir).cli; }

package/update-pair.json

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