arkcli-update

arkcli version check and upgrade

Before starting, read ../arkcli-shared/SKILL.md, and follow its call attribution, structured output, and confirmation rules. This command does not access business accounts and does not require running auth status。

Check only

By default, use the zero-network local cache:

arkcli --format json update --check

Judge by status , do not look only at the compatibility field update_available：

status	Meaning	Agent behavior
unknown	No valid cache for the current release channel	Explicitly say "unknown"; when a real-time result is needed, use --refresh
up_to_date	The cache or registry has confirmed that the current version is not older than latest	You may report that it is already the latest; also explain source
update_available	latest is strictly newer than current	Report the version difference; do not upgrade automatically

source is none / cache / registry，checked_at is the cache or query time. When a real-time query is needed and you want to warm the cache along the way:

arkcli --format json update --check --refresh

--refresh will access the npm registry built into the current binary; on failure, preserve the original error and do not package stale cache as a real-time result.

Perform upgrade

Enter the write flow only when the user explicitly requests upgrading the current arkcli. First show current → latest and the current release channel, then obtain confirmation for this round; only after confirmation may the Agent add --yes：

arkcli update --yes

update will launch external npm, which is opaque_external_execution，does not support --dry-run. Do not attempt, fake, or replace Client Preview with the raw API; use a version difference explanation plus explicit confirmation to complete the safety loop.

A successful upgrade must simultaneously satisfy: npm returns success, the package version under the same npm global root equals latest, and the --version of the npm-managed target executable also equals latest. When the command returns failure, you must not claim the upgrade is complete.

Explicit arkcli update and arkcli update --check are available in all update modes;disabled only disables implicit behavior.

Persistent update policy

Execute only when the user explicitly requests changing the policy:

# 未来对应产品/平台 gate 开启后：显式授权当前 exact install
# 当前 release 会返回 automatic unavailable，不写配置
arkcli config set update.mode automatic

# 关闭静默自动安装，但保留后台检查与更新提示
arkcli config set update.mode notify

# 关闭后台检查、提示、自动更新和安装后缓存预热
arkcli config set update.mode disabled

Ordinary npm postinstall, first run, and environment variables must not infer automatic authorization; the compatibility default when update.mode is missing is always notify. Fail-closed transactions are implemented for Windows, macOS, and Linux, but all six product/platform production gates are currently false, so config set update.mode automatic will explicitly return unavailable before reading or writing config and consent receipt. The Agent must not interpret implementation completion, discovery of a new version, or the npm installation form as having obtained automatic permission.

After some future product/platform gate passes real cross-version acceptance and is enabled,automatic the interaction flow is as follows:

1. An ordinary interactive command completes successfully; that command always completes using the old version from startup.
2. The CLI requires that the exact stable product/package/registry/tag, forward patch, dual-clock observation, 10/50/100 cohort, explicit consent, and one-time rollout token all hold.
3. The detached helper waits for the current process to exit precisely, directly downloads the SRI/URL fixed by the reservation, and writes inert bytes into an isolated stage; it does not execute npm, Node, lifecycle, or candidate.
4. Windows uses persistent bootstrap, execution lease, journal, and FileId-bound no-replace rename; macOS uses RENAME_SWAP; Linux uses RENAME_EXCHANGE. Safe miss when atomic cutover is unsupported or any evidence drifts.
5. Only the next command after success uses the new version; failure does not change the success exit code of the just-executed business command, and the old version or exact rollback is preserved.

Currently no product/platform has entered the production automatic apply chain. Even if the gate opens in the future, CI, non-TTY, Client Preview, AI Skill workflow, internal maintenance commands,config/update commands, candidate/integration builds, directly run non-npm binaries, insufficient container/environment evidence, or inconsistent npm prefix will still safe miss; failure backs off for the same target version for 24 hours.

Failure and platform routing

• npm missing: hand the manual command given by the CLI to the user, and do not install Node/npm yourself.
• npm prefix / Node / NVM inconsistency: stop; prompt the user to switch back to the Node environment where the current arkcli is installed. Do not force continuation with another npm on PATH.
• Current binary is not inside an npm global package: the CLI will explain that this copy is unaffected; non-interactive environments must obtain authorization again before adding --yes. Even if npm package verification succeeds, do not claim the current copy has changed.
• Windows explicit arkcli update: the command only means "scheduled". The out-of-package helper will install after the parent process exits and write update-apply.log; only a new arkcli --version showing the target version, or a log recording installed and verified, allows completion to be reported.
• Windows apply uses a fail-closed rollback transaction: before updating, save the original package and the launcher generated by npm; if npm fails, any validation of package/version/executable/launcher fails, or an unfinished previous transaction is found, the old installation must be restored or stopped with recovery evidence preserved. Failure logs must not be interpreted as "partial success", and do not delete .arkcli-update-* recovery directory.
• macOS/Linux explicit arkcli update retains the existing manual npm upgrade semantics; do not describe the not-yet-enabled automatic atomic cutover as if the explicit command already used that path.

Prohibited behavior

• does not run postinstall on behalf of the user, nor overwrite existing notify/disabled; only when the user explicitly requests a policy change does the Agent execute config set update.mode ...。
• Do not simulate automatic updates with cron, system services, or Agent scheduled tasks.
• When the user only asks "is there a new version", do not run the real arkcli update。
• Do not interrupt the current business command or change its exit code because of an ordinary update notice.
• Do not interpret status=unknown as "no update" or "already up to date".

Evaluation cases are in references/evals.md。