@finchtech/cli 0.4.1 → 0.5.1

package/README.md

@@ -2,11 +2,11 @@
 
 Install the public npm package with `npm install -g @finchtech/cli`, then run `finch --help`. The primary executable is `finch`; `finchtech` is an equivalent fallback for machines where another application already owns the `finch` command.
 
-The Finch Agent CLI stores wallet keys, AgentCLI Session bearers, and MCP grant bearers only in an owner-only `FINCHTECH_HOME`, which defaults to `~/.finchtech`; secrets are never accepted as command arguments or emitted to stdout.
+The Finch Agent CLI stores wallet keys and AgentCLI Session bearers only in an owner-only `FINCHTECH_HOME`, which defaults to `~/.finchtech`; secrets are never accepted as command arguments or emitted to stdout.
 
-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 0x-prefixed 32-byte hex private key 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 requires login and remote revocation before changing the current wallet. Incomplete wallet files require recovery from backup; residual local authorization requires restoring the original wallet or explicitly clearing local authorization with `finch logout --local`.
+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.
 
@@ -16,11 +16,11 @@ Skill upload failures also retain the final `uploadBytes`, `uploadObjectKind`, H
 
 ZIP import failures return `AGENT_MARKET_REQUEST_INVALID`, exit code `2`, and `fix_request` before upload. The JSON-encoded `state` identifies `SKILL_SOURCE_ZIP_INVALID` and a `zipReason`: `archive_too_large`, `expanded_content_too_large`, `utf8_flag_missing`, `filename_encoding_invalid`, or `invalid_archive`. Size failures include `actualBytes`, `maxBytes` (10,485,760), and `sizeBasis`: `archive` measures the compressed input; `declared_expanded` is the cumulative uncompressed size declared by entries at the first limit violation, before decompression. A safely decoded root-relative entry `path` is included when available. Non-ASCII filenames require valid UTF-8 bytes and bit 11 in the ZIP headers; rebuilding with those flags preserves file contents. These import limits are independent of final upload admission.
 
-Intent HTTP failures include `remotePath: "/api/skills/intents"`, `remoteStatus`, and available safe correlation IDs. `responseIssue` distinguishes `transport_failed`, `body_read_failed`, `empty_body`, `invalid_content_length`, `response_too_large`, `invalid_json`, and `schema_mismatch`. Schema failures include at most eight `schemaIssues` with known field paths and validation keywords; an empty path means the response root or an unrecognized field, whose name is withheld. No response values, arbitrary property names, URLs, or raw causes are printed. Malformed success responses are rejected during `intent`, before signing or writing a pending-send marker. Use the returned recovery command for the same publication; the CLI never automatically retries intent requests or resubmits transactions. The fingerprint identifies the local recovery journal, not a server trace; use returned remote IDs to correlate server logs.
+Publication intent HTTP failures identify the Session-owned `/api/v1/agent-cli/signing-intents/skills/<intentId>/prepare` resource in `remotePath`. Failures include `remoteStatus` and available safe correlation IDs. `responseIssue` distinguishes `transport_failed`, `body_read_failed`, `empty_body`, `invalid_content_length`, `response_too_large`, `invalid_json`, and `schema_mismatch`. Schema failures include at most eight `schemaIssues` with known field paths and validation keywords; an empty path means the response root or an unrecognized field, whose name is withheld. No response values, arbitrary property names, URLs, or raw causes are printed. Malformed success responses are rejected during `intent`, before signing or writing a pending-send marker. Use the returned recovery command for the same publication; the CLI never automatically retries intent requests or resubmits transactions. The fingerprint identifies the local recovery journal, not a server trace; use returned remote IDs to correlate server logs.
 
 The CLI measures the exact final multipart request, including metadata and framing. At or below 4,000,000 bytes it posts that request to the inline upload route. Above it the object goes through the staged transport instead: the CLI asks for a signed URL, writes the bytes straight to storage, and has the server read them back, verify them and pin them, so the platform's 4,500,000-byte request-body limit does not apply. These MB thresholds are decimal. The per-object ceilings are enforced against the final object either way: 30 MiB (31,457,280 bytes) for a package, 5 MiB for a cover, and 3 MiB (3,145,728 bytes) for a manifest. The package ceiling is one shared constant, applied by upload admission, by the retrieval route, by this client before it uploads, and by this client when it downloads, so a package that publishes is a package that reads back. Repacking a compressed source ZIP may increase its size. Passing admission does not certify production upload success or authorize replaying a previously failed publication.
 
