@c4roa0/agentpay-user 0.0.0-stage → 0.3.1

package/doc/reference/skill-input-output-cache.md

@@ -0,0 +1,93 @@
+# Skill glue and shared input/output persistence
+
+Implemented design reference. Current release/participant gates are tracked in
+[TODO](../TODO.md); this document is not new deployment or payment authorization.
+
+## Responsibilities
+
+The editable Skill is glue: it validates application input, explicitly identifies
+input/output files and adapts application data to its Provider interface. The
+installed User client owns common persistence and recovery. Runtime continues to
+own the existing bounded payment, service authorization and delivery verification
+path. This work does not move those operations into arbitrary Skill callbacks.
+
+Shared caching does not impose a common Provider business payload or result
+format. Input remains supported bounded JSON, including arrays and nested data;
+it is not necessarily text. Binary data belongs in separate files, not an enlarged
+JSON/base64 payload. Only hashes and existing required metadata reach Settlement;
+private content remains local or travels to the selected Provider.
+
+## Invocation lifecycle
+
+1. Validate input and select/preserve the original request ID. Persist explicit
+   file declarations and preparation state before copying files or submitting a
+   paid invocation. An incomplete snapshot cannot be mistaken for a file-free call.
+2. Save JSON using the existing checkpoint mechanism. Snapshot only files the
+   Skill explicitly declares; ordinary strings, paths and URLs are not instructions
+   to read or fetch. Record a stable file key, size and content digest. Write files
+   durably before marking the complete input snapshot ready.
+3. Application adaptation consumes the saved copies, not mutable original paths.
+   Preserve the exact final business request used for its existing request hash.
+   Provider-specific upload/reference construction must not be silently invented
+   by the common client. A changed or expired upload reference is not permission
+   to change an already submitted business request or create another Order.
+4. Continue through the existing Runtime payment/invocation path. Before the first
+   network submission, durably record that submission may occur; a crash or missing
+   local Order ID is not proof of non-payment.
+5. Retain the existing verified structured-result persistence. A Skill explicitly
+   selects output files for the existing Order-scoped cache. Cache/download failure
+   is distinct from paid service failure: retain the verified result and retry
+   caching only, without invoking the paid service again or confirming receipt.
+6. Resume by original request identity and saved inputs. A valid saved result can
+   be read without requiring its original input files to remain available. A resume
+   that still needs input bytes must stop if their snapshot is missing or corrupt.
+
+Inputs are request-scoped because an Order may not exist yet. Outputs keep their
+existing Order/evidence scope. Do not invent Order IDs for input caching or change
+delivery hash rules to match cache digests. Runtime URLs are connection locations;
+port changes do not create new request or file identities. The separate
+[address recovery plan](runtime-address-recovery.md) still requires atomic
+existing-only continuation when recovering potentially submitted requests.
+
+## Retry and storage boundaries
+
+- Repeating a matching invocation selects its existing snapshot before reading
+  mutable sources. An edited/deleted original file does not replace saved bytes.
+  Deliberately using new input remains an explicit new request; `--force` retains
+  its existing additional-purchase meaning and never bypasses Policy limits.
+- A missing snapshot after possible submission is a recovery problem, not a reason
+  to reconstruct from changed files. Legacy JSON-only requests remain JSON-only;
+  never infer missing file declarations from historical strings.
+- Use bounded streaming, private local storage, atomic manifests and the existing
+  portable locking approach where appropriate. Do not introduce Linux-only process
+  identity checks or another lock protocol just for this feature.
+- Reuse download validation for explicitly declared URL sources; do not assume
+  HTTPS-only Providers. Do not forward Wallet, Runtime or platform credentials to
+  file hosts. Do not follow symlinks or automatically inspect unrelated local files.
+- Input and output usage must both be visible and bounded. Reusing numeric defaults
+  does not establish a shared quota unless accounting actually includes both stores.
+  Final limits and CLI presentation must be documented with implementation.
+- Never automatically evict inputs needed by unresolved requests. Explicit deletion
+  must explain loss of local recovery, retain request/digest history, and prevent
+  future retries from silently substituting fresh input. Cache cleanup is not Order
+  cancellation. Existing uninstall confirmation covers deletion of local data.
+
+## Implementation sequence and acceptance
+
+The user changed the sequence to **cache foundation first**. The detailed
+[local cache design](local-cache-foundation.md) owns storage and management.
+
+1. Review existing storage; specify shared layout, formats, quotas, crash states,
+   cleanup and management. No payment/Skill integration in this loop.
+2. Implement the shared file store and management commands; reuse existing output
+   capabilities instead of running separate input/output storage engines.
+3. Verify the foundation with maintained arbitrary-byte fixtures, large streams,
+   concurrent operations, disk failures, process interruption and cleanup races.
+4. Attach input snapshots and existing verified results to request recovery;
+   implement address-independent original-record selection and atomic existing-only
+   continuation. Missing history must never create replacement purchases.
+5. Update editable templates and common Skill-client hooks, then verify two business
+   payloads through the same Runtime. Output-download retries must not repeat paid
+   execution. Participant deployment follows review and controlled verification.
+
+No services, policies, stored purchases or public APIs are changed by this plan.

