@finchtech/cli 0.5.0 → 0.5.1

package/README.md

@@ -6,7 +6,7 @@ The Finch Agent CLI stores wallet keys and AgentCLI Session bearers only in an o
 
 For an existing private key, run `finch wallet use --file <PATH>` on a fresh installation, then `finch login --help` to choose an authentication chain. The file must contain a single 32-byte hex private key (64 hexadecimal digits, optionally prefixed with `0x`) and have owner-only permissions. First import is offline and makes that wallet current. `finch wallet create` generates a new identity instead. An existing Account switch with a stored Session revokes that Account before changing the current wallet. With no stored Session, switching is offline and does not claim remote revocation. A pending login must be recovered before switching; other partial or corrupt Session state requires explicit repair. Incomplete wallet files require recovery from backup; residual local authorization requires restoring the original wallet or explicitly clearing local authorization with `finch logout --local`.
 
-`finch logout` revokes Account-bound remote authority before removing local Session and grant state. If invalid, corrupt, or legacy Session metadata prevents that flow, `finch logout --local` performs an explicit offline reset of only `session/` and `grants/`. It makes no network request and reports `remoteRevoked: false`; it remains available while an irreversible recovery is pending and preserves profiles, registered wallets, transaction journals, and recovery records so the user can log in again and run the recorded recovery command. Ordinary logout and wallet switching remain blocked until that recovery completes.
+`finch logout` revokes Account-bound CLI/MCP remote authority before removing local Session and grant state. `finch logout --local` clears only local `session/` and `grants/`, makes no network request and reports `remoteRevoked: false`. Both preserve profiles, registered wallets and transaction/publication journals. Ordinary logout and wallet switching proceed independently of unfinished journals; resume a journal later with its original wallet and matching Account/environment.
 
 CLI-authored EVM addresses accept canonical lowercase or valid EIP-55 input and are normalized to lowercase before request validation and transport. Invalid mixed-case and uppercase forms are rejected. Remote responses and Remote MCP plans remain strictly lowercase so normalization cannot change signed or hashed plan bytes.
 
@@ -36,7 +36,7 @@ Each entry point applies the same origin, redirect, state, scope, and RFC 9207 i
 
 Doctor's `ready: true` is scoped by `readinessScope: "cli_session_and_mcp_discovery"`. Its `harnessOAuth.status` is always `not_checked`: CLI login and valid discovery metadata do not establish that the connected Harness has usable OAuth credentials, a saved issuer, or working refresh. The result includes identity-verification and native reauthorization guidance. If the Harness reports an OAuth failure, start its native MCP authorization flow again, approve the fresh request through the entry points above, then verify MCP identity again.
 
-Run `finch login --help` to list supported production authentication chain IDs (1, 10, 56, 8453, 42161). For example, `finch login --chain-id 56` selects BNB Smart Chain for authentication only.
+Run `finch login --help` to list supported production authentication chain IDs (1, 10, 56, 8453, 42161, 43114). For example, `finch login --chain-id 56` selects BNB Smart Chain for authentication only.
 
 Ordinary installs require no profile file or environment selection. Network commands default to the PROD endpoint at `https://www.finchtech.ai`. `finch login --chain-id <CHAIN_ID>` explicitly selects only the authentication chain, which the selected server must support. Market transaction chains come from Remote MCP/API plans and are independent of the login chain. `intent approve` signs only the shared publication-v2 or Local-purchase-v1 EIP-712 authorization; it cannot sign arbitrary transaction calldata.
 
