@petercjl/codex-own 0.6.3 → 0.6.5

package/README.md

@@ -44,6 +44,20 @@ Windows 桌面在启动 Agent 会话时自动检测并验证系统安装的 Git
 
 日常应用内更新使用随 App 交付的更新组件，无需手动更新全局 npm 管理工具。API Key、配置、对话和语言偏好会保留。断网时当前 App 保持可用；下载失败可以重试，已校验分片会复用；已准备好的更新会在下次打开时恢复。旧版本首次升级到带更新组件的版本，以及故障恢复，可以使用下文的终端更新命令。
 
+## 更新后的自动清理
+
+从桌面 0.6.4 起，主界面加载并持续正常运行 30 秒后，codex-own 会确认当前受管理版本，再自动清理已成功安装的完整归档和已退出的更新助手。升级前的程序及配置/对话快照成套保留最近一次完整回滚，更早且有成功事务记录的备份会回收。当前应用、密钥、配置、对话、独立 Node/npm/Python 运行时及手动备份保持完整。
+
+已校验分片缓存默认上限为 2 GiB，优先回收长期未使用的分片；待安装或失败更新需要的分片受保护，期间可能暂时超过上限。无法识别的目录、未完成事务、被占用文件和不完整的回滚资料会保留。清理异常不影响当前应用及正常更新；“更新”窗口会显示本次启动回收的空间。清理计划、结果和启动确认记录各保留最近 20 条。
+
+可直接发给 Agent：
+
+> 请检查 codex-own 的更新文件占用，并预览自动清理范围和保留的回滚备份。
+
+> 请通过 @petercjl/codex-own 清理已用完的更新文件和更旧的受管理备份，保留最近一次完整回滚。
+
+开发者入口：`codex-own cleanup plan` 只读预览；`codex-own cleanup run --yes` 按相同策略执行。`--cache-limit-mib <0..16384>` 可指定本次清理的缓存上限。清理需要当前桌面已记录成功启动；仅升级 npm 管理工具不会产生这份启动证明。清理使用安装操作锁，原版 Codex 和系统/npm 全局缓存不在范围内。
+
 ## 增量下载
 
 从 0.4.0 起，更新前会扫描已安装的 codex-own 程序，复用与新版相同的内容块，只从 npm 下载缺少的块。支持跳过版本；首次安装仍下载完整资源。进度会显示“复用多少块、需要下载多少 MiB、全量多少 MiB”，结果中的 `transfer` 保留这些统计。少量代码改动通常只影响部分块；上游引擎、大型二进制或签名资源变化时，下载量会相应增加。
@@ -87,11 +101,23 @@ npm install --global --prefix "$HOME/.local" @petercjl/codex-own@latest
 "$HOME/.local/bin/codex-own" version
 ```
 
-可选：需要使用模型时，再配置 API Key 并启动。将只包含一行 DashScope API Key 的文件放到下载目录，命名为 codex-own-api-key.txt；文件在其他位置时修改路径。配置前退出应用，已有可用配置可跳过配置命令。
+**API Key 文件路径必须改为你实际下载的位置，不能直接复制占位路径。** 配置前先保存任务；命令会关闭 codex-own，完成配置后从 Mac“应用程序”打开 codex-own。
 
 ```bash
-"$HOME/.local/bin/codex-own" configure --api-key-file "$HOME/Downloads/codex-own-api-key.txt" --yes
-"$HOME/.local/bin/codex-own" launch
+apiKeyFile="【填写 API Key 文件的实际完整路径】"
+if [ -f "$apiKeyFile" ]; then
+    ownPattern='^/Applications/codex-own[.]app/Contents/'
+    pkill -TERM -f "$ownPattern" || true
+    for i in {1..10}; do
+        pgrep -f "$ownPattern" >/dev/null || break
+        sleep 1
+    done
+    pkill -KILL -f "$ownPattern" || true
+    "$HOME/.local/bin/codex-own" configure --api-key-file "$apiKeyFile" --yes &&
+    "$HOME/.local/bin/codex-own" doctor
+else
+    printf '%s\n' "请先填写 apiKeyFile，确认文件路径和文件名正确。"
+fi
 ```
 
 以后更新：先退出 codex-own，再更新 npm 管理工具和桌面程序。配置与对话保存在 ~/Library/Application Support/codex-own-independent。
@@ -104,70 +130,88 @@ npm install --global --prefix "$HOME/.local" @petercjl/codex-own@latest
 
 ## 在 Windows 上通过 PowerShell 安装和测试
 
-适用于运行 x64 Node.js 的 Windows。先从 Node.js 官网安装 Windows x64 的 LTS 版本（要求 Node.js 22 或以上，包含 npm），再重新打开普通用户 PowerShell。建议预留 10 GB 空间，用于下载、解压和备份。
-
-[Node.js 官方下载](https://nodejs.org/en/download)
+适用于 Windows x64，使用包含 npm 的官方 Node.js 22+ x64 发行包。可使用系统安装或用户目录的官方便携版。先核对实际 node.exe 位置；多套 Node、第三方 Agent 便携 Node 和 npm 的 .cmd 入口可能选择不同运行时。
 
-安装验收只需完成前三步。无需 Agent、API Key 或模型登录。
+**下列 $node 使用常见安装路径。请按实际 Node 安装位置修改后执行。** 普通用户 PowerShell 即可，无需改变脚本执行策略。建议首次安装预留至少 10 GB；更新还需保留旧程序和用户数据快照所需空间。
 
-第一步：检查环境并安装 npm 管理工具。使用 .cmd 入口，无需修改 PowerShell 脚本执行策略。逐段执行，每一步成功后再继续。
+第一步：在当前窗口设置 UTF-8，并检查真正执行安装的 Node 和 npm：
 
 ```powershell
