@c4roa0/agentpay-user 0.3.11 → 0.3.12

package/doc/TODO.md

@@ -1,12 +1,19 @@
 # User TODO
 
+- [x] Participant 0.3.11 update resumed original installation; unlock/status confirmed original Policy, Market connection and two settled Orders after restoring Anvil forwarding.
+- [x] Prepare resumed switch without premature startup; preserve repair checkpoint across current-version interruption.
+- [x] Show setup guidance for a fresh unfinished installation, without treating missing established Wallet files as new setup.
+- [x] Classify chain RPC transport failure in Wallet and show actionable User recovery guidance; controlled RPC/IPC tests passed.
+- [ ] Publish Wallet RPC guidance, pin its verified package in User, then publish and verify combined cleanup.
+
 - [x] Allow update of an exact confirmed stopped switch target, then resume using new code; preserve retry checkpoint and reject other targets/live services (controlled verification).
-- [ ] Publish and accept the update recovery path; document one-time bootstrap for older updaters already blocked before download.
+- [x] Publish User 0.3.11 update recovery and document one-time bootstrap for older blocked updaters; tag/package integrity verified.
+- [x] Participant update recovery after bootstrap preserved original Wallet/Policy/Orders (2026-11-12).
 
 - [x] Fix switching back from setup cancelled before Wallet creation; retain stop/listener and established-data checks.
 - [x] Publish User 0.3.10 switch-back fix; matching tag and npm integrity verified.
 - [ ] Verify participant switch-back to the original installation after installing 0.3.10.
-- [ ] Improve unconfigured installation status/info: direct to setup, not service start or missing-key recovery.
+- [x] Improve unconfigured installation status/info: direct to setup, not service start or missing-key recovery (unreleased).
 
 - [x] Verify local official Skill files before downloading and stream update repair progress (2026-11-12; targeted checks).
 - [x] Publish local official-Skill verification and streaming update progress in User 0.3.9; tag and npm integrity verified (2026-11-12).

package/doc/usage.md

@@ -72,3 +72,17 @@ User 0.3.9 and 0.3.10 stop before downloading when unit replacement is unfinishe
 For those versions only, install the intended fixed User version with npm in the
 same program folder, then run `agentpay service start` there. Do not uninstall or
 create a replacement Wallet to recover an interrupted switch.
+
+### Setup and connection warnings
+
+An installation whose setup was cancelled before Wallet creation displays
+“Setup not finished”; continue with `agentpay setup`. Existing Wallet records with
+missing files instead require review; do not create a replacement Wallet.
+
+“Cannot connect to the chain RPC” refers to the blockchain connection, not the
+Market website. Restore the RPC connection and any SSH forwarding used by your
+deployment. Keep Wallet unlocked; Runtime retries the original Order checks.
+Manual `agentpay orders status ORDER_ID` also retries without making a payment.
+
+Update recovery prepares the selected installation first; repair performs the
+final service start. If interrupted between these steps, rerun `agentpay update`.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@c4roa0/agentpay-user",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "type": "module",
   "dependencies": {
     "@c4roa0/agentpay-protocol": "0.14.3",
-    "@c4roa0/agentpay-wallet": "0.3.3",
+    "@c4roa0/agentpay-wallet": "0.3.4",
     "ethers": "^6.17.0",
     "fs-native-extensions": "1.5.3"
   },

package/progress.md

@@ -1,8 +1,42 @@
 # AgentPay User progress
 
+## User 0.3.12 release candidate — 2026-11-12
+
+Pins published Wallet 0.3.4 for actionable RPC errors. Includes single-start update
+recovery and incomplete-setup guidance, including missing-Policy and mixed-error
+review fixes. All 66 targeted User checks passed; tag publication and participant
+acceptance remain pending.
+
+## Participant recovery and guidance cleanup — 2026-11-12
+
+Participant installed User 0.3.11 and resumed the original installation through
+update. After unlock and restoring the Anvil tunnel, status showed Wallet 0.3.3 /
+Runtime 0.3.11, original Policy/Market connection and two settled Orders. The old
+missing-result warning remains separate. This verifies return from incomplete B;
+B has not run as a configured independent Wallet/Runtime pair.
+
+Unreleased cleanup prepares the switch without starting services, then repair
+starts them once. Current-version recovery now saves a repair checkpoint before
+selecting units. Status/info distinguish fresh incomplete setup from lost existing
+Wallet files. Wallet classifies RPC transport failure without exposing raw errors;
+User preserves the code through recovery, status and Order guidance. Targeted tests
+use temporary files, controlled service management and real local RPC/IPC failure;
+they do not establish participant acceptance of these new changes. Publish Wallet
+first, then pin the verified release in User before publishing the combined change.
+
+Review follow-up: missing Policy with saved Order history or a Market connection
+now requires file recovery, while key-only first setup can continue. Mixed RPC
+and manual-review Order issues lead to the Order list rather than network-only
+guidance. All 24 targeted info/status checks passed using temporary files and
+controlled status observations; no participant data or services changed.
+
 ## Update recovery during an unfinished switch — 2026-11-12
 
