@c4roa0/agentpay-user 0.3.9 → 0.3.11

package/doc/TODO.md

@@ -1,7 +1,15 @@
 # User TODO
 
+- [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] 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] Verify local official Skill files before downloading and stream update repair progress (2026-11-12; targeted checks).
-- [ ] Publish and verify the local official-Skill check optimization in the next User patch.
+- [x] Publish local official-Skill verification and streaming update progress in User 0.3.9; tag and npm integrity verified (2026-11-12).
 
 - [x] Publish User 0.3.8 with matching v0.3.8 tag; full CI, standalone package and public registry integrity passed (2026-11-12).
 

package/doc/usage.md

@@ -60,3 +60,15 @@ 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.

package/package.json

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

package/progress.md

@@ -1,8 +1,40 @@
 # AgentPay User progress
 
+## Update recovery during an unfinished switch — 2026-11-12
+
+User 0.3.11 candidate: 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 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
+the corrected switch is run. Full two-running-installation acceptance is pending.
+
 ## Official Skill local verification — 2026-11-12
 
-User 0.3.9 candidate: update/repair verifies the release-pinned local ZIP and its extracted
+Published as `v0.3.9` at `8fbae4e`. Full GitHub behavior and standalone package
+checks passed; npm latest and archive integrity independently verified. Wallet stays
+0.3.3, Protocol 0.14.3 and official test Skill 1.2.1.
+[Release workflow](https://github.com/c4rO-0/agentpay-user/actions/runs/43162494802).
+
+User 0.3.9: update/repair verifies the release-pinned local ZIP and its extracted
 files before using the network. Matching files skip download; edited or incomplete
 extracted files are preserved with guidance. Software-update repair progress streams
 as it happens. Targeted update/package regressions passed; the actual pinned 1.2.1

package/src/npm-update.mjs

@@ -106,7 +106,13 @@ 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…');
+      const output = await service('start',options);
+      if(output)write(output);
+    };
     if (pending && current.version === pending.targetVersion) {
       installing = true;
       if (current.dependencies?.['@c4roa0/agentpay-wallet'] !== pending.walletVersion ||
@@ -115,6 +121,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 +139,15 @@ 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};
+        await resumeSwitch(options);
+        const output=await repair(options); if(output)write(output);
+        return 0;
+      }
       write(`User ${current.version} is current. Checking the official test Skill.`);
       await officialTest({userDir,dataDir,write});
       return 0;
@@ -149,7 +165,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 +219,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/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';
@@ -45,6 +45,26 @@ async function targetUnitsPrepared(unitDir, target) {
   } catch { return false; }
 }
 
+// A cancelled first setup can own generated units before it has a Wallet or
+// runtime address. Only that demonstrably unconfigured state may omit settings;
+// missing settings in an established installation still require review.
+async function previousServiceSettings(dataDir) {
+  try { return await readServiceSettings(dataDir); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    for (const directory of [dataDir, join(dataDir,'wallet'), join(dataDir,'runtime')]) {
+      const info = await lstat(directory).catch(e => { if(e.code==='ENOENT' && directory!==dataDir)return null;throw e; });
+      if (info && (!info.isDirectory() || info.isSymbolicLink() || info.uid!==process.getuid() || info.mode & 0o077))
+        throw Error('Previous installation directories need ownership review before switching.');
+    }
+    for (const name of ['wallet/session.keystore.json','wallet/policy.json','runtime/local-services.json','runtime/connection.json']) {
+      const exists = await lstat(join(dataDir,name)).then(()=>true,e=>{if(e.code==='ENOENT')return false;throw e;});
+      if (exists) throw Error('Previous installation has saved Wallet or Runtime settings, but its service configuration is incomplete. Keep its files and repair it before switching.');
+    }
+    return null;
+  }
+}
+
 // The caller holds this lock through unit replacement and start/stop. No prompts
 // can grant approval to a different target while the current transition writes.
 export async function withServiceSelection({target, action, ask, write = console.log, ctl, unitDir, operation, verifyReady = waitForServiceReadiness}) {
@@ -84,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};
       }
@@ -104,9 +124,9 @@ export async function withServiceSelection({target, action, ask, write = console
       }
     }
     if (different) {
-      const settings = await readServiceSettings(previous.dataDir);
+      const settings = await previousServiceSettings(previous.dataDir);
       if (await listenerPresent(join(previous.dataDir,'wallet/wallet.sock')) ||
-          await listenerPresent({host:'127.0.0.1',port:Number(new URL(settings.runtimeUrl).port)}))
+          (settings && await listenerPresent({host:'127.0.0.1',port:Number(new URL(settings.runtimeUrl).port)})))
         throw Error('An original Wallet or Runtime listener is still running. Stop it before switching; no new service was started.');
     }
     if (different) {
@@ -168,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;
@@ -177,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/update-pair.json

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