@c4roa0/agentpay-user 0.0.0-stage → 0.3.0

package/doc/README.md

@@ -0,0 +1,52 @@
+# User documentation
+
+## Start by role
+
+| Reader | Start here |
+| --- | --- |
+| Installing User | [README](../README.md), [installation](runbooks/user-onboarding.md), [usage](usage.md) |
+| Managing an existing installation | [Commands](runbooks/commands.md), [updates](runbooks/local-update.md), [background services](runbooks/local-autostart.md) |
+| Skill author / Agent integrator | [Shared Runtime client](runbooks/runtime-skill-client.md), [invocation contract](reference/multi-service-runtime.md), [file cache](reference/result-file-cache.md) |
+| Contributor | [Developer guide](develope.md), [source map](architecture.md), [design](design.md), [tests](../test/README.md) |
+| Security reviewer | [Reporting](../SECURITY.md), [owner page boundary](reference/local-safe-owner-ui.md), [recovery](reference/original-order-recovery.md) |
+| Maintainer | [Progress](../progress.md), [TODO](TODO.md), [public-source review](security/public-source-review-2026-11-06.md) |
+| AI contributor | [AGENTS](../AGENTS.md), then current progress and affected interfaces |
+
+## User guides
+
+- [Owner browser approval](runbooks/safe-owner-web.md)
+- [Renew or revoke permission](runbooks/policy-renewal.md)
+- [Deployment authorization update](runbooks/deployment-authorization-update.md)
+- [Wallet backup and restoration](runbooks/wallet-identity.md)
+- [Market connection](runbooks/market-connection.md)
+- [Order support](runbooks/order-support.md) and [cancellation](runbooks/order-cancellation.md)
+- [Cache management](runbooks/local-cache.md)
+- [Emergency payment stop](runbooks/emergency-payment-stop.md)
+
+## Implementation references
+
+- [Public deployment settings and signer selection](reference/public-deployment-settings.md)
+- [Wallet identity and Policy history](reference/wallet-identity-policy-history.md)
+- [Startup and Order recovery](reference/runtime-startup-recovery.md)
+- [Runtime address recovery](reference/runtime-address-recovery.md)
+- [Cache foundation](reference/local-cache-foundation.md), [input/output snapshots](reference/skill-input-output-cache.md), [result persistence](reference/runtime-result-cache.md)
+- [Harness integration](reference/harness-skill-runtime.md)
+- [Local repair](reference/local-update.md)
+- [Onboarding writing rules](reference/onboarding-writing.md)
+
+## Scoped development / advanced procedures
+
+- [Official package maintenance](runbooks/official-test-package.md), [random test example](reference/random-skill-contract.md)
+- [Terminal demo preview](runbooks/terminal-authorization-preview.md)
+- [Private Anvil setup](runbooks/private-anvil-terminal-setup.md)
+- [Initial Safe authorization](runbooks/safe-policy-setup.md), [advanced migration](runbooks/safe-policy-migration.md)
+- [Unlock instructions](runbooks/unlock-wallet.md)
+
+The [User/Wallet distribution plan](plans/user-wallet-distribution.md) describes future
+compatibility and combined packaging work. `reference/` describes implemented design;
+`runbooks/` provides operation steps; `security/` records boundaries and review scope.
+Private platform histories and harnesses are retained outside this public tree.
+
+- [User npm integration verification](reference/npm-integration-verification.md): candidate installation, repair and evidence limits.
+
+- [npm publication](runbooks/npm-publication.md): archive checks, initial upload and GitHub Trusted Publisher.

package/doc/TODO.md