-node --version
-node -p "process.arch"
-npm.cmd --version
-npm.cmd install --global @petercjl/codex-own@latest
+$ErrorActionPreference = "Stop"
+[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+$OutputEncoding = [Console]::OutputEncoding
+chcp.com 65001 > $null
+$node = "C:\Program Files\nodejs\node.exe"
+if (-not (Test-Path -LiteralPath $node -PathType Leaf)) { throw "请填写实际的 Node.js 22+ x64 可执行文件路径。" }
+$bootstrap = (& $node -p 'JSON.stringify({version:process.versions.node,arch:process.arch,executable:process.execPath})') | ConvertFrom-Json
+if ($LASTEXITCODE -ne 0 -or [int]($bootstrap.version.Split('.')[0]) -lt 22 -or $bootstrap.arch -ne "x64") { throw "安装引导要求 Node.js 22+ x64，请核对实际路径。" }
+$bootstrap | Format-List
+$npmCli = Join-Path (Split-Path -Parent $node) "node_modules\npm\bin\npm-cli.js"
+if (-not (Test-Path -LiteralPath $npmCli -PathType Leaf)) { throw "所选 Node 目录缺少 npm，请使用包含 npm 的官方 Node.js 发行包。" }
+& $node $npmCli --version
+if ($LASTEXITCODE -ne 0) { throw "npm 检查失败。" }
 ```
 
-process.arch 应输出 x64。第二步：解析命令路径并安装桌面程序。$codexOwn 只在当前窗口有效；打开新窗口后重新执行赋值行。
+第二步：通过同一个 Node 安装并调用管理工具：
 
 ```powershell
-$codexOwn = Join-Path (npm.cmd prefix --global) "codex-own.cmd"
-& $codexOwn install --yes
+& $node $npmCli install --global @petercjl/codex-own@latest --registry=https://registry.npmjs.org
+if ($LASTEXITCODE -ne 0) { throw "管理工具安装失败。" }
+$npmRoot = (& $node $npmCli root --global).Trim()
+if ($LASTEXITCODE -ne 0) { throw "无法取得 npm 全局目录。" }
+$codexOwn = Join-Path $npmRoot "@petercjl\codex-own\bin\codex-own.mjs"
+& $node $codexOwn install --yes --progress stdout
+if ($LASTEXITCODE -ne 0) { throw "桌面安装失败，请保留错误并先诊断。" }
 ```
 
-管理工具和桌面资源全部从 registry.npmjs.org 下载。Windows 桌面资源约 1 GB，具体大小随版本变化。最多并行下载 4 个分片，安装时显示分片编号、下载百分比和已接收大小，然后显示校验、解压、安装。看到“安装完成”和 ok: true 才表示完成。
-
-若已有手动安装的 codex-own，先退出应用，将第二步的安装命令替换为以下接管命令；原安装会被备份。
+第三步：验收结果。doctor 的 bootstrap 应指向所选 Node；installed 有版本，lock 为 false，pendingTransactions 为空；runtime doctor 验证独立 Node/npm/Python。先完成 API 配置，再从 Windows 开始菜单打开 codex-own。
 
 ```powershell
-& $codexOwn install --adopt --yes
+& $node $codexOwn doctor --json
+& $node $codexOwn version
+& $node $codexOwn runtime doctor
 ```
 
-第三步：检查安装结果。doctor 中 installed 应有版本、lock 为 false，pendingTransactions 为空；开始菜单出现 codex-own。仅检查安装时，configured: false 是正常状态。
+$node、$npmCli、$codexOwn 仅对当前窗口有效；换窗口后按前两步重新赋值。已有未受管理的独立安装可用 install --adopt --yes 接管并保留备份。程序位于 %LOCALAPPDATA%\Programs\codex-own\current，配置和对话位于 %LOCALAPPDATA%\codex-own-independent。
+
+**API Key 文件路径必须改为你实际下载的位置，不能直接复制占位路径。** 配置前先保存任务并退出 codex-own；已有可用配置可跳过。安装验收无需 API Key。
 
 ```powershell
-& $codexOwn doctor
-& $codexOwn version
+$apiKeyFile = "【填写 API Key 文件的实际完整路径】"
+if (-not (Test-Path -LiteralPath $apiKeyFile -PathType Leaf)) { throw "请先填写实际 Key 文件路径。" }
+Get-Process -Name "codex-own" -ErrorAction SilentlyContinue | Stop-Process -Force
+if (Get-Process -Name "codex-own" -ErrorAction SilentlyContinue) { throw "应用尚未完全退出。" }
+& $node $codexOwn configure --api-key-file $apiKeyFile --yes
+if ($LASTEXITCODE -ne 0) { throw "API 配置失败。" }
 ```
 
-程序目录：%LOCALAPPDATA%\Programs\codex-own\current。配置与对话目录：%LOCALAPPDATA%\codex-own-independent。二者独立于原版 Codex。
+日常优先使用应用内“更新”。需要手动更新时，退出应用，用同一 $node 和 $npmCli 更新 @petercjl/codex-own@latest，再执行 & $node $codexOwn update install --yes --progress stdout。保留配置与对话。
 
-安装测试通过后即可停止；账号配置和模型对话属于后续使用测试。
+## 安装失败与恢复
 
-可选：需要使用模型时，将只包含一行 DashScope API Key 的文件放到下载目录，命名为 codex-own-api-key.txt。配置前先退出应用，文件位置不同则修改路径；已有可用配置可跳过配置命令。
+安装器直接读取 TAR/PAX/gzip/ZIP 归档中的 Unicode 名称、类型、大小及内容 SHA256，核对解压结果，最多重试 3 次。UNPACK_INCOMPLETE/UNPACK_FAILED 提供缺失样例；持续缺失同一批 DLL 或脚本时检查安全软件拦截记录和可信来源，按设备安全策略处理，安装器不会关闭防护。正常和失败安装都尝试清理本次 staging，被占用目录会报告并保留，已校验分片缓存仍可复用。
+
+Windows 先查看诊断及恢复计划：
 
 ```powershell
-& $codexOwn configure --api-key-file "$HOME\Downloads\codex-own-api-key.txt" --yes
-& $codexOwn launch
+& $node $codexOwn doctor --json
+& $node $codexOwn repair plan
 ```
 
-以后更新：先退出 codex-own，再执行以下命令。更新保留独立配置和对话。
+确认 allowed: true 并同意回收失败安装的临时目录后：
 
 ```powershell
-npm.cmd install --global @petercjl/codex-own@latest
-$codexOwn = Join-Path (npm.cmd prefix --global) "codex-own.cmd"
-& $codexOwn update check
-& $codexOwn update install --yes
+& $node $codexOwn repair run --yes
+& $node $codexOwn doctor --json
 ```
 
-下载失败：连续 30 秒无数据会重试当前分片，最多 3 次。出现 DOWNLOAD_FAILED 时检查 npm 网络连接，再执行同一安装命令；已校验分片会复用。下载期间按 Ctrl+C 可以取消。遇到 BUSY 时先确认是否有另一安装进程，保留错误信息，不直接删除锁文件。
+Mac 使用 "$HOME/.local/bin/codex-own" doctor --json、repair plan 和 repair run --yes。恢复备份并移走确认死亡进程的 operation.lock，清理 inactive stage 和有所有权回执的 next 副本；保留应用、配置、密钥、对话、缓存及回滚。活动或未知锁、recovery.lock 和未完成事务需要维护者检查，不能通过删文件强行继续。
 
-npm 安装出现缓存 ENOENT 或缓存损坏提示时，先检查缓存，再重新安装 npm 工具：
+默认 stdout 仅为 JSON，进度走 stderr；--progress stdout 是交互终端显示模式，与 --json 互斥；--quiet 关闭进度。CLI 入口在加载管理器前验证 Node 22+。doctor.bootstrap 返回实际可执行路径、版本及架构。
 
-```powershell
-npm.cmd cache verify
-npm.cmd install --global @petercjl/codex-own@latest
-```
+可发送给 Agent：
+
+> 请检查 codex-own 的安装环境和失败残留，使用 @petercjl/codex-own 的恢复计划诊断，保留配置与对话。
 
-管理工具与桌面版本分别报告。API Key 和用户数据保存在 npm 包之外。更多命令见 `codex-own help`。
+> 请通过 @petercjl/codex-own 修复已确认可清理的安装残留，然后重试安装。

package/bin/codex-own.mjs

@@ -1,35 +1,5 @@
 #!/usr/bin/env node
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import {pkg,packageRoot,read,fail,paths,doctor,latest,state,install,launch,rollback,hash,rejectLinks,configure} from '../lib/manager.mjs';
-import {manifestFor} from '../lib/manager.mjs';
-import {installRuntime,runtimeDoctor,rollbackRuntime,runRuntime,toolEnv} from '../lib/tool-runtime.mjs';
-import {components} from '../lib/binding.mjs';
-const args=process.argv.slice(2),[command,sub]=args;
-const flag=n=>args.includes('--'+n),value=n=>{const i=args.indexOf('--'+n);return i<0?undefined:args[i+1];};
-const yes=()=>{if(!flag('yes'))fail('CONFIRMATION_REQUIRED','Mutating commands require --yes');};
-function toolSelectionGate(){const p=paths();if(!state(p))return;const file=path.join(p.target,process.platform==='darwin'?'Contents/Resources':'resources','own-updater','desktop-version.json'),meta=fs.existsSync(file)?read(file):null;if(meta?.updaterContract!==2||meta.runtimeContract!==1)fail('INCOMPATIBLE_BINDING','Upgrade the desktop to component contract 2 before independently changing its tools');}
-async function skill(){const source=path.join(packageRoot,'skills','codex-own');if(sub==='source')return {ok:true,source,version:pkg.version};const agent=value('agent')||'codex';if(!['codex','sealseek'].includes(agent))fail('UNSUPPORTED_AGENT',agent);const base=value('target-root')||(agent==='codex'?path.join(os.homedir(),'.codex','skills'):null);if(!base)fail('TARGET_REQUIRED','Provide the configured Agent skill root with --target-root');const dest=path.join(base,'codex-own'),marker=path.join(dest,'.codex-own-managed.json');rejectLinks(base);rejectLinks(dest);const exists=fs.existsSync(dest);const owned=exists&&fs.existsSync(marker)&&read(marker).package===pkg.name;const srcHash=hash(fs.readFileSync(path.join(source,'SKILL.md')));if(sub==='status')return {ok:true,source,destination:dest,installed:exists,managed:owned,current:owned&&hash(fs.readFileSync(path.join(dest,'SKILL.md')))===srcHash};if(!['install','update'].includes(sub))fail('INVALID_COMMAND','skill source/status/install/update');yes();if(exists&&!owned)fail('UNMANAGED_TARGET','Existing skill is not managed');let backup=null;if(exists){backup=dest+'.backup-'+Date.now();fs.cpSync(dest,backup,{recursive:true,force:false,errorOnExist:true});}fs.mkdirSync(dest,{recursive:true});const ui=path.join(dest,'agents','openai.yaml'),customUI=fs.existsSync(ui)?fs.readFileSync(ui):null;fs.cpSync(source,dest,{recursive:true});if(customUI)fs.writeFileSync(ui,customUI);fs.writeFileSync(marker,JSON.stringify({package:pkg.name,version:pkg.version,hash:srcHash}));if(hash(fs.readFileSync(path.join(dest,'SKILL.md')))!==srcHash)fail('VERIFY_FAILED','Skill copy mismatch');return {ok:true,source,destination:dest,backup,version:pkg.version};}
-async function main(){
- if(!command||command==='help'||command==='--help')return {commands:['version','capabilities','doctor','install --yes [--adopt]','configure --api-key-file <file> --yes','update check','update install --yes','runtime install|update|doctor|env|run|rollback','launch','rollback --restore-data --yes','skill source|status|install|update'],note:'Application data and private tools remain outside npm manager packages. Quit the app before desktop updates. Manager, desktop and tool runtime versions are reported separately.'};
- if(command==='version'||command==='--version')return {manager:pkg.version,desktop:state()?.version||null,desktopIdentity:state()?.desktop?.identity||null,runtime:toolEnv.active()?.version||null};
- if(command==='capabilities')return read(path.join(packageRoot,'capabilities.json'));
- if(command==='doctor')return {...doctor(),runtime:runtimeDoctor()};
- if(command==='runtime'){
-  if(sub==='doctor')return runtimeDoctor();
-  if(sub==='env'){const env=toolEnv.environment();if(!env)fail('RUNTIME_NOT_INSTALLED','Install private tools first');return {ok:true,contract:1,root:toolEnv.runtimeRoot(),environment:Object.fromEntries(Object.entries(env).filter(([k])=>['PATH','ZDOTDIR','BASH_ENV','CODEX_OWN_NODE','CODEX_OWN_PYTHON','CODEX_OWN_RUNTIME_VERSION','AGENT_WORKBENCH_NPM_CLI'].includes(k)||/^(NPM_CONFIG_|PYTHON|PIP_)/.test(k)))};}
-  if(sub==='run'){const i=args.indexOf('--');process.exitCode=runRuntime(i<0?args.slice(2):args.slice(i+1));return;}
-  if(sub==='install'||sub==='update'){yes();const m=await manifestFor(value('version')||await latest());if(toolEnv.active()?.version!==m.runtimes.version)toolSelectionGate();return installRuntime(m.runtimes,{selection:'user-update'});}
-  if(sub==='rollback'){yes();if(toolEnv.active()?.previous)toolSelectionGate();return rollbackRuntime();}
-  return {commands:['runtime install --yes','runtime update --yes','runtime doctor','runtime env','runtime run -- <node|npm|npx|python|python3|pip> [args]','runtime rollback --yes']};
- }
- if(command==='launch')return launch();
- if(command==='skill')return skill();
- if(command==='configure'){yes();return configure(value('api-key-file'));}
- if(command==='install'){yes();return install({adopt:flag('adopt'),version:value('version'),archive:value('archive'),manifest:value('manifest')?read(value('manifest')):undefined});}
- if(command==='update'){const v=await latest();if(sub==='check'){const m=await manifestFor(v),c=components(state(),m,paths().platform,toolEnv.active()?.version);return {ok:true,manager:pkg.version,desktop:state()?.version||null,available:v,...c,managerUpdate:pkg.version!==v,updateAvailable:c.desktopUpdate||c.runtimeUpdate};}if(sub==='install'){yes();return install({version:v});}}
- if(command==='rollback'){yes();return rollback({restoreData:flag('restore-data')});}
- fail('INVALID_COMMAND','See codex-own help');
-}
-try{const result=await main();if(result!==undefined){console.log(JSON.stringify(result,null,2));if(result.ok===false)process.exitCode=1;}}catch(e){console.error(JSON.stringify({ok:false,code:e.code||'OPERATION_FAILED',message:e.message}));process.exitCode=1;}
+// Check before importing modules that require supported Node.
+if(Number(process.versions.node.split('.')[0])<22){
+ console.error(JSON.stringify({ok:false,code:'NODE_VERSION_UNSUPPORTED',message:'codex-own 需要 Node.js 22 或以上，请核对入口实际使用的 Node。',nodeVersion:process.version,executable:process.execPath}));process.exitCode=1;
+}else await import('../lib/cli.mjs');

package/capabilities.json

@@ -6,6 +6,8 @@
     "configure",
     "update check",
     "update install",
+    "cleanup plan",
+    "cleanup run",
     "launch",
     "rollback",
     "doctor",
@@ -18,7 +20,9 @@
     "runtime doctor",
     "runtime env",
     "runtime run",
-    "runtime rollback"
+    "runtime rollback",
+    "repair plan",
+    "repair run"
   ],
   "platforms": {
     "darwin-arm64": "implemented",
@@ -27,6 +31,37 @@
   "dataPolicy": "independent external directories; preserve credentials and conversations",
   "updatePolicy": "desktop checks npm latest at startup and every six hours; explicit download and restart/install; pinned verified build; backup before switch; CLI remains available for recovery",
   "authentication": "npm install does not grant model access; existing independent credentials remain local",
+  "cleanupPolicy": {
+    "contract": 1,
+    "trigger": "owned main interface loaded and alive for 30 seconds; installed version and component identity must match",
+    "defaultCacheLimitMiB": 2048,
+    "rollbackCopies": 1,
+    "reclaims": [
+      "applied desktop archives",
+      "completed inactive helpers",
+      "superseded complete app/data backup pairs",
+      "least recently used unpinned blocks"
+    ],
+    "preserves": [
+      "live app and user data",
+      "private tool versions",
+      "latest complete rollback",
+      "pending/failed/unknown updates",
+      "active processes",
+      "manual recovery backups"
+    ],
+    "temporaryCacheExcess": "pending or unknown receipts pin required blocks; locked files remain available for inspection",
+    "diagnosticRecordsPerCategory": 20,
+    "preview": "cleanup plan",
+    "execute": "cleanup run --yes [--cache-limit-mib <0..16384>]",
+    "results": [
+      "reclaimedBytes",
+      "rollbackRetained",
+      "warnings",
+      "cacheLimitExceeded",
+      "report"
+    ]
+  },
   "windowsAgentShell": {
     "contract": 1,
     "preferred": "verified system Git Bash; explicit exec_command shell selection",
@@ -103,5 +138,25 @@
     },
     "sameDesktop": "zero desktop download and activation; app may remain open",
     "legacy": "one bridge desktop upgrade required before ordinary manager-only reuse"
+  },
+  "installationRecovery": {
+    "contract": 1,
+    "bootstrapMinimumNode": 22,
+    "diagnostics": [
+      "bootstrap",
+      "lockDetails",
+      "orphanStages",
+      "recoveryLock"
+    ],
+    "extractAttempts": 3,
+    "inventory": "direct Unicode TAR/PAX/gzip/ZIP inventory; entry types, sizes and SHA256; path/link safety; tar errors retained",
+    "failedStaging": "finally cleanup; occupied files reported",
+    "recovery": "explicit --yes; refuse live/unknown locks, active apps and incomplete transactions",
+    "progress": {
+      "default": "stderr; stdout JSON",
+      "human": "--progress stdout",
+      "quiet": "--quiet"
+    },
+    "runtimeSelectionBackupLimit": 20
   }
 }

package/lib/archive-inventory.mjs

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {list} from 'tar';
+import AdmZip from 'adm-zip';
+
+const unsafe=message=>Object.assign(new Error(message),{code:'UNSAFE_ARCHIVE'});
+const digest=data=>crypto.createHash('sha256').update(data).digest('hex');
+export function validateArchiveName(name){
+ if(typeof name!=='string'||!name||/^[a-zA-Z]:|^\/|^\\|[\0\r\n]/.test(name)||name.replaceAll('\\','/').split('/').includes('..'))throw unsafe('Unsafe archive entry');
+}
+// Parse archive bytes rather than Windows tar's locale-dependent console text.
+// Inventory hashes also detect truncated or silently modified extracted files.
+export function archiveInventory(file){
+ const fd=fs.openSync(file,'r'),magic=Buffer.alloc(4);try{fs.readSync(fd,magic,0,4,0);}finally{fs.closeSync(fd);}
+ const result=[];let total=0;
+ function add(entry){validateArchiveName(entry.name);if(!Number.isSafeInteger(entry.size)||entry.size<0||entry.size>8*1024**3||result.length>=200000||(total+=entry.size)>32*1024**3)throw unsafe('Excessive archive inventory');result.push(entry);return entry;}
+ if(magic.readUInt32LE(0)===0x04034b50||magic.readUInt32LE(0)===0x06054b50){
+  if(fs.statSync(file).size>128*1024**2)throw unsafe('Runtime ZIP exceeds supported size');
+  for(const e of new AdmZip(file).getEntries()){
+   const link=((e.header.attr>>>16)&0xf000)===0xa000,type=e.isDirectory?'Directory':link?'SymbolicLink':'File';
+   const item=add({name:e.entryName,type,size:e.header.size});
+   if(type==='File')item.sha256=digest(e.getData());else if(link)item.link=e.getData().toString('utf8');
+  }
+ }else{
+  list({file,sync:true,strict:true,preservePaths:true,onReadEntry:e=>{
+   if(['ExtendedHeader','GlobalExtendedHeader','NextFileHasLongPath','NextFileHasLongLinkpath'].includes(e.type))return;
+   if(!['File','OldFile','ContiguousFile','Directory','SymbolicLink','Link'].includes(e.type))throw unsafe('Unsupported archive entry type');
+   const item=add({name:e.path,type:e.type,size:e.size,link:e.linkpath});
+   if(['File','OldFile','ContiguousFile'].includes(e.type)){const hash=crypto.createHash('sha256');e.on('data',b=>hash.update(b));e.on('end',()=>{item.sha256=hash.digest('hex');});}
+  }});
+ }
+ if(!result.length)throw unsafe('Empty archive');
+ for(const e of result){if(['File','OldFile','ContiguousFile'].includes(e.type)&&!e.sha256)throw unsafe('Incomplete archive content');if(e.link){if(/^[a-zA-Z]:|^\/|^\\|[\0\r\n]/.test(e.link))throw unsafe('Unsafe archive link');const base=e.type==='Link'?'':path.posix.dirname(e.name.replaceAll('\\','/'));const normalized=path.posix.normalize(path.posix.join(base,e.link.replaceAll('\\','/')));if(normalized==='..'||normalized.startsWith('../'))throw unsafe('Escaping archive link');}}
+ return result;
+}
+export function extractedHash(file){
+ const hash=crypto.createHash('sha256'),buffer=Buffer.allocUnsafe(256*1024),fd=fs.openSync(file,'r');
+ try{let count;while((count=fs.readSync(fd,buffer,0,buffer.length,null))>0)hash.update(buffer.subarray(0,count));return hash.digest('hex');}finally{fs.closeSync(fd);}
+}

package/lib/cleanup.mjs

@@ -0,0 +1,177 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+import {paths,state,locked,rejectLinks,exclusive,appIdentity,validateManifest,fail} from './manager.mjs';
+
+export const CLEANUP_POLICY=Object.freeze({contract:1,cacheLimitBytes:2*1024**3,rollbackCopies:1,reportLimit:20,healthyStartupSeconds:30});
+const PACKAGE='@petercjl/codex-own',UUID='[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}';
+const json=file=>{rejectLinks(file);try{return JSON.parse(fs.readFileSync(file,'utf8'));}catch{return null;}};
+const norm=file=>process.platform==='win32'?path.resolve(file).toLowerCase():path.resolve(file);
+const same=(a,b)=>typeof a==='string'&&typeof b==='string'&&norm(a)===norm(b);
+const contains=(base,file)=>same(base,file)||norm(file).startsWith(norm(base)+path.sep);
+const version=v=>/^\d+\.\d+\.\d+$/.test(v||'');
+function notNewer(a,b){if(!version(a)||!version(b))return false;const aa=a.split('.').map(Number),bb=b.split('.').map(Number);for(let i=0;i<3;i++){if(aa[i]!==bb[i])return aa[i]<bb[i];}return true;}
+function exists(file){return fs.existsSync(file);}
+function regular(file){rejectLinks(file);return exists(file)&&fs.lstatSync(file).isFile();}
+function names(dir){rejectLinks(dir);return exists(dir)?fs.readdirSync(dir):[];}
+function bytes(file){const s=fs.lstatSync(file);if(s.isSymbolicLink())return s.size;if(s.isDirectory())return fs.readdirSync(file).reduce((n,name)=>n+bytes(path.join(file,name)),0);return s.size;}
+function fingerprint(file){const s=fs.lstatSync(file);return {size:s.size,mtimeMs:s.mtimeMs,ino:s.ino};}
+function unchanged(file,expected){try{const s=fingerprint(file);return s.size===expected.size&&s.mtimeMs===expected.mtimeMs&&s.ino===expected.ino;}catch{return false;}}
+function currentInstall(p,identify){
+  rejectLinks(p.manager);rejectLinks(p.target);
+  regular(path.join(p.manager,'state.json'));
+  const s=state(p),meta=path.join(p.target,p.platform.startsWith('darwin-')?'Contents/Resources':'resources','own-updater','desktop-version.json');
+  if(s?.identity!=='local.codex-own'||!same(s.target,p.target)||!version(s.version)||!s.desktop||!/^[a-f0-9]{64}$/.test(s.desktop.identity)||s.desktop.identity!==s.releaseManifest?.platforms?.[p.platform]?.sha256||identify(p.target)!=='local.codex-own'||json(meta)?.version!==s.version)
+    fail('UNMANAGED_TARGET','Cleanup requires the matching managed desktop and component identity');
+  return s;
+}
+function pendingTransactions(p){return names(p.manager).filter(n=>new RegExp('^transaction-'+UUID+'\\.json$').test(n)&&json(path.join(p.manager,n.replace('.json','.complete.json')))?.ok!==true);}
+function healthFor(p,s){
+  const root=path.join(p.manager,'health');
+  return names(root).filter(n=>new RegExp('^startup-'+UUID+'\\.json$').test(n)).map(n=>({file:path.join(root,n),value:json(path.join(root,n))})).filter(({value:h})=>h?.schema===1&&h.package===PACKAGE&&h.version===s.version&&h.desktopIdentity===s.desktop.identity&&same(h.target,p.target)).sort((a,b)=>String(b.value.readyAt).localeCompare(String(a.value.readyAt)))[0]||null;
+}
+
+// Only return matched owned roots, never persist unrelated process arguments.
+export function activeCleanupRoots(roots){
+  if(!roots.length)return [];
+  if(process.platform==='win32'){
+    const quoted=roots.map(r=>"'"+r.replaceAll("'","''")+"'").join(',');
+    const ps=`$ErrorActionPreference='Stop';$ProgressPreference='SilentlyContinue';[Console]::OutputEncoding=[Text.UTF8Encoding]::new($false);$roots=@(${quoted});@(Get-CimInstance Win32_Process | ForEach-Object { $f=$_.ExecutablePath;$c=$_.CommandLine; foreach($r in $roots){$prefix=$r+'\\';if(($f -and ($f.Equals($r,[StringComparison]::OrdinalIgnoreCase) -or $f.StartsWith($prefix,[StringComparison]::OrdinalIgnoreCase))) -or ($c -and ($c.IndexOf($prefix,[StringComparison]::OrdinalIgnoreCase) -ge 0))){$r}} }) | ConvertTo-Json -Compress`;
+    const text=execFileSync('powershell.exe',['-NoProfile','-NonInteractive','-EncodedCommand',Buffer.from(ps,'utf16le').toString('base64')],{encoding:'utf8',windowsHide:true,timeout:30000});
+    const result=text.trim()?JSON.parse(text):[];return [...new Set(Array.isArray(result)?result:[result])];
+  }
+  const lines=execFileSync('ps',['-axo','command='],{encoding:'utf8',timeout:10000}).split('\n');
+  return roots.filter(r=>lines.some(line=>line.includes(r+path.sep)));
+}
+function manifestParts(m,platform){
+  validateManifest(m,platform);
+  return [m.platforms[platform],...Object.values(m.runtimes?.platforms?.[platform]||{})].flatMap(a=>a.parts||[]).map(a=>a.sha256);
+}
+function helperResult(dir,p){
+  const runtime=path.join(dir,'runtime'),meta=json(path.join(runtime,'desktop-version.json')),ready=json(path.join(runtime,'handoff-ready.json'));
+  if(meta?.source!=='https://registry.npmjs.org/@petercjl%2fcodex-own/latest'||meta.updaterContract!==2||!ready?.ready)return null;
+  if(ready.schema===2){
+    if(!Number.isSafeInteger(ready.pid)||ready.pid<1||ready.current!==meta.version||!new RegExp('^update-result-'+UUID+'\\.json$').test(path.basename(ready.resultFile||''))||!same(path.dirname(ready.resultFile),p.manager))return null;
+    try{process.kill(ready.pid,0);return null;}catch(e){if(e.code!=='ESRCH')return null;}
+    if(typeof ready.receipt!=='string'||path.basename(ready.receipt)!=='receipt.json'||!/^update-[a-zA-Z0-9]+$/.test(path.basename(path.dirname(ready.receipt)))||!same(path.dirname(path.dirname(ready.receipt)),path.join(p.manager,'prepared')))return null;
+    const result=json(ready.resultFile),receipt=json(ready.receipt),applied=json(ready.receipt+'.applied.json');
+    return result?.version===receipt?.version&&applied?.ok===true&&applied.version===receipt?.version?result:null;
+  }
+  // Legacy helpers have no PID/result receipt. A completed log plus an owned
+  // executable-process scan is required before reclaiming their copied runtime.
+  const log=path.join(dir,'install.log');if(!regular(log))return null;
+  const fd=fs.openSync(log,'r'),size=fs.fstatSync(fd).size,b=Buffer.alloc(Math.min(size,131072));
+  try{fs.readSync(fd,b,0,b.length,Math.max(0,size-b.length));}finally{fs.closeSync(fd);}
+  for(const line of b.toString('utf8').split('\n').reverse()){try{const r=JSON.parse(line).result;if(r)return r;}catch{}}
+  return null;
+}
+
+export function planCleanup({p=paths(),cacheLimitBytes=CLEANUP_POLICY.cacheLimitBytes,identify=appIdentity,processRoots=activeCleanupRoots,lockHeld=false}={}){
+  if(!Number.isSafeInteger(cacheLimitBytes)||cacheLimitBytes<0||cacheLimitBytes>16*1024**3)fail('INVALID_ARGUMENT','Cache limit must be between 0 and 16 GiB');
+  const result={ok:true,contract:1,version:null,cacheLimitBytes,actions:[],preserved:[],plannedBytes:0};
+  const defer=reason=>({...result,actions:[],plannedBytes:0,deferred:true,reason});
+  if(!lockHeld&&exists(path.join(p.manager,'operation.lock')))return defer('BUSY');
+  let s;try{s=currentInstall(p,identify);}catch(e){if(e.code==='UNSAFE_PATH')throw e;return defer('UNMANAGED_TARGET');}result.version=s.version;
+  if(pendingTransactions(p).length)return defer('INCOMPLETE_TRANSACTION');
+  const health=healthFor(p,s);if(!health)return defer('HEALTH_NOT_CONFIRMED');
+  if(s.previous){
+    const id=typeof s.previous.app==='string'?path.basename(s.previous.app).match(new RegExp('^\\.codex-own-backup-('+UUID+')$'))?.[1]:null;
+    if(!id||!same(s.previous.app,path.join(path.dirname(p.target),'.codex-own-backup-'+id))||!same(s.previous.data,path.join(p.manager,'backups',id,'data')))return defer('UNKNOWN_ROLLBACK');
+    rejectLinks(s.previous.app);rejectLinks(s.previous.data);
+    const j=json(path.join(p.manager,'transaction-'+id+'.json')),done=json(path.join(p.manager,'transaction-'+id+'.complete.json'));
+    if(done?.ok!==true||j?.version!==s.version||!same(j?.target,p.target)||!same(j?.old,s.previous.app)||!same(j?.backup,path.dirname(s.previous.data)))return defer('ROLLBACK_INCOMPLETE');
+    if(!exists(s.previous.app)||!exists(s.previous.data)||identify(s.previous.app)!=='local.codex-own')return defer('ROLLBACK_INCOMPLETE');
+  }
+  result.rollbackRetained=!!s.previous;
+  const protectedPaths=[p.target,p.core,p.desktop,s.previous?.app,s.previous?.data].filter(Boolean);
+  const protects=f=>protectedPaths.some(q=>contains(f,q)||contains(q,f));
+  const action=(kind,files,reason)=>{for(const f of files){rejectLinks(f);if(protects(f))fail('UNSAFE_PATH','Cleanup candidate intersects protected application data');}result.actions.push({kind,files,reason,bytes:files.reduce((n,f)=>n+bytes(f),0),fingerprints:files.map(fingerprint)});};
+  const pinned=new Set();let pinAll=false;
+  const prepared=path.join(p.manager,'prepared');
+  for(const name of names(prepared)){
+    if(!/^update-[a-zA-Z0-9]+$/.test(name))continue;
+    const dir=path.join(prepared,name),receipt=path.join(dir,'receipt.json');rejectLinks(dir);
+    const r=regular(receipt)?json(receipt):null,applied=regular(receipt+'.applied.json')?json(receipt+'.applied.json'):null;
+    let valid=false;
+    try{valid=!!r&&[1,2].includes(r.schema)&&r.platform===p.platform&&r.version===r.manifest?.version&&version(r.version);if(valid)manifestParts(r.manifest,p.platform);}catch{valid=false;}
+    const completed=valid&&applied?.ok===true&&applied.version===r.version&&notNewer(r.version,s.version);
+    if(!completed){
+      if(valid)for(const hash of manifestParts(r.manifest,p.platform))pinned.add(hash);else pinAll=true;
+      result.preserved.push({path:dir,reason:valid?'PENDING_OR_FAILED_UPDATE':'UNKNOWN_UPDATE_RECEIPT'});continue;
+    }
+    const archive=path.join(dir,'desktop.tar.gz');if(regular(archive))action('applied-archive',[archive],'APPLIED_UPDATE_AND_HEALTHY_DESKTOP');
+  }
+  const backups=[];
+  for(const name of names(p.manager)){
+    const match=name.match(new RegExp('^transaction-('+UUID+')\\.json$'));if(!match)continue;
+    const j=json(path.join(p.manager,name)),done=json(path.join(p.manager,name.replace('.json','.complete.json'))),id=match[1];
+    const old=path.join(path.dirname(p.target),'.codex-own-backup-'+id),backup=path.join(p.manager,'backups',id);
+    if(done?.ok!==true||!notNewer(j?.version,s.version)||!same(j?.target,p.target)||!same(j?.old,old)||!same(j?.backup,backup))continue;
+    const files=[old,backup].filter(exists);if(!files.length)continue;
+    if(files.some(protects)){result.preserved.push({path:backup,reason:'LATEST_COMPLETE_ROLLBACK'});continue;}
+    for(const f of files)rejectLinks(f);
+    let owned=true;try{if(exists(old))owned=identify(old)==='local.codex-own';}catch{owned=false;}
+    if(!owned){result.preserved.push({path:old,reason:'UNKNOWN_APP_IDENTITY'});continue;}
+    backups.push({old,files});
+  }
+  const handoffs=[];const helperBase=path.join(p.manager,'handoffs');
+  for(const name of names(helperBase)){
+    if(!/^apply-[a-zA-Z0-9]+$/.test(name))continue;
+    const dir=path.join(helperBase,name);rejectLinks(dir);const r=helperResult(dir,p);
+    if(r?.ok===true&&same(r.target,p.target)&&notNewer(r.version,s.version))handoffs.push(dir);
+    else result.preserved.push({path:dir,reason:'ACTIVE_FAILED_OR_UNKNOWN_HELPER'});
+  }
+  let active;try{active=processRoots([...backups.map(b=>b.old),...handoffs]);}catch{return defer('PROCESS_INSPECTION_UNAVAILABLE');}
+  for(const b of backups){if(active.some(a=>same(a,b.old))){result.preserved.push({path:b.old,reason:'ACTIVE_OLD_APP'});continue;}action('old-rollback',b.files,'SUPERSEDED_COMPLETE_TRANSACTION');}
+  for(const dir of handoffs){if(active.some(a=>same(a,dir))){result.preserved.push({path:dir,reason:'ACTIVE_UPDATE_HELPER'});continue;}action('completed-helper',[dir],'COMPLETED_HELPER_AND_HEALTHY_DESKTOP');}
+  const cache=path.join(p.manager,'npm-assets'),blocks=[];
+  for(const name of names(cache)){if(!/^[a-f0-9]{64}\.bin$/.test(name))continue;const f=path.join(cache,name);if(!regular(f))continue;const st=fs.statSync(f);blocks.push({file:f,hash:name.slice(0,64),bytes:st.size,used:st.mtimeMs});}
+  let total=blocks.reduce((n,b)=>n+b.bytes,0);result.cacheBytesBefore=total;
+  for(const b of blocks.sort((a,b)=>a.used-b.used||a.hash.localeCompare(b.hash))){
+    if(total<=cacheLimitBytes)break;if(pinAll||pinned.has(b.hash))continue;
+    action('cache-block',[b.file],'LEAST_RECENTLY_USED_UNPINNED_BLOCK');total-=b.bytes;
+  }
+  result.cacheBytesAfter=total;result.cacheLimitExceeded=total>cacheLimitBytes;result.cacheProtection=pinAll?'UNKNOWN_RECEIPT':pinned.size?'PENDING_UPDATE':null;
+  for(const [folder,prefix,keep] of [['cleanup-reports','report-',CLEANUP_POLICY.reportLimit-1],['cleanup-intents','intent-',CLEANUP_POLICY.reportLimit-1],['health','startup-',CLEANUP_POLICY.reportLimit]]){
+    const dir=path.join(p.manager,folder),records=names(dir).filter(n=>new RegExp('^'+prefix+UUID+'\\.json$').test(n)).map(n=>path.join(dir,n)).filter(regular).filter(f=>{const r=json(f);return r?.schema===1&&r.package===PACKAGE;}).sort((a,b)=>fs.statSync(b).mtimeMs-fs.statSync(a).mtimeMs);
+    for(const file of records.slice(keep))if(!same(file,health.file))action('old-report',[file],'BOUNDED_DIAGNOSTIC_HISTORY');
+  }
+  result.plannedBytes=result.actions.reduce((n,a)=>n+a.bytes,0);return result;
+}
+
+async function performCleanup(options){
+  const p=options.p||paths(),plan=planCleanup({...options,p,lockHeld:true});
+  if(plan.deferred)return {...plan,reclaimedBytes:0};
+  const intents=path.join(p.manager,'cleanup-intents');rejectLinks(intents);fs.mkdirSync(intents,{recursive:true,mode:0o700});
+  exclusive(path.join(intents,'intent-'+crypto.randomUUID()+'.json'),{schema:1,package:PACKAGE,version:plan.version,target:p.target,plannedAt:new Date().toISOString(),actions:plan.actions});
+  const removed=[],warnings=[];let reclaimedBytes=0;
+  for(const a of plan.actions){
+    for(let i=0;i<a.files.length;i++){
+      const file=a.files[i];let before;
+      try{
+        rejectLinks(file);if(!unchanged(file,a.fingerprints[i])){warnings.push({path:file,code:'CANDIDATE_CHANGED'});break;}
+        before=bytes(file);await fs.promises.rm(file,{recursive:true,maxRetries:2,retryDelay:100});reclaimedBytes+=before;removed.push({kind:a.kind,path:file,bytes:before});
+      }catch(e){let remaining;try{remaining=bytes(file);}catch{}if(Number.isSafeInteger(before)&&Number.isSafeInteger(remaining))reclaimedBytes+=Math.max(0,before-remaining);warnings.push({path:file,code:e.code||'CLEANUP_FAILED'});break;}
+    }
+  }
+  const cache=path.join(p.manager,'npm-assets'),cacheBytesAfter=names(cache).filter(n=>/^[a-f0-9]{64}\.bin$/.test(n)).map(n=>path.join(cache,n)).filter(regular).reduce((n,f)=>n+fs.statSync(f).size,0);
+  const result={schema:1,package:PACKAGE,ok:true,version:plan.version,completedAt:new Date().toISOString(),reclaimedBytes,removed,warnings,cacheLimitBytes:plan.cacheLimitBytes,cacheBytesAfter,cacheLimitExceeded:cacheBytesAfter>plan.cacheLimitBytes,cacheProtection:plan.cacheProtection,rollbackCopies:CLEANUP_POLICY.rollbackCopies,rollbackRetained:plan.rollbackRetained};
+  const dir=path.join(p.manager,'cleanup-reports');rejectLinks(dir);fs.mkdirSync(dir,{recursive:true,mode:0o700});
+  const report=path.join(dir,'report-'+crypto.randomUUID()+'.json');exclusive(report,result);
+  return {...result,report};
+}
+export async function runCleanup(options={}){const p=options.p||paths();return locked(p,()=>performCleanup({...options,p}));}
+
+// Called only by the desktop worker after the controller's main-window health
+// gate. A matching installed component is mandatory; spawning an app is not proof.
+export async function cleanupAfterHealthyStartup(current,options={}){
+  const p=options.p||paths(),identify=options.identify||appIdentity;
+  return locked(p,()=>{
+    const s=currentInstall(p,identify);if(s.version!==current)fail('INSTALLATION_CHANGED','The running desktop differs from its managed installation');
+    if(pendingTransactions(p).length)return {ok:true,deferred:true,reason:'INCOMPLETE_TRANSACTION',reclaimedBytes:0};
+    const dir=path.join(p.manager,'health');rejectLinks(dir);fs.mkdirSync(dir,{recursive:true,mode:0o700});
+    exclusive(path.join(dir,'startup-'+crypto.randomUUID()+'.json'),{schema:1,package:PACKAGE,version:current,target:p.target,desktopIdentity:s.desktop.identity,readyAt:new Date().toISOString(),evidence:'main-window-loaded-and-alive-30s'});
+    return performCleanup({...options,p});
+  });
+}

package/lib/cli.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import {pkg,packageRoot,read,fail,paths,doctor,latest,state,install,launch,rollback,hash,rejectLinks,configure} from '../lib/manager.mjs';
+import {manifestFor} from '../lib/manager.mjs';
+import {installRuntime,runtimeDoctor,rollbackRuntime,runRuntime,toolEnv} from '../lib/tool-runtime.mjs';
+import {components} from '../lib/binding.mjs';
+import {planCleanup,runCleanup} from '../lib/cleanup.mjs';
+import {repairPlan,repairRun} from './maintenance.mjs';
+import {setProgressMode} from './network.mjs';
+const args=process.argv.slice(2),[command,sub]=args;
+const flag=n=>args.includes('--'+n),value=n=>{const i=args.indexOf('--'+n);return i<0?undefined:args[i+1];};
+const yes=()=>{if(!flag('yes'))fail('CONFIRMATION_REQUIRED','Mutating commands require --yes');};
+function toolSelectionGate(){const p=paths();if(!state(p))return;const file=path.join(p.target,process.platform==='darwin'?'Contents/Resources':'resources','own-updater','desktop-version.json'),meta=fs.existsSync(file)?read(file):null;if(meta?.updaterContract!==2||meta.runtimeContract!==1)fail('INCOMPATIBLE_BINDING','Upgrade the desktop to component contract 2 before independently changing its tools');}
+async function skill(){const source=path.join(packageRoot,'skills','codex-own');if(sub==='source')return {ok:true,source,version:pkg.version};const agent=value('agent')||'codex';if(!['codex','sealseek'].includes(agent))fail('UNSUPPORTED_AGENT',agent);const base=value('target-root')||(agent==='codex'?path.join(os.homedir(),'.codex','skills'):null);if(!base)fail('TARGET_REQUIRED','Provide the configured Agent skill root with --target-root');const dest=path.join(base,'codex-own'),marker=path.join(dest,'.codex-own-managed.json');rejectLinks(base);rejectLinks(dest);const exists=fs.existsSync(dest);const owned=exists&&fs.existsSync(marker)&&read(marker).package===pkg.name;const srcHash=hash(fs.readFileSync(path.join(source,'SKILL.md')));if(sub==='status')return {ok:true,source,destination:dest,installed:exists,managed:owned,current:owned&&hash(fs.readFileSync(path.join(dest,'SKILL.md')))===srcHash};if(!['install','update'].includes(sub))fail('INVALID_COMMAND','skill source/status/install/update');yes();if(exists&&!owned)fail('UNMANAGED_TARGET','Existing skill is not managed');let backup=null;if(exists){backup=dest+'.backup-'+Date.now();fs.cpSync(dest,backup,{recursive:true,force:false,errorOnExist:true});}fs.mkdirSync(dest,{recursive:true});const ui=path.join(dest,'agents','openai.yaml'),customUI=fs.existsSync(ui)?fs.readFileSync(ui):null;fs.cpSync(source,dest,{recursive:true});if(customUI)fs.writeFileSync(ui,customUI);fs.writeFileSync(marker,JSON.stringify({package:pkg.name,version:pkg.version,hash:srcHash}));if(hash(fs.readFileSync(path.join(dest,'SKILL.md')))!==srcHash)fail('VERIFY_FAILED','Skill copy mismatch');return {ok:true,source,destination:dest,backup,version:pkg.version};}
+async function main(){
+ if(flag('progress')&&!value('progress'))fail('INVALID_ARGUMENT','Provide --progress stderr|stdout|quiet');
+ if(flag('json')&&value('progress')==='stdout')fail('INVALID_ARGUMENT','JSON mode requires progress on stderr or quiet');
+ setProgressMode(flag('quiet')?'quiet':value('progress')||'stderr');
+ if(command==='repair'){if(sub==='plan')return repairPlan();if(sub==='run'){yes();return repairRun();}fail('INVALID_COMMAND','repair plan or repair run --yes');}
+ if(!command||command==='help'||command==='--help')return {commands:['version','capabilities','doctor','repair plan','repair run --yes','install --yes [--adopt]','configure --api-key-file <file> --yes','update check','update install --yes','cleanup plan [--cache-limit-mib <0..16384>]','cleanup run --yes [--cache-limit-mib <0..16384>]','runtime install|update|doctor|env|run|rollback','launch','rollback --restore-data --yes','skill source|status|install|update'],note:'Node >=22; doctor.bootstrap reports the actual executable. Default stdout is JSON; --progress stdout is for human terminals; --quiet disables progress. Repair preserves application/user data and refuses active or incomplete transactions.'};
+ if(command==='version'||command==='--version')return {manager:pkg.version,desktop:state()?.version||null,desktopIdentity:state()?.desktop?.identity||null,runtime:toolEnv.active()?.version||null};
+ if(command==='capabilities')return read(path.join(packageRoot,'capabilities.json'));
+ if(command==='doctor')return {...doctor(),runtime:runtimeDoctor()};
+ if(command==='cleanup'){
+  const limit=value('cache-limit-mib'),options={};if(flag('cache-limit-mib')&&limit===undefined)fail('INVALID_ARGUMENT','Provide --cache-limit-mib <0..16384>');if(limit!==undefined){if(!/^\d+$/.test(limit)||Number(limit)>16384)fail('INVALID_ARGUMENT','Cache limit must be an integer from 0 to 16384 MiB');options.cacheLimitBytes=Number(limit)*1048576;}
+  if(sub==='plan')return planCleanup(options);
+  if(sub==='run'){yes();return runCleanup(options);}
+  fail('INVALID_COMMAND','cleanup plan or cleanup run --yes');
+ }
+ if(command==='runtime'){
+  if(sub==='doctor')return runtimeDoctor();
+  if(sub==='env'){const env=toolEnv.environment();if(!env)fail('RUNTIME_NOT_INSTALLED','Install private tools first');return {ok:true,contract:1,root:toolEnv.runtimeRoot(),environment:Object.fromEntries(Object.entries(env).filter(([k])=>['PATH','ZDOTDIR','BASH_ENV','CODEX_OWN_NODE','CODEX_OWN_PYTHON','CODEX_OWN_RUNTIME_VERSION','AGENT_WORKBENCH_NPM_CLI'].includes(k)||/^(NPM_CONFIG_|PYTHON|PIP_)/.test(k)))};}
+  if(sub==='run'){const i=args.indexOf('--');process.exitCode=runRuntime(i<0?args.slice(2):args.slice(i+1));return;}
+  if(sub==='install'||sub==='update'){yes();const m=await manifestFor(value('version')||await latest());if(toolEnv.active()?.version!==m.runtimes.version)toolSelectionGate();return installRuntime(m.runtimes,{selection:'user-update'});}
+  if(sub==='rollback'){yes();if(toolEnv.active()?.previous)toolSelectionGate();return rollbackRuntime();}
+  return {commands:['runtime install --yes','runtime update --yes','runtime doctor','runtime env','runtime run -- <node|npm|npx|python|python3|pip> [args]','runtime rollback --yes']};
+ }
+ if(command==='launch')return launch();
+ if(command==='skill')return skill();
+ if(command==='configure'){yes();return configure(value('api-key-file'));}
+ if(command==='install'){yes();return install({adopt:flag('adopt'),version:value('version'),archive:value('archive'),manifest:value('manifest')?read(value('manifest')):undefined});}
+ if(command==='update'){const v=await latest();if(sub==='check'){const m=await manifestFor(v),c=components(state(),m,paths().platform,toolEnv.active()?.version);return {ok:true,manager:pkg.version,desktop:state()?.version||null,available:v,...c,managerUpdate:pkg.version!==v,updateAvailable:c.desktopUpdate||c.runtimeUpdate};}if(sub==='install'){yes();return install({version:v});}}
+ if(command==='rollback'){yes();return rollback({restoreData:flag('restore-data')});}
+ fail('INVALID_COMMAND','See codex-own help');
+}
+try{const result=await main();if(result!==undefined){console.log(JSON.stringify(result,null,2));if(result.ok===false)process.exitCode=1;}}catch(e){console.error(JSON.stringify({ok:false,code:e.code||'OPERATION_FAILED',message:e.message,...Object.fromEntries(['missing','missingCount','stage','partialTarget','tarExit'].filter(k=>e[k]!==undefined).map(k=>[k,e[k]]))}));process.exitCode=1;}