Know which stage failed before you decide what to do.
Build, verification, inspection and publication establish different things. A build can leave files after a failed final gate. Inspection can succeed without a manifest. Verification can pass without a Hub baseline or a signature check. Publication can succeed while the local signature refresh warns. Keep the exact command, the target, the package paths and the messages.
| Command | Exit 0 | Exit 1 | Exit 2 |
|---|---|---|---|
build | Pair written and the post-build check passed | Invalid target, installation or capture failure, archive or manifest error, or failed post-build check | Argument parse error |
verify | Manifest, archive, command, environment and any available baseline checks passed | Missing package or manifest, identity or checksum or content mismatch, missing expected command or environment key, or baseline regression | Argument parse error |
inspect | Inspection printed | Invalid target, package not found, or archive unreadable | Argument parse error |
publish | Transfer accepted, matching bytes skipped, or a finalize conflict treated as success | Invalid target, package or manifest not found, credentials not found, or upload failure | Argument parse error |
version, help and legal exit 0; legal exits 2 on conflicting flags or an output error. --verbose prints each step and each expected command, shim and environment key; --debug adds a version and build banner for support.
A static gate is not a run of the tool.
verify checks identity, checksum, sizes, expected commands and environment names. It does not execute the tool, check a Hub signature, test symlink targets or binary architecture, or load libraries. Validate the packaged tool in the destination environment, and for a runtime with extension modules include the extensions consumers need.
The Hub baseline comparison is optional. Missing credentials, no published package of the same tool and target, or a connection failure skip it and local verification still runs; verbose output says which. A baseline regression, by contrast, is a local gate failure after evidence was obtained. When no published package of the same distribution exists, the comparison can use another distribution of the same tool and target, so check the baseline name in verbose output before treating a regression as real.
A build against an existing installation without a verification marker is accepted with a warning. The builder does not recover the original source evidence from the bytes; if you need stronger provenance, prepare a controlled installation and keep the installer evidence.
Retry the same command; confirm what the Hub serves.
Each chunk gets up to AIDC_MAX_RETRIES attempts (three by default). Keep the local archive unchanged and run publish again after a transient interruption; the builder looks for reusable progress for the same digest. Sessions below five percent progress are replaced, so a restart after an early interruption is expected. Credential rejection and content conflicts need their own repair, and raising the attempt count is not a remedy for a consistently rejected request.
aidc-pack treats a finalization conflict as success and does not force replacement. To see what is served, run aidc hub packages <tool> --detailed from an aidc installation on the same MAIT channel (this needs the Hub feature in its credentials) and compare the checksum for your version and target with the one aidc-pack inspect prints. If they differ, do not announce that your reviewed bytes are available. When several distribution variants share that version and target, ask the publication owner for the exact variant’s checksum; this listing does not identify the distribution beside each checksum. A warning Package exists on hub but checksum mismatch means the Hub already holds an artifact for this tool, version and target, possibly another distribution variant; publication continues.
A warning about fetching the signature after publication does not establish that the earlier upload failed. Repair any reported access or file-write problem before retrying the refresh. The artifact may already be accepted while the local manifest still lacks a signature; confirm the remote artifact first, then run publish again to retry the metadata refresh. Local verify never checks the Hub signature.
aidc-pack has no cleanup command; know what a build leaves.
Capture failures can leave the named capture container behind, and repeated builds of the same tool and version can then report a name conflict. Have the environment owner inspect and remove only containers confirmed abandoned. A build can also leave installation files behind, and tools it installed through AIDC remain until you remove them with aidc uninstall. A rebuild of the same identity reuses the filenames, so move any diagnostic copies out of the active pair first.
aidc-pack has no uninstall command. An executable supplied by the MAIT image goes away with the image; delete a standalone executable you placed on your path yourself. Delete the package directory (./packages or your AIDC_PACK_STORAGE_PATH) once its archives and manifests are no longer needed. Keep the credentials file if other MAIT tools on the account use it. aidc-pack legal lists the third-party components built into the executable and covers aidc-pack itself, not the tools it packages.