@@ -0,0 +1,97 @@
+# User TODO
+
+## npm update follow-up — 2026-11-07
+
+- [x] Implement confirmed `agentpay update [-f]`, exact User target and matching Wallet; invoke new repair and pinned official Skill check.
+- [x] Fix relocation preparation ordering, matching legacy purge and packaged document links.
+- [x] Complete update/migration regressions (374 full-suite and 35 final targeted checks) and real npm replacement of local candidate artifacts; controlled service/registry dependencies.
+- [ ] After User release, verify a real published-version npm upgrade and participant service recovery.
+
+## npm client distribution — 2026-11-07
+
+- [x] Record npm-first plan; combined source ZIP is optional, not the primary installer.
+- [x] Step 1: commit verified User/Wallet Protocol dependency migration baseline.
+- [x] Step 2: prepare Wallet public entry points, compiled npm artifact and standalone acceptance (29 behavioral tests plus installed-package CLI/IPC lifecycle).
+- [x] Review step 2: guard normal packing against missing/stale builds, correct public-interface docs and verify a standalone TypeScript consumer.
+- [x] Step 3: migrate User to Wallet npm dependency and `agentpay` entry; remove sibling/build assumptions; isolated tarball/process acceptance passed.
+- [x] Step 4a: exact installed-package checks, service-path/client relocation, installer lock, recovery-safe preparation and explicit uninstall modes.
+- [ ] Step 4b: running-daemon version/interface negotiation and participant upgrade/interruption acceptance.
+- [ ] Step 5: publish Wallet then User via OIDC; verify registry installs and update Market guides.
+  - [x] Wallet 0.3.0 first Token publication; registry integrity/latest and fresh public install/CLI/IPC verified.
+  - [x] Owner configured Wallet npm Trusted Publisher (pending validation).
+  - [ ] Validate Wallet OIDC with a later reviewed release. User publication and Market guide updates remain pending.
+- [ ] Step 6: participant setup/upgrade/restart/uninstall and official Anvil paid acceptance.
+
+
+## Public npm Protocol dependency
+
+- [x] Pin npm core 0.14.3; migrate imports, fixtures, lockfile and notices.
+- [x] Update exact User/Wallet pair checks; reject mixed archive/npm or mismatched dependencies.
+- [x] Remove vendor-directory assumptions from install/repair fingerprints.
+- [x] Verify isolated sibling install/build, all 364 tests and real prepare-only retry; remove old archives.
+- [ ] Commit/push the matching User and Wallet revisions together before participant synchronization.
+
+
+## Public-source preparation
+
+- [x] Inventory current source, archives, private harnesses and contributor prerequisites.
+- [x] Select MPL 2.0 for original User code; preserve separate third-party licenses.
+- [x] Privately archive old Protocol packages, platform-only scripts and operational history.
+- [x] Use the reviewed public Protocol artifact; remove unused MySQL dependency.
+- [x] Replace sibling Agent/Protocol test dependencies with attributed local/public-package fixtures.
+- [x] Rewrite current entry guides and source map; separate implemented references from future plans.
+- [x] Finish behavioral test review, code readability checks and isolated User + Wallet verification: 364 tests passed, no failures or skips.
+- [x] Correct follow-up review findings: identity/support instructions, explicit signer flow, installation prerequisites and legacy-preview comments.
+- [x] Owner approved history reset/public visibility; anonymous main ref verified, with no published tags.
+- [ ] Verify full anonymous clone and ZIP installation independently of source-ref access.
+
+## Independent distribution (next development loop)
+
+- [ ] Define the supported Wallet client/IPC boundary and source/build/running compatibility requirements.
+- [ ] Replace exact version pairing with reviewed compatibility checks; preserve keys, Policies and recovery.
+- [ ] Optional later: combined ZIP/platform assets after primary npm installation acceptance.
+- [ ] Verify fresh Git/ZIP installation and missing/incompatible/stale version recovery; update Market guidance.
+
+See [distribution plan](plans/user-wallet-distribution.md). These changes are not
+implemented by the current source cleanup. Repair still applies downloaded local code.
+
+## Network and owner approval gates
+
+- [ ] Design official test package/network mapping (N4), keeping release-pinned executable SHA checks.
+- [ ] Finish general deployment/artifact output and coherent confirmation settings (N5/N7).
+- [ ] Finish public URL/settings handoff (N8); ordinary public-network users must not need private rehearsal tunnels.
+- [ ] After the official domain is chosen, define the default HTTPS Market address.
+- [ ] Accept multisig, interrupted owner signing, headless tunnel and portable-page recovery with participants.
+- [ ] Verify browser RPC reachability/CORS and approved Safe versions on the selected network.
+- [ ] Run explicitly scoped same-code public-testnet acceptance; no real funds/reset is implied by these tasks.
+- [ ] Evaluate WalletConnect/QR only if required; current browser flow uses an injected wallet.
+
+## Retained participant and recovery acceptance
+
+- [ ] Complete original-key/Policy restore on an isolated installation, including invalid/absent/expired/revoked scope and unavailable RPC; never fall back to a new purchase.
+- [ ] Complete post-renewal Market reconnection cancellation/failure checks and grouped old/new Policy Order/case access; viewing Orders alone does not prove support mutation.
+- [ ] Verify case evidence, original-result retrieval, withdrawal/reopening and deadlines through participant entry points.
+- [ ] Complete remaining real Runtime interruption and late-funding recovery acceptance with authoritative financial reconciliation.
+- [ ] Verify full desktop login/reboot, reminder failure/dismissal, wrong-password recovery and deferred service handoff.
+- [ ] Verify confirmed uninstall on disposable local data and no change to on-chain permission.
+- [ ] Verify detailed status/cache/owner-page presentation and narrow-terminal readability with participants.
+- [ ] Verify maintained Skill discovery, tool permission and execution in supported Agent harnesses.
+- [ ] Define maintenance-response handling (503/Retry-After) while retaining original request identity.
+- [ ] Complete official package release/configuration handoff, installation and endpoint/settings refresh for release.
+- [ ] Inspect implicit address, service, platform and repository assumptions during each change.
+
+Prior Market schema/cutover, nickname and display tasks are platform-owned; they must
+not turn into User database access. Existing source now implements key restore/info,
+Policy renewal/revoke, user service startup and deployment-mismatch guidance. Their
+older unchecked implementation labels are superseded by current code; remaining
+participant/recovery acceptance is retained above. Historical one-off request
+investigations remain private operator work, not a public contributor prerequisite.
+
+## Deferred / release gates
+
+- [ ] Independent security review, supported-version policy and release provenance before real funds.
+- [ ] macOS startup, graphical unlock and embedded-Node/multi-platform packaging remain separately scoped.
+- [ ] Broader business/harness acceptance uses maintained fixtures; do not require third-party Skills for installation verification.
+
+Original chronological TODO snapshots are preserved in the private workspace.
+Consolidation does not turn historical partial evidence into completed acceptance.