@@ -48,6 +48,11 @@ On the first stateful command after upgrading, the CLI removes obsolete `grants/
 
 Repeated `finch login --chain-id <CHAIN_ID>` first recovers a pending login, then verifies and returns an existing Session on that same authentication chain. A confirmed 401 starts a fresh login; a network failure or mismatched identity preserves local authority and reports the failure. Use `finch logout` before changing authentication authority. On Unix, the default state directory requires `chmod 700 ~/.finchtech`, and a private-key input file requires `chmod 600 <KEY_FILE>`; apply the same modes to a custom state home. The CLI creates and protects a missing home itself.
 
+If the server returns `AGENT_SESSION_INVALID`, run `finch login --chain-id <CHAIN_ID>` with the same wallet, endpoint and authentication chain. The CLI preserves the remote error JSON and prints renewal guidance on stderr. Use `finch mcp doctor` to read the stored login chain when needed. After login, verify CLI/MCP identity and resume the original recovery command.
+
+`finch logout --local` clears local Session and legacy grant files while preserving wallets and recovery journals; it leaves server authorization unchanged. Ordinary logout and wallet switching retain Account-wide CLI/MCP revocation. CLI 0.5.1 allows these transitions independently of unfinished journals. Resume each journal under its original wallet and matching Account/environment. The obsolete `mutations/recovery-index.json` is retained during upgrade but is no longer read or written; the protected journal is the sole local progress record. Upgrade to CLI 0.5.1 to receive this fix; changing the Skill alone does not update an installed CLI.
+
+
 
 Local AgentOn HMAC generation is not a product command. `credentials material-download <setupId> --out-file <absolute-path>` claims the AgentOn setup, downloads only its exact live lease as raw FCR1, and creates a new owner-only file; stdout contains only `keyId` and `path`. `credentials fulfill` accepts only Direct credential uploads. It accepts either an existing protected FCR1 with `--from-file <path>`, or a protected raw Bearer token with `--bearer-token-file <path> --key-id <keyId>`; the latter validates one whitespace-free token and adds the `Bearer ` prefix only in CLI memory. Secret bytes never enter argv or stdout.
 
@@ -78,7 +83,7 @@ Version 0.3.1 fixes Skill search continuation: pass the returned `nextCursor` un
 Older clients receive an upgrade message from the Skill search API.
 
 Version 0.3.0 upgrades Skill publication and encrypted delivery together. Upgrade with
-`npm install -g @finchtech/cli@0.5.0` and verify `finch --version` before publishing new Skills
+`npm install -g @finchtech/cli@0.5.1` and verify `finch --version` before publishing new Skills
 or downloading encrypted Skills from the upgraded gateway. Older CLI versions cannot use
 the new encrypted delivery, including for historical Skills; 0.3.0 retains historical package support.
 
@@ -136,7 +141,7 @@ and use that command rather than repeating publish-submit. Cleanup failures do n
 still exists. If source is unavailable or its excluded-path inventory changed across CLI versions,
 the fingerprint-only recovery command can use the already stored publication bytes.
 
-These fixes require CLI 0.3.3 or newer; npm 0.3.2 does not include them. Updating a Skill does not upgrade the installed CLI. Journal v6 saves a pending stage before signing/submitting. Missing hashes in creating stages of a pending or legacy v4/v5 journal block automatic resubmission; follow the reported chain-state checks and contact support. CLI 0.3.7 permits the URI assignment stage to converge through its typed recovery path. Known hashes are verified without rebroadcast. The pending marker also blocks destructive local authorization/wallet cleanup through the recovery inventory.
+These fixes require CLI 0.3.3 or newer; npm 0.3.2 does not include them. Updating a Skill does not upgrade the installed CLI. Journal v6 saves a pending stage before signing/submitting. Missing hashes in creating stages of a pending or legacy v4/v5 journal block automatic resubmission; follow the reported chain-state checks and contact support. CLI 0.3.7 permits the URI assignment stage to converge through its typed recovery path. Known hashes are verified without rebroadcast. The pending marker protects transaction resubmission while authorization cleanup and wallet switching preserve the journal.
 
 ## Bootstrap and health reports (CLI 0.3.4+)
 
@@ -164,10 +169,14 @@ CLI 0.4.0 adds `finch mcp connect` and `finch mcp authorize --stdin`, delivers l
 
 ## Avalanche Skill transactions (CLI 0.4.1+)
 
-CLI 0.4.1 supports Skill publication, acquisition, management, and delivery on Avalanche C-Chain (`43114`), alongside Ethereum, Optimism, BNB Smart Chain, Base, and Arbitrum. Preserve the Remote MCP plan's exact chain for every custody action; Avalanche transactions use AVAX for prices and gas. An Avalanche-connected Browser authenticates on Base before returning to the Skill's transaction chain. CLI login authentication chains remain unchanged; do not use `finch login --chain-id 43114`. Updating the website or the Finch Market Skill does not upgrade an installed CLI.
+CLI 0.4.1 supports Skill publication, acquisition, management, and delivery on Avalanche C-Chain (`43114`), alongside Ethereum, Optimism, BNB Smart Chain, Base, and Arbitrum. Preserve the Remote MCP plan's exact chain for every custody action; Avalanche transactions use AVAX for prices and gas. The current PROD server supports Avalanche wallet authentication directly on Avalanche. CLI 0.5.1 also includes Avalanche in the PROD authentication-chain help; use `finch login --help` for the supported list. Updating the website or the Finch Market Skill does not upgrade an installed CLI.
 
 ## Session-only release order (CLI 0.5.0)
 
 CLI 0.5.0 depends on the Agent, Task and Skill intent migrations/routes from Issue #1144 parts 1–3. Apply the ordered migrations through the separately authorized workflow and deploy the corresponding Session endpoints before distributing this package. Validate CLI custody/recovery against the intended environment, publish the reviewed package, then release the matching Finch Market Skill instructions. A repository version bump or website deployment is not npm publication; before that release, public npm 0.4.1 retains its older command and preparation-file workflow.
 
 Keep existing journals when upgrading. Agent recovery uses the owned operation/intent endpoints; old Task v2 journals adopt their original preparation audit receipt; old Skill purchase/convert checkpoints adopt only an already verified receipt. Unexecuted old plan files must be prepared again through MCP. Historical Skill publication journals without an intent ID cannot safely manufacture one or fall back to business authority: preserve the journal and reconcile any broadcast stages before continuing. Old clients' server interfaces remain available during rollout; their eventual retirement is separate work.
+
+## Recovery-preserving Account transitions (CLI 0.5.1)
+
+CLI 0.5.1 allows ordinary logout and wallet switching with unfinished transaction/publication journals, preserving Account-wide CLI/MCP revocation and the original recovery evidence. It removes the redundant local recovery index. Invalid or expired Sessions receive direct same-authority login guidance. The bundle also includes the shared Avalanche PROD authentication allowlist already deployed on Finch.