-User 0.3.11 candidate: the updater may replace the exact previously confirmed switch target
+Published as `v0.3.11` at `6cf9f0d`. Full CI behavior and standalone package checks
+passed; npm archive integrity independently verified. Wallet remains 0.3.3.
+[Release workflow](https://github.com/c4rO-0/agentpay-user/actions/runs/43178613605).
+
+User 0.3.11: the updater may replace the exact previously confirmed switch target
 only after managed services and known listeners are stopped. It retains the switch
 journal, runs the new service command after package installation, then repairs the
 installation. A failed resume keeps the update checkpoint for retry; another target

package/src/local-info.mjs

@@ -1,3 +1,4 @@
+import { inspectLocalSetup } from "./local-setup-state.mjs";
 // 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/.
@@ -89,7 +90,20 @@ export async function showLocalInfo({
     );
     return 1;
   }
-  let incomplete = false;
+  const setup = await inspectLocalSetup(dataDir);
+  if (setup.state === "needed") {
+    write([
+      "------------------------------------------------------------",
+      "> Wallet information",
+      "------------------------------------------------------------",
+      "[WAIT] Setup not finished",
+      setup.hasKey ? "Your local key is saved. Continue setup to finish this installation." : "No Wallet has been created for this installation yet.",
+      "", "Data folder", "  " + dataDir,
+      "", "Next", "  " + setup.next,
+    ].join("\n"));
+    return 0;
+  }
+  let incomplete = setup.state === "attention";
   const read = async (name) => {
     try {
       return await privateJson(dataDir, name);
@@ -119,6 +133,11 @@ export async function showLocalInfo({
     "> Wallet information",
     divider,
     "Saved settings · live status: agentpay status",
+    ...(setup.state === "attention" ? [
+      "[!] Local Wallet files need attention",
+      "Keep this data folder. Check missing files against your backup before continuing.",
+      "Do not create a replacement Wallet to recover existing Orders.",
+    ] : []),
     ...section("Wallet & authorization"),
     `  Network: ${Number.isSafeInteger(policy?.chainId) && policy.chainId > 0 ? `eip155:${policy.chainId}` : "Not recorded"}`,
     ...field("Safe account", address(policy?.safe)),

package/src/local-setup-state.mjs

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MPL-2.0
+// Distinguish an unfinished first setup from missing data in an existing Wallet.
+// This is read-only guidance; it never creates keys or changes installation routing.
+import {lstat} from 'node:fs/promises';
+import {join} from 'node:path';
+
+export async function inspectLocalSetup(dataDir) {
+  try {
+    for (const path of [dataDir,join(dataDir,'wallet'),join(dataDir,'runtime')]) {
+      const info=await lstat(path).catch(e=>{if(e.code==='ENOENT')return null;throw e;});
+      if(info && (!info.isDirectory() || info.isSymbolicLink() || info.uid!==process.getuid() || info.mode & 0o077))
+        return {state:'attention'};
+    }
+    async function present(name) {
+      const info=await lstat(join(dataDir,name)).catch(e=>{if(e.code==='ENOENT')return null;throw e;});
+      if(!info)return false;
+      if(!info.isFile() || info.isSymbolicLink() || info.uid!==process.getuid() || info.mode & 0o077)throw Error('Unsafe saved file');
+      return true;
+    }
+    const key=await present('wallet/session.keystore.json');
+    const policy=await present('wallet/policy.json');
+    const settings=await present('runtime/local-services.json');
+    if(key && policy && settings)return {state:'ready'};
+    // A saved connection or Order history indicates prior use. A key alone can
+    // belong to an interrupted first setup and must still allow setup to resume.
+    const priorUse=await present('market-connection.json') || await present('runtime/invocations.json');
+    if(!policy && priorUse)return {state:'attention'};
+    const prior=policy || priorUse || await present('runtime/connection.json');
+    if(!key && prior)return {state:'attention'};
+    if(policy && !settings)return {state:'attention'};
+    const deployment=await present('user-deployment.json') || await present('anvil-onboarding.json');
+    return {state:'needed',hasKey:key,next:deployment ? 'agentpay setup' : 'agentpay install --market YOUR_MARKET_URL'};
+  } catch {return {state:'attention'};}
+}

package/src/npm-update.mjs

@@ -110,7 +110,8 @@ async function updateUnderLock({
     const resumeSwitch = async options => {
       if (!scope.resumeSwitch) return;
       write('Continuing your previously confirmed installation switch…');
-      const output = await service('start',options);
+      // Prepare the confirmed target without launching it; repair starts it once.
+      const output = await service('activate-setup',options);
       if(output)write(output);
     };
     if (pending && current.version === pending.targetVersion) {
@@ -144,8 +145,17 @@ async function updateUnderLock({
           write('Update cancelled. The saved switch was kept.'); return 0;
         }
         const options={env:{...process.env,AGENTPAY_USER_DATA_DIR:dataDir},cwd:target.prefix,timeout:600000};
+        // Even without a new package, keep repair resumable if the process exits
+        // after selecting the target units but before the one final service start.
+        if (!stable(current.dependencies?.['@c4roa0/agentpay-wallet']) || !stable(current.dependencies?.['@c4roa0/agentpay-protocol']))
+          throw Error('Installed package dependencies could not be verified.');
+        await atomicWritePrivate(progressPath, JSON.stringify({version:1,installation:userDir,dataDir,
+          targetVersion:current.version,walletVersion:current.dependencies['@c4roa0/agentpay-wallet'],
+          protocolVersion:current.dependencies['@c4roa0/agentpay-protocol']}) + '\n');
+        installing = true;
         await resumeSwitch(options);
         const output=await repair(options); if(output)write(output);
+        await unlink(progressPath);
         return 0;
       }
       write(`User ${current.version} is current. Checking the official test Skill.`);

package/src/order-review.mjs

@@ -256,13 +256,15 @@ export function localReviewDetails(
   if (
     unknownOriginal ||
     unavailable ||
-    (o?.errorCode && o.errorCode !== "ORDER_CHECK_UNAVAILABLE")
+    (o?.errorCode && !["ORDER_CHECK_UNAVAILABLE", "CHAIN_RPC_UNAVAILABLE"].includes(o.errorCode))
   ) {
     text(
       "Check the original Agent conversation and payment history. If still unclear, contact AgentPay support with the reference IDs below.",
     );
     text("Do not create another purchase to resolve this record.");
-  } else if (o?.errorCode === "ORDER_CHECK_UNAVAILABLE")
+  } else if (o?.errorCode === "CHAIN_RPC_UNAVAILABLE")
+    text("Restore the chain RPC connection and any SSH tunnel. Keep Wallet unlocked; Runtime retries automatically. Do not pay again.");
+  else if (o?.errorCode === "ORDER_CHECK_UNAVAILABLE")
     text(
       "Runtime retries automatically. Keep Wallet unlocked and check your network if this continues.",
     );
@@ -358,6 +360,8 @@ export function localOrderSummary(entry, observation, review) {
       ? "SETTLED_RESULT_UNAVAILABLE"
       : null);
   const reasons = {
+    CHAIN_RPC_UNAVAILABLE:
+      "Cannot connect to the chain RPC. Check your network and any SSH tunnel. Runtime retries automatically; keep the original request.",
     RECOVERY_POLICY_UNAVAILABLE:
       "Original Policy cannot authorize this check (it may be revoked or belong to another key).",
     ORIGINAL_POLICY_UNKNOWN:

package/src/order-status-panel.mjs

@@ -42,11 +42,13 @@ export async function showOrderStatus({
     return 0;
   } catch (error) {
     write("\n> Order status");
-    write("[WAIT] Could not update from Settlement");
+    write(error.code === "CHAIN_RPC_UNAVAILABLE" ? "[WAIT] Cannot connect to the chain RPC" : "[WAIT] Could not update from Settlement");
     write(
       ["LOCKED", "WALLET_LOCKED"].includes(error.code)
         ? "Unlock Wallet: agentpay wallet unlock"
-        : "Check agentpay status and your network, then retry this query.",
+        : error.code === "CHAIN_RPC_UNAVAILABLE"
+          ? "Check your network and any SSH port forwarding, then retry this query. No new payment is needed."
+          : "Check agentpay status and your network, then retry this query.",
     );
     const summary = localOrderSummary(entry, observation, review);
     write("\n> Last local record · not refreshed");

package/src/runtime-recovery.mjs

@@ -32,6 +32,7 @@ const resultIssue = (o) =>
           ? "SETTLED_RESULT_UNAVAILABLE"
           : null;
 const knownCodes = new Set([
+  "CHAIN_RPC_UNAVAILABLE",
   "LOCKED",
   "POLICY_UNBOUND",
   "POLICY_MIGRATION_PENDING",

package/src/status-panel.mjs

@@ -1,3 +1,4 @@
+import { inspectLocalSetup } from "./local-setup-state.mjs";
 import { assessRunningSoftware } from "./software-versions.mjs";
 import { walletCliPath } from "./wallet-package.mjs";
 // SPDX-License-Identifier: MPL-2.0
@@ -179,10 +180,12 @@ export async function collectLocalStatus() {
     readAuthorizationStatus(dataDir),
     readMarketStatus(dataDir),
     inspectDeploymentStatus(dataDir),
+    inspectLocalSetup(dataDir),
   ]);
   const value = (i) =>
     results[i].status === "fulfilled" ? results[i].value : null;
   return {
+    setup: value(7),
     software: assessRunningSoftware(value(0), value(3)),
     deployment: value(6) || { state: "unknown" },
     market: value(5) || { state: "unknown" },
@@ -279,7 +282,7 @@ export function renderStatusPanel(
   const onlyRetryable =
     r?.orders.review > 0 &&
     issues.length === r.orders.review &&
-    issues.every((issue) => issue.code === "ORDER_CHECK_UNAVAILABLE");
+    issues.every((issue) => ["ORDER_CHECK_UNAVAILABLE", "CHAIN_RPC_UNAVAILABLE"].includes(issue.code));
   const stopped = (s) =>
     s && ["failed", "inactive", "deactivating"].includes(s.ActiveState);
   let title = "Local checks passed",
@@ -292,6 +295,16 @@ export function renderStatusPanel(
     detail =
       "Your saved installation could not be read. Keep your existing Wallet data.";
     next = "agentpay service logs runtime";
+  } else if (model.setup?.state === "needed") {
+    title = "Setup not finished";
+    level = "wait";
+    detail = "Complete setup for this installation before starting its services.";
+    next = model.setup.next;
+  } else if (model.setup?.state === "attention") {
+    title = "Local Wallet files need attention";
+    level = "error";
+    detail = "Existing files are missing or could not be safely checked. Keep this data folder; do not create a replacement Wallet.";
+    next = "agentpay wallet info";
   } else if (model.deployment?.state === "changed") {
     title = "Spending permission needs updating";
     level = "error";
@@ -384,6 +397,11 @@ export function renderStatusPanel(
     detail =
       "Platform deployment check is unavailable. Check your network and retry.";
     next = "agentpay status";
+  } else if (onlyRetryable && issues.some(issue => issue.code === "CHAIN_RPC_UNAVAILABLE")) {
+    title = "Cannot connect to the chain RPC";
+    level = "wait";
+    detail = "Check your network and any SSH port forwarding. Order checks retry automatically; do not repeat purchases.";
+    next = "Restore the connection, then run agentpay status.";
   } else if (onlyRetryable) {
     title = "Order checks temporarily unavailable";
     level = "wait";
@@ -447,7 +465,7 @@ export function renderStatusPanel(
     "",
   ];
   if (!model.configurationError) {
-    if (model.software) {
+    if (model.software && model.setup?.state !== "needed") {
       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("");
@@ -461,15 +479,17 @@ export function renderStatusPanel(
         ? w.locked
           ? "Running · locked"
           : "Running · unlocked"
+        : model.setup?.state === "needed"
+          ? "Not started · setup needed"
         : stopped(ws)
           ? "Stopped"
           : "Not checked",
-      w ? (w.locked ? "wait" : "ok") : "error",
+      w ? (w.locked ? "wait" : "ok") : model.setup?.state === "needed" ? "wait" : "error",
     );
     row(
       "Runtime",
-      r ? "Running" : stopped(rs) ? "Stopped" : "Not checked",
-      r ? "ok" : "error",
+      r ? "Running" : model.setup?.state === "needed" ? "Not started · setup needed" : stopped(rs) ? "Stopped" : "Not checked",
+      r ? "ok" : model.setup?.state === "needed" ? "wait" : "error",
     );
     if (r)
       row(
@@ -489,7 +509,9 @@ export function renderStatusPanel(
       );
     lines.push("", "> Policy");
     const policyState =
-      model.deployment?.state === "changed"
+      model.setup?.state === "needed"
+        ? ["wait", "Setup not finished"]
+        : model.deployment?.state === "changed"
         ? ["error", "Update required · deployment changed"]
         : w?.policyRenewalPending
           ? ["wait", "Renewal incomplete"]
@@ -509,7 +531,7 @@ export function renderStatusPanel(
       lines.push(
         `  Valid until: ${new Date(authorization.validUntil * 1000).toLocaleString()}`,
       );
-    if (model.deployment?.state === "unknown")
+    if (model.deployment?.state === "unknown" && model.setup?.state !== "needed")
       lines.push(`  ${badge("wait")} Platform compatibility not confirmed`);
     if (model.deployment?.state === "downloaded")
       lines.push(

package/update-pair.json

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