@c4roa0/agentpay-user 0.3.6 → 0.3.7

package/doc/README.md

@@ -1,5 +1,7 @@
 # User documentation
 
+- [Existing-installation update acceptance](records/npm-update-participant-2026-11-11.md): participant update to User 0.3.6 / Wallet 0.3.3 and retained records.
+
 - [Directory npm update verification](records/local-npm-update-2026-11-08.md): real package update and preflight boundary.
 
 ## Start by role

package/doc/TODO.md

@@ -1,7 +1,19 @@
 # User TODO
 
+- [x] Participant directory-local update to User 0.3.6 / Wallet 0.3.3: running versions, original Orders in CLI/Market and available result cache verified (2026-11-11).
+- [ ] Fresh-install and interrupted-update acceptance remain separate; discuss scope before execution.
+
+
+- [x] Clarify full Cache IDs and missing details argument; support bounded, unique read-only short-ID lookup (2026-11-11).
+- [ ] Publish cache-details guidance with the next reviewed User release.
+
+
+- [x] Clarify npm update preview with actual installed Wallet versus target, unchanged and unknown states (2026-11-11).
+- [ ] Include update-preview wording in the next reviewed User release; no new release was made for this edit.
+
+
 - [x] Preserve maintenance error guidance and original request identity; controlled HTTP/IPC verification (2026-11-10).
-- [ ] Include maintenance guidance in the next reviewed npm release; no release performed by this change.
+- [x] Publish User 0.3.6 with exact Wallet 0.3.3 dependency; registry identity/integrity verified (2026-11-10).
 
 ## Existing Market address update
 

package/doc/records/npm-update-participant-2026-11-11.md

@@ -0,0 +1,25 @@
+# Existing npm installation update acceptance
+
+Date: 2026-11-11. Evidence: participant terminal output and website confirmation.
+
+The participant updated a directory-local npm installation through `agentpay update`:
+User 0.3.5 to 0.3.6, with matching Wallet 0.3.3. The update repaired service paths,
+restarted Wallet and Runtime, and verified official test Skill 1.2.1 against the
+built-in SHA-256 without starting a purchase. After deliberate unlock, status
+reported Wallet 0.3.3 and Runtime 0.3.6 running, with local history checks complete.
+
+Both saved Orders remained settled. Policy validity, login startup and the locally
+saved Market connection remained present. The participant confirmed both Orders
+were still visible on the website. The retained result cache listed its original
+timestamp and Order association, and details reported the JSON result available
+(28-byte content, approximately 3.4 KiB retained storage). No export or independent
+byte-by-byte backup comparison was performed. The older Order's missing local
+result was already present before updating and was not resolved by this update.
+
+Two usability findings were corrected in source: show installed and target Wallet
+versions separately, and clarify full Cache IDs with bounded unique short-ID lookup
+for read-only details. Controlled tests passed; these fixes are not in npm 0.3.6.
+
+This accepts the observed existing-installation update and retained records. It
+is not fresh-install, interrupted-update recovery, financial reconciliation or
+real-network acceptance. No new payment or authorization was required.

package/package.json

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

package/progress.md

@@ -1,20 +1,63 @@
 # AgentPay User progress
 
