@c4roa0/agentpay-user 0.3.10 → 0.3.12

package/doc/TODO.md

@@ -1,8 +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).
+- [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.
-- [ ] Deliver the fix and verify participant switch-back to the original installation.
-- [ ] Improve unconfigured installation status/info: direct to setup, not service start or missing-key recovery.
+- [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.
+- [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

@@ -60,3 +60,29 @@ then compare its installed files. Matching local files need no download. Missing
 archives trigger a download; changed or incomplete extracted files are kept and
 reported for review. These checks do not start a payment or select a newer Skill
 from Market. Software updates display repair progress while it runs.
+
+### Updating after an interrupted installation switch
+
+From the installation you previously selected, run `agentpay update`. If its
+background services have stopped, the updater can install the new version and
+continue that same switch. It preserves Wallet data and the confirmed target. If
+recovery fails, run the same command again; do not delete the switch records.
+
+User 0.3.9 and 0.3.10 stop before downloading when unit replacement is unfinished.
+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.10",
+  "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,9 +1,61 @@
 # 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
+
+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
+cannot adopt the transition. An existing confirmed switch no longer needs duplicate
+consent during resume. 35 update/selection checks passed with temporary storage,
+real local sockets and controlled npm/systemctl; participant acceptance remains open.
+Already-installed 0.3.9/0.3.10 updaters still reject this state before fetching code,
+so the current stranded installation needs a one-time npm bootstrap. This fix cannot
+retroactively change an installed updater.
+
 ## Participant incomplete-setup switch — 2026-11-12
 
+Published as `v0.3.10` at `6e89266`; 20 targeted selection checks, full CI behavior
+and standalone package checks passed. npm latest and archive integrity independently
+verified. Wallet stays 0.3.3; participant switch-back remains to be verified.
+[Release workflow](https://github.com/c4rO-0/agentpay-user/actions/runs/43173745431).
+
 Participant A-to-B setup cancellation exposed a switch-back failure: B had no
-Wallet directory, but selection required complete service settings. User 0.3.10 candidate
+Wallet directory, but selection required complete service settings. User 0.3.10 fix
 allows demonstrably unconfigured B to release selection after confirmed systemd
 stop and socket checks. Existing key/Policy/connection or invalid directories still
 block missing-configuration bypass. Original participant A remains stopped until

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

@@ -106,7 +106,14 @@ async function updateUnderLock({
     } catch(error) { if(error.code !== 'ENOENT') throw error; }
     dataDir ??= await resolveUserDataDir({userDir});
     if (pending && pending.dataDir !== dataDir) throw Error('The interrupted update belongs to another data folder. Keep its recovery record for review.');
-    const scope = await serviceScope({userDir,dataDir});
+    const scope = await serviceScope({userDir,dataDir,resumeUpdate:true});
+    const resumeSwitch = async options => {
+      if (!scope.resumeSwitch) return;
+      write('Continuing your previously confirmed installation switch…');
+      // 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) {
       installing = true;
       if (current.dependencies?.['@c4roa0/agentpay-wallet'] !== pending.walletVersion ||
@@ -115,6 +122,7 @@ async function updateUnderLock({
       write('Continuing the interrupted update. Checking installed packages and service settings.');
       const configured = await lstat(join(dataDir,'runtime/local-services.json')).then(s=>s.isFile(),e=>{if(e.code==='ENOENT')return false;throw e;});
       if (configured) {
+        await resumeSwitch({env:{...process.env,AGENTPAY_USER_DATA_DIR:dataDir},cwd:target.prefix,timeout:600000});
         const output = await repair({env:{...process.env,AGENTPAY_USER_DATA_DIR:dataDir},cwd:target.prefix,timeout:600000});
         if(output)write(output);
       } else await officialTest({userDir,dataDir,write});
@@ -132,6 +140,24 @@ async function updateUnderLock({
     if (pending && (metadata.version !== pending.targetVersion || metadata.dependencies["@c4roa0/agentpay-wallet"] !== pending.walletVersion || metadata.dependencies["@c4roa0/agentpay-protocol"] !== pending.protocolVersion))
       throw Error("The published package differs from the interrupted update. No program files were changed.");
     if (!newer(metadata.version,current.version)) {
+      if (scope.resumeSwitch) {
+        if (!force && (await ask("Continue the previously confirmed installation switch? Type 'confirm', or 'q' to cancel")).trim().toLowerCase() !== 'confirm') {
+          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.`);
       await officialTest({userDir,dataDir,write});
       return 0;
@@ -149,7 +175,8 @@ async function updateUnderLock({
     write(`User    ${current.version} → ${metadata.version}`);
     write(`Wallet  ${walletVersion === targetWallet ? `${walletVersion} (unchanged)` : `${walletVersion || 'not confirmed'} → ${targetWallet}`}`);
     write(`Installation folder: ${target.prefix}`);
-    write(scope.active ? 'Background services will pause. Keys, permissions, Orders and cache are kept.' : 'This installation is inactive. The running Wallet and Runtime will not change.');
+    if (scope.resumeSwitch) write('After updating, AgentPay will finish your previously confirmed installation switch.');
+    write(scope.active ? 'Background services will pause. Keys, permissions, Orders and cache are kept.' : scope.resumeSwitch ? 'Services are stopped. Keys, permissions, Orders and cache are kept.' : 'This installation is inactive. The running Wallet and Runtime will not change.');
     if (!force && (await ask("Type 'confirm' to update, or 'q' to cancel")).trim().toLowerCase() !== 'confirm') {
       write('Update cancelled. Nothing was changed.'); return 0;
     }
@@ -202,7 +229,8 @@ async function updateUnderLock({
        installed.dependencies?.['@c4roa0/agentpay-protocol'] !== metadata.dependencies['@c4roa0/agentpay-protocol'])
       throw Error('The installed version does not match the confirmed update.');
     if (configured) {
-      write(scope.active ? '3/3 Restore services and verify the official test Skill.' : '3/3 Verify the inactive installation and official test Skill.');
+      await resumeSwitch(options);
+      write(scope.active || scope.resumeSwitch ? '3/3 Restore services and verify the official test Skill.' : '3/3 Verify the inactive installation and official test Skill.');
       // A fresh Node process loads the NEW repair/client/official digest, not old imports.
       const output = await repair(options);
       if(output) write(output);

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/service-selection.mjs

@@ -6,7 +6,7 @@ import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { autostartFiles, units } from './autostart-files.mjs';
 import { installationDirectory } from './installation-paths.mjs';
-import { withInstallationOperation } from './installation-operation.mjs';
+import { withInstallationOperation, runInstallationCommand } from './installation-operation.mjs';
 import { readServiceSettings, listenerPresent } from './local-services.mjs';
 import { atomicWritePrivate } from './private-journal-files.mjs';
 import { ensureRuntimeConnection } from './runtime-connection-settings.mjs';
@@ -104,7 +104,7 @@ export async function withServiceSelection({target, action, ask, write = console
       write('Current data: ' + previous.dataDir);
       write('Selected data: ' + target.dataDir);
       write('Wallet and Runtime will stop. Keys, permissions and Order records stay in their own folders.');
-      if (!ask || String(await ask("Type 'confirm' to switch, or 'q' to cancel")).trim().toLowerCase() !== 'confirm') {
+      if (!recovery && (!ask || String(await ask("Type 'confirm' to switch, or 'q' to cancel")).trim().toLowerCase() !== 'confirm')) {
         write('Switch cancelled. Existing services were kept.');
         return {cancelled:true};
       }
@@ -188,7 +188,8 @@ export async function withServiceLifecycleLock(operation) {
 
 // Called while holding the installation-operation lock. Maintenance of an inactive
 // program tree must never claim the fixed service pair or rewrite active data.
-export async function maintenanceServiceScope({userDir,dataDir,unitDir}) {
+export async function maintenanceServiceScope({userDir,dataDir,unitDir, resumeUpdate = false,
+  ctl = (...args) => runInstallationCommand('systemctl',['--user',...args],{timeout:30000})}) {
   const canonical = async path => realpath(path).catch(error=>{if(error.code==='ENOENT')return resolve(path);throw error;});
   userDir = await canonical(userDir); dataDir = await canonical(dataDir);
   let saved;
@@ -197,8 +198,26 @@ export async function maintenanceServiceScope({userDir,dataDir,unitDir}) {
     const {assertPrivateFile}=await import('./private-journal-files.mjs');
     await assertPrivateFile(path); saved=JSON.parse(await readFile(path,'utf8'));
     if(saved.version!==1)throw Error('Unrecognized service selection. Keep it for review.');
-    if(['stopping','preparing'].includes(saved.phase) && !await targetUnitsPrepared(unitDir,saved.target))
-      throw Error('A service switch is unfinished. Retry service start from its selected installation before maintenance.');
+    if(['stopping','preparing'].includes(saved.phase) && !await targetUnitsPrepared(unitDir,saved.target)) {
+      if (!resumeUpdate || !saved.target ||
+          await canonical(saved.target.userDir)!==userDir || await canonical(saved.target.dataDir)!==dataDir)
+        throw Error('A service switch is unfinished. Run agentpay update from its originally selected installation.');
+      // Read-only preflight: the prior confirmation remains bound to this exact
+      // target. Do not replace code while any managed process could still use it.
+      await installedServiceSelection(unitDir,saved);
+      for (const name of units) {
+        const result=await ctl('show',name,'--property=ActiveState','--value');
+        if (!['inactive','failed'].includes(String(result.stdout||'').trim()))
+          throw Error('The interrupted switch still has running services. Stop them before updating.');
+      }
+      for (const path of new Set([saved.previous?.dataDir,dataDir].filter(Boolean))) {
+        const settings=await previousServiceSettings(path);
+        if (await listenerPresent(join(path,'wallet/wallet.sock')) ||
+            (settings && await listenerPresent({host:'127.0.0.1',port:Number(new URL(settings.runtimeUrl).port)})))
+          throw Error('An installation listener is still running. Stop it before updating.');
+      }
+      return {active:false,resumeSwitch:true};
+    }
   } catch(error) {if(error.code!=='ENOENT')throw error;}
   const owner=await installedServiceSelection(unitDir) || saved?.target;
   if(!owner)return {active:true}; // Existing single-install setup/repair behavior.

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.10",
-  "walletVersion": "0.3.3",
+  "userVersion": "0.3.12",
+  "walletVersion": "0.3.4",
   "typesDependency": "0.14.3"
 }