@finchtech/cli 0.3.8 → 0.3.9

package/README.md

@@ -1,132 +1,136 @@
-# Finch Agent CLI
-
-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.
-
-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`.
-
-`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.
-
-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.
-
-Valid remote Identity, Agent, Task, Skill, and OAuth errors are emitted in their original domain envelope with the remote trace ID. Local transport failures use `CLI_REMOTE_UNAVAILABLE`; malformed or contract-invalid responses use `CLI_RESPONSE_INVALID`. Locally synthesized failures use a null trace ID rather than impersonating a server trace.
-
-Skill upload failures also retain the final `uploadBytes`, `uploadObjectKind`, HTTP `remoteStatus` (null when no response was obtained), and available allowlisted `remoteCode`, `remoteRequestId`, and `remoteTraceId` in the JSON-encoded `state`. Locally synthesized errors retain the existing null `reasonCode` and `traceId` contract; downstream evidence is labelled explicitly in `state`. These fields never include raw response text, upload filenames, credentials, or transport causes. `not_attempted` refers only to chain submission: storage may have accepted an object before a response was lost. Follow `contact_support` until the individual attempt is reconciled; another publication's status is not evidence about this attempt.
-
-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.
-
-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 authorize`, `mcp grant`, `creator`, `credentials`, `intent`, `operation show`, `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.
-
-`finch mcp doctor` is read-only. It returns a `checks` object for endpoint, wallet, local Session, remote Session authority, and MCP discovery. Each check reports `ok`, `missing`, `invalid`, `unavailable`, or `skipped`, with guidance for unhealthy checks. Missing login or wallet state does not prevent independent discovery checks; an invalid endpoint prevents network checks. The command emits one JSON report with exit code 0 when ready, or 2 when any required check is unhealthy. It verifies that the active CLI authority, AgentCLI Session, local wallet, MCP challenge, OAuth metadata, and source-controlled persistent-Harness manifest agree. The Agent Harness owns Remote MCP configuration, OAuth credentials, and refresh; the CLI does not configure or launch Codex and never reads Harness OAuth material. During the Harness's native OAuth flow, the authorization page supplies an exact `finch mcp authorize <REQUEST_TOKEN>` command. The versioned base64url token carries the original OAuth request without shell metacharacters so Windows package-manager and Volta launchers cannot split it; the CLI decodes it before applying the existing origin, callback, state, and scope checks. That command uses only the active local AgentCLI Session and opens the verified callback without returning its one-use code. It never uses a Browser Session, Social account, or extension wallet as Agent authority. Configure `https://www.finchtech.ai/mcp` once through the Harness, then use MCP `identity_actor_get` together with `finch status` to verify exact Account and wallet alignment before custody. The server-reported environment is diagnostic and never selects the CLI endpoint or a transaction chain.
-
-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, complete its native MCP authorization flow and the authorization page's fresh `finch mcp authorize` command, 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.
-
-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.
-
-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 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 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.
-
-## ZIP import and SkillRoot publication
-
-Version 0.3.1 fixes Skill search continuation: pass the returned `nextCursor` unchanged as
-`--cursor`. Search uses the server rules; the CLI does not implement a matching algorithm.
-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.3.8` 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.
-
-A single `.zip` passed to `skill publish-submit --path` or `skill version-submit --path` is expanded locally before filtering and primary-document hashing; request a `file` source plan for this input. Directory inputs keep ZIP assets as ordinary files. Imports support stored/DEFLATE ZIPs up to the package ceiling compressed and expanded, with at most 1024 entries. Unsafe paths, symbolic links, encrypted ZIPs, ZIP64, conflicting entries, and corrupt content are refused. Include `SKILL.md`, `README.md`, or one unambiguous root Markdown document.
-
-New Skills publish a DAG-CBOR SkillRoot hash in one graph bundle. Existing Skill identities keep ZIP-hash updates. New Skills require this updated CLI; it verifies every object and decrypts protected files locally into an ordinary ZIP. Historical ZIP downloads and whole-package decryption remain supported. A pending publication reuses its uploaded bytes and saved root commitment on resume.
-
-The [publication ADR](../../docs/adr/ADR-0064-20260908-skillroot-publication.md) specifies the pinned draft, bundle/profile format, compatibility trust boundary, and rollout order.
-
-Finch-managed and Lit downloads use Oracle V2 device-sealed grants and a non-extractable local CryptoKey.
-The updated gateway also supports historical Finch-managed and Lit ZIPs through this delivery. It refuses
-old bare-key buyer requests; use the updated CLI. Both providers use the same sealed delivery. See
-[ADR-0065](../../docs/adr/ADR-0065-20260908-skill-oracle-v2-delivery.md) for deployment requirements.
-
-Publication preparation accepts an optional `summary` (up to 500 characters). It is committed in
-SkillRoot exactly as supplied, matching Browser publication metadata; omission means an empty summary.
-Equal public file bytes, paths, name, summary, version and history produce equal roots. Encrypted
-publications use random keys/IVs and need not produce the same root. Updates send the proposed
-manifest for server validation; URI intents are prepared after the new chain binding is confirmed.
-
-Finch-managed publication key requests use a signed timestamp and a one-time nonce. Each request is
-valid for five minutes; retrying after expiry or a lost response requires a fresh signature. The
-gateway rejects older CLI publication requests without timestamps. Historical downloads are unchanged.
-
-### Local publication failures
-
-Directory publication rejects symbolic links, including internal relative links and broken links.
-It skips excluded paths (for example `.git`, `node_modules`, `.aws`, and credential files) before reading
-or descending into them. `excluded` lists a skipped directory once instead of enumerating its children.
-Keep required resource paths functional when preparing a link-free source; deleting required links is
-not a valid repair. ZIP imports also reject symbolic links.
-
-Source errors keep exit code 2 and `AGENT_MARKET_REQUEST_INVALID`. Parse the JSON string in `error.state`
-for `diagnosticCode`: `SKILL_SOURCE_SYMLINK_UNSUPPORTED`, `SKILL_SOURCE_UNREADABLE`, or
-`SKILL_UPLOAD_SIZE_INVALID`, `SKILL_SOURCE_ZIP_INVALID`, `SKILL_SOURCE_PRIMARY_DOCUMENT_INVALID`, or `SKILL_MANIFEST_SIZE_INVALID`. Source diagnostics include a root-relative `path` (`.` for the selected
-root); size diagnostics include `actualBytes` and `maxBytes`. The internal packaging bound is the package ceiling and applies to the final
-upload object, including SkillRoot metadata and encryption overhead. STORE ZIP construction does not
-compress files. A size rejection occurs before that upload and before transaction submission.
-
-Publish, version, and publication-recovery failures also include `phase`, `fingerprint`,
-`transactionHashes` (keyed by `primary`, `uri`, or `lit`), `submissionStatus`, and `recoveryCommand` in
-`error.state`. `packaging` includes local hashing/encryption; `transaction` covers signing, broadcast,
-and receipt handling. A validated remote error keeps its code, message, trace and HTTP status
-(`remoteStatus`), with its original state retained as `remoteState`; publication retry guidance takes
-precedence over a remote service's generic retry flag. Private causes, RPC URLs, credentials and
-journal contents are never printed.
-
-Publication failures report `retryable` and `nextAction` according to the failure. A projection failure after confirmed transactions can be retryable; inspect `unconfirmedActions` before claiming the complete publication succeeded. This is not permission to replay a paid operation.
-`not_attempted` means no send was attempted in this invocation and no hashes were found in the
-validated journal; it is not proof about other invocations. `hash_known` includes known transaction
-hashes. `uncertain` means sending or durable checkpointing failed. For creation/version/key stages, contact support before retrying or
-recovering, even when a hash is shown. A non-null `recoveryCommand` is provided only after a journal
-is validated or saved and no submission/checkpoint uncertainty was observed. Recheck CLI/MCP identity
-and use that command rather than repeating publish-submit. Cleanup failures do not claim a journal
-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.
-
-## Bootstrap and health reports (CLI 0.3.4+)
-
-First-wallet offline import, installed Account-switch revocation, partial doctor checks and exit code 2, contextual wallet recovery guidance, login authentication-chain help, and strict OAuth UUID response validation require CLI 0.3.4 or newer. Updating the website or Skill does not upgrade an installed CLI.
-
-## WebP image detection (CLI 0.3.5+)
-
-CLI 0.3.5 fixes valid WebP covers and packaged detail images being rejected when binary file-size bytes were decoded as UTF-8. Upgrade the installed CLI to receive the local detection fix; website or Skill updates alone do not update the executable. Image types, size limits, and publication recovery rules are unchanged.
-
-## Market category compatibility (CLI 0.3.6+)
-
-Use CLI 0.3.6 or newer for the expanded market categories. Skill response display categories now accept bounded text, so future taxonomy additions do not require another CLI upgrade. Updating the website or this Skill does not upgrade an installed CLI.
-
-## Staged uploads and external media (CLI 0.3.7+)
-
-CLI 0.3.7 supports authorized external-media manifests and 30 MiB final packages on both upload and download. Browser publishing still uses multipart and refuses external media. Failed staged uploads attempt ticket release and report its result in the sanitized diagnostic. Presentation submission reports progress and whether setting the same URI can safely converge; a stale plan, authorization failure or invalid input still requires correction before retrying. Read the maintained Finch Market Skill for the complete external-host and recovery boundaries.
+# Finch Agent CLI
+
+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.
+
+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`.
+
+`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.
+
+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.
+
+Valid remote Identity, Agent, Task, Skill, and OAuth errors are emitted in their original domain envelope with the remote trace ID. Local transport failures use `CLI_REMOTE_UNAVAILABLE`; malformed or contract-invalid responses use `CLI_RESPONSE_INVALID`. Locally synthesized failures use a null trace ID rather than impersonating a server trace.
+
+Skill upload failures also retain the final `uploadBytes`, `uploadObjectKind`, HTTP `remoteStatus` (null when no response was obtained), and available allowlisted `remoteCode`, `remoteRequestId`, and `remoteTraceId` in the JSON-encoded `state`. Locally synthesized errors retain the existing null `reasonCode` and `traceId` contract; downstream evidence is labelled explicitly in `state`. These fields never include raw response text, upload filenames, credentials, or transport causes. `not_attempted` refers only to chain submission: storage may have accepted an object before a response was lost. Follow `contact_support` until the individual attempt is reconciled; another publication's status is not evidence about this attempt.
+
+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.
+
+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 authorize`, `mcp grant`, `creator`, `credentials`, `intent`, `operation show`, `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.
+
+`finch mcp doctor` is read-only. It returns a `checks` object for endpoint, wallet, local Session, remote Session authority, and MCP discovery. Each check reports `ok`, `missing`, `invalid`, `unavailable`, or `skipped`, with guidance for unhealthy checks. Missing login or wallet state does not prevent independent discovery checks; an invalid endpoint prevents network checks. The command emits one JSON report with exit code 0 when ready, or 2 when any required check is unhealthy. It verifies the endpoint, wallet/key binding, Account, Session identity, environment, audience and expiry, plus the MCP challenge and required OAuth capabilities. Each remote read has a 15-second timeout. Wallet inspection does not migrate legacy files. Client guide availability, client names, guide versions and repository paths do not affect readiness; `compatibilityManifestUrl` is only an informational link. The Agent Harness owns Remote MCP configuration, OAuth credentials, and refresh; the CLI does not configure or launch the Harness and never reads Harness OAuth material. During the Harness's native OAuth flow, the authorization page supplies an exact `finch mcp authorize <REQUEST_TOKEN>` command. The versioned base64url token carries the original OAuth request without shell metacharacters so Windows package-manager and Volta launchers cannot split it; the CLI decodes it before applying the existing origin, callback, state, and scope checks. That command uses only the active local AgentCLI Session and opens the verified callback without returning its one-use code. It never uses a Browser Session, Social account, or extension wallet as Agent authority. Configure `https://www.finchtech.ai/mcp` once through the Harness, then use MCP `identity_actor_get` together with `finch status` to verify exact Account and wallet alignment before custody. The server-reported environment is diagnostic and never selects the CLI endpoint or a transaction chain.
+
+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, complete its native MCP authorization flow and the authorization page's fresh `finch mcp authorize` command, 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.
+
+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.
+
+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 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 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.
+
+## ZIP import and SkillRoot publication
+
+Version 0.3.1 fixes Skill search continuation: pass the returned `nextCursor` unchanged as
+`--cursor`. Search uses the server rules; the CLI does not implement a matching algorithm.
+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.3.9` 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.
+
+A single `.zip` passed to `skill publish-submit --path` or `skill version-submit --path` is expanded locally before filtering and primary-document hashing; request a `file` source plan for this input. Directory inputs keep ZIP assets as ordinary files. Imports support stored/DEFLATE ZIPs up to the package ceiling compressed and expanded, with at most 1024 entries. Unsafe paths, symbolic links, encrypted ZIPs, ZIP64, conflicting entries, and corrupt content are refused. Include `SKILL.md`, `README.md`, or one unambiguous root Markdown document.
+
+New Skills publish a DAG-CBOR SkillRoot hash in one graph bundle. Existing Skill identities keep ZIP-hash updates. New Skills require this updated CLI; it verifies every object and decrypts protected files locally into an ordinary ZIP. Historical ZIP downloads and whole-package decryption remain supported. A pending publication reuses its uploaded bytes and saved root commitment on resume.
+
+The [publication ADR](../../docs/adr/ADR-0064-20260908-skillroot-publication.md) specifies the pinned draft, bundle/profile format, compatibility trust boundary, and rollout order.
+
+Finch-managed and Lit downloads use Oracle V2 device-sealed grants and a non-extractable local CryptoKey.
+The updated gateway also supports historical Finch-managed and Lit ZIPs through this delivery. It refuses
+old bare-key buyer requests; use the updated CLI. Both providers use the same sealed delivery. See
+[ADR-0065](../../docs/adr/ADR-0065-20260908-skill-oracle-v2-delivery.md) for deployment requirements.
+
+Publication preparation accepts an optional `summary` (up to 500 characters). It is committed in
+SkillRoot exactly as supplied, matching Browser publication metadata; omission means an empty summary.
+Equal public file bytes, paths, name, summary, version and history produce equal roots. Encrypted
+publications use random keys/IVs and need not produce the same root. Updates send the proposed
+manifest for server validation; URI intents are prepared after the new chain binding is confirmed.
+
+Finch-managed publication key requests use a signed timestamp and a one-time nonce. Each request is
+valid for five minutes; retrying after expiry or a lost response requires a fresh signature. The
+gateway rejects older CLI publication requests without timestamps. Historical downloads are unchanged.
+
+### Local publication failures
+
+Directory publication rejects symbolic links, including internal relative links and broken links.
+It skips excluded paths (for example `.git`, `node_modules`, `.aws`, and credential files) before reading
+or descending into them. `excluded` lists a skipped directory once instead of enumerating its children.
+Keep required resource paths functional when preparing a link-free source; deleting required links is
+not a valid repair. ZIP imports also reject symbolic links.
+
+Source errors keep exit code 2 and `AGENT_MARKET_REQUEST_INVALID`. Parse the JSON string in `error.state`
+for `diagnosticCode`: `SKILL_SOURCE_SYMLINK_UNSUPPORTED`, `SKILL_SOURCE_UNREADABLE`, or
+`SKILL_UPLOAD_SIZE_INVALID`, `SKILL_SOURCE_ZIP_INVALID`, `SKILL_SOURCE_PRIMARY_DOCUMENT_INVALID`, or `SKILL_MANIFEST_SIZE_INVALID`. Source diagnostics include a root-relative `path` (`.` for the selected
+root); size diagnostics include `actualBytes` and `maxBytes`. The internal packaging bound is the package ceiling and applies to the final
+upload object, including SkillRoot metadata and encryption overhead. STORE ZIP construction does not
+compress files. A size rejection occurs before that upload and before transaction submission.
+
+Publish, version, and publication-recovery failures also include `phase`, `fingerprint`,
+`transactionHashes` (keyed by `primary`, `uri`, or `lit`), `submissionStatus`, and `recoveryCommand` in
+`error.state`. `packaging` includes local hashing/encryption; `transaction` covers signing, broadcast,
+and receipt handling. A validated remote error keeps its code, message, trace and HTTP status
+(`remoteStatus`), with its original state retained as `remoteState`; publication retry guidance takes
+precedence over a remote service's generic retry flag. Private causes, RPC URLs, credentials and
+journal contents are never printed.
+
+Publication failures report `retryable` and `nextAction` according to the failure. A projection failure after confirmed transactions can be retryable; inspect `unconfirmedActions` before claiming the complete publication succeeded. This is not permission to replay a paid operation.
+`not_attempted` means no send was attempted in this invocation and no hashes were found in the
+validated journal; it is not proof about other invocations. `hash_known` includes known transaction
+hashes. `uncertain` means sending or durable checkpointing failed. For creation/version/key stages, contact support before retrying or
+recovering, even when a hash is shown. A non-null `recoveryCommand` is provided only after a journal
+is validated or saved and no submission/checkpoint uncertainty was observed. Recheck CLI/MCP identity
+and use that command rather than repeating publish-submit. Cleanup failures do not claim a journal
+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.
+
+## Bootstrap and health reports (CLI 0.3.4+)
+
+First-wallet offline import, installed Account-switch revocation, partial doctor checks and exit code 2, contextual wallet recovery guidance, login authentication-chain help, and strict OAuth UUID response validation require CLI 0.3.4 or newer. Updating the website or Skill does not upgrade an installed CLI.
+
+## WebP image detection (CLI 0.3.5+)
+
+CLI 0.3.5 fixes valid WebP covers and packaged detail images being rejected when binary file-size bytes were decoded as UTF-8. Upgrade the installed CLI to receive the local detection fix; website or Skill updates alone do not update the executable. Image types, size limits, and publication recovery rules are unchanged.
+
+## Market category compatibility (CLI 0.3.6+)
+
+Use CLI 0.3.6 or newer for the expanded market categories. Skill response display categories now accept bounded text, so future taxonomy additions do not require another CLI upgrade. Updating the website or this Skill does not upgrade an installed CLI.
+
+## Staged uploads and external media (CLI 0.3.7+)
+
+CLI 0.3.7 supports authorized external-media manifests and 30 MiB final packages on both upload and download. Browser publishing still uses multipart and refuses external media. Failed staged uploads attempt ticket release and report its result in the sanitized diagnostic. Presentation submission reports progress and whether setting the same URI can safely converge; a stale plan, authorization failure or invalid input still requires correction before retrying. Read the maintained Finch Market Skill for the complete external-host and recovery boundaries.
+
+## Diagnostic and interoperability fixes (CLI 0.3.9+)
+
+CLI 0.3.9 removes the `mcp.supportedClients` field from doctor. Its health checks do not fetch client guides or migrate legacy wallet files. Omitted or empty OAuth scope uses the server-resolved registered defaults; explicit requested scopes remain checked. Callback target, original query values and state remain verified, independently of query ordering or authorization-code length. Upgrade the installed CLI to receive these fixes; updating the Skill or website alone does not apply them.

package/dist/finch.js

@@ -17652,7 +17652,7 @@ var init_schemas = __esm({
       requiresHuman: { type: "boolean" },
       requiresTwitter: { type: "boolean" },
       autoSettle: { type: "boolean" },
-      settlementMode: { type: "string", enum: ["merchant_manual", "fcfs_realtime", "weighted_lottery", "delayed_auto_7d"] },
+      settlementMode: { type: "string", enum: ["merchant_manual", "fcfs_realtime", "weighted_lottery", "delayed_auto_7d", "merchant_review_7d"] },
       deadline: nullableString,
       startAt: nullableString,
       goals: { type: "array", maxItems: 5, items: openObjectSchema },
@@ -17665,7 +17665,7 @@ var init_schemas = __esm({
     }, ["content"]);
     taskReviewRequestSchema = strictObjectSchema2({
       submissionIds: { type: "array", minItems: 1, maxItems: 100, uniqueItems: true, items: canonicalUuidSchema2 },
-      action: { type: "string", enum: ["approve", "cancel_award", "reject", "spam", "favorite", "unfavorite"] },
+      action: { type: "string", enum: ["approve", "cancel_award", "reject", "review_later", "spam", "favorite", "unfavorite"] },
       spamReason: { type: "string", maxLength: 200 }
     }, ["submissionIds", "action"]);
     signedAwardSchema = strictObjectSchema2({
@@ -55201,6 +55201,18 @@ function jsonObject(value) {
   }
   return value;
 }
+function includesCapabilities(value, required4) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string" && item.length > 0) && required4.every((item) => value.includes(item));
+}
+function sameOriginEndpoint(value, origin2) {
+  if (typeof value !== "string") return false;
+  try {
+    const url2 = new URL(value);
+    return url2.origin === origin2 && url2.username === "" && url2.password === "" && url2.hash === "";
+  } catch {
+    return false;
+  }
+}
 function protectedResourceMetadataAuthority(authenticate, origin2, resourcePath) {
   const matches = [...authenticate.matchAll(/(?:^|[\s,])resource_metadata="([^"]+)"/gu)];
   if (!/(?:^|[\s,])Bearer(?:[\s,]|$)/iu.test(authenticate) || matches.length !== 1) {
@@ -55465,7 +55477,8 @@ var init_api2 = __esm({
             method: options.method.toUpperCase(),
             headers,
             body,
-            redirect: "error"
+            redirect: "error",
+            ...options.signal === void 0 ? {} : { signal: options.signal }
           });
         } catch (cause) {
           throw new CliHttpError("CLI_REMOTE_UNAVAILABLE", null, { cause });
@@ -55534,7 +55547,8 @@ var init_api2 = __esm({
           return await this.fetchImplementation(`${this.origin}${path2}`, {
             method: "GET",
             redirect: "error",
-            cache: "no-store"
+            cache: "no-store",
+            signal: AbortSignal.timeout(15e3)
           });
         } catch (cause) {
           throw new CliHttpError("CLI_REMOTE_UNAVAILABLE", null, { cause });
@@ -55563,7 +55577,7 @@ var init_api2 = __esm({
           throw new CliHttpError("CLI_REMOTE_UNAVAILABLE", resourceResponse.status);
         }
         const resource = jsonObject(await readBoundedJson(resourceResponse));
-        if (resource.resource !== resourceMetadataAuthority.resource || JSON.stringify(resource.authorization_servers) !== JSON.stringify([this.origin])) {
+        if (resource.resource !== resourceMetadataAuthority.resource || !includesCapabilities(resource.authorization_servers, [this.origin])) {
           throw new CliHttpError("CLI_RESPONSE_INVALID", resourceResponse.status);
         }
         const authorizationResponse = await this.publicFetch("/.well-known/oauth-authorization-server");
@@ -55572,33 +55586,14 @@ var init_api2 = __esm({
           throw new CliHttpError("CLI_REMOTE_UNAVAILABLE", authorizationResponse.status);
         }
         const authorization = jsonObject(await readBoundedJson(authorizationResponse));
-        if (authorization.issuer !== this.origin || authorization.authorization_endpoint !== `${this.origin}/oauth/authorize` || authorization.token_endpoint !== `${this.origin}/oauth/token` || authorization.registration_endpoint !== `${this.origin}/oauth/register` || JSON.stringify(authorization.response_types_supported) !== JSON.stringify(["code"]) || JSON.stringify(authorization.grant_types_supported) !== JSON.stringify(["authorization_code", "refresh_token"]) || JSON.stringify(authorization.token_endpoint_auth_methods_supported) !== JSON.stringify(["none"]) || JSON.stringify(authorization.code_challenge_methods_supported) !== JSON.stringify(["S256"])) {
+        if (authorization.issuer !== this.origin || authorization.authorization_endpoint !== `${this.origin}/oauth/authorize` || !sameOriginEndpoint(authorization.token_endpoint, this.origin) || !sameOriginEndpoint(authorization.registration_endpoint, this.origin) || !includesCapabilities(authorization.response_types_supported, ["code"]) || !includesCapabilities(authorization.grant_types_supported, ["authorization_code", "refresh_token"]) || !includesCapabilities(authorization.token_endpoint_auth_methods_supported, ["none"]) || !includesCapabilities(authorization.code_challenge_methods_supported, ["S256"])) {
           throw new CliHttpError("CLI_RESPONSE_INVALID", authorizationResponse.status);
         }
-        const manifestResponse = await this.publicFetch("/mcp/client-compatibility.json");
-        if (manifestResponse.status !== 200) {
-          await manifestResponse.body?.cancel().catch(() => void 0);
-          throw new CliHttpError("CLI_REMOTE_UNAVAILABLE", manifestResponse.status);
-        }
-        const manifest4 = jsonObject(await readBoundedJson(manifestResponse));
-        const mcp = jsonObject(manifest4.mcp);
-        const source = jsonObject(manifest4.source);
-        if (!Array.isArray(manifest4.clients) || manifest4.clients.length !== 1) {
-          throw new CliHttpError("CLI_RESPONSE_INVALID", manifestResponse.status);
-        }
-        const client = jsonObject(manifest4.clients[0]);
-        const install = jsonObject(client.install);
-        const authorize = jsonObject(client.authorize);
-        const verify = jsonObject(client.verify);
-        if (manifest4.schemaVersion !== 3 || manifest4.manifestId !== "finch.remote-mcp-clients" || mcp.serverName !== "finch" || mcp.url !== mcpUrl || mcp.transport !== "streamable_http" || mcp.authorization !== "oauth" || source.repository !== "https://github.com/FinchipAI/Finch-Site" || source.path !== "apps/mcp/src/client-compatibility.ts" || client.id !== "codex" || client.supportLevel !== "verified" || install.kind !== "native_cli" || install.executable !== "codex" || JSON.stringify(install.arguments) !== JSON.stringify(["mcp", "add", "finch", "--url", mcpUrl]) || authorize.kind !== "native_cli" || authorize.executable !== "codex" || JSON.stringify(authorize.arguments) !== JSON.stringify(["mcp", "login", "finch"]) || verify.kind !== "harness_ui" || verify.surface !== "mcp_tools" || client.reload !== "new_session") {
-          throw new CliHttpError("CLI_RESPONSE_INVALID", manifestResponse.status);
-        }
         return Object.freeze({
           url: mcpUrl,
           transport: "streamable_http",
           authorization: "oauth",
-          compatibilityManifestUrl,
-          supportedClients: Object.freeze(["codex"])
+          compatibilityManifestUrl
         });
       }
       async uploadSkillObject(input) {
@@ -55900,7 +55895,7 @@ var init_api2 = __esm({
         if (response.status === 202 && body?.status === "indexing_pending") return "indexing_pending";
         throw new CliHttpError("CLI_RESPONSE_INVALID", response.status);
       }
-      getSession(bearer) {
+      getSession(bearer, signal) {
         const operation3 = IDENTITY_V1_OPERATIONS.session;
         return this.request({
           method: operation3.method,
@@ -55908,7 +55903,8 @@ var init_api2 = __esm({
           successStatus: operation3.successStatus,
           errorContract: "identity",
           responseSchema: operation3.responseSchema,
-          bearer
+          bearer,
+          ...signal === void 0 ? {} : { signal }
         });
       }
       authorizeMcp(requestPath, bearer) {
@@ -57204,7 +57200,7 @@ var init_application = __esm({
         const redirectValues = request.searchParams.getAll("redirect_uri");
         const stateValues = request.searchParams.getAll("state");
         const scopeValues = request.searchParams.getAll("scope");
-        if (request.origin !== profile.origin || request.pathname !== "/oauth/authorize" || request.username !== "" || request.password !== "" || request.hash !== "" || requestUrl !== `${profile.origin}${request.pathname}${request.search}` || redirectValues.length !== 1 || stateValues.length > 1 || scopeValues.length !== 1) {
+        if (request.origin !== profile.origin || request.pathname !== "/oauth/authorize" || request.username !== "" || request.password !== "" || request.hash !== "" || requestUrl !== `${profile.origin}${request.pathname}${request.search}` || redirectValues.length !== 1 || stateValues.length > 1 || scopeValues.length > 1) {
           throw new TypeError("MCP OAuth request URL does not match the active profile authority.");
         }
         let registeredRedirect;
@@ -57221,10 +57217,10 @@ var init_application = __esm({
         if (response.authorized !== true || response.accountId !== authority.session.accountId || String(response.walletAddress).toLowerCase() !== authority.walletAddress || typeof response.clientName !== "string" || response.clientName.length < 1 || response.clientName.length > 128 || !Array.isArray(response.scopes) || response.scopes.some((scope) => typeof scope !== "string" || scope.length < 1) || typeof response.callbackUrl !== "string") {
           throw new CliAuthorityError();
         }
-        const requestedScopes = scopeValues[0].split(" ").filter(Boolean).sort();
-        const returnedScopes = [...response.scopes].sort();
-        if (requestedScopes.length < 1 || requestedScopes.length !== returnedScopes.length || requestedScopes.some((scope, index2) => scope !== returnedScopes[index2])) {
-          throw new CliAuthorityError();
+        const requestedScopes = [...new Set((scopeValues[0] ?? "").split(" ").filter(Boolean))].sort();
+        const returnedScopes = [...new Set(response.scopes)].sort();
+        if (returnedScopes.length < 1 || requestedScopes.length > 0 && (requestedScopes.length !== returnedScopes.length || requestedScopes.some((scope, index2) => scope !== returnedScopes[index2]))) {
+          throw new TypeError("MCP OAuth granted scopes do not match the authorization request.");
         }
         let callback;
         try {
@@ -57233,13 +57229,17 @@ var init_application = __esm({
           throw new TypeError("MCP OAuth callback is invalid.");
         }
         const codes = callback.searchParams.getAll("code");
-        if (codes.length !== 1 || !/^[A-Za-z0-9_-]{43}$/u.test(codes[0])) {
+        if (codes.length !== 1 || codes[0].length < 1 || callback.searchParams.has("error")) {
           throw new TypeError("MCP OAuth callback is invalid.");
         }
         const expectedCallback = new URL(registeredRedirect.href);
         expectedCallback.searchParams.set("code", codes[0]);
         if (stateValues.length === 1) expectedCallback.searchParams.set("state", stateValues[0]);
-        if (callback.href !== expectedCallback.href) {
+        const expectedParameters = new URLSearchParams(expectedCallback.search);
+        const callbackParameters = new URLSearchParams(callback.search);
+        expectedParameters.sort();
+        callbackParameters.sort();
+        if (callback.origin !== registeredRedirect.origin || callback.pathname !== registeredRedirect.pathname || callback.protocol !== registeredRedirect.protocol || callback.username !== "" || callback.password !== "" || callback.hash !== "" || callbackParameters.toString() !== expectedParameters.toString()) {
           throw new TypeError("MCP OAuth callback does not match the registered redirect and state.");
         }
         await required2(this.browserLauncher, "browser launcher").open(callback.href);
@@ -57412,7 +57412,8 @@ var init_application = __esm({
                 message: localFailureMessage(cause)
               }];
             } else if (cause instanceof CliHttpError) {
-              return [null, { status: cause.status === 401 || cause.status === 403 || cause.code === "CLI_RESPONSE_INVALID" ? "invalid" : "unavailable", message: guidance }];
+              const unavailable = cause.status === 429 || cause.status !== null && cause.status >= 500;
+              return [null, { status: !unavailable && (cause.status === 401 || cause.status === 403 || cause.code === "CLI_RESPONSE_INVALID") ? "invalid" : "unavailable", message: guidance }];
             } else if (cause instanceof TypeError || cause instanceof CliAuthorityError) {
               return [null, { status: "invalid", message: guidance }];
             } else {
@@ -57425,7 +57426,7 @@ var init_application = __esm({
           "Check the protected FINCHTECH_HOME/profile.json endpoint override."
         );
         const [wallet, walletCheck] = await inspect(
-          () => required2(this.state.readWalletAddress, "state.readWalletAddress").call(this.state),
+          () => required2(this.state.readWalletAddress, "state.readWalletAddress").call(this.state, { migrateLegacy: false }),
           "Restore the current wallet from backup."
         );
         const [session, sessionCheck] = await inspect(
@@ -57439,7 +57440,7 @@ var init_application = __esm({
             if (session.origin !== profile.origin || wallet.walletAddress !== session.walletAddress) {
               throw new CliAuthorityError();
             }
-            const remote = asObject(await required2(this.api.getSession, "api.getSession").call(this.api, session.rawBearer), "MCP doctor Session");
+            const remote = asObject(await required2(this.api.getSession, "api.getSession").call(this.api, session.rawBearer, AbortSignal.timeout(15e3)), "MCP doctor Session");
             if (remote.sessionId !== session.sessionId || remote.accountId !== session.accountId || remote.walletAddress !== session.walletAddress || remote.environment !== session.environment || remote.audience !== "agent_cli" || typeof remote.sessionExpiresAt !== "string" || !Number.isFinite(Date.parse(remote.sessionExpiresAt)) || Date.parse(remote.sessionExpiresAt) <= Date.now()) throw new CliAuthorityError();
             return { sessionExpiresAt: remote.sessionExpiresAt };
           }, "Verify the endpoint and current wallet, then run finch login --help to renew the CLI login. If the server is unavailable, retry later.");
@@ -57451,7 +57452,7 @@ var init_application = __esm({
         if (profile !== null) {
           [mcp, mcpDiscoveryCheck] = await inspect(async () => {
             const discovery = await required2(this.api.inspectRemoteMcp, "api.inspectRemoteMcp").call(this.api);
-            if (discovery.url !== `${profile.origin}/mcp` || discovery.authorization !== "oauth" || JSON.stringify(discovery.supportedClients) !== JSON.stringify(["codex"])) {
+            if (discovery.url !== `${profile.origin}/mcp` || discovery.authorization !== "oauth" || discovery.transport !== "streamable_http") {
               throw new TypeError("MCP discovery authority mismatch.");
             }
             return discovery;
@@ -58304,7 +58305,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@finchtech/cli",
-      version: "0.3.8",
+      version: "0.3.9",
       description: "Finch Agent CLI for wallet-owned marketplace and MCP workflows.",
       type: "module",
       bin: {
@@ -59133,7 +59134,13 @@ function privateKey(value) {
 function validatedWallet(input) {
   const address2 = walletAddress(input.walletAddress);
   const key = privateKey(input.privateKey);
-  if (privateKeyToAccount(key).address.toLowerCase() !== address2) {
+  let derivedAddress;
+  try {
+    derivedAddress = privateKeyToAccount(key).address.toLowerCase();
+  } catch (cause) {
+    throw new CliStateError("CLI_STATE_CORRUPT", { cause });
+  }
+  if (derivedAddress !== address2) {
     throw new CliStateError("CLI_STATE_CORRUPT");
   }
   return Object.freeze({ walletAddress: address2, privateKey: key });
@@ -59205,13 +59212,7 @@ var init_wallet_store = __esm({
         await this.writeIndex(nextIndex);
         if (makeCurrent || currentIndex.length === 0) await this.writeCurrent(wallet.walletAddress);
       }
-      async migrateLegacyOnce() {
-        try {
-          await this.files.readJson("wallet/current.json");
-          return;
-        } catch (cause) {
-          if (!(cause instanceof CliStateError) || cause.code !== "CLI_STATE_NOT_FOUND") throw cause;
-        }
+      async readLegacy() {
         const readOptional = async (read2) => {
           try {
             return await read2();
@@ -59226,15 +59227,26 @@ var init_wallet_store = __esm({
         ]);
         if (metadata === null && key === null) {
           const index2 = await this.readIndex();
-          if (index2.length === 0) return;
+          if (index2.length === 0) return null;
           throw new CliStateError("CLI_STATE_CORRUPT");
         }
         if (metadata === null || key === null) throw new CliStateError("CLI_STATE_CORRUPT");
         const legacy = record4(metadata);
-        await this.registerInternal(validatedWallet({
+        return validatedWallet({
           walletAddress: legacy.walletAddress,
           privateKey: key.toString("utf8")
-        }), true);
+        });
+      }
+      async migrateLegacyOnce() {
+        try {
+          await this.files.readJson("wallet/current.json");
+          return;
+        } catch (cause) {
+          if (!(cause instanceof CliStateError) || cause.code !== "CLI_STATE_NOT_FOUND") throw cause;
+        }
+        const legacy = await this.readLegacy();
+        if (legacy === null) return;
+        await this.registerInternal(legacy, true);
         await this.files.remove("wallet/private-key");
         await this.files.remove("wallet/metadata.json");
       }
@@ -59267,9 +59279,17 @@ var init_wallet_store = __esm({
         await this.migrateLegacy();
         return this.readIndex();
       }
-      async readCurrent() {
-        await this.migrateLegacy();
-        const current = record4(await this.files.readJson("wallet/current.json"));
+      async readCurrent(options = {}) {
+        if (options.migrateLegacy !== false) await this.migrateLegacy();
+        let current;
+        try {
+          current = record4(await this.files.readJson("wallet/current.json"));
+        } catch (cause) {
+          if (options.migrateLegacy !== false || !(cause instanceof CliStateError) || cause.code !== "CLI_STATE_NOT_FOUND") throw cause;
+          const legacy = await this.readLegacy();
+          if (legacy === null) throw cause;
+          return legacy;
+        }
         if (current.version !== 1) throw new CliStateError("CLI_STATE_CORRUPT");
         try {
           return await this.readRegistered(walletAddress(current.walletAddress));
@@ -59563,16 +59583,16 @@ var init_local_state = __esm({
       async saveWallet(input) {
         await this.wallets.register(input);
       }
-      async readWallet() {
+      async readWallet(options) {
         try {
-          return await this.wallets.readCurrent();
+          return await this.wallets.readCurrent(options);
         } catch (cause) {
           if (cause instanceof CliStateError) throw new CliStateError(cause.code, { cause, diagnostic: "wallet" });
           throw cause;
         }
       }
-      async readWalletAddress() {
-        const wallet = await this.readWallet();
+      async readWalletAddress(options) {
+        const wallet = await this.readWallet(options);
         return Object.freeze({ walletAddress: wallet.walletAddress });
       }
       async assertWalletBootstrap() {
@@ -60967,7 +60987,7 @@ var init_task_protocol_sender = __esm({
           const fields = record5(typedData.types, "Task award types").AwardAuthorization;
           const selected = taskDeployment(domain2.chainId);
           deployment ??= selected;
-          if (deployment.chainId !== selected.chainId || typedData.primaryType !== "AwardAuthorization" || domain2.name !== "Finch Task Vault" || domain2.version !== "0" || domain2.chainId !== deployment.chainId || JSON.stringify(fields) !== JSON.stringify(awardTypes.AwardAuthorization) || message.awardId !== record5(award.authorization, "Task award authorization").awardId) {
+          if (deployment.chainId !== selected.chainId || typedData.primaryType !== "AwardAuthorization" || domain2.name !== "Finch Task Vault" || domain2.version !== "0" || domain2.chainId !== deployment.chainId || !Array.isArray(fields) || fields.length !== awardTypes.AwardAuthorization.length || fields.some((field, index2) => typeof field !== "object" || field === null || Array.isArray(field) || Object.keys(field).length !== 2 || field.name !== awardTypes.AwardAuthorization[index2].name || field.type !== awardTypes.AwardAuthorization[index2].type) || message.awardId !== record5(award.authorization, "Task award authorization").awardId) {
             throw new TypeError("Task award signing authority is invalid.");
           }
           const canonicalDomain = {
@@ -61574,9 +61594,9 @@ function assetPlan(value, walletAddress2) {
   ], "Skill asset plan");
   const chainId = assertAuthority(plan, "asset_upload", walletAddress2, false);
   const skillId = string4(plan.skillId, "Skill id", /^[1-9][0-9]*$/u);
-  if (plan.assetKind !== "cover" || plan.maxBytes !== 5242880) throw new TypeError("Skill cover authority is invalid.");
+  if (plan.assetKind !== "cover" || typeof plan.maxBytes !== "number" || !Number.isSafeInteger(plan.maxBytes) || plan.maxBytes < 1) throw new TypeError("Skill cover authority is invalid.");
   const accepted = plan.acceptedMediaTypes;
-  if (!Array.isArray(accepted) || JSON.stringify(accepted) !== JSON.stringify(["image/png", "image/jpeg", "image/webp", "image/gif"])) {
+  if (!Array.isArray(accepted) || accepted.length < 1 || new Set(accepted).size !== accepted.length || accepted.some((mediaType) => typeof mediaType !== "string" || !/^image\/[a-z0-9.+-]+$/u.test(mediaType))) {
     throw new TypeError("Skill cover media authority is invalid.");
   }
   const action = object5(plan.localAction, "Skill local action");
@@ -62513,6 +62533,7 @@ var init_skill_local_flow = __esm({
         if (!stat.isFile() || stat.isSymbolicLink()) throw new TypeError("Skill cover path must be one regular file.");
         if (stat.size < 1 || stat.size > plan.maxBytes) throw new TypeError("Skill cover size is outside the prepared bound.");
         const bytes = new Uint8Array(await readFile2(absolute));
+        if (bytes.byteLength < 1 || bytes.byteLength > plan.maxBytes) throw new TypeError("Skill cover size is outside the prepared bound.");
         const mediaType = detectedImageMediaType(bytes);
         if (mediaType === null || !plan.acceptedMediaTypes.includes(mediaType)) {
           throw new TypeError("Skill cover bytes do not match an accepted image type.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finchtech/cli",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Finch Agent CLI for wallet-owned marketplace and MCP workflows.",
   "type": "module",
   "bin": {
@@ -34,11 +34,11 @@
     "typescript-eslint": "8.67.0",
     "viem": "2.55.15",
     "vitest": "4.1.10",
-    "@finch/skill-market-contracts": "0.1.0",
     "@finch/agent-market-contracts": "0.1.0",
-    "@finch/skill-content": "0.1.0",
     "@finch/deployment-manifest": "0.1.0",
-    "@finch/task-market-contracts": "0.1.0"
+    "@finch/skill-market-contracts": "0.1.0",
+    "@finch/task-market-contracts": "0.1.0",
+    "@finch/skill-content": "0.1.0"
   },
   "scripts": {
     "build": "esbuild src/bootstrap.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/finch.js --banner:js=\"#!/usr/bin/env node\"",