-## User 0.3.6 release candidate — 2026-11-10
+## User 0.3.7 release preparation — 2026-11-11
+
+Patch release includes installed/target Wallet version preview and clearer Cache ID
+help with unique short-ID lookup for read-only details. Wallet remains pinned to
+0.3.3 and Protocol to 0.14.3. Manifest, lockfile and update-pair versions are aligned.
+Publication and registry verification are pending; no local participant service or
+private data is changed by preparing the release.
+
+
+## Existing client update accepted — 2026-11-11
+
+Participant directory-local npm update to User 0.3.6 / Wallet 0.3.3 completed.
+Running versions, unlocked Wallet, two settled Orders, unchanged saved validity,
+startup/Market connection and retained available result cache were observed.
+Participant confirmed both original Orders remain visible on Market. The older
+missing result predates this update. No new payment or Policy was created.
+[Evidence and limits](doc/records/npm-update-participant-2026-11-11.md). Update-preview and Cache ID guidance fixes are
+verified in source, not yet published. Fresh installation and interrupted-update
+acceptance remain next for discussion; neither has started in this loop.
+
+
+## Cache details guidance — 2026-11-11
+
+Missing details IDs now show a short example before accessing local storage.
+List guidance explains that the namespace is part of the ID. Read-only details
+accept a unique prefix with at least eight hexadecimal characters; ambiguous,
+missing or incomplete bounded lookups require a full ID. Export and cleanup keep
+their existing exact-identity rules. All 19 targeted cache/CLI regressions passed
+with isolated process tests outside the restricted sandbox; no live cache changed.
+Source only, pending publication. There is no input: ID namespace: inputs use the
+attachment ID shown by list, while results can use result: or runtime-result:0x.
+
+
+## Update preview clarity — 2026-11-11
+
+The confirmation screen now lists installed User and Wallet versions separately
+from update targets. Wallet is read from the installed dependency, not inferred
+from User's requested dependency. Unchanged versions are explicit; unreadable or
+missing Wallet metadata shows “not confirmed” without blocking the normal repair
+through npm. Controlled update tests cover all three cases and cancellation without
+service/install mutation. This source change is not yet published; running-process
+versions remain the responsibility of status after update/restart.
+
+
+## User 0.3.6 published — 2026-11-10
 
 Pins published Wallet 0.3.3, retaining Protocol 0.14.3. Maintenance errors provide
 same-request guidance without automatic write retries. Package manifest, lockfile
-and update-pair metadata agree. Publication uses the matching v0.3.6 tag after
-independent installation and behavior checks; completion is not implied by this
-candidate record. No local data, Policy or service changes occur on publication.
+and update-pair metadata agree. Published through matching tag v0.3.6 after 391 behavior tests and independent
+installation/lifecycle checks. Public npm metadata and SHA-512 match the verified
+archive. No local data, Policy or service changes occur on publication.
 
 
 ## Maintenance guidance — 2026-11-10
 
 Added explicit maintenance guidance without automatic write retries or replacement
 purchases. Controlled HTTP/IPC tests verify that retry retains original request
-identifiers. This is source verification, not live financial acceptance. Changes
-have not been published to npm.
+identifiers. This is source verification, not live financial acceptance. These changes were subsequently published in 0.3.6; see the release record above.
 
 
 ## Acceptance bookkeeping — 2026-11-10

package/src/cache-management-cli.mjs

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

package/src/npm-update.mjs

@@ -7,6 +7,7 @@ import { access, appendFile, copyFile, chmod, lstat, mkdir, mkdtemp, open, readF
 import { constants } from 'node:fs';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
 import { createInterface } from 'node:readline/promises';
 import { installedUserDir, resolveUserDataDir, rememberUserDataDir } from './local-data-directory.mjs';
 import { installationDirectory } from './installation-paths.mjs';
@@ -91,7 +92,18 @@ export async function updateFromNpm({
       await officialTest({userDir,dataDir,write});
       return 0;
     }
-    write(`User ${current.version} → ${metadata.version} · Wallet ${metadata.dependencies['@c4roa0/agentpay-wallet']}`);
+    // Read the installed dependency, not the version requested by User's manifest.
+    // Missing/broken packages must not prevent npm from repairing the installation.
+    let walletVersion;
+    try {
+      const file = createRequire(join(userDir,'package.json')).resolve('@c4roa0/agentpay-wallet/package.json');
+      const wallet = JSON.parse(await readFile(file,'utf8'));
+      if(wallet.name === '@c4roa0/agentpay-wallet' && stable(wallet.version)) walletVersion = wallet.version;
+    } catch {}
+    const targetWallet = metadata.dependencies['@c4roa0/agentpay-wallet'];
+    write('Installed packages → update target');
+    write(`User    ${current.version} → ${metadata.version}`);
+    write(`Wallet  ${walletVersion === targetWallet ? `${walletVersion} (unchanged)` : `${walletVersion || 'not confirmed'} → ${targetWallet}`}`);
     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') {

package/update-pair.json

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