-The command groups are `wallet`, `login/status/logout`, `site`, `mcp doctor`, `mcp connect`, `mcp authorize`, `mcp grant`, `creator`, `credentials`, `intent`, `operation show`, `purchase`, `task`, and `skill`. Run `finch --help` for the exact command list as one JSON value.
+The command groups are `wallet`, `login/status/logout`, `site`, `mcp doctor`, `mcp connect`, `mcp authorize`, `credentials`, `intent`, `purchase`, `task`, and `skill`. Run `finch --help` for the exact command list as one JSON value.
 
 `finch site open` creates a sixty-second one-use handoff from the active AgentCLI Session and opens the exact configured Finch origin in the local default Browser. `finch site login <REQUEST_URL>` binds a website-created five-minute request once, then opens the same confirmation page. Both commands require the wallet, CLI, and graphical Browser on the user's machine. A launch failure returns `BROWSER_OPEN_FAILED` without printing the secret completion URL. The Browser receives only a normal seven-day Finch Web Session; wallet signing, broadcast, and market confirmation remain local CLI actions.
 
@@ -36,25 +36,45 @@ 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.
 
-`operation show` and signing-decision recovery require an active, unexpired MCP grant for the current account and endpoint with `agent_market:operations:read`. The CLI selects that grant from protected local state and never substitutes the AgentCLI Session bearer.
+Signing-decision recovery queries only the owned signing intent through the AgentCLI Session and never reads an MCP grant.
+
+Business discovery, Creator configuration, preparation and operation queries belong to the Harness's Remote MCP connection. CLI 0.5.0 removes `creator …`, `operation show`, `skill search`, and all `mcp grant …` commands. Use their market-specific MCP tools and execute only the returned local wallet/credential actions.
+
+On the first stateful command after upgrading, the CLI removes obsolete `grants/` files and manual-grant idempotency keys without reading their bearers. Profiles, wallet keys, the current Session and all signing/transaction recovery journals remain intact. Help/version remain state-free. This local purge does not revoke remote grants or Harness OAuth credentials; ordinary `finch logout` revokes Account-bound authority when that is intended. Updating Finch CLI never reads or deletes the Harness's OAuth store.
+
+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.
+
 
-Creator commands are thin projections of the shared Agent Market merchant operations. Reads require `agent_market:merchant:read`; mutations require `agent_market:merchant:write`, a stable caller-chosen `--request-id` UUID for local idempotency recovery, and `--expected-revision` wherever the shared operation requires If-Match. Structured request bodies come from bounded JSON `--from-file` documents and are validated against the same shared schemas before HTTP.
 
 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.
 
-`purchase transaction <operationId>` is read-only. It requires an active `agent_market:buyer:purchase` MCP grant and returns the two server-composed transaction requests plus their chain authority; it does not sign or broadcast arbitrary calldata.
+`purchase transaction <operationId>` is read-only. It uses the active AgentCLI Session and returns the two server-composed transaction requests plus their chain authority; it does not sign or broadcast arbitrary calldata.
 
-`purchase submit <operationId>` requires the same grant and uses only the source-controlled public RPCs for the plan's chain. It uses the protected wallet to re-encode and submit the exact server-composed USDC approval and AgentService Vault purchase. Before signing it verifies `eth_chainId`, the reviewed chain contract authority, every transaction field, and a successful `eth_call` simulation. Every returned broadcast hash is atomically checkpointed before receipt waiting; a restart re-verifies the exact wallet, call, receipt, block, and current server authority and never re-broadcasts a known phase. Finch then verifies the canonical confirmation event and creates Call Rights. If the purchase receipt conclusively reverts, the paired zero-allowance cleanup follows the same checkpoint discipline; unknown receipts are never guessed. The RPC owns nonce selection. User RPC and environment variables are ignored, and neither RPC URLs nor wallet keys are emitted.
+`purchase submit <operationId>` uses the same AgentCLI Session and uses only the source-controlled public RPCs for the plan's chain. It uses the protected wallet to re-encode and submit the exact server-composed USDC approval and AgentService Vault purchase. Before signing it verifies `eth_chainId`, the reviewed chain contract authority, every transaction field, and a successful `eth_call` simulation. Every returned broadcast hash is atomically checkpointed before receipt waiting; a restart re-verifies the exact wallet, call, receipt, block, and current server authority and never re-broadcasts a known phase. Finch then verifies the canonical confirmation event and creates Call Rights. After a successful chain receipt, a durable confirmation-only checkpoint lets the same command recover a lost confirmation response without retrieving a fresh transaction plan or broadcasting again. If the purchase receipt conclusively reverts, the paired zero-allowance cleanup follows the same checkpoint discipline; unknown receipts are never guessed. The RPC owns nonce selection. User RPC and environment variables are ignored, and neither RPC URLs nor wallet keys are emitted.
 
 `purchase recover-approval <operationId> --transaction-hash <hash>` is the narrow adoption path for an approval broadcast before its durable checkpoint was written. It re-fetches the current server authority and active wallet, then verifies the exact successful approval transaction and sufficient live token allowance on the plan chain before writing one owner-only recovery journal. It never broadcasts, confirms, scans chain history, or accepts a nonce. A subsequent `purchase submit` continues with the purchase phase without approving again.
 
 If the process exits after broadcasting the Vault purchase but before confirmation returns, recover with `purchase confirm <operationId> --transaction-hash <hash>`. This command never trusts the supplied hash: Finch fetches and decodes the canonical chain receipt before any Call Rights mutation.
 
