@finchtech/cli 0.5.2 → 0.5.3

package/README.md

@@ -10,13 +10,15 @@ For an existing private key, run `finch wallet use --file <PATH>` on a fresh ins
 
 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.
+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 carry a local trace ID matching the secret-safe `finch_cli_local_failure` record on stderr. This identifies a local attempt, not a server request.
 
-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.
+Remote MCP technical failures use stable public codes `API_CONNECTION_FAILED`, `API_TIMEOUT`, `API_RATE_LIMITED`, and `API_RESPONSE_INVALID`. Authentication and permission failures reuse the family codes (`UNAUTHORIZED`/`FORBIDDEN` for Skill and Task; Agent/Identity use their existing auth/scope codes). Unknown failures retain the family internal/store code. A technical code describes the reason, not whether a write executed: on an unknown write outcome, read the resource before deciding whether to retry. MCP text includes the available trace; protocol failures link the tool trace to the upstream trace in secret-safe diagnostics. Response-body socket failures and timeouts retain their category for JSON and Artifact downloads, separately from malformed JSON.
+
+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 null `reasonCode`; local `traceId` and explicitly labelled downstream evidence in `state` identify separate diagnostic boundaries. 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.
 
-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.
+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. Retry the same publication command or use its saved recovery command; completed stages are checked on chain, and pending transactions are awaited before another attempt. 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.
 
@@ -72,7 +74,7 @@ Skill preparations return `walletIntent.intentId`. With the updated CLI, run `sk
 
 `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` is retired and refuses before wallet or network access. Use Remote MCP `skill_market_presentation_update` to save listing text, cover, demo video and detail tabs as database overrides without a transaction. 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.
+Recover wallet results with `skill recover intent <fingerprint>` and publication material with `skill recover publication <fingerprint>`. Publication recovery checks chain facts and preserves known transaction identities to avoid duplicate gas. Old buyer journals are admitted only as receipt-only recovery after the server reconstructs and verifies their confirmed canonical transaction. Existing publication journals recover from chain state, including v4/v5/v6 records. 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.
 
@@ -134,14 +136,24 @@ 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 protects transaction resubmission while authorization cleanup and wallet switching preserve the journal.
+hashes. An unknown outcome is recoverable: retry `publish-submit` / `version-submit` with the same
+intent and source, or use the saved fingerprint recovery command after checking CLI/MCP identity.
+The CLI reads the exact owner, package hash and version, URI, or version-specific key flag on chain
+before each stage. Completed stages are skipped; a slug owned by another wallet is an explicit conflict.
+A reverted transaction is discarded after a fresh state check. A pending hash is awaited; confirmed
+nonce replacement or receipt timeout permits a fresh state check and another attempt.
+
+Journal v7 saves the signed transaction hash and nonce before broadcast. Hashless completion uses
+confirmed-block chain evidence without inventing a transaction hash; such transaction fields in a
+successful result are `null`. The gateway records these facts so remaining URI/key stages can proceed.
+`indexing_pending` does not block further chain stages. Legacy v4/v5/v6 journals follow the same chain
+checks. Journals predating Session intent references use the existing publication admission and
+projection adapters with their saved immutable material; new submissions still require an intent.
+Keep journals and their original wallet material across authorization changes. Fingerprint-only
+recovery can use stored bytes when the source is unavailable. Cleanup failures do not claim the journal
+still exists. These behaviors require CLI 0.5.3 or newer and the corresponding
+gateway plus `20261010020000_skill_publication_chain_checkpoints.sql`, applied separately through the
+protected environment workflow. Updating a website or Skill does not update the installed CLI.
 
 ## Bootstrap and health reports (CLI 0.3.4+)
 
@@ -175,7 +187,7 @@ CLI 0.4.1 supports Skill publication, acquisition, management, and delivery on A
 
 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.
+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 recover from chain state and submit only unfinished stages through the existing publication admission adapter, using their saved immutable material. Old clients' server interfaces remain available during rollout; their eventual retirement is separate work.
 
 ## Recovery-preserving Account transitions (CLI 0.5.1)