package/doc/architecture.md

@@ -0,0 +1,96 @@
+# User Runtime architecture
+
+## Processes and authority
+
+```text
+Human / Agent
+  ├─ ./run → local administration, owner browser approval, service management
+  └─ installed Skill → shared client → authenticated loopback Runtime
+                                      ├─ narrow Wallet IPC → bounded signatures
+                                      └─ Provider HTTP → private input/output
+Wallet / User participant clients → public Settlement and Market APIs
+```
+
+Wallet runs separately and holds the encrypted Session Key. Safe/Module enforce
+on-chain permission. User owns orchestration and recovery, not Provider business
+logic or platform storage. No Settlement checkout or database access is required.
+
+## Shared Protocol dependency
+
+User and Wallet pin `@c4roa0/agentpay-protocol@0.14.3` from npm. Their lockfiles
+record integrity. The current repair gate still checks the exact repository versions
+and shared Protocol dependency in `update-pair.json`; `typesDependency` is the
+retained v1 field name for that npm version. It is not a compatibility range.
+Installation/repair fingerprints cover manifests and lockfiles rather than a vendor
+folder. Policy, Order and cached request identities are independent of this package
+name change. Independent-version compatibility remains a separate planned feature.
+
+## Source map
+
+| Area | Main files | Responsibility |
+| --- | --- | --- |
+| CLI | `run`, `scripts/agentpay-cli.mjs`, `src/user-cli.mjs` | Node discovery, grouped commands and help |
+| Install / repair | `install-user.mjs`, `install-and-setup.mjs`, `install-preflight.mjs`, `local-update.mjs` | Dependency/build preparation, checkpoints, downloaded settings and safe restart |
+| Setup | `guided-setup.mjs`, `user-setup-guide.mjs`, `anvil-onboarding.mjs` | Terminal sequence and saved-step continuation; explicit signer mode |
+| Permission | `policy-terminal-guide.mjs`, `safe-policy-plan.mjs`, `renew-policy.mjs`, `policy-operations.mjs`, `policy-migration.mjs` | Drafts, approved operations and verified local binding |
+| Owner signing | `owner-signer.mjs`, `owner-approval-server.mjs`, `web/owner-approval.js`, `safe-owner-anvil.mjs` | Fixed browser approval plans or guarded explicit test signer |
+| Local services | `local-services.mjs`, `autostart-files.mjs`, `setup-autostart.mjs`, `scripts/local-service.mjs` | Linux user services, startup preferences and locked Wallet restart |
+| Runtime | `index.mjs`, `caller-auth.mjs`, `transport.mjs`, `service-reference.mjs`, `service-url.mjs` | Caller authentication, per-call routing, payment and evidence orchestration |
+| Durable request / result | `invocation-store.mjs`, `invocation-result.mjs`, `runtime-recovery.mjs` | Original identities/checkpoints, provisional versus verified output, read-only startup checks |
+| Skill client | `runtime-client.mjs`, `skill-client.mjs`, `client-request-lock.mjs` | Local discovery, input snapshots, original-request selection and replay |
+| Files / cache | `file-cache.mjs`, `file-download.mjs`, `file-cache-owner.mjs`, `cache-management.mjs`, `result-cache-view.mjs` | Explicit transfers, integrity/limits, provenance, cleanup and display |
+| Orders | `order-support.mjs`, `order-cancellation.mjs`, `order-closure.mjs`, `order-review.mjs` | Original result retrieval, cases, cancellation and local review/archive |
+| Market | `connect-market.mjs`, `local-wallet-ipc.mjs` | Deliberate account connection and fixed Wallet proof |
+| Presentation | `status-panel.mjs`, `order-list-panel.mjs`, `order-status-panel.mjs`, `local-info.mjs` | Human-readable local/remote observations and next actions |
+| Packages | `skill-bundle.mjs`, `skill-zip.mjs`, `active-skill.mjs` | ZIP boundaries, installation and official material selection |
+| Official test | `official-paid-test.mjs`, `official-test-package.mjs`, `official-test-update.mjs` | Reviewed package digest, explicit price consent and test recovery |
+
+Unless a path starts with `scripts/` or `web/`, filenames in this table are under
+`src/`. Most scripts are thin command entries. `anvil-onboarding.mjs` retains its
+historical filename but supports explicit external-owner signing as well; do not
+infer permission to choose a test signer from the filename.
+
+## Purchase and recovery path
+
+1. Skill code calls the shared client with a service reference and validated input.
+   The client saves request/input identity before contacting Runtime.
+2. Runtime authenticates the local caller, resolves or resumes the durable request,
+   obtains terms through Wallet and preserves the accepted transaction conditions.
+3. Wallet prepares/reads the Order and signs only within its verified boundaries.
+   Runtime forwards payment material through the defined Provider protocol; no
+   Session Key is exposed.
+4. Provider input/output remain on the private service path. Runtime stores received
+   output separately from its verified result and checks matching delivery evidence.
+5. Repeated calls reuse original checkpoints. Startup reconciliation observes Order
+   state; it does not create replacement purchases or automatically acknowledge
+   receipt. Only a completed verified result is eligible for normal cached replay.
+
+The startup checker and local result store track different facts: an Order may be
+paid out while its result is missing locally. Keep this visible and offer original
+result recovery; do not charge again to hide the inconsistency.
+
+## Local state
+
+The selected private User data directory defaults to
+`$HOME/.local/share/agentpay/user`. `local-data-directory.mjs` resolves it; do not
+hard-code an operator's historical directory. Important state includes Wallet's
+keystore/Policy, Runtime caller credential and connection locator, invocation
+history, input/result caches, owner-operation journals and Market connection receipt.
+The receipt is local convenience metadata, not live website authorization.
+
+Owner approval pages receive only fixed public operation plans. They cannot access
+Wallet IPC or keys. Successful browser execution is followed by local chain
+verification before binding. A lost response resumes the original plan.
+
+## External dependencies and development boundary
+
+User resolves the installed Wallet package through public client, local-administration
+and CLI exports. Exact reviewed dependency versions are checked; independent
+running-process compatibility negotiation remains planned. User imports ethers from its own
+declared dependency. The pinned public Protocol package provides types, hashes and
+fixtures. No Agent, Protocol source checkout or private platform repository is
+required for the local test suite.
+
+Tests use public interfaces and controlled remote responses. The explicit fault
+loader only instruments a spawned test Runtime; production startup contains no
+crash-test switch. See [test guide](https://github.com/c4rO-0/agentpay-user/blob/main/test/README.md) for evidence limits.

package/doc/design.md

@@ -0,0 +1,60 @@
+# User Runtime design
+
+## Bounded purchases, separate authority
+
+The human grants bounded Safe spending permission once. Normal eligible Skill
+calls use that permission without repeated owner signatures. User coordinates the
+interaction; Wallet owns the Session Key and only exposes bounded operations.
+Neither Skill code nor Runtime receives generic owner signing authority.
+
+A Skill may use local logic and zero, one or multiple services. Each paid call
+carries its own registered service reference and private JSON input. Business
+validation belongs to the Skill/Provider. Runtime validates common identities,
+amount/usage bounds, delivery evidence and recovery state. The official random
+service is only the installation payment test, not a global service requirement.
+
+## Preserve one purchase attempt
+
+Request identity binds the service, input and accepted conditions, not the local
+Runtime port. Retry resumes the original attempt or returns its verified saved
+result. Ambiguous or incomplete history pauses for review; it must not become a
+new paid attempt. A deliberate new purchase requires explicit new-request intent.
+
+User persists private input snapshots, request/payment checkpoints and results.
+Received output is not a verified result until its evidence is checked. Binary
+attachments are explicitly cached, bounded and integrity checked; arbitrary output
+links are not downloaded automatically. See [cache reference](reference/result-file-cache.md).
+
+## Authority is not display grouping
+
+Market groups Wallets by network, Module, Safe and execution address. Each verified
+Policy still bounds access to its original Orders. A nickname is display metadata,
+not a machine identity. Renewing permission preserves local history and does not
+implicitly grant access to another delegate's Orders. See
+[Wallet identity](reference/wallet-identity-policy-history.md).
+
+Expiry stops new spending, while original-Order support follows its own verified
+rules and deadlines. Revocation, Module disablement, process stop and local lock
+are different operations. A saved binding alone does not establish current chain
+readiness. Historical reads never silently switch the active spending Policy.
+
+## Network and operator boundaries
+
+Anvil and supported public EVM deployments use the same product flow with explicit
+validated configuration and signer selection. Anvil chain ID is not permission to
+use unlocked test accounts. External-owner signing must work on Anvil too.
+Deployment changes require deliberate authorization review; they do not rewrite
+saved requests or grant arbitrary signing.
+
+User accesses Market and Settlement through public participant APIs, not their
+databases or private files. Local caller authentication is not OS sandboxing against
+code running as the same user. Logs and public services must not receive private
+inputs, result bodies, keys or bearer credentials.
+
+## Remaining product work
+
+User consumes a pinned public Wallet package without sibling source assumptions.
+Running-process compatibility negotiation and optional combined installers remain
+[planned](plans/user-wallet-distribution.md). Real-network, multisig and additional
+platform acceptance remain explicit gates in [TODO](TODO.md); private results do
+not establish production safety.

package/doc/develope.md

@@ -0,0 +1,68 @@
+# Develop AgentPay User
+
+## Independent checkout
+
+Read [README](../README.md). Use Node.js 22.22.3 or newer and npm in User:
+
+```sh
+npm ci
+npm test
+```
+
+The test command runs files sequentially to limit resource use. It uses disposable
+files, keys, subprocesses and loopback endpoints. No private Settlement/Market source,
+database, live chain or Provider checkout is needed. Protocol fixtures are loaded
+from the pinned package; reference Skill fixtures live under `test/fixtures/`.
+Some tests use real Wallet IPC; others deliberately simulate upstream interfaces.
+
+For focused iteration:
+
+```sh
+node --check src/runtime-client.mjs
+node --test test/runtime-client.test.mjs
+node --test test/multi-service-runtime.test.mjs
+```
+
+Do not use `./run payment test` as an unattended unit test: it requires configured
+services and explicit consent for a real paid Order on the configured test network.
+Do not run install/setup against your personal state to prepare unit-test fixtures.
+
+## Reading order
+
+1. [Architecture/source map](architecture.md) and [design rationale](design.md).
+2. `src/user-cli.mjs` for command routing; setup/repair modules for human flows.
+3. `src/runtime-client.mjs` and `src/skill-client.mjs` for the Skill boundary.
+4. `src/index.mjs`, `invocation-store.mjs` and `runtime-recovery.mjs` for one request
+   from preparation through delivery and restart observation.
+5. `owner-signer.mjs`, `safe-policy-plan.mjs` and the browser page before changing
+   owner approval; inspect Wallet's authority checks separately.
+
+Use [documentation by role](README.md) and the [test map](https://github.com/c4rO-0/agentpay-user/blob/main/test/README.md) to find
+more focused material. Plans describe future work; local reference documents and
+current source describe implemented behavior.
+
+## Verification rules
+
+Test user-observable outcomes through product entries. Keep exact signature/hash,
+amount, expiry, capability and cross-Order rejection tests where they protect a
+specific boundary. A mocked package manager tests orchestration, not installation;
+a mocked Provider cannot prove funding or actual delivery. Recorded private
+acceptance is not public-network or production approval.
+
+Fault injection belongs only to the explicit test loader. If source layout changes,
+update its anchors to the same durable boundary and rerun process recovery tests.
+Never add test-only branches to normal Runtime or change request identity to make
+recovery pass. At least two controlled business payloads must use the same engine;
+normal operation must not depend on the random example.
+
+## Maintainability and scope
+
+Keep code multiline and comment trust decisions, saved-state transitions and
+recovery ordering. Avoid comments that repeat statements. Preserve canonical bytes,
+wire names and public errors during formatting. Prefer one focused regression over
+several assertions about implementation shape.
+
+User consumes Wallet through its public package exports and exact reviewed version.
+Running-process compatibility negotiation remains in the
+[distribution plan](plans/user-wallet-distribution.md). No automatic source downloads are
+introduced by repair. Keep private platform experiments outside this repository.

package/doc/plans/user-wallet-distribution.md

@@ -0,0 +1,91 @@
+# Independent User and Wallet distribution
+
+Updated 2026-11-07. The approved primary distribution direction is npm for Protocol,
+Wallet and User. This replaces the 2026-11-06 combined-source-ZIP-first plan.
+Repositories, processes and releases remain separate; Node is still required.
+
+## Intended user experience
+
+Ordinary users install `@c4roa0/agentpay-user` and run `agentpay setup`. User installs
+its reviewed Wallet dependency; both consume public Protocol. No sibling source
+folders, pnpm or local TypeScript build are required for the published User path.
+Wallet remains independently installable. Git checkouts are for contributors; the User 0.3.0 candidate now uses the same
+public Wallet package. User npm publication remains a separate release step.
+Combined ZIPs and platform binaries are optional later work, not a release prerequisite.
+
+npm installation only installs program files. Key creation, background-service
+configuration, owner approval and payments require explicit product commands.
+No postinstall hook may initialize keys, register services or authorize spending.
+Keys, Policies, request history and cache stay outside package installation paths.
+
+## Dependency and authority boundaries
+
+User -> Wallet -> Protocol, and User -> Protocol. Publish only reviewed runtime
+files, public declarations, documentation and licenses. Wallet ships compiled JS.
+Use exact reviewed dependency versions initially; independent compatibility ranges
+are a later step. Versions need not have the same number across repositories.
+
+Replace User imports of Wallet internals with documented IPC-client and local
+administration entry points, and resolve the CLI through the installed package.
+Normal service calls remain capability-scoped IPC; trusted local administration is
+not an Agent API. Do not expose generic signing or let a package dependency move
+Session Key ownership into Runtime. Generic private-file helpers belong to User's
+own storage boundary, not a new public Wallet API solely to preserve an old import.
+
+Check installed interface requirements and running Wallet identity before enabling
+incompatible operations. Installation/version metadata alone is not proof that the
+current daemon matches. Preserve diagnostic and recovery access on mismatch; never
+replace purchases, Policy identity or keys to resolve an upgrade failure.
+
+## Upgrade and uninstall
+
+Review -> confirm -> stop services -> install update -> repair executable paths ->
+start and self-check -> request unlock. Do not let an arbitrary latest-version
+lookup replace executable code. `repair` repairs installed files; downloading an
+update is a distinct action. Failed/interrupted updates retain private data and
+must give a concrete recovery path. Moving npm/Node installations must not leave
+systemd pointing silently to a missing or older executable.
+
+Distinguish program removal (stop/remove services, retain private data) from explicit
+confirmed deletion of local keys/history/configuration. Document recovery if npm is
+uninstalled first. Do not rely on npm lifecycle hooks for sensitive cleanup.
+
+## Closed loops and acceptance
+
+1. Commit the verified Protocol npm migration for User and Wallet as a baseline.
+2. Prepare Wallet public package entry points and compiled artifact. Inventory User
+   consumers; test installed tarball CLI and real IPC/key lifecycle independently.
+   No npm upload or User package migration in this loop.
+3. Integrate User with the Wallet package; remove sibling source/build assumptions;
+   expose `agentpay`, align service paths, installer, repair and uninstall.
+4. Verify version/interface and running-process compatibility, update interruption,
+   data preservation and bounded mismatch handling. Keep exact pins until ranges
+   and their negative tests are explicitly designed.
+5. Configure independent OIDC release workflows. Publish Wallet first, then User;
+   verify public registry installs. Update Market and human guides to tested commands.
+6. Accept fresh install, restart/unlock, upgrade, uninstall and the official paid
+   connectivity test through the same product path on Anvil. Multi-service behavior
+   uses maintained controlled fixtures. Real-network acceptance remains separate.
+
+Current scope update — 2026-11-07: owner authorized User package adoption and
+installer/service/repair/uninstall integration in sequence. Implemented and tested
+with public Wallet 0.3.0. User 0.3.0 remains private/unpublished pending review and
+participant acceptance. Exact installed versions are checked; running-daemon version
+negotiation is still a separate compatibility task. No participant services, keys,
+Policies or Orders were changed in this development loop.
+
+## Approved npm update — 2026-11-07
+
+`agentpay update` queries the configured npm registry for User, displays the exact
+release and pinned Wallet version, and asks before changing services. `-f` bypasses
+only that confirmation. Target installation is exact, engine-strict and skips
+lifecycle hooks; artifacts must already be runnable. Global npm installs are
+supported; source/npm-link checkouts use their own source updates and repair.
+
+The installer lock protects requirements/stop/package replacement. Release it before
+the new version's repair acquires it; contention refuses safely with a retry rather
+than bypassing the lock. Repair runs in a new process, so it uses the new official
+Skill digest and package interfaces. Other Skills and original test requests remain.
+No paid test, Policy renewal or key initialization is implicit in update. Failed
+installation/repair preserves private data and provides a repair/reinstall path.
+Unconfigured installs continue through explicit setup after software update.

package/doc/reference/harness-skill-runtime.md

@@ -0,0 +1,120 @@
+# Harness Skill and local payment integration
+
+Implemented design reference. Current release/participant gates are tracked in
+[TODO](../TODO.md); this document is not new deployment or payment authorization.
+
+## User journey and responsibilities
+
+1. Install/configure local AgentPay once. The human grants bounded Safe spending
+   permission; Wallet independently verifies and binds it. Owner signing on real
+   networks remains separate pending work.
+2. Install a Skill in the selected harness through its supported discovery path.
+   Package installation is distinct from Safe authorization and does not pay.
+3. The harness reads SKILL.md and executes the package's thin business wrapper.
+4. The wrapper uses a shared local AgentPay client to discover local connection
+   settings, authenticate to Runtime, submit input and resume the same invocation.
+5. Runtime orchestrates the purchase through Wallet's narrow APIs and Provider;
+   Wallet owns keys and independent checks. Results return to the harness.
+
+SKILL.md explains when to call, arguments, expected results and recovery actions.
+The wrapper handles business input/output. The shared client owns local discovery,
+transport/authentication and retry identity handling; it must not implement a
+second payment engine. Runtime retains durable Order/payment recovery. Payment
+admission and authoritative price/identity are checked by Settlement/Wallet, not
+accepted from untrusted package text.
+
+A new eligible service satisfying the existing dynamic Registry Policy needs no
+new owner signature. Several Skills using the same Policy share that Policy's
+budget; installing a Skill does not create an additional allowance. Harness tool
+execution permission is separate from spending authority. A local caller token
+allows requests within existing bounds; it is not a key or generic signer.
+
+## Current source and concrete gaps
+
+- The official reference package candidate 1.1.0 contains SKILL.md and a thin random.mjs
+  bootstrap. It loads the installed User client from private connection.json.
+  Setup publishes this connection; default/custom data directory discovery and
+  explicit URL/credential-file overrides are implemented. Release and actual
+  harness discovery remain pending.
+- Runtime routes per-call registered references through a common JSON transport.
+  It starts without a selected package. Business validation lives in the Skill and
+  Provider. active-skill.json is retained only for official test material; it is
+  not process-wide service configuration. Generic package saving and harness
+  discovery remain separate operations.
+- SKILL.md instructs resolving commands from the installed package. Actual
+  harness execution must
+  resolve the installed Skill's directory without assuming the current workspace.
+- Installer download transport requires HTTPS or loopback HTTP. A Market page on
+  public-IP HTTP cannot be used as an installer URL; do not weaken the
+  transport rule to make that command work. The Market Web source now omits this
+  rehearsal-only command from the public Skill guide (deployment pending).
+
+## First implementation loop
+
+The reusable local client and random wrapper now call the common Runtime
+endpoint. They resolve settings from the user's installed AgentPay state;
+keep credentials outside the Skill and read them only in the local process. Keep
+explicit configuration available for non-default directories. Do not load scripts
+or shell fragments from connection files or infer a different paid service.
+
+Expose a non-paying connection/identity check and invocation with structured
+results/errors. Distinguish connectivity, unlocked Wallet/Policy readiness and
+actual delivery; a successful /health read does not establish payment readiness.
+Document that prerequisite errors need human setup/unlock; the model must not be
+asked for passwords, private keys or owner signing secrets.
+
+The implemented interface is --invoke <min> <max> [--force]. Matching calls
+resume unfinished work or reuse verified output; only --force deliberately creates
+another request with the same input. The diagnostic --resume <request-id> remains
+for selecting a specific record when forced calls create ambiguity. New calls
+generate a UUID; checkpoints retain original input, service and Runtime URL before
+POST. Transport does not retry or create replacement purchases automatically.
+
+Generate a sufficiently long request identifier once per deliberate invocation
+and durably retain it before sending. Retry of an uncertain request keeps that
+identifier and identical input. The client must not invent a replacement purchase
+on timeout. Keep Runtime's existing conflict detection and recovery authoritative;
+default recovery and diagnostic selection are implemented.
+
+Acceptance: missing/wrong settings, unavailable Runtime, invalid credential,
+service mismatch and timeout-after-acceptance retain correct outcomes and request
+identity. No secret should enter model-visible output. Use focused local-process
+fixtures first; actual paid harness tests need a separately agreed payment scope.
+The selected distribution is a local module in the installed User repository,
+located through an owner-held connection file. No dependency download occurs
+at invocation. Candidate 1.1.0 needs the updated User installation. Existing
+published 1.0.1 bytes remain available but are not accepted as this new
+service-reference format; no compatibility translation or rewrite is provided.
+Release/deployment and actual harness execution remain unverified.
+
+## Following loops
+
+- Deploy the reviewed common Runtime contract and per-request state after checking
+  older pending requests, matching dependencies and the official package.
+  Preserve wire skillId meanings and private input/output boundaries. Supporting
+  many installed Skills must not require global active-Skill replacement per call.
+- Package the wrapper/client integration for both harnesses. Verify discovery,
+  script-path resolution, local configuration access and tool permissions in each.
+  Shared file conventions do not prove identical permission or sandbox behavior.
+- Update Market installation copy and repository guides to show harness installation
+  and the one-time Wallet prerequisite. Keep the specialized rehearsal installer in
+  developer instructions. Do not advertise generic execution before it works.
+- Run actual first-use and resume scenarios in both harnesses; retain exact private
+  payment/reconciliation evidence separately from source/HTTP tests.
+
+## Security and ownership
+
+Session Keys, owner keys, unlock secrets and caller tokens never enter published
+packages or model prompts. Local credential access is not OS isolation: a harness
+with the user's filesystem permissions may read files that account can read.
+Use narrow execution permissions where available; do not claim SKILL.md itself
+is a security boundary. Private results stay on the local client/Runtime/Provider
+path. Installation never expands Policy limits or grants arbitrary signing.
+
+## Official reference surfaces
+
+- [Claude Code Skills](https://code.claude.com/docs/en/skills)
+- [DeepSeek Harness Skills](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/skills.md)
+
+These establish discovery/instruction mechanisms; they are not AgentPay compatibility
+results. Verify exact supported versions and directories during implementation.