cairn-ai 0.6.0 → 0.7.0

package/README.pt.md

@@ -102,12 +102,14 @@ cairn upgrade
 cairn doctor
 cairn uninstall
 cairn toolcheck
+cairn auto-upgrade status
 ```
 
-- `cairn install`: instala de forma transacional custom marketplace source, versioned runtime, secoes config do Cairn e mirrors atuais.
-- `cairn upgrade`: substitui apenas entradas intactas do ownership manifest apos staged validation e usa rollback em falhas.
-- `cairn doctor`: valida ownership digests, features efetivos do Codex, status real do plugin e runtime locators sem reparar.
-- `cairn uninstall`: remove apenas entradas gerenciadas intactas; alvos modified ou unmanaged sao preservados como conflict.
+- `cairn install [--hosts all|codex,claude,antigravity]`: instala de forma transacional custom marketplace source, versioned runtime, secoes config do Cairn e mirrors atuais. O canonical runtime fica em `~/.cairn/install/` e o resto e instalado apenas para os hosts escolhidos. Sem `--hosts`, a primeira instalacao em um terminal pergunta os hosts; execucoes nao interativas e CI instalam todos.
+- `cairn upgrade [--hosts all|codex,claude,antigravity]`: substitui apenas entradas intactas do ownership manifest apos staged validation e usa rollback em falhas. Mantem os hosts registrados, a menos que `--hosts` os altere, migra uma instalacao do Cairn 0.6.0 ou anterior e atualiza um Claude Code plugin cache que ainda tenha outra versao. Se a versao instalada for mais nova que esta CLI, `install` e `upgrade` recusam sem mudar nada; `--allow-downgrade` instala mesmo assim a versao desta CLI.
+- `cairn doctor`: valida ownership digests, features efetivos do Codex, status real do plugin e runtime locators sem reparar. Imprime primeiro `Hosts: <ids>` e verifica apenas os hosts escolhidos (incluindo `Claude plugin cache version`). Uma instalacao legacy e relatada com a indicacao de migrar com `cairn upgrade`.
+- `cairn uninstall`: primeiro compara cada entrada nao config do ownership manifest com seu installed digest e recusa todo o uninstall, sem mudar nada, se algum managed artifact foi modificado ou removido. Caso contrario, remove ou restaura as entradas gerenciadas e os retained runtimes, limpa os managed scaffolds vazios, preserva alvos unmanaged e seus diretorios pai e aplica rollback a falhas antes do commit. Tambem remove `~/.cairn/update/`, e mantem `~/.cairn/config.json` e `~/.cairn/projects/`. Uma instalacao com layout legacy e removida no lugar, sem migracao.
+- `cairn auto-upgrade status|on|off|run`: `status` imprime em JSON a configuracao, a versao instalada, a ultima verificacao e o aviso pendente; `on`/`off` gravam `autoUpgrade` em `~/.cairn/config.json` e imprimem o mesmo relatorio; `run` consulta o npm agora, sem esperar o intervalo de 24 horas nem o backoff. Exit 0 e sucesso, 1 erro de execucao ou execucao com falha, 2 erro de uso.
 - `cairn toolcheck`: detecta repository stacks e verifica required tools; apenas um installer suportado e aprovado e executado, caso contrario `installer-unavailable`.
 - `cairn cleanup --root <repo>`: por padrao relata em modo read-only residuos legacy `.cairn` locais do projeto. `--yes` migra/reconcilia valid active state para o user-home store, remove apenas residuos conhecidos de state/lock/tool, preserva arquivos desconhecidos e remove o diretorio somente quando vazio.
 - `cairn memory check|index [--root <repo>]`: `check` compara `MEMORY.md` com `docs/memory/*.md` e imprime um relatorio JSON; sai com 1 para notas nao indexadas, dead links, duplicatas, resumos desatualizados, caracteres de controle em resumos ou caminhos inseguros, e warnings so falham com `--strict`. Entradas sao linhas de lista sob `## Domain Knowledge` (ou todas as linhas de lista num arquivo antigo sem essa secao); um link de nota em outra secao e uma mencao que `index` nunca reescreve. `index` adiciona notas ausentes e, quando o `Summary:` muda, troca so o resumo apos o link (uma linha com varios links fica como esta); remove apenas linhas placeholder do Cairn que coincidem exatamente nessa secao, nunca apaga entradas nem dead links e preserva o restante byte a byte. `--dry-run` mostra uma previa. Se o ponto de insercao estiver dentro de um bloco de codigo nao fechado, `index` nao escreve nada e sai com 1 com `unclosed-fence`. Erros de uso saem com 2; `cairn memory` sem subcomando continua imprimindo a orientacao.
@@ -120,10 +122,35 @@ cairn toolcheck
 
 O custom marketplace lifecycle separa source e versioned runtime. Staged validation precede cada commit, o ownership manifest vincula todos os managed digests e uma falha aciona reverse-order rollback. Artifacts modified ou unmanaged sao preserved e relatados como conflict. O Cairn altera apenas suas TOML sections e nao forca feature/agent settings publicos.
 
-Clean uninstall remove o Cairn marketplace cache root somente quando todos os managed scaffold directories estao vazios; qualquer conteudo unmanaged e preservado. O source repository, repository `MEMORY.md`/`PLAN.md` e user-home Cairn goal state, o package global `cairn-ai`, package-manager caches e legacy backups/settings fora do ownership manifest atual nao sao removidos automaticamente.
+Clean uninstall remove `~/.cairn/install/` e o Codex cache root `$CODEX_HOME/plugins/cache/cairn` somente quando todos os managed scaffold directories estao vazios; qualquer conteudo unmanaged e preservado. O source repository, repository `MEMORY.md`/`PLAN.md` e user-home Cairn goal state, o package global `cairn-ai`, package-manager caches e legacy backups/settings fora do ownership manifest atual nao sao removidos automaticamente.
 
 Codex usa `skills/` e `commands/`. Claude Code usa comandos espelhados e agent definitions em `.claude/`. Antigravity usa `.agents/workflows` e global skills mirrors.
 
+## Install Layout And Auto-Upgrade
+
+O Cairn guarda a instalacao em `CAIRN_HOME` (padrao `~/.cairn`). Os caminhos de cada host continuam definidos separadamente por `CODEX_HOME`, `CLAUDE_HOME`, `ANTIGRAVITY_HOME`, `ANTIGRAVITY_CLI_HOME` e `CODEX_CONFIG_PATH`.
+
+```text
+~/.cairn/
+  install/                  arquivos gerenciados pelo lifecycle
+    lifecycle.json          ownership manifest (schema 2: hosts, origin, retained runtimes)
+    lifecycle.lock, transaction.json, transactions/
+    runtime/<version>/      canonical runtime usado por todos os runtime locators e pelos hooks do Claude Code
+    codex/                  Codex local marketplace source
+    claude/                 Claude Code local marketplace
+  projects/                 goal state
+  config.json               configuracoes do usuario ("autoUpgrade")
+  update/                   estado do auto-upgrade
+$CODEX_HOME/plugins/cache/cairn/cairn/<version>/   copia no Codex plugin cache (somente se Codex for escolhido)
+```
+
+- Hosts: apenas `install` e `upgrade` aceitam `--hosts`, com `all` ou uma lista separada por virgulas de `codex`, `claude` e `antigravity`. A selecao fica no ownership manifest e `upgrade`, `doctor` e `uninstall` a seguem. Ela muda com `cairn upgrade --hosts <list>`; um arquivo gerenciado modificado de um host removido causa recusa. O prompt interativo (todos por padrao, apenas Claude Code, apenas Codex, apenas Antigravity ou uma lista) aparece somente quando nada esta instalado.
+- Migracao: uma instalacao do Cairn 0.6.0 ou anterior (tudo em `$CODEX_HOME/plugins/cache/cairn`) passa para `~/.cairn/install/` com um unico `cairn upgrade`, que tambem registra de novo o plugin do Claude Code a partir do novo caminho do marketplace. Uma migracao com falha ou interrompida e restaurada, e arquivos gerenciados modificados a recusam sem mudancas. A instalacao legacy migra com todos os hosts; um `--hosts` parcial fica para a execucao seguinte. Depois, gerencie a instalacao apenas com um Cairn CLI que conheca este layout e reinicie as sessoes abertas durante a migracao.
+- Retencao: um upgrade que muda a versao mantem o canonical runtime anterior e a copia do Codex cache por 3 dias (no maximo 3 de cada tipo) para que sessoes iniciadas antes continuem funcionando. O install ou upgrade seguinte remove os vencidos, e uninstall remove todos. Uma copia do Codex cache igual ou superior a nova versao nunca e mantida, porque o Codex carrega a versao mais alta do cache.
+- Claude Code plugin cache: se ainda tiver outra versao, `cairn upgrade` o atualiza com `claude plugin marketplace update cairn` e `claude plugin update cairn@cairn --scope user`. Se falhar, a instalacao atualizada e mantida, os comandos para concluir manualmente sao impressos e a saida e exit 1.
+- Auto-upgrade: ativado por padrao. No maximo uma vez a cada 24 horas (e nao nas 24 horas apos um install ou upgrade), `SessionStart` inicia um processo separado que le a versao mais recente de `cairn-ai` no npm, instala essa versao exata com `--ignore-scripts` em `~/.cairn/update/stage/`, verifica e executa o `cairn-lifecycle.mjs upgrade --auto` dela. Todas as versoes novas sao aplicadas, inclusive major, e nunca ha downgrade. O `SessionStart` seguinte mostra o resultado (`updated`, `failed` ou `manual`) em uma linha, uma unica vez. Nao funciona para instalacoes a partir de um git checkout (`origin: "checkout"`) nem ao executar de um source checkout.
+- Desativar: `cairn auto-upgrade off`, `CAIRN_AUTO_UPGRADE=0` (ou `false`, `off`, `no`) ou `"autoUpgrade": false` em `~/.cairn/config.json`. Um `config.json` ilegivel tambem desativa. O estado e o log da ultima execucao ficam em `~/.cairn/update/`.
+
 ## Antigravity Compatibility
 
 Antigravity suporta Agent Skills e Workflows baseados em `SKILL.md` chamados como `/workflow-name`. Cairn instala estes paths para essa superficie.

package/README.zh.md

@@ -102,12 +102,14 @@ cairn upgrade
 cairn doctor
 cairn uninstall
 cairn toolcheck
+cairn auto-upgrade status
 ```
 
-- `cairn install`: 以事务方式安装 custom marketplace source、versioned runtime、Cairn-owned config sections 和当前 host mirrors。
-- `cairn upgrade`: staged validation 后只替换 ownership manifest 中未修改的 entry，失败时 rollback。
-- `cairn doctor`: 只读验证 ownership digests、effective Codex features、真实 plugin status 和 runtime locators。
-- `cairn uninstall`: 只删除未修改的 managed entry；modified 或 unmanaged target 会 preserve 并报告 conflict。
+- `cairn install [--hosts all|codex,claude,antigravity]`: 以事务方式安装 custom marketplace source、versioned runtime、Cairn-owned config sections 和当前 host mirrors。 canonical runtime 位于 `~/.cairn/install/`，其余内容只为所选 host 安装。未提供 `--hosts` 时，在 terminal 中首次安装会询问 host，非交互运行和 CI 会安装所有 host。
+- `cairn upgrade [--hosts all|codex,claude,antigravity]`: staged validation 后只替换 ownership manifest 中未修改的 entry，失败时 rollback。 除非用 `--hosts` 修改，否则沿用已记录的 hosts；会迁移 Cairn 0.6.0 及更早版本的安装，并更新仍为其他版本的 Claude Code plugin cache。 已安装版本比当前 CLI 更新时，`install` 和 `upgrade` 不做任何更改并拒绝；如仍要安装当前 CLI 的版本，加 `--allow-downgrade`。
+- `cairn doctor`: 只读验证 ownership digests、effective Codex features、真实 plugin status 和 runtime locators。 第一行输出 `Hosts: <ids>`，只检查所选 host(包括 `Claude plugin cache version`)。发现 legacy 安装时提示运行 `cairn upgrade` 迁移。
+- `cairn uninstall`: 先将 config 以外的所有 ownership manifest entry 与 installed digest 对照，只要有任何 managed artifact 被修改或删除，就不做任何更改并拒绝整个 uninstall。否则删除或恢复 managed entry 和 retained runtimes，清理空的 managed scaffold，preserve unmanaged target 及其父目录，并 rollback commit 前的失败。 同时删除 `~/.cairn/update/`，保留 `~/.cairn/config.json` 和 `~/.cairn/projects/`。legacy layout 的安装不经迁移直接原地删除。
+- `cairn auto-upgrade status|on|off|run`: `status` 以 JSON 输出设置、已安装版本、上次检查时间和待显示的 notice；`on`/`off` 将 `autoUpgrade` 写入 `~/.cairn/config.json` 并输出同样的报告；`run` 忽略 24 小时周期和 backoff，立即检查 npm。exit 0 表示成功，1 表示执行错误或运行失败，2 表示用法错误。
 - `cairn toolcheck`: 检测 repository stacks 和 required tools；只执行已批准的 supported installer，否则返回 `installer-unavailable`。
 - `cairn cleanup --root <repo>`: 默认只读报告 legacy project-local `.cairn` residue。`--yes` 将 valid active state 迁移/协调到 user-home store，只删除 known state/lock/tool residue，保留 unknown files，并且仅在目录为空时清理目录。
 - `cairn memory check|index [--root <repo>]`: `check` 对照 `MEMORY.md` 与 `docs/memory/*.md` 并输出一个 JSON 报告；存在 unindexed notes、dead links、duplicates、stale summaries、summary 中的控制字符或 unsafe paths 时 exit 1，warnings 仅在 `--strict` 下失败。条目是 `## Domain Knowledge` 下的列表行(没有该 section 的旧文件则为所有列表行)；其他 section 中的 note 链接只是提及，`index` 不会改写。`index` 添加缺失的 notes，`Summary:` 变化时只替换链接后的 summary 部分(含多个链接的行保持原样)；只删除该 section 内完全匹配的 Cairn placeholder 行，不删除条目或 dead links，其余内容逐字节保留。可用 `--dry-run` 预览。插入位置位于未闭合的 code fence 内时，`index` 不写入任何内容，并以 `unclosed-fence` exit 1。用法错误 exit 2；不带子命令的 `cairn memory` 仍输出原有指引。
@@ -120,10 +122,35 @@ cairn toolcheck
 
 custom marketplace lifecycle 将 source 与 versioned runtime 分离。每次 commit 前执行 staged validation，ownership manifest 绑定全部 managed digests，失败时执行 reverse-order rollback。modified 或 unmanaged artifacts 会 preserve 并报告 conflict。Cairn 只修改自身 TOML sections，不强制 public feature/agent settings。
 
-Clean uninstall 仅在所有 managed scaffold directory 均为空时删除 Cairn marketplace cache root，并保留任何 unmanaged content。它不会自动删除 source repository、repository `MEMORY.md`/`PLAN.md`、user-home Cairn goal state、全局 `cairn-ai` package、package-manager cache，或当前 ownership manifest 之外的 legacy backup/settings。
+Clean uninstall 仅在所有 managed scaffold directory 均为空时删除 `~/.cairn/install/` 和 Codex cache root `$CODEX_HOME/plugins/cache/cairn`，并保留任何 unmanaged content。它不会自动删除 source repository、repository `MEMORY.md`/`PLAN.md`、user-home Cairn goal state、全局 `cairn-ai` package、package-manager cache，或当前 ownership manifest 之外的 legacy backup/settings。
 
 Codex 使用 `skills/` 和 `commands/`。Claude Code 使用 `.claude/` 下的 mirrored commands 和 agent definitions。Antigravity 使用 `.agents/workflows` 和 global skills mirrors。
 
+## Install Layout And Auto-Upgrade
+
+Cairn 将安装内容放在 `CAIRN_HOME`(默认 `~/.cairn`)下。各 host 的路径仍分别由 `CODEX_HOME`、`CLAUDE_HOME`、`ANTIGRAVITY_HOME`、`ANTIGRAVITY_CLI_HOME`、`CODEX_CONFIG_PATH` 决定。
+
+```text
+~/.cairn/
+  install/                  lifecycle 管理的文件
+    lifecycle.json          ownership manifest (schema 2: hosts, origin, retained runtimes)
+    lifecycle.lock, transaction.json, transactions/
+    runtime/<version>/      所有 runtime locator 和 Claude Code hooks 使用的 canonical runtime
+    codex/                  Codex local marketplace source
+    claude/                 Claude Code local marketplace
+  projects/                 goal state
+  config.json               用户设置 ("autoUpgrade")
+  update/                   auto-upgrade 状态
+$CODEX_HOME/plugins/cache/cairn/cairn/<version>/   Codex plugin cache copy (仅在选择 Codex 时)
+```
+
+- Hosts: 只有 `install` 和 `upgrade` 接受 `--hosts`，值为 `all` 或 `codex`、`claude`、`antigravity` 的逗号列表。选择会记录在 ownership manifest 中，`upgrade`、`doctor`、`uninstall` 都遵循它。用 `cairn upgrade --hosts <list>` 修改；被移除 host 的 managed file 若已被修改则拒绝。交互式 prompt(全部(默认)、仅 Claude Code、仅 Codex、仅 Antigravity、逗号列表)只在尚未安装任何内容时出现。
+- 迁移: Cairn 0.6.0 及更早版本的安装(`$CODEX_HOME/plugins/cache/cairn` 下的全部内容)只需一次 `cairn upgrade` 即迁移到 `~/.cairn/install/`，Claude Code plugin 也会用新的 marketplace 路径重新注册。迁移失败或中断时会恢复原状，存在被修改的 managed file 时不做任何改动并拒绝。legacy 安装以全部 host 迁移，因此非全部的 `--hosts` 需在下一次运行时指定。迁移后只用认识该 layout 的 Cairn CLI 管理，并重启迁移期间打开的 session。
+- 保留期: 改变版本的 upgrade 会把上一个 canonical runtime 和 Codex cache copy 保留 3 天(每类最多 3 个)，让 upgrade 前启动的 session 继续工作。过期的由下一次 install/upgrade 删除，uninstall 会全部删除。不低于新版本的 Codex cache copy 不会保留，因为 Codex 会加载 cache 中最高的版本。
+- Claude Code plugin cache: 若仍为其他版本，`cairn upgrade` 会用 `claude plugin marketplace update cairn` 和 `claude plugin update cairn@cairn --scope user` 更新。更新失败时保留已升级的安装，输出手动完成的命令并以 exit 1 结束。
+- Auto-upgrade: 默认开启。`SessionStart` 每 24 小时最多一次(install 或 upgrade 后 24 小时内不检查)启动一个 detached process：从 npm 读取最新的 `cairn-ai` 版本，以该确切版本加 `--ignore-scripts` 安装到 `~/.cairn/update/stage/` 并验证，然后运行该 package 的 `cairn-lifecycle.mjs upgrade --auto`。包括 major 在内的所有新版本都会应用，从不降级。下一个 `SessionStart` 用一行只提示一次结果(`updated`、`failed`、`manual`)。从 git checkout 安装(`origin: "checkout"`)或从 source checkout 运行时不会执行。
+- 关闭: `cairn auto-upgrade off`、`CAIRN_AUTO_UPGRADE=0`(也可用 `false`、`off`、`no`)，或在 `~/.cairn/config.json` 中设置 `"autoUpgrade": false`。无法读取的 `config.json` 也视为关闭。状态和上次运行日志位于 `~/.cairn/update/`。
+
 ## Antigravity Compatibility
 
 Antigravity 支持通过 `/workflow-name` 调用的 `SKILL.md` based Agent Skills and Workflows。Cairn 会为该 surface 安装这些 paths。

package/commands/cairn-doctor.md

@@ -10,9 +10,12 @@ bunx cairn-ai@latest doctor
 
 The doctor validates the custom marketplace installation and ownership manifest without repairing it. Diagnostics are read-only; rollback is performed only by lifecycle transaction recovery.
 
+The first line is `Hosts: <ids>`; only the selected hosts are checked and only their host CLIs are run. A legacy installation is reported with a hint to run `cairn upgrade`.
+
 Checks:
 
 - Source plugin manifest.
+- Canonical runtime under `~/.cairn/install/runtime/<version>/`.
 - Codex cached installation.
 - Marketplace file.
 - Hook manifest link in the installed copy.
@@ -20,6 +23,6 @@ Checks:
 - `cairn@cairn` installed/enabled/version from the actual Codex CLI.
 - effective Codex plugin/hook/multi-agent feature state (reported, never forced).
 - hook trust state.
-- Claude Code commands and agents mirror files.
+- Claude Code commands and agents mirror files, plugin files, and `cairn@cairn` registered/enabled state and `Claude plugin cache version`.
 - Antigravity IDE/CLI skills and workflows mirror files.
 - Installed runtime locators and their referenced scripts, templates, and model guidance.

package/commands/cairn-install.md

@@ -6,19 +6,25 @@ Run from the published or global package, not from the installed cache copy:
 
 ```sh
 bunx cairn-ai@latest install
+bunx cairn-ai@latest install --hosts claude
 ```
 
-The current custom marketplace lifecycle remains in use; this is not a migration to `codex plugin add`. Do not invoke lifecycle install/upgrade from the cached plugin root because that copy is the replacement target.
+The current custom marketplace lifecycle remains in use; this is not a migration to `codex plugin add`. Do not invoke lifecycle install/upgrade from an installed copy (`~/.cairn/install/` or the Codex plugin cache) because that copy is the replacement target.
+
+Hosts: `--hosts all` or a comma list of `codex`, `claude`, `antigravity` (also `--hosts=<list>`). Without it, a first install at a terminal asks once (all hosts is the default); non-interactive runs and CI install every host. The selection is recorded in the ownership manifest and followed by upgrade, doctor, and uninstall.
 
 Actions:
 
-- Stage and validate the Cairn installation, then transactionally commit the custom marketplace source and versioned runtime cache.
-- Add the `hooks/hooks.json` link to the installed manifest.
+- Stage and validate the Cairn installation, then transactionally commit the canonical runtime `~/.cairn/install/runtime/<version>/` (`CAIRN_HOME` overrides `~/.cairn`) and, for Codex, the marketplace source `~/.cairn/install/codex/` and the versioned runtime cache `$CODEX_HOME/plugins/cache/cairn/cairn/<version>/`.
+- Add the `hooks/hooks.json` link to the installed manifests.
 - Register only Cairn-owned marketplace, plugin, and hook trust sections in `~/.codex/config.toml`; do not rewrite public feature or agent settings.
 - Install `cairn-*` commands and agents mirror files for Claude Code.
-- Generate the Claude Code plugin `cairn@cairn` (four skills plus hooks that call the installed runtime) in the Cairn-owned local marketplace, then register it with `claude plugin marketplace add` and `claude plugin install cairn@cairn --scope user` after the files commit. Skip with a manual command when the `claude` CLI is missing, and never touch a different marketplace named `cairn`.
+- Generate the Claude Code plugin `cairn@cairn` (four skills plus hooks that call the canonical runtime) in the Cairn-owned local marketplace `~/.cairn/install/claude/`, then register it with `claude plugin marketplace add` and `claude plugin install cairn@cairn --scope user` after the files commit. Skip with a manual command when the `claude` CLI is missing, and never touch a different marketplace named `cairn`.
 - Install `cairn-*` skills and workflows mirror files for Antigravity IDE/CLI.
 - Write runtime locators so all mirrors resolve scripts, templates, and model guidance from the installed plugin root.
-- Record every current managed destination and digest in the ownership manifest under the custom marketplace, and rollback committed phases in reverse order on failure.
+- Install only the surfaces of the selected hosts; the canonical runtime is always installed.
+- Record every current managed destination and digest, the host selection, and the install origin in the ownership manifest `~/.cairn/install/lifecycle.json`, and rollback committed phases in reverse order on failure.
+- Automatic upgrades are on by default for a package install; see `cairn auto-upgrade status|on|off|run`.
 - Use the separate pinned SHA-256 release 0.2.2 file-hash allowlist only to validate that exact legacy file set; it is not the current package file list or a cryptographic signature.
 - Adopt an exact, unmodified supported legacy install only after release-integrity validation; preserve and reject modified or unknown artifacts.
+- Refuse, changing nothing, when the installed version is newer than this CLI; `--allow-downgrade` installs this CLI's version anyway.

package/commands/cairn-uninstall.md

@@ -8,15 +8,20 @@ Run from the published or global package:
 bunx cairn-ai@latest uninstall
 ```
 
-The custom marketplace ownership manifest is authoritative. Uninstall removes or restores only destinations whose current digest still matches the recorded installed digest; modified or unmanaged targets are preserved as conflicts. A failure rolls back the transaction.
+The custom marketplace ownership manifest is authoritative. Uninstall first compares every non-config managed destination with its recorded installed digest and refuses the whole uninstall, changing nothing, if any managed artifact was modified or removed. Otherwise it removes or restores the managed destinations; unmanaged targets and their parent directories are preserved. A failure rolls back the transaction.
 
 Managed items:
 
 - Cairn marketplace, plugin, and hook trust state blocks in `~/.codex/config.toml`.
-- `~/.codex/plugins/cache/cairn`.
+- `~/.cairn/install/` (ownership manifest, canonical and retained runtimes, Codex marketplace source, Claude Code marketplace).
+- `$CODEX_HOME/plugins/cache/cairn` (Codex versioned runtime cache and retained copies).
+- The Claude Code plugin `cairn@cairn` registration.
+- Auto-upgrade state in `~/.cairn/update/`.
 - Claude Code `cairn-*` commands and agents mirror files.
 - Antigravity IDE/CLI `cairn-*` skills and workflows mirror files.
 
-After the transaction commits, Cairn removes empty managed scaffold directories bottom-up and removes the custom marketplace root only after releasing its own lifecycle lock. A directory containing any unmanaged child is preserved; pruning never uses recursive deletion.
+Only the hosts recorded in the ownership manifest are touched. An installation made by Cairn 0.6.0 or earlier is removed in place without migrating.
 
-The source work folder, repository `MEMORY.md`, `PLAN.md`, `docs/`, and user-home Cairn goal state are not deleted. The globally installed `cairn-ai` package, package-manager download caches, legacy backup files, and legacy shared settings not recorded by the current ownership manifest are also outside this command's scope and require a separate, explicit cleanup decision.
+After the transaction commits, Cairn removes empty managed scaffold directories bottom-up and removes `~/.cairn/install/` and `$CODEX_HOME/plugins/cache/cairn` only when empty, after releasing its own lifecycle lock. `~/.cairn/update/` loses its known state files and is removed when empty. A directory containing any unmanaged child is preserved; pruning never uses recursive deletion.
+
+The source work folder, repository `MEMORY.md`, `PLAN.md`, `docs/`, and user-home Cairn goal state (`~/.cairn/projects/`) and settings (`~/.cairn/config.json`) are not deleted. The globally installed `cairn-ai` package, package-manager download caches, legacy backup files, and legacy shared settings not recorded by the current ownership manifest are also outside this command's scope and require a separate, explicit cleanup decision.

package/commands/cairn-upgrade.md

@@ -6,9 +6,10 @@ Run from the published or global package, not from the installed cache copy:
 
 ```sh
 bunx cairn-ai@latest upgrade
+bunx cairn-ai@latest upgrade --hosts codex,claude
 ```
 
-The current custom marketplace lifecycle remains in use. The cached plugin root is a replacement target and must not upgrade itself.
+The current custom marketplace lifecycle remains in use. An installed copy (`~/.cairn/install/` or the Codex plugin cache) is a replacement target and must not upgrade itself.
 
 Actions:
 
@@ -18,3 +19,9 @@ Actions:
 - Refresh runtime locators for every installed surface.
 - Stage and validate all candidates before commit; rollback committed phases in reverse order on failure.
 - Preserve and report a conflict for modified, unmanaged, or invalid legacy artifacts.
+- Keep the recorded hosts unless `--hosts` (`all` or a comma list of `codex`, `claude`, `antigravity`) changes them; deselected hosts are removed, and a modified artifact of a deselected host refuses the upgrade.
+- Migrate an installation made by Cairn 0.6.0 or earlier (everything under `$CODEX_HOME/plugins/cache/cairn`) to `~/.cairn/install/` in one transaction, re-registering the Claude Code plugin from its new marketplace path. A failed or interrupted migration is restored; a legacy installation migrates with every host, so a narrower `--hosts` is refused until the next run. Restart sessions that were open during the migration.
+- After a version change, keep the previous canonical runtime and Codex cache copy for 3 days (at most 3 of each); expired ones are removed by the next install or upgrade. A Codex cache copy at or above the new version is never kept, because Codex loads the highest cached version.
+- When the Claude Code plugin cache holds a different version, run `claude plugin marketplace update cairn` and `claude plugin update cairn@cairn --scope user`. If that fails, keep the upgraded files, print those commands, and exit 1.
+- Refuse, changing nothing, when the installed version is newer than this CLI; `--allow-downgrade` moves the installation to this CLI's version anyway.
+- `upgrade --auto` is reserved for the auto-upgrade runner; it keeps the recorded hosts, never downgrades (it cannot be combined with `--allow-downgrade`), and refuses to run without an existing installation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn-ai",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity",
   "license": "MIT",
   "author": {
@@ -41,7 +41,7 @@
     "README.*.md"
   ],
   "scripts": {
-    "check": "node --check scripts/cairn.mjs && node --check scripts/cairn-paths.mjs && node --check scripts/cairn-safe-fs.mjs && node --check scripts/cairn-goal.mjs && node --check scripts/cairn-state.mjs && node --check scripts/cairn-cleanup.mjs && node --check scripts/cairn-lifecycle.mjs && node --check scripts/cairn-toolcheck.mjs && node -e \"JSON.parse(require('node:fs').readFileSync('package.json','utf8')); JSON.parse(require('node:fs').readFileSync('.codex-plugin/plugin.json','utf8')); JSON.parse(require('node:fs').readFileSync('hooks/hooks.json','utf8')); JSON.parse(require('node:fs').readFileSync('scripts/release-integrity-0.2.2.json','utf8'))\" && npm test",
+    "check": "node --check scripts/cairn.mjs && node --check scripts/cairn-paths.mjs && node --check scripts/cairn-safe-fs.mjs && node --check scripts/cairn-goal.mjs && node --check scripts/cairn-state.mjs && node --check scripts/cairn-cleanup.mjs && node --check scripts/cairn-lifecycle.mjs && node --check scripts/cairn-lifecycle-layout.mjs && node --check scripts/cairn-lifecycle-hosts.mjs && node --check scripts/cairn-update-state.mjs && node --check scripts/cairn-auto-upgrade.mjs && node --check scripts/cairn-toolcheck.mjs && node -e \"JSON.parse(require('node:fs').readFileSync('package.json','utf8')); JSON.parse(require('node:fs').readFileSync('.codex-plugin/plugin.json','utf8')); JSON.parse(require('node:fs').readFileSync('hooks/hooks.json','utf8')); JSON.parse(require('node:fs').readFileSync('scripts/release-integrity-0.2.2.json','utf8'))\" && npm test",
     "test": "node --test",
     "prepack": "npm run check"
   },

package/scripts/cairn-auto-upgrade.mjs

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { lstat, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createLifecycleLock } from "./cairn-lifecycle-lock.mjs";
+import { assertNoSymlinkComponents } from "./cairn-safe-fs.mjs";
+import {
+  AUTO_UPGRADE_EXIT, UPDATE_PACKAGE_NAME, autoUpgradeSetting, emptyUpdateState, noticeRecord, readInstallManifest,
+  readJsonFile, readPendingNotice, readUpdateState, removeUpdateState, updatePaths, writeFileAtomic, writeJsonAtomic,
+} from "./cairn-update-state.mjs";
+
+// The detached auto-upgrade runner (`run`, started by the SessionStart hook) and the `cairn auto-upgrade` CLI.
+// The runner is the old version and the package it installs is the new one. Only three things are fixed between
+// versions: the `cairn-lifecycle.mjs upgrade --auto` call, `version` in CAIRN_HOME/install/lifecycle.json, and the
+// meaning of the lifecycle exit code (0 done, AUTO_UPGRADE_EXIT.manual a Claude Code step left to the user, anything
+// else not confirmed).
+export const AUTO_UPGRADE_USAGE = "Usage: cairn auto-upgrade status|on|off|run";
+const VIEW_TIMEOUT_MS = 30_000;
+const INSTALL_TIMEOUT_MS = 120_000;
+const LIFECYCLE_TIMEOUT_MS = 300_000;
+const LOG_LIMIT_BYTES = 64 * 1024;
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+const REGISTRY_VERSION = /^\d+\.\d+\.\d+$/;
+const REGISTRY_VERSION_MAX_LENGTH = 32;
+const LOCK_BUSY = "Timed out waiting for Cairn lifecycle lock";
+
+class UsageError extends Error {}
+
+if (isCliEntry()) {
+  try {
+    process.exitCode = await main(process.argv.slice(2));
+  } catch (error) {
+    console.error(`Cairn auto-upgrade error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = error instanceof UsageError ? 2 : 1;
+  }
+}
+
+// Exit codes follow the root CLI: 0 success or help, 1 an execution error or a failed run, 2 a usage error.
+export async function main(args, env = process.env) {
+  const [command, ...rest] = args;
+  if (command === undefined || command === "help" || command === "--help") {
+    console.log(AUTO_UPGRADE_USAGE);
+    return 0;
+  }
+  if (!["status", "on", "off", "run"].includes(command)) throw new UsageError(`unknown command: ${command}`);
+  if (rest.length > 0) throw new UsageError(`auto-upgrade ${command} does not accept arguments: ${rest.join(" ")}`);
+  if (command === "on" || command === "off") setAutoUpgrade(env, command === "on");
+  if (command !== "run") {
+    printJson(statusReport(env));
+    return 0;
+  }
+  const report = await runAutoUpgrade(env);
+  printJson(report);
+  return ["failed", "check-failed", "manual"].includes(report.result?.kind) ? 1 : 0;
+}
+
+export function statusReport(env = process.env) {
+  const paths = updatePaths(env);
+  const setting = autoUpgradeSetting(env, paths);
+  const manifest = readInstallManifest(paths);
+  const state = readUpdateState(paths);
+  return {
+    enabled: setting.enabled,
+    source: setting.source,
+    installed: manifest,
+    lastCheckedAt: state?.lastCheckedAt ?? null,
+    latestSeen: state?.latestSeen ?? null,
+    nextAttemptAt: state?.nextAttemptAt ?? null,
+    consecutiveFailures: state?.consecutiveFailures ?? 0,
+    failedVersion: state?.failedVersion ?? null,
+    lastResult: state?.lastResult ?? null,
+    pendingNotice: readPendingNotice(paths),
+    config: paths.config,
+    statePath: paths.state,
+    log: paths.log,
+  };
+}
+
+// Other config.json keys are kept. A config.json that is not a readable JSON object is left as it is.
+function setAutoUpgrade(env, enabled) {
+  const paths = updatePaths(env);
+  const read = readJsonFile(paths.config);
+  const object = read.status === "ok" && read.value && typeof read.value === "object" && !Array.isArray(read.value);
+  if (read.status !== "missing" && !object) throw new Error(`${paths.config} is not a readable JSON object; fix or remove it`);
+  writeJsonAtomic(paths.config, { ...(object ? read.value : {}), autoUpgrade: enabled });
+}
+
+export async function runAutoUpgrade(env = process.env) {
+  const paths = updatePaths(env);
+  if (!autoUpgradeSetting(env, paths).enabled) return { ran: false, reason: "disabled" };
+  if (!readInstallManifest(paths)) return { ran: false, reason: "not-installed" };
+  await assertNoSymlinkComponents(paths.home, paths.stage);
+  await mkdir(paths.root, { recursive: true });
+  // A held update.lock means another runner is working: exit without waiting. A lock left by a dead process is
+  // reclaimed by the lifecycle lock rules.
+  let report;
+  try {
+    report = await createLifecycleLock({ lifecycleLockPath: paths.lock })
+      .withLifecycleLock(() => runLocked(env, paths), { timeoutMs: 1, retryMs: 1 });
+  } catch (error) {
+    if (String(error?.message).startsWith(LOCK_BUSY)) return { ran: false, reason: "locked" };
+    throw error;
+  }
+  // An uninstall finished while this runner worked: its update state goes too, as uninstall would have removed it.
+  if (report.reason === "not-installed" && readJsonFile(paths.manifest).status === "missing") await removeUpdateState(env);
+  return report;
+}
+
+async function runLocked(env, paths) {
+  // Read again under the lock: a lifecycle command or another runner may have changed the installation.
+  if (!autoUpgradeSetting(env, paths).enabled) return { ran: false, reason: "disabled" };
+  const manifest = readInstallManifest(paths);
+  if (!manifest) return { ran: false, reason: "not-installed" };
+  const now = new Date();
+  const previous = { ...emptyUpdateState(), ...(readUpdateState(paths) ?? {}) };
+  if (manifest.origin === "checkout") {
+    const state = { ...previous, lastCheckedAt: now.toISOString(), lastResult: result("skipped", now, manifest.version, null, "checkout-origin installation") };
+    writeJsonAtomic(paths.state, state);
+    return { ran: false, reason: "checkout", result: state.lastResult };
+  }
+  const log = [];
+  let state;
+  try {
+    const lookup = runNpm(["view", `${UPDATE_PACKAGE_NAME}@latest`, "version", "--json"], { cwd: paths.root, env, timeout: VIEW_TIMEOUT_MS });
+    log.push(logEntry("npm view", lookup));
+    const latest = registryVersion(lookup);
+    state = latest.error
+      ? checkFailure(previous, { now, from: manifest.version, to: null, detail: latest.error })
+      : isNewer(latest.version, manifest.version)
+        ? await upgradeTo(latest.version, { env, paths, manifest, previous, now, log })
+        : settled(previous, { now, kind: "current", from: manifest.version, to: latest.version });
+  } catch (error) {
+    // An unexpected error (a file system failure around the stage) is recorded like a lookup failure: no notice, and
+    // a backoff so the next sessions do not retry it at once.
+    const detail = `unexpected error: ${error instanceof Error ? error.message : String(error)}`;
+    log.push(detail);
+    state = checkFailure(previous, { now, from: manifest.version, to: null, detail });
+  }
+  if (state.uninstalled) return { ran: false, reason: "not-installed" };
+  try {
+    writeJsonAtomic(paths.state, state);
+    return { ran: true, result: state.lastResult };
+  } finally {
+    writeLog(paths.log, now, log);
+  }
+}
+
+async function upgradeTo(target, { env, paths, manifest, previous, now, log }) {
+  const from = manifest.version;
+  await rm(paths.stage, { recursive: true, force: true });
+  await assertNoSymlinkComponents(paths.home, paths.stage);
+  await mkdir(paths.stage, { recursive: true });
+  // npm installs into the nearest package.json; without this one it would climb to CAIRN_HOME or the home directory.
+  await writeFile(join(paths.stage, "package.json"), `${JSON.stringify({ name: "cairn-auto-upgrade-stage", private: true }, null, 2)}\n`);
+  try {
+    // The stage is the cwd, so no path is passed to npm (npm.cmd splits paths with spaces on Windows).
+    const install = runNpm(["install", "--ignore-scripts", "--no-audit", "--no-fund", "--no-save", `${UPDATE_PACKAGE_NAME}@${target}`], {
+      cwd: paths.stage, env, timeout: INSTALL_TIMEOUT_MS,
+    });
+    log.push(logEntry("npm install", install));
+    if (install.error || install.status !== 0) {
+      return checkFailure(previous, { now, from, to: target, detail: `npm install failed: ${lastLine(install)}` });
+    }
+    const problem = await verifyStagedPackage(paths.stage, target);
+    if (problem) return upgradeFailure(previous, { paths, now, from, to: target, detail: `verification failed: ${problem}` });
+    const lifecycle = spawnSync(process.execPath, [join(paths.stage, "node_modules", UPDATE_PACKAGE_NAME, "scripts", "cairn-lifecycle.mjs"), "upgrade", "--auto"], {
+      cwd: paths.root, env, encoding: "utf8", timeout: LIFECYCLE_TIMEOUT_MS, windowsHide: true, maxBuffer: 16 * 1024 * 1024,
+    });
+    log.push(logEntry("cairn-lifecycle upgrade --auto", lifecycle));
+    // An uninstall finished while the package was staged (`upgrade --auto` then installs nothing): there is nothing
+    // left to upgrade or to report.
+    if (readJsonFile(paths.manifest).status === "missing") return { uninstalled: true };
+    const installed = readInstallManifest(paths);
+    // The manifest decides: the files moved to the target version or they did not.
+    if (installed?.version !== target) {
+      return upgradeFailure(previous, { paths, now, from, to: target, detail: `upgrade exited ${lifecycle.status ?? lifecycle.error?.code}: ${lastLine(lifecycle)}` });
+    }
+    if (lifecycle.status === 0 || lifecycle.status === AUTO_UPGRADE_EXIT.manual) {
+      const kind = lifecycle.status === 0 ? "updated" : "manual";
+      writeJsonAtomic(paths.notice, noticeRecord(kind, from, target, now.toISOString()));
+      return settled(previous, { now, kind, from, to: target, detail: kind === "manual" ? lastLine(lifecycle) : null });
+    }
+    // The files moved but the run failed after its commit: reported once like a failed upgrade. The next check finds
+    // the target version installed, so the upgrade is not retried.
+    return upgradeFailure(previous, { paths, now, from, to: target, detail: `upgrade exited ${lifecycle.status ?? lifecycle.error?.code} after its commit: ${lastLine(lifecycle)}` });
+  } finally {
+    // A stage that cannot be removed (a held file, a changed permission) must not hide the result; the next run
+    // removes it before staging again.
+    try { await rm(paths.stage, { recursive: true, force: true }); } catch (error) { log.push(`stage removal failed: ${error.message}`); }
+  }
+}
+
+function settled(previous, { now, kind, from, to, detail = null }) {
+  return {
+    ...previous, lastCheckedAt: now.toISOString(), latestSeen: to, consecutiveFailures: 0, nextAttemptAt: null,
+    failedVersion: null, lastResult: result(kind, now, from, to, detail),
+  };
+}
+
+// Lookup and install failures (offline, no npm, a registry error) back off 1h, 2h, … up to 24h without a notice.
+function checkFailure(previous, { now, from, to, detail }) {
+  const failures = previous.lastResult?.kind === "check-failed" ? failureCount(previous) + 1 : 1;
+  return {
+    ...previous, latestSeen: to ?? previous.latestSeen, consecutiveFailures: failures,
+    nextAttemptAt: new Date(now.getTime() + Math.min(HOUR_MS * 2 ** (failures - 1), DAY_MS)).toISOString(),
+    lastResult: result("check-failed", now, from, to, detail),
+  };
+}
+
+// A version that failed verification or the upgrade backs off 24h, 48h, … up to 7 days, with one notice per version.
+// A newer release starts over.
+function upgradeFailure(previous, { paths, now, from, to, detail }) {
+  const sameVersion = previous.failedVersion === to;
+  const failures = sameVersion && previous.lastResult?.kind === "failed" ? failureCount(previous) + 1 : 1;
+  if (!sameVersion) writeJsonAtomic(paths.notice, noticeRecord("failed", from, to, now.toISOString()));
+  return {
+    ...previous, lastCheckedAt: now.toISOString(), latestSeen: to, consecutiveFailures: failures, failedVersion: to,
+    nextAttemptAt: new Date(now.getTime() + Math.min(DAY_MS * 2 ** (failures - 1), 7 * DAY_MS)).toISOString(),
+    lastResult: result("failed", now, from, to, detail),
+  };
+}
+
+function failureCount(state) {
+  return Number.isSafeInteger(state.consecutiveFailures) && state.consecutiveFailures > 0 ? state.consecutiveFailures : 0;
+}
+
+function result(kind, now, from, to, detail) {
+  return { kind, at: now.toISOString(), from, to, detail };
+}
+
+// Only an exact x.y.z release of at most 32 characters is accepted; npm 12 may wrap it in an object.
+function registryVersion(lookup) {
+  if (lookup.error || lookup.status !== 0) return { error: `npm view failed: ${lastLine(lookup)}` };
+  let value;
+  try { value = JSON.parse(lookup.stdout); } catch { return { error: "npm view did not return JSON" }; }
+  if (value && typeof value === "object" && !Array.isArray(value)) value = value.version;
+  if (typeof value !== "string" || value.length > REGISTRY_VERSION_MAX_LENGTH || !REGISTRY_VERSION.test(value)) {
+    return { error: `npm view returned an invalid version: ${String(JSON.stringify(value)).slice(0, 80)}` };
+  }
+  return { version: value };
+}
+
+// Strictly newer by major.minor.patch, or the same core release of an installed prerelease. Never a downgrade.
+function isNewer(latest, installed) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(-.+)?$/.exec(installed);
+  if (!match) return false;
+  const next = latest.split(".").map(BigInt);
+  const current = match.slice(1, 4).map(BigInt);
+  for (let index = 0; index < 3; index += 1) if (next[index] !== current[index]) return next[index] > current[index];
+  return Boolean(match[4]);
+}
+
+// The staged package must be exactly cairn-ai@<target> with no dependencies, symlinks, or special files.
+async function verifyStagedPackage(stage, target) {
+  const modules = join(stage, "node_modules");
+  const packageRoot = join(modules, UPDATE_PACKAGE_NAME);
+  try {
+    for (const entry of (await readdir(modules)).sort()) {
+      if (!entry.startsWith(".") && entry !== UPDATE_PACKAGE_NAME) return `unexpected package in node_modules: ${entry}`;
+    }
+    const special = await firstSpecialEntry(packageRoot);
+    if (special) return `not a regular file or directory: ${relative(stage, special)}`;
+    const manifest = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
+    if (manifest?.name !== UPDATE_PACKAGE_NAME || manifest.version !== target) {
+      return `package.json names ${manifest?.name}@${manifest?.version}, expected ${UPDATE_PACKAGE_NAME}@${target}`;
+    }
+    const plugin = JSON.parse(await readFile(join(packageRoot, ".codex-plugin", "plugin.json"), "utf8"));
+    if (plugin?.name !== "cairn" || plugin.version !== target) {
+      return `.codex-plugin/plugin.json names ${plugin?.name}@${plugin?.version}, expected cairn@${target}`;
+    }
+    if (!(await lstat(join(packageRoot, "scripts", "cairn-lifecycle.mjs"))).isFile()) return "scripts/cairn-lifecycle.mjs is not a regular file";
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
+async function firstSpecialEntry(path) {
+  const info = await lstat(path);
+  if (info.isFile()) return null;
+  if (!info.isDirectory()) return path;
+  for (const entry of (await readdir(path)).sort()) {
+    const found = await firstSpecialEntry(join(path, entry));
+    if (found) return found;
+  }
+  return null;
+}
+
+// CAIRN_NPM_CLI follows the CAIRN_CLAUDE_CLI rule: a .mjs/.js stand-in runs through this Node binary, anything else
+// is run directly (through the shell on Windows for npm.cmd).
+function runNpm(args, { cwd, env, timeout }) {
+  const cli = env.CAIRN_NPM_CLI ?? "npm";
+  const options = { cwd, env, encoding: "utf8", timeout, windowsHide: true, maxBuffer: 16 * 1024 * 1024 };
+  if (/\.m?js$/.test(cli)) return spawnSync(process.execPath, [cli, ...args], options);
+  return spawnSync(cli, args, { ...options, shell: process.platform === "win32" });
+}
+
+function logEntry(label, run) {
+  return `$ ${label} (exit ${run.status ?? run.error?.code ?? run.signal ?? "unknown"})\n${run.stdout ?? ""}${run.stderr ?? ""}`;
+}
+
+// The last run's npm and lifecycle output, keeping the end when it exceeds 64 KiB.
+function writeLog(path, now, entries) {
+  try {
+    let text = `${now.toISOString()}\n${entries.join("\n")}\n`;
+    const bytes = Buffer.from(text, "utf8");
+    if (bytes.length > LOG_LIMIT_BYTES) text = bytes.subarray(bytes.length - LOG_LIMIT_BYTES).toString("utf8");
+    while (Buffer.byteLength(text, "utf8") > LOG_LIMIT_BYTES) text = text.slice(1);
+    writeFileAtomic(path, text);
+  } catch {
+    // The log is diagnostic only.
+  }
+}
+
+function lastLine(run) {
+  const text = [run.stderr, run.stdout].map((value) => String(value ?? "").trim()).find(Boolean) ?? run.error?.message ?? `exit ${run.status}`;
+  return text.split("\n").filter((line) => line.trim()).at(-1)?.trim().slice(0, 300) ?? "";
+}
+
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+function isCliEntry() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch {
+    return import.meta.url === pathToFileURL(process.argv[1]).href;
+  }
+}