package/doc/reference/wallet-identity-policy-history.md

@@ -0,0 +1,23 @@
+# Wallet identity and Policy history
+
+Market display identity is network + Module + Safe + execution address (delegate).
+The nickname belongs to that identity. Several individually verified Policies may
+be attached, but each remains the access boundary for its own Orders. Same-key
+copies with the same tuple are one Wallet, not separately verified machines.
+
+User keeps one active local spending Policy and preserves original request scopes.
+`./run market connect` proves the current Policy; renewal can continue connection
+to the same Wallet. Failure to connect does not undo a successful on-chain renewal
+or authorize recreating a Policy. Connection receipts are local metadata, not proof
+of live website access.
+
+Spending expiry, revocation and Module disablement stop the applicable new payments.
+Original Order reads/support use their original verified scope and Order-specific
+rules/deadlines; retaining history does not grant a different key access. Never
+merge by Safe or nickname alone. Historical read verification does not change the
+active binding or authorize a new purchase.
+
+Use [Market connection](../runbooks/market-connection.md), [renewal](../runbooks/policy-renewal.md)
+and [backup/restore](../runbooks/wallet-identity.md) for current user procedures.
+Account grouping is not a revocation mechanism: consult
+[emergency stop](../runbooks/emergency-payment-stop.md) for a compromised key.

package/doc/runbooks/commands.md

