@c4roa0/agentpay-user 0.3.7 → 0.3.8

package/README.md

@@ -31,7 +31,9 @@ private key into AgentPay. See [installation and first use](doc/runbooks/user-on
 Program files and private state are separate. Keys, Policies, Orders and cache
 normally live in `~/.local/share/agentpay/user`; an existing custom data directory
 is retained. Installation checkpoints use `~/.local/state/agentpay/user` (or
-`$XDG_STATE_HOME/agentpay/user`). Upgrading program files does not erase either.
+`$XDG_STATE_HOME/agentpay/user` on first setup). AgentPay remembers that location
+so terminal and background services use the same records. Upgrading program files
+does not erase either.
 
 ## Install in a folder instead
 

package/doc/README.md

@@ -1,5 +1,15 @@
 # User documentation
 
+- [Real two-installation switching](records/dual-install-systemd-2026-11-12.md): live systemd cancellation, switching, restoration and evidence limits.
+
+- [Historical request routing](records/historical-request-routing-2026-11-11.md): switch-time indexing, missing records and conservative recovery limits.
+
+- [Local instances and installation recovery](plans/local-instances-and-install-recovery.md): agreed design and implementation sequence.
+
+- [Installation maintenance verification](records/installation-maintenance-2026-11-11.md): inactive maintenance and interrupted-writer recovery, with evidence limits.
+
+- [Isolated client acceptance](records/client-isolated-acceptance-2026-11-11.md): installation, failure retry, uninstall and the interruption blocker.
+
 - [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.

package/doc/TODO.md

@@ -1,15 +1,42 @@
 # User TODO
 
+- [x] Recover failed service start/stop without blocking repair; incomplete target unit replacement remains protected (2026-11-12, controlled service-manager verification).
+
+- [x] Fix shared-data switch client relocation and retry without a repair deadlock; isolated selection/connection checks pass (2026-11-11).
+- [x] Preserve availability for preference-only operations and require authenticated matching-service readiness before publishing the default; failed readiness permits retry/repair (controlled transport/service verification, 2026-11-11).
+- [x] Stage downloaded settings until switch consent under the shared lock; cancellation preserves prior deployment and avoids binding the new installation.
+- [x] Persist one state-directory locator for CLI, background processes and candidate Skill loaders; cross-environment and concurrent-first-use process tests passed.
+
+- [x] Coordinate uninstall with service switching; preserve another installation’s managed pair, recheck confirmed scope and retry partial unit removal (19 targeted checks; systemctl simulated).
+- [x] Implement inactive update/repair and inherited writer exclusion, plus interrupted-update continuation; isolated process/controlled service checks passed.
+- [x] Real A/B/A user-systemd switching, cancellation and same-install start verified (2026-11-12); A restored locked with unchanged key/Policy.
+- [ ] Complete remaining login/reboot and full guided-install acceptance; uninstall still refuses occupied ports of unconfirmed ownership.
+
+- [x] Inventory local instance consumers and document the concrete interface/change map (2026-11-11; design only).
+- [x] Align design to multiple installations with one active Runtime/Wallet per OS user; remove mandatory harness launcher (2026-11-11).
+- [x] Persist canonical per-installation data binding and preserve it across shared checkpoint writes; focused regression checks passed (2026-11-11).
+- [x] Implement and check storage-choice module (reuse/new/cancel); public installer selection now connects through a service-switch gate (2026-11-11).
+- [x] Connect installer selection and service-start switching with confirmation, stopped-state/listener checks and Runtime lifetime exclusion; focused checks passed (2026-11-11; systemd results simulated).
+- [x] Correct shared-directory purge, mixed-unit retry, manual setup regression, first-start preparation and startup-preference inheritance; 37 targeted checks pass (2026-11-11).
+- [ ] Verify complete switch-crash recovery and real systemd switching/login before release; preserve historical request scope across switches. Inactive maintenance isolation is implemented with scoped verification.
+
+
+
+- [x] Isolated public npm fresh install, registry failure/retry and disposable-data uninstall (2026-11-11; no real systemd or financial acceptance).
+- [x] Replace existence-only locking for new operations: inherited native lock survives caller death while writers live, then permits retry. Old unknown locks require review; they are not automatically removed.
+- [ ] Publish folder-local npm uninstall completion guidance after review.
+
+
 - [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.
+- [ ] Complete configured multi-instance installation and interrupted-update recovery acceptance after the scoped implementation; isolated fresh npm installation already passed, systemd and recovery gaps remain.
 
 
 - [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] Publish cache-details guidance in User 0.3.7; tag/registry integrity verified (2026-11-11).
 
 
 - [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] Publish update-preview wording in User 0.3.7 (2026-11-11).
 
 
 - [x] Preserve maintenance error guidance and original request identity; controlled HTTP/IPC verification (2026-11-10).
@@ -168,3 +195,11 @@ investigations remain private operator work, not a public contributor prerequisi
 
 Original chronological TODO snapshots are preserved in the private workspace.
 Consolidation does not turn historical partial evidence into completed acceptance.
+
+- [x] Update candidate Agent template/default loader; selected storage is pinned for each invocation, unavailable selection has no fallback.
+- [ ] Review/build/deploy candidate Agent template 0.1.2 and official bundle 1.2.2, then update the reviewed User official digest; no publication authorized by source changes.
+
+- [x] Protect new default request ownership across data folders; restore selected connection on Runtime bind; persist startup changes and allow Node-path-independent recovery (2026-11-11, scoped tests).
+- [x] Index historical client request identities during confirmed switching; reject missing selection/checkpoints and conflicting owners, preserve startup with an unclassified-history barrier (controlled verification).
+- [ ] Accept historical request routing in the complete two-install public-entry/systemd rehearsal before rollout.
+- [ ] Finish actual login/switch and full public-entry interruption acceptance; isolated inactive maintenance/concurrency verification is complete.

package/doc/plans/local-instances-and-install-recovery.md

@@ -0,0 +1,250 @@
+# Multiple installations, one active Runtime
+
+Status: approved direction, 2026-11-11; partial implementation under verification. This replaces
+concurrent-instance routing and the proposed harness launcher. No live installation
+has been migrated.
+
+## User experience
+
+A user can keep a development installation and an everyday installation on the same
+computer, each with separate dependencies and data. Under one OS user, only one
+managed Runtime/Wallet pair runs at a time. Skills use that pair as the default exit.
+The user does not select an instance in every Skill or change the harness launcher.
+
+- On installation, existing configuration offers **Use existing / Create separate /
+  Cancel**. Creating a separate installation does not activate it automatically.
+- Starting the already active installation is idempotent.
+- Starting a different installation shows the current and target names/data folders
+  and asks whether to switch. A noninteractive call cannot silently approve this.
+- Switching stops the original pair, verifies it has stopped, then starts the target.
+  Wallet starts locked. It never copies keys, renews Policies or merges Order history.
+- If the original pair cannot be stopped, switching stops there. If the target fails
+  to start, show the failure and recovery command; do not silently start another pair.
+- Stopping the active pair leaves the default unavailable until the user starts it
+  or explicitly switches. There is no fallback to another Wallet.
+
+Keep existing default data in place. Reusing it from another program installation
+requires explicit ownership transfer and stopping the previous writer. A new data
+folder gets a stable local reference and a readable label. Neither is a Market
+Wallet identity, Policy or device identity. Renaming does not change authorization.
+
+## Default Skill connection
+
+Shared User client code resolves the single active installation and its connection.
+Skill business code supplies service selection, input/output validation and optional
+file handling. It does not search Wallet directories or choose an installation.
+Internal connection files remain an implementation detail of the shared client.
+
+Do not introduce mandatory `agentpay exec` or per-harness environment selection.
+A new `agentpay skill run` command is not required by this design. Preserve the
+existing Skill-facing calling convention where practical and keep a stable shared
+client entry. Runtime upgrades must not require publishing every installed Skill.
+
+The current template reads clientModule from connection.json before importing the
+shared client. Implementation must address that bootstrap as well as Runtime URL
+lookup. Inventory source, folder-local npm and global npm resolution before choosing
+the minimal bootstrap change. If template bytes must change, publish a versioned
+migration once; do not silently rewrite immutable packages or claim old downloaded
+Skills already follow the new default. No background package download is allowed
+as a side effect of invoking a Skill.
+
+Resolve the active connection once per invocation. A switch while a call is in flight
+must fail or preserve its original request, never retry against the newly active
+Wallet. Saved recovery records retain their originating storage/authorization scope.
+A missing original record must not become a fresh purchase in the other installation.
+Provide a prompt to return to the original installation when that scope is known.
+Port, program path and local label do not enter payment or request identity.
+
+This is logical routing under one OS account, not protection against hostile code
+running as that same account. An unavailable default must produce a useful error;
+merely finding an HTTP listener is not proof it is the selected Runtime.
+
+## Installation and active state
+
+For the first version, one program installation binds one data instance. Development
+source and everyday folder-local npm installations have independent dependency trees.
+A global npm installation is one installation, not multiple global versions.
+
+Maintain private local records of canonical installation roots and bound data folders,
+plus one active selection. Do not store keys in this catalog. Resolve ownership and
+path aliases before claiming storage; two aliases cannot claim the same data twice.
+Read-only commands must not perform adoption or change the active selection.
+
+CLI lifecycle/update/uninstall commands operate on their installation's bound data,
+and display when a different installation is active. Skill invocation alone uses the
+default active connection. This distinction prevents a repair in an inactive source
+checkout from taking over the everyday installation.
+
+Resolve command context once and pass it to children. Legacy data-directory overrides
+must agree with the bound context or enter explicit adoption; they cannot silently
+retarget services or delete another instance.
+
+## Lifecycle, switching and startup
+
+Keep one managed systemd user service pair and one login reminder, targeting the
+active installation. Reuse existing fixed unit names where their ownership can be
+verified; parallel instance-specific units are no longer required. Login startup
+starts only the selected pair. Preserve the existing login-start preference when
+switching, and show it in the switch summary.
+
+Serialize switch/start/stop/repair and active endpoint publication. Check real process
+ownership, not only service-manager state: a manually started old process must also
+prevent starting another managed pair. A Runtime lifetime ownership guard must reject
+competing starts from supported product entry points. Arbitrary external programs
+are outside this guarantee; never kill an unrelated process to reclaim a port.
+
+During switching the default is unavailable. Publish the new active connection only
+after startup and authentication/readiness verification. Journal switch phases so an
+interruption can report or resume an incomplete transition without running both pairs.
+Do not automatically unlock the new Wallet. Endpoint port conflicts fail explicitly;
+a prior free-port probe is not a reservation. Bind and caller authentication remain
+mandatory. The default is a logical selection, not a promise of a fixed TCP port.
+
+Uninstalling or updating an inactive installation must not stop, restart or rewrite
+the active service pair. Updating the active installation may briefly stop it and
+then repair/restart that same pair. Uninstalling it leaves no active default; it does
+not activate a replacement. Confirm local data deletion separately as today, and
+never revoke on-chain authorization as an uninstall side effect.
+
+## Interrupted installation recovery
+
+The reproduced failure is recorded in
+[isolated acceptance](../records/client-isolated-acceptance-2026-11-11.md): killing
+all updater writers leaves an empty install.lock and permanently blocks retry.
+
+The first implementation serializes maintenance under one shared OS-user operation
+lock. This is deliberately conservative: inactive installations keep running services
+unchanged, but two administration commands do not write concurrently. Finer-grained
+parallel updates are deferred; there is no installation/lifecycle lock ordering cycle.
+Runtime lifetime and request/cache locks remain separate from maintenance.
+
+The existing native lock primitive uses open-file-description locks on Linux. npm
+and short-lived administration children inherit the descriptor; a killed caller does
+not free it while the writer lives. Real child-process checks verify this behavior.
+Daemon processes do not inherit it. No PID/age/procfs stale-lock rule is used.
+Recognizable v2 markers can be recovered only after acquiring the OS lock. Unknown
+legacy markers remain blocked for review. npm installation hooks are disabled so
+package scripts cannot leave untracked descendant writers. macOS service acceptance
+remains deferred; raw external npm commands are outside AgentPay's coordination.
+
+Persist non-secret checkpoints: selected installation/data, target versions, phase,
+and prior active/service state. Re-entry validates installed dependencies before
+resuming repair. It must not activate a previously inactive installation, resume a
+payment, change Policy, or invent a replacement request. Failure messages distinguish
+active writers, safely recoverable interruption and uncertain ownership.
+
+## Change map
+
+| Component | Required change |
+| --- | --- |
+| User installation-paths / local-data-directory | Per-install binding and state, single active selection, explicit adoption |
+| User CLI and command scripts | Resolve context once; show bound/active distinction; confirm switching through service start |
+| User install / npm-update / local-update / uninstall | Scoped exclusion/checkpoints; inactive operations preserve the active services |
+| User autostart / local-service / status / endpoint migration | One managed pair, lifetime ownership, serialized switching, correct status/log targets |
+| User runtime-client / runtime-connection-settings / skill-client | Stable shared bootstrap and default resolution; invocation never reroutes mid-request |
+| Wallet | Verify separate data/socket state and clean stop/start; keep signing and Policy rules unchanged |
+| Agent template / official Skill | Assess minimal shared-bootstrap migration; retain business-only glue and version immutable changes |
+| Market / Settlement / Protocol | No new API or domain model required; existing template and fixed-package distribution remain |
+
+Update User README, usage, command guide and installation/recovery docs with the
+actual supported selection behavior. Agent examples must match the shared client.
+Review any official Skill package change before updating User's built-in digest.
+
+## Delivery order and acceptance
+
+1. **Binding and storage:** install two program trees through public entry points;
+   reuse/adoption preserves existing identity; separate installation does not copy
+   keys or take over the active pair.
+2. **Single active lifecycle and recovery:** switch both ways; cancellation, failed
+   stop/start, concurrent starts and interrupted switch never leave two active pairs.
+   Login preference is preserved. Inactive update/uninstall leaves the active pair
+   usable. Real SIGKILL tests cover both all writers ended and surviving npm children.
+3. **Default Skill entry:** same maintained Skill entry reaches the active pair after
+   deliberate switching without editing harness configuration. Exercise two controlled
+   business payloads. An interrupted old request cannot become a payment by the new
+   Wallet. Verify missing default and port collision errors with no fallback.
+4. **Package and participant checks:** source, folder-local and global npm paths;
+   template migration if needed; keys, Policies, original requests and cache preserved.
+   Prepare the user rehearsal only after these checks, with explicit release approval.
+
+Use maintained fixtures, not third-party Skills or unapproved paid tests. Isolated
+checks do not prove financial acceptance. macOS service integration remains deferred
+until a test machine is available. This design update does not authorize package
+publication, live migration, chain writes or new payments.
+
+### Uninstall implementation checkpoint
+
+Removal and service switching use the same lifecycle lock. The confirmation preview
+is revalidated inside the lock; changed targets require another confirmation. Valid
+foreign managed units are left intact, and shared active data cannot be purged.
+A partial unit deletion can be retried. The default selection remains stopped after
+removal, so Skills cannot silently select another Wallet. Unknown occupied ports
+remain a conservative refusal. Installer/update and child-writer exclusion are now integrated. Actual systemd and
+full participant interruption acceptance remain open.
+
+### Historical request implementation checkpoint
+
+Confirmed switching imports known client selection/checkpoint scopes and request IDs
+from both involved folders without rewriting history. Runtime-only or unreadable
+history cannot establish the original Skill input; retain a conservative unclassified
+owner barrier. Do not fail Runtime startup solely because old requests need review.
+A different default installation must not automatically invoke a replacement when
+this barrier applies. Explicit `--force` still means a deliberate new purchase.
+
+Missing selection/checkpoint files stop automatic recovery; conflicts require the
+original installation and saved `--resume` identifier. New ownership selection and
+local checkpoint creation share the short maintenance lock; payment/network calls
+remain outside it. [Verification and limits](../records/historical-request-routing-2026-11-11.md).
+
+## Readiness and startup preferences — 2026-11-11
+
+A successful service-manager start request is not readiness. Before publishing the
+default connection, check the selected data directory's authenticated Wallet status
+and Runtime status, including the installed pair's reported versions. Wallet may be
+locked and historical Order checks may still be running. Neither condition alone
+prevents a running connection from being selected.
+
+Preference changes and same-installation preparation preserve availability; they
+do not revive stopped services. Removal closes the default. If unit installation
+succeeds but readiness fails, keep the default closed and allow repair or another
+start. Login startup performs the same checks while holding the selection lock,
+and cannot publish another program/data selection or an unfinished switch.
+
+These checks have isolated transport and service-control fixture coverage. Actual
+systemd switch/login acceptance remains a separate gate.
+
+## Confirm before applying settings; keep one state location — 2026-11-11
+
+The installer validates downloaded public settings in memory. While holding the
+installation operation lock, it requests the normal setup activation/switch. Only
+successful activation permits writing deployment settings and importing missing
+legacy setup files. Cancellation does not bind the new installation or change the
+old deployment. The activation child inherits the operation lock, so another
+installation cannot switch services between consent and configuration application.
+Dependency preparation may already have completed; cancelling does not roll back
+installed program packages. A failed download never requests a service switch.
+
+On first mutation/start, the chosen state directory is recorded in the private
+`~/.local/state/agentpay/state-location.json`. This small file contains only the
+state directory path; Wallet data and its identity stay in their own data folder.
+Existing XDG state directories are retained in place. Subsequent CLI commands,
+background processes and candidate Skill loaders follow this locator even if their
+XDG environment differs. Read-only lookup does not create it. Initial concurrent
+writers publish without overwriting another location; conflicting commands retry.
+Changing XDG is not a state migration or a way to start a second Runtime.
+
+The locator is retained when uninstalling an installation because other bindings
+and original-request ownership may still use the shared catalog. Invalid/private-
+permission failures stop lookup instead of silently choosing another directory.
+This is local routing under one OS account, not isolation against hostile code
+running as that user. Existing immutable Skill packages are not rewritten.
+
+## Service command failures — 2026-11-12
+
+After verifying all generated target unit files, persist an unavailable default
+before daemon reload or start/stop. A failed command must not be confused with
+unfinished file replacement: stop can be retried, and startup failure permits
+repair. An older preparing/stopping journal can use the same recovery only when
+all exact target units exist and agree. Partial or conflicting files still require
+completing the recorded switch. The unavailable journal phase does not assert
+that the processes have stopped; status and stopped-listener checks remain required.

package/doc/records/client-isolated-acceptance-2026-11-11.md

@@ -0,0 +1,37 @@
+# Isolated client acceptance — 2026-11-11
+
+Real public npm packages and public CLI processes were used in temporary homes,
+installation/state/data directories. No real keys, services, Policies or Orders were
+used. Retained sentinel bytes do not establish recovery of a funded transaction.
+
+## Passed
+
+- Fresh User 0.3.7 install resolved Wallet 0.3.3 and Protocol 0.14.3 without sibling
+  repositories. CLI worked. Already-current update preserved fixture bytes.
+- Unreachable registry stopped before replacing User 0.3.6. Restoring connectivity
+  and retrying the same command upgraded to 0.3.7 with fixture bytes intact.
+- Real terminal uninstall: cancellation and default removal preserved data; explicit
+  delete confirmation removed only selected disposable data, retaining program files.
+  No systemd units existed in this isolated home; their removal was not tested.
+- Completion lacked directory-local npm removal instructions. Added in source;
+  uninstall regression passed. Not yet published.
+
+## Blocking finding
+
+A real updater process group was killed with SIGKILL after printing
+“1/3 Check the update requirements.” Program replacement had not begun. All
+updater/npm processes in that group ended; fixture bytes remained intact. Retrying
+reported another installation may be running. Empty install.lock persisted and
+blocked progress. The failed scene and logs are retained; no manual lock removal
+was used to pass this check.
+
+The exclusive-create lock is shared by install, update, location writes and
+endpoint changes. Repair uses install; uninstall treats lock existence as busy.
+Recovery must cover all consumers. Deleting a lock after a timeout is unsafe:
+a child npm writer can outlive its parent. Old empty locks cannot prove no writer
+exists. Proposed next loop: agree a shared operation-lock lifecycle that preserves
+child-writer exclusion, crash recovery and explicit legacy uncertainty handling;
+then validate through real process interruption and competing commands.
+
+Fresh setup/authorization, real systemd uninstall, mid-package-replacement recovery
+and funded-Order recovery are not established. No production state changed.

package/doc/records/dual-install-systemd-2026-11-12.md

@@ -0,0 +1,40 @@
+# Two-installation systemd switch — 2026-11-12
+
+This rehearsal used actual Linux user systemd services and public User commands.
+Installation A was the source checkout; B was a folder-local npm installation of
+an archive built from the reviewed User commit `a8e3d88`. It carried candidate code
+under the existing 0.3.7 manifest; it was not published to npm. Both used Wallet
+0.3.3 and Protocol 0.14.3. A's previous 0.3.2 dependency tree was retained for rollback
+before an offline frozen dependency installation.
+
+## Observed behavior
+
+- B had separate private storage and a newly initialized, unfunded Wallet with no
+  Policy. Its unlock secret was used only to initialize the encrypted key; B was
+  never unlocked. Settings and caller credentials were controlled prerequisites.
+- Public `service start` switching required confirmation. Cancelling preserved A's
+  Runtime PID. Confirmation stopped A and started B on the same loopback port.
+- B reported matching software versions, a locked Wallet, no Policy and no Orders.
+  Its authenticated Runtime status endpoint responded successfully.
+- Starting the selected B again preserved its Runtime PID.
+- Switching back restored A. Its encrypted Session Key and Policy file hashes
+  matched the pre-switch values. A's existing Orders and Market connection remained
+  visible; this was not a byte-for-byte audit of every historical/cache file.
+- Both services were active at completion and login startup remained enabled.
+  Wallet stayed locked. No authorization, purchase, payment or chain write was
+  initiated by the test.
+
+The first attempt successfully switched to B and restored A, but the harness treated
+B's nonzero status exit (locked/unconfigured Wallet) as an execution failure. The
+harness was corrected to accept that expected status while still requiring real
+service readiness. The subsequent full run passed. No product change was needed
+for that harness correction.
+
+## Evidence limits and retained state
+
+This establishes live service switching and cancellation, not desktop login after
+reboot, fresh guided installation/owner authorization, or funded recovery. Existing
+unclassified request warnings remained visible; no third-party Skill or forced new
+purchase was used to bypass them. The dedicated B installation/data and rollback
+dependencies remain private, inactive test material for traceability. The active
+selection is A. Logs/scripts are retained outside the public source tree.

package/doc/records/historical-request-routing-2026-11-11.md

@@ -0,0 +1,47 @@
+# Historical request routing — 2026-11-11
+
+Working-tree verification only; no participant history, authorization or payment
+was changed.
+
+## Implemented behavior
+
+A confirmed installation switch inventories the previous and selected data folders'
+client request/selection stores and Runtime invocation history. It reads bounded,
+private local files, retaining originals unchanged. The shared routing index stores
+service/input hashes, original request IDs and data-folder ownership, not inputs,
+results, keys or signed payment payloads. No Market or Settlement request is involved.
+
+Default Skill calls claim ownership and select a local request under the same short
+maintenance lock used by switching. Network/payment work occurs afterwards against
+the already pinned connection. A matching old request reuses its original ID.
+A request belonging to another installation prompts the caller to return there.
+Conflicting owners require explicit `--resume` in the intended installation.
+
+Missing selection or checkpoint files no longer silently create a replacement.
+Known historical IDs constrain selection, and an ID retained in a pending record
+must be resumed from its checkpoint rather than recreated. `--force` remains an
+explicit new-purchase choice; migration does not override that later choice.
+
+Runtime-only history cannot establish a Skill's original pre-upload/preparation
+input. Unreadable or unlinked records therefore retain an unclassified-owner barrier.
+They do not prevent Runtime startup or a confirmed switch. Automatic invocation in
+another installation is blocked with review guidance; only deliberate `--force`
+can authorize treating a call as new. Explicit original-request resume remains local.
+This can conservatively block unrelated new inputs after switching from very old
+history; it does not imply every such input previously incurred a payment.
+
+## Evidence and limits
+
+Targeted runtime-client, default-runtime-lifecycle, service-selection and
+invocation-store checks passed. The final run, including candidate Skill bootstrap
+and reference-client regressions, passed all 37 checks. Tests exercise the shared Skill entry against
+controlled local HTTP services, preserve IDs for two different JSON business
+payloads, reject replacement before any invocation HTTP call, and cover missing
+selection/checkpoint, conflicting installations, explicit force/retry and malformed
+old history during a switch. Historical-only fixtures prepare missing/old metadata;
+they are not claims of real payment recovery. Service management remains simulated.
+
+Only known selected data folders are inventoried; unrelated disks or directories
+are not searched. Older immutable Skill bootstraps do not automatically gain default
+selection. Candidate template publication, complete two-install entry-point/systemd
+acceptance and participant review remain release gates.

package/doc/records/installation-maintenance-2026-11-11.md

@@ -0,0 +1,46 @@
+# Installation maintenance verification — 2026-11-11
+
+This record covers working-tree changes; no release or participant service was changed.
+
+## Behavior checked
+
+- Inactive npm update and repair preserve the selected service pair and private data.
+  Controlled npm metadata and systemctl responses isolate this orchestration check.
+- Independent processes cannot enter maintenance while a writer holds the shared
+  lock. Killing the caller with SIGKILL leaves its real child writer protected.
+  After that child exits, another process succeeds without manual lock deletion.
+- A short-lived administration child can inherit the lock; unrelated processes
+  remain excluded. Command timeout waits for child closure before returning.
+- Interrupted update after npm success still resumes repair. Retry retains the
+  confirmed version; successful completion removes the recovery checkpoint.
+- Uninstall preserves another installation's units, rejects shared active data,
+  rechecks confirmation, supports partial-unit retry and recognizes v2 recovery.
+- Installation bindings, address updates and service selection use the same
+  maintenance boundary. Trailing path separators do not cause a false switch.
+
+The final combined run passed 77 targeted checks. A subsequent marker-publication
+interruption check also passed, along with the three existing process-lock checks.
+Targeted suites cover installation-maintenance, npm-update, local-update,
+local-data-directory, uninstall-local, service-selection and platform-endpoints.
+Installation entry suites also cover install-user, install-and-setup,
+install-selection, setup-service-selection and setup-autostart. Tests use private
+throwaway directories; real process-lock evidence does not imply real systemd
+or financial acceptance.
+
+An independent offline `npm ci --ignore-scripts --no-audit --no-fund` installed the
+pinned packages. Wallet 0.3.3, Protocol 0.14.3's public ESM entry and native locking
+loaded successfully. The initial diagnostic incorrectly used require/package.json
+against Protocol's ESM export map; the corrected ESM import succeeded. Worktree
+installation tests initially found an older Wallet dependency; they passed in an
+isolated copy using the correct dependencies. Existing worktree dependencies were
+not changed to make tests pass.
+
+## Limits and next gates
+
+The maintenance lock serializes administrative writes across installations. Runtime
+service operation continues during inactive maintenance. Unknown legacy installer
+locks remain blocked, not automatically deleted. Direct external npm/file changes
+are outside this coordination. Uninstall still refuses an occupied port whose owner
+cannot be confirmed. Historical Skill requests are not retroactively scoped by this
+work. Complete two-install systemd switching/login, actual package-update interruption
+and participant acceptance remain required before rollout.

package/doc/reference/local-update.md

@@ -8,7 +8,8 @@ refreshes managed service paths under the installer lock. Existing client connec
 URLs and caller credentials must match before a client-module path can be refreshed.
 A mismatch stops preparation rather than rewriting transaction identity.
 
-Installation checkpoints live in XDG state storage; old source-install checkpoints
+Installation checkpoints use the saved per-user state location, initially chosen
+from XDG state storage; old source-install checkpoints
 are read to preserve a custom data-directory selection. Deployment settings are
 copied into private User data only when no canonical file exists. Neither path
 changes keys, Policies, requests or recovery records.

package/doc/runbooks/commands.md

@@ -102,3 +102,31 @@ Protocol reporting reads the installed package resolved by that process, rather
 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.
+
+## Multiple installations (unreleased working tree)
+
+Run `agentpay service start` from the installation you want to use. When another
+installation owns the background services, the command shows both data folders and
+asks for `confirm` before stopping the old pair. Cancellation keeps the old services.
+Noninteractive commands cannot approve a switch. Wallet and Order data stay in their
+own folders; unlock the selected Wallet after starting it.
+
+Install now offers reuse, separate data or cancellation when it finds existing data.
+The setup guide checks service ownership before continuing. A separate data folder
+starts empty; it does not copy a Session Key or spending permission.
+
+These changes are under development. Actual systemd switching and login behavior have
+not yet been accepted; default Skill discovery and interrupted-switch recovery remain
+open. Do not use these working-tree changes as a released multi-installation guide.
+
+### Original requests after switching installations
+
+If a Skill says a request belongs to another installation, return to that installation
+and inspect `agentpay orders list`. Use the Skill's `--resume REQUEST_ID` option with
+its original request identifier. An Order ID and a Skill request ID are different.
+
+Missing or conflicting history is kept for review; switching does not recreate a
+purchase. Very old records may prevent automatic invocation in another installation
+because the original input cannot be identified. `--force` is only for an intentional
+new purchase, never a way to recover an old result. Read-only status, order inspection
+and service startup remain available.

package/doc/runbooks/local-update.md

@@ -27,10 +27,13 @@ registry dependency, not a transitive dependency or a linked/custom-source packa
 
 It checks the published User version and shows its exact Wallet dependency. Confirm
 to continue, or cancel without changing services. `agentpay update -f` skips only
-this confirmation. The updater checks requirements in a temporary installation directory, stops configured services,
+this confirmation. The updater checks requirements in a temporary installation directory, stops this installation’s selected services,
 installs the confirmed version and invokes the new version's repair to refresh
 services and verify its pinned official test Skill. No paid test runs automatically.
-Other installed Skills and original requests are kept. Wallet needs unlocking after
+An inactive installation stays inactive: updating or repairing it does not stop the
+selected Wallet/Runtime. Use `agentpay service start` from that installation when you
+want to switch. Another command changing services or program files will ask you to
+wait and retry. Other installed Skills and original requests are kept. Wallet needs unlocking after
 restart. A current User version still checks the official test Skill.
 
 Only genuine npm installations are updated. A source checkout or `npm link`
@@ -42,7 +45,8 @@ ship usable runtime artifacts. It never independently selects the newest Wallet.
 
 If npm fails after services stop, keep your private data. Review the shown log;
 reinstall the intended User version with npm if program files are incomplete, then
-run `agentpay repair`. Interrupted installers may leave a lock to inspect. Repair
+run `agentpay repair`. If the updater was interrupted, rerun `agentpay update`: it retains the confirmed
+version and finishes repair even if npm already installed it. Repair
 failure is not reported as update success. A newer update cannot silently downgrade
 a version changed while you were reviewing the confirmation.
 
@@ -64,8 +68,10 @@ Wallet starts locked after restart. No Wallet compilation is required.
 
 If preparation fails after stopping services, they remain stopped. Resolve the
 reported cause and repeat repair; the log path is shown. An interrupted run may
-leave an installation lock: inspect it before removing it. There is no automatic
-code rollback. Running-package negotiation is not implemented; complete the managed
+leave a lock marker. New-format operations allow retry after all writer processes
+exit; while a writer is alive, wait for it to finish. Do not delete a lock to bypass
+that check. An older lock whose writer cannot be identified is preserved for review.
+There is no automatic code rollback. Running-package negotiation is not implemented; complete the managed
 restart before relying on a newly installed version.
 
 ## Uninstall

package/package.json

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