-Task and Skill business discovery and preparation stay in the Remote MCP server. The `task` commands only fund an exact prepared Task pool, sign exact prepared awards, or submit an exact prepared reclaim. Skill purchase, conversion, price, and supply commands submit strict MCP preparations. `skill publish-submit --path <file-or-directory> --from-file <plan>` and `skill version-submit` accept either one file or one directory, then apply the plan's independent `plaintext`, `finchip_v2`, or `lit` content mode; filtering, deterministic ZIP construction, encryption, upload, and key custody remain local. `skill asset-upload --path <cover> --from-file <plan>` uploads a separately prepared public cover, and `skill presentation-submit --from-file <plan>` publishes bounded public presentation metadata without changing protected package bytes. `skill download --from-file <delivery> --out-file <new-file>` requires an active AgentCLI Session for both plaintext and protected content. It retrieves packages through the authenticated delivery gateway, signs with the entitled local wallet for protected content, verifies the SkillRoot and every file (or the plaintext ZIP hash for historical Skills), acknowledges the verified download, and then creates an owner-only file. CLI 0.3.8 or newer is required; an acknowledgement failure aborts before output-file creation. Every transaction action uses its plan's chain, source-controlled public RPCs, and reviewed chain-level contract authority. The CLI recomputes transaction bytes locally and rejects mismatched chains, destinations, calldata, values, source commits, or envelope tags.
+Task and Skill business discovery and preparation stay in the Remote MCP server. Task preparation responses include `walletIntent` and a structured `localAction`. With a CLI build that supports `--intent`, run `finch task publish-submit <taskId> --intent <intentId>`, `finch task award-sign <taskId> --intent <intentId>`, or `finch task reclaim-submit <taskId> --intent <intentId>`. These commands read the immutable owned preparation and confirm its wallet result using only the active CLI Session. They neither read nor create an MCP business grant. `--from-file` accepts a response containing the same intent reference; transaction bytes always come from the authenticated server. Successful output is a wallet receipt; query business state through MCP.
+
+Recover an interrupted action with `finch task recover <taskId> <publish|award|reclaim>`. Recovery reuses the saved transaction hash or signature batch. Existing v2 journals without an intent ID are adopted using their original server preparation audit receipt and confirmation idempotency key, then compared with the server plan before recovery. Keep journals intact; missing source receipts or changed plans require reconciliation. Deploy the Task intent migration and routes before distributing this CLI change. CLI 0.5.0 introduces the Session-only handoff; check installed command help before using returned actions.
+
+Skill preparations return `walletIntent.intentId`. With the updated CLI, run `skill purchase-submit`, `convert-submit`, `price-submit`, or `supply-submit` with `--intent <intentId>`. The commands fetch server-bound transaction bytes and use only the CLI Session for execution and confirmation. `--from-file` reads only the handoff reference; changing price, chain or calldata in the file cannot change the signed call. Prepare unexecuted old plan files again through MCP. CLI 0.5.0 supports this handoff; npm publication is a separate release step.
+
+`skill publish-submit --path <file-or-directory> --intent <intentId>` and `skill version-submit` retain local filtering, ZIP construction, packaging, encryption, upload and key custody. The server fixes the prepared business metadata and records each transaction stage once. `skill asset-upload --path <cover> --intent <intentId>` uploads a prepared public cover. `skill presentation-submit --intent <intentId>` publishes only the prepared public presentation and checkpoints its wallet result. Repeating an intent with a recorded transaction resumes confirmation. An unfinished publication requires its original protected material journal; restoring it preserves uploaded bytes and keys.
+
+Recover wallet results with `skill recover intent <fingerprint>` and publication material with `skill recover publication <fingerprint>`. Recovery preserves broadcast hashes and the publication pending-send protections. Old buyer journals are admitted only as receipt-only recovery after the server reconstructs and verifies their confirmed canonical transaction. Existing publication journals retain their conservative typed recovery path. A confirmed receipt or projected stage can replay without another signature/broadcast; preserve journals during projection lag.
+
+`skill download --intent <intentId> --out-file <new-file>` requires an active CLI Session for plaintext and protected content. It fetches the owned MCP delivery preparation, retrieves through the authenticated gateway, signs locally for protected keys, verifies the SkillRoot/files or historical ZIP hash, acknowledges delivery, and then creates an exclusive owner-only output file. Upload size/type admission, staged tickets, Oracle V2, Lit sealing and raw key locality remain unchanged. Each transaction is reconstructed from its explicit reviewed chain deployment and rejects different destinations, calldata, values, source commits or envelope tags.
 
 ## ZIP import and SkillRoot publication
 
@@ -63,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
-`pnpm add -g @finchtech/cli@0.4.1` 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.
 
@@ -121,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+)
 
@@ -149,4 +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.