@@ -0,0 +1,103 @@
+# User command reference
+
+Use `agentpay` after installing the package or linking a source checkout with
+`npm link`. From a source folder, `./run` is the same entry; it uses Node on PATH
+or `AGENTPAY_NODE`.
+
+```sh
+agentpay help
+agentpay status
+```
+
+Top-level operations are `install --market URL`, `setup`, `repair [-f]`,
+`update [-f]`, `uninstall [--delete-data]` and `status`.
+Update checks npm and installs User with its pinned Wallet, then checks the official
+test Skill. It asks before changes unless `-f` is given. Source/npm-link installations
+use manual source updates followed by repair. Repair checks installed packages and
+confirms service interruption; `-f` skips that prompt only. Uninstall removes
+services and keeps data unless `--delete-data` is explicitly confirmed. Neither
+operation revokes on-chain permission.
+
+| Group | Operations |
+| --- | --- |
+| `wallet` | `info`, `unlock`, `lock`, `restore` |
+| `policy` | `info`, `renew`, `revoke` |
+| `service` | `start`, `stop`, `restart`, `autostart on/off`, `logs wallet/runtime` |
+| `market` | `connect [--market URL]` |
+| `orders` | `list`, `details ID`, `status ID`, `retrieve ID`, `case ID`, `archive ID`, `unarchive ID`, `files ID [remove KEY]` |
+| `cache` | `info`, `list`, `details ID`, `export ID PATH`, `clean`, `settings [KEY VALUE]` |
+| `payment` | `test` |
+
+A group without an action shows help; it never unlocks, revokes or changes files.
+Use `<group> help`, or `service autostart help`, to see focused instructions. Old
+flat commands such as `unlock`, `renew`, `connect-market`, `order ID details` are
+no longer accepted; use the grouped forms shown here.
+
+## Common tasks
+
+```sh
+agentpay service start
+agentpay wallet unlock
+agentpay status
+agentpay payment test
+
+agentpay policy renew
+agentpay policy revoke
+
+agentpay orders list
+agentpay orders details ORDER_ID
+agentpay orders retrieve ORDER_ID
+
+agentpay service autostart off
+agentpay service stop
+agentpay service logs runtime
+```
+
+`policy renew` covers expired renewal and active replacement. Revoking permission
+requires owner confirmation, and existing Orders retain their support rules.
+Service stop/Wallet lock do not revoke permission. Archive hides a local warning;
+it does not cancel or settle an Order. Retrieve requests the original result and
+never buys a replacement. Cache removal only removes local copies.
+
+Online Order operations require an unlocked Wallet. Start/unlock instructions and
+`status` guide you to the next action; setup renews expired authorization first.
+
+`status` includes a Policy section and expiry. “Within saved validity period” describes
+local saved validity, not a new chain/payment-readiness check. Revocation records
+are the last verification by this command suite. Unknown or conflicting scope is
+shown as unconfirmed; use `policy info` for saved details.
+
+`payment test` is the maintained end-to-end purchase check. In this release it uses
+the reviewed private-Anvil official Skill. It shows the current price and service
+time and asks before every new paid Order. If a test is unfinished, the same command
+resumes its saved request instead of starting another purchase. Completed test records
+are archived before a new one; the original onboarding test and Skill selection stay
+untouched. After verified delivery, Wallet acknowledges receipt, which can bring
+forward Provider payout.
+
+The command checks payment, delivery and receipt acknowledgement. Provider payout
+follows the Order’s settlement schedule; success does not claim final payout.
+
+
+### Order status sources
+
+`agentpay orders status ID` reads the current Settlement record through Wallet.
+It displays retrieval time and the record update time when available; it does not
+independently query the chain. If querying fails, the command labels the last
+local record and its saved check time. A successful query does not rewrite local
+history; Runtime maintains its own recovery observations. Use
+`agentpay orders details ID` for the saved local record.
+
+## Running-version checks (User 0.3.1)
+
+`agentpay status` compares the installed User/Wallet pair with the versions reported
+by the running processes. A mismatch leads to `agentpay repair`; missing reporting
+requires a paired package update first. Repair only records success after both
+processes report the expected package, local reporting interface and Protocol versions.
+These checks do not change Policy validity, Order identity or payment permissions.
+User 0.3.1 installs the required Wallet 0.3.1 dependency automatically.
+
+Protocol reporting reads the installed package resolved by that process, rather than
+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.

package/doc/runbooks/deployment-authorization-update.md

@@ -0,0 +1,42 @@
+# Update spending permission after contract changes
+
+Run `./run setup` or `./run policy renew`. Both check the published deployment and
+explain a mismatch before owner transactions. An existing Market connection supplies
+the HTTPS (or private loopback) configuration source. Without one, the guide can
+use the public deployment file downloaded by installation. `status` labels this
+as downloaded evidence rather than a current platform check.
+
+Review updated permission, using `details` to inspect old/new contracts. Factory and
+Module changes are supported within the same network, Safe, execution key, token,
+Registry and RPC. Network/token/Registry moves require separate review. Removing a
+Module as an emergency stop is not silently undone by an ordinary renewal.
+
+An update defaults to unspent allowance. Exhausted allowance has no automatic new
+budget default. Remaining validity supplies the duration default; retaining that
+default preserves the original expiry. Editing budget or duration deliberately
+requests new limits, which the owner reviews before signing. Ordinary renewal
+continues to offer a new budget and duration. No service-specific logic is involved.
+
+Owner approval revokes the original Policy before creating its replacement, enabling
+the destination Module if required. Wallet independently checks original revocation,
+matching identity, destination chain data and zero destination spend before binding.
+Original Policy scope and Orders remain in history. Temporary failure or leaving the
+webpage resumes the saved plan; do not delete records or create replacement purchases.
+A completed chain/binding operation with unfinished local synchronization retries
+that synchronization before a subsequent fresh renewal.
+
+After successful binding, setup settings/public Policy/draft projections are updated.
+Previous setup/draft files are retained privately. Existing Market connection flow
+continues; failure there does not undo authorization. No automatic login or new
+spending authority is granted by merely downloading deployment settings.
+
+`./run status` shares a 60-second success/error cache for deployment checks. A changed
+deployment takes priority over local missing-result warnings; Orders retain their
+warnings below. A failed check is unavailable, never healthy or proof of revocation.
+Matching deployment does not guarantee a particular service or Order can be bought.
+
+Development checks use controlled RPC/IPC fixtures. The recorded private participant
+MetaMask renewal, payment journey and historical Order viewing passed within their
+recorded scope. Full interruption/multisig and public-network acceptance remain
+separate tasks in [TODO](../TODO.md); viewing history does not prove every support
+mutation. No real-network compatibility is claimed by Anvil tests.

package/doc/runbooks/emergency-payment-stop.md

@@ -0,0 +1,80 @@
+# Emergency stop: disable AgentPay payments from your Safe
+
+Use this procedure if your computer or Wallet Session Key may be compromised.
+Use another trusted device and your Safe owner wallet. Do not enter owner keys,
+Session Keys or unlock passwords into Market or send them to support.
+
+This procedure assumes the Safe owner signers remain under your control.
+A compromised owner signer requires a separate Safe account recovery response;
+disabling a Module alone is not sufficient if an attacker can enable it again.
+
+## What disabling the Module means
+
+Your Safe permits the AgentPay Spending Module to execute bounded payments.
+Removing that Module from this Safe stops all new payments through that Module,
+across all its Policies and Wallet execution addresses. It does not disable the
+Module for other users' Safes or shut down AgentPay.
+
+A copied Session Key cannot bypass this stop: AgentPay funding calls the Safe's
+module execution function, which requires the Module to remain enabled.
+The stop takes effect only when the disabling transaction executes successfully
+on-chain. A pending proposal or owner signature is not a completed stop; payments
+may still execute before it.
+
+## Stop payments from a trusted device
+
+1. Open [Safe Wallet](https://app.safe.global/), select the correct network and Safe.
+2. Open Settings and find Modules (under advanced settings in some versions).
+   Identify the AgentPay Spending Module by its exact address, not only its label.
+   Your saved setup and `./run wallet info` expose that address, but information
+   displayed on the compromised computer must be independently checked.
+3. Select removal for that Module. Review the Safe, network and target Module.
+   Obtain the Safe's required owner approvals and execute the transaction.
+4. Confirm a successful chain receipt and verify
+   `isModuleEnabled(moduleAddress) == false` on the correct Safe.
+5. Check for other enabled AgentPay Module versions on this Safe, and repeat if
+   necessary. Each network and Safe must be handled separately.
+
+Safe exposes this through `disableModule(prevModule, module)`, called by a Safe
+transaction targeting the Safe itself. `prevModule` is the predecessor in its
+enabled-module linked list, not a previous AgentPay release. Do not guess this
+address or submit a direct owner-account call as a substitute for a Safe transaction.
+
+Official references:
+[Managing Modules](https://help.safe.global/articles/7039805766-add-a-module),
+[disableModule](https://docs.safe.global/reference-smart-account/modules/disableModule).
+
+## What remains unchanged
+
+- Safe owner operations remain available. Other unrelated enabled modules are not removed.
+- Already-funded Order Vaults retain their delivery, cancellation, dispute, payout
+  and refund rules. This operation does not refund them.
+- Policy records remain on-chain. Disabling does not revoke or delete them.
+- Market Disconnect, sign-out, stopping Runtime or locking Wallet do not replace
+  this chain operation. An attacker may hold a copied key elsewhere.
+- This is a payment stop, not revocation of every history/support credential.
+  Do not assume copied credentials lose all non-payment access.
+
+## Before restoring payments
+
+Keep the Module disabled while investigating. Replace the compromised execution
+key and revoke its still-valid Policies through the Safe owner before re-enabling
+the Module. Review all relevant Policies, including ones absent from Market's
+connected list. Re-enabling without this cleanup can restore an attacker's
+remaining spending permission.
+
+Use a trusted installation for the replacement Wallet. Do not restore a suspected
+leaked key as a security remedy. Keep Order history and incident evidence; do not
+repeat paid requests to recover missing results.
+
+## Current product and rehearsal limits
+
+Market currently provides connection management and revocation documentation;
+it does not execute this emergency Safe transaction. `./run policy revoke`
+addresses the locally selected Policy, not every Policy or the entire Module.
+See [Policy renewal and revocation](policy-renewal.md).
+
+The private Anvil rehearsal is not available through the hosted Safe Wallet.
+It needs a separately prepared owner-authorized Safe transaction and independent
+chain checks. No emergency Module-disable rehearsal has been completed by writing
+this guide. Do not send private rehearsal transactions to a real network.

package/doc/runbooks/local-autostart.md

@@ -0,0 +1,212 @@
+# Local automatic startup (Linux)
+
+Wallet and Runtime can start as systemd user services when you log in. Wallet starts
+locked. Your Session Key and existing Safe Policy are reused; no password is saved.
+This does not enable startup before login or require administrator access/linger.
+
+## Enable during setup
+
+After the official connectivity test succeeds, the Linux terminal guide asks once
+whether Wallet and Runtime should start automatically when you log in. Choosing yes
+installs/enables the services and reminder without restarting current processes.
+Choosing no keeps manual startup. Your choice is remembered; q leaves it undecided.
+A saved yes is retried after partial installation failure without repeating consent
+or creating another payment. Manual enable/disable updates the same preference.
+
+The installer verifies that existing listeners belong to its matching guide processes
+or existing user services. Missing/stale PID records, mismatched arguments/data paths,
+and system-managed processes block automatic adoption. It never kills a PID from a
+saved file. On the private shared host, operator services remain operator-managed.
+
+## Manage after setup
+
+The terminal setup start step saves your public Runtime/Settlement addresses in
+`runtime/local-services.json` under your remembered User data directory. From User:
+
+```bash
+./run service autostart on
+```
+
+This installs and enables the services for the next login. It does not replace or
+stop current terminal-started or operator-managed processes. Current guide processes are left running; the handoff is deferred until they exit
+or the computer restarts. Do not run two managers for the same Wallet.
+If a login happens while old processes still run, managed startup refuses the occupied
+socket/port; inspect status and explicitly stop the old processes before using start.
+After a clean login, use `./run wallet unlock` to resume signing.
+
+If you completed setup before this feature, an operator can save the matching public
+addresses once with `node scripts/autostart.mjs configure RUNTIME_URL SETTLEMENT_URL`.
+Use your existing deployment, not arbitrary endpoints. This saves settings only.
+Do not change endpoints to work around an incomplete request or Policy migration.
+
+## Manage
+
+From User, `./run status` shows the services. Use `start` or
+`stop` for these managed processes. Before manually starting them, stop any existing
+terminal/operator-managed instance explicitly. A live Wallet socket or Runtime port
+is rejected; it is never removed to take over an existing process.
+
+`./run service autostart off` disables login startup without stopping current processes.
+`./run service stop` stops them now without changing the login preference.
+`./run service start` starts them manually; `./run service restart` restarts them locked.
+`./run service logs runtime` shows recent Runtime service errors. Wallet data and history remain.
+This is not on-chain revocation, deletion of the installation, or Order cancellation.
+
+Files are installed under `~/.config/systemd/user/`: agentpay-local-wallet.service,
+agentpay-local-runtime.service and agentpay-wallet-reminder.service. The installer
+does not use or change `~/.config/autostart`, including its permissions or contents.
+A conflicting existing file is preserved and reported. Services use absolute Node
+and source paths; do not move/delete those paths before disabling/reconfiguring.
+The current implementation uses the standard ~/.config location.
+
+## Login reminder
+
+A systemd user oneshot, enabled for graphical-session.target, checks Wallet status
+and sends one best-effort notification
+if it is locked. It does not unlock, prompt for a password, open a terminal or make
+a payment. The notification tells you to open User and run `./run wallet unlock`.
+There is no click-to-unlock action in this first version.
+
+Linux needs a desktop environment that starts systemd graphical-session.target and
+imports its display/session environment, a notification service, and `notify-send`.
+The reminder stays active until graphical logout (PartOf + RemainAfterExit) so normal
+Wallet restarts do not repeat it. Manual service start starts only Wallet/Runtime. With SSH/headless
+sessions, missing notification support or an already unlocked Wallet, no popup is
+sent. Runtime/Skill locked errors still show the unlock command. A missed notification
+does not grant authority or block service startup. If Wallet does not become available
+during bounded checking, inspect service status; notification is not a health monitor.
+
+## Acceptance scope
+
+Isolated process tests verify locked Wallet/Runtime startup, duplicate Wallet refusal,
+stop/restart with unchanged test key and no invocation. Unit/CLI tests and systemd
+file validation passed. The terminal installer now offers deferred automatic startup after its successful
+connectivity test; it does not immediately replace guide processes. The participant reported successful Wallet restart/lock/unlock and a manually triggered
+desktop reminder. Runtime exited with status 1; its journal is still required. Actual
+login/reboot and complete Runtime recovery acceptance remain pending. macOS launchd support is pending.
+Do not manually enable these user services on the shared rehearsal host while its operator
+services use the same data/socket/port. No existing rehearsal service was changed.
+
+The `startupChoice` field in local-services.json records the requested preference,
+not proof that systemd enable/start succeeded. Use status to inspect actual services.
+If setup reports automatic startup pending, current processes remain in place and
+local keys/Policy/history remain unchanged; retry enable after correcting the problem.
+
+Desktop environments without that systemd session integration may not show a reminder;
+Wallet/Runtime still start through the user default target and locked-call guidance
+remains available. No password is collected through the notification. The former
+prototype desktop entry is not generated or automatically deleted by this version.
+
+## Uninstall
+
+Run `./run uninstall` in an interactive terminal. It lists the selected local
+installation and requires the exact phrase `DELETE LOCAL AGENTPAY DATA`.
+Confirmation stops/removes its managed services and permanently deletes its local
+Session Key, credentials, installed Skills, recovery history and installer settings.
+It preserves the source repositories and tells you to delete User and Wallet folders
+once cleanup succeeds. Other installations and unrelated startup files are preserved.
+Unknown service definitions, active external listeners or unsafe paths block cleanup.
+
+Uninstall does **not** revoke Safe authorization or cancel Orders. Resolve pending
+Orders and revoke permission separately before retiring an installation. Reinstalling
+cannot recover deleted keys or request history. Neither `stop` nor `autostart-off`
+deletes data. Graphical password input is deferred; unlock remains a terminal command.
+
+## Private rehearsal networking
+
+Current Anvil settings contain loopback RPC, Settlement and package URLs, and the
+published reference package still uses a loopback Provider URL. A desktop using those
+settings needs the arranged SSH tunnels. Existing nginx routes do not rewrite saved
+configuration or package identities. Keep Anvil and local Wallet/Runtime private.
+A production installation must use public HTTPS Market/Settlement/Provider URLs and
+an appropriate chain RPC; SSH forwarding is not a normal user installation step.
+Public settings/package handoff and production owner signing remain release work.
+
+## Startup self-check and historical Orders
+
+Runtime starts its authenticated local listener before checking business history.
+`./run status` shows process state, local inventory, Wallet availability and Order
+check counts separately. A running process is not proof that a purchase is eligible.
+The local `/status` endpoint requires the existing caller credential; `/health`
+remains a minimal liveness endpoint.
+
+The background task only reads Wallet status and original Settlement Orders. Locked
+Wallets wait for unlock; unavailable services are retried with bounded backoff.
+It does not create Orders, send payments, execute Provider work, confirm receipt or
+cancel Orders. Existing Settlement workers retain their automatic refund duties.
+
+Old invocation records stay unchanged. Known legacy requests cannot be replayed as
+new purchases. Valid inventory permits unrelated requests through ordinary checks;
+unreadable/missing/conflicting history or failed recovery-state writes pause new
+paid calls without stopping the status listener. Missing caller authentication or
+an occupied port still prevents unsafe startup.
+
+Financial state and verified result availability are separate. A settled Order with
+no verified local output is reported explicitly; Runtime will not re-execute that
+settled service request to replace missing output. Unknown IDs, mismatched identities,
+legacy output formats and unavailable original deployment access require review.
+Do not delete history or add routing-version fields to bypass those protections.
+
+Observations are saved privately beside `runtime/invocations.json` in
+`runtime/invocations.json.recovery.json`; the original history, signed payloads and
+result files are not migrated or erased. The observation file contains identifiers,
+check times and conclusions, not private inputs, outputs or signatures. It is part
+of the selected local data removed only by confirmed uninstall. Cached observations
+are not a substitute for the Wallet/Settlement checks on each actual invocation.
+
+The queue handles at most 4 records per pass, one read at a time. The IPC timeout allows Wallet's
+30-second HTTP deadline to finish before the next read. Passes wait about
+10–11 seconds after the previous pass; pending Orders are rechecked after 30 seconds, failed reads use
+backoff up to five minutes, and terminal observations at most hourly. `./run status`
+wakes a pass without bypassing per-Order backoff. Large inventories can take several
+passes. All observed times are Unix milliseconds internally.
+
+### Reading status
+
+`./run status` groups services, Orders and one suggested next command. A live Wallet
+read takes precedence over an older background observation when describing lock state.
+Green `[OK]`, yellow `[WAIT]` and red `[!]` distinguish normal, waiting and blocked
+conditions in interactive terminals. Redirected output is plain text; `NO_COLOR` or
+`TERM=dumb` also disables color. Labels remain readable without color.
+
+Status layout wraps explanations for terminals of at least 40 columns, keeps service
+columns aligned with or without color, and does not show zero Orders when inventory
+is unavailable. A successful summary says local checks passed, not payment approved.
+
+Login startup reports Enabled/Disabled only when systemd confirms that setting.
+Not configured for this user means the corresponding user unit is absent; it does
+not describe administrator-managed services. Could not check means the query did
+not establish the setting. Temporary enablement and masking are shown separately.
+Start/restart output confirms that systemd accepted a request, not that Runtime
+finished self-check; use status next. Stop/off remain separate operations.
+
+### What to do next
+
+| Status | Action |
+| --- | --- |
+| Runtime/Wallet stopped | Use the displayed start command, then check status. |
+| Status unavailable | Inspect the indicated service log; do not reset history. |
+| Locked | Run `./run wallet unlock`; background Order checks resume. |
+| Permission missing | Run `./run setup`. An existing migration must follow its original update instructions instead. |
+| Initial checks in progress | Leave services running; check after about 15 seconds. Large histories take longer. |
+| Order check temporarily unavailable | Automatic backoff continues. If persistent, check network and Runtime logs. |
+| Orders in progress | Keep services running and use the original Agent conversation. Only resume supported original requests with their original identifiers. |
+| Identity/state/result conflict, unknown Order or missing Order ID | Preserve history; ask AgentPay support to review the Order/status. Do not share secrets or signed payloads. |
+| Payment complete; local result unavailable | Check the original conversation, then ask the Provider using the Order ID. Repeated status checks cannot reconstruct the result; do not pay again to recover it. |
+| Local checks passed | This check is finished. Normal checks still apply to each purchase. |
+
+Mixed histories retain per-Order explanations; pending Orders continue automatic
+checks even when another Order needs review. Background terminal-state rechecks
+remain enabled; the guidance does not change recovery scheduling.
+
+## Missing startup settings
+
+`./run service start` prepares missing user-service configuration for an initialized Wallet.
+It reuses private User settings and asks for any missing endpoint in the terminal.
+It never reads platform secret configuration or changes your Policy.
+`./run market connect` uses the same preparation before rebuilding/restarting when
+needed. Preparing services does not turn on login startup. Conflicting saved
+addresses stop the flow for review; no new identity is generated.
+
+An old system-level installation requires an operator handoff first; User does not
+stop root services. Do not initialize another Wallet to fix process management.