@petercjl/codex-own 0.6.4 → 0.6.5

package/README.md

@@ -101,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。
@@ -118,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 空间，用于下载、解压和备份。
+适用于 Windows x64，使用包含 npm 的官方 Node.js 22+ x64 发行包。可使用系统安装或用户目录的官方便携版。先核对实际 node.exe 位置；多套 Node、第三方 Agent 便携 Node 和 npm 的 .cmd 入口可能选择不同运行时。
 
-[Node.js 官方下载](https://nodejs.org/en/download)
-
-安装验收只需完成前三步。无需 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。保留配置与对话。
+
+## 安装失败与恢复
 
-安装测试通过后即可停止；账号配置和模型对话属于后续使用测试。
+安装器直接读取 TAR/PAX/gzip/ZIP 归档中的 Unicode 名称、类型、大小及内容 SHA256，核对解压结果，最多重试 3 次。UNPACK_INCOMPLETE/UNPACK_FAILED 提供缺失样例；持续缺失同一批 DLL 或脚本时检查安全软件拦截记录和可信来源，按设备安全策略处理，安装器不会关闭防护。正常和失败安装都尝试清理本次 staging，被占用目录会报告并保留，已校验分片缓存仍可复用。
 
-可选：需要使用模型时，将只包含一行 DashScope API Key 的文件放到下载目录，命名为 codex-own-api-key.txt。配置前先退出应用，文件位置不同则修改路径；已有可用配置可跳过配置命令。
+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,42 +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';
-import {planCleanup,runCleanup} from '../lib/cleanup.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','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:'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==='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}));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

@@ -20,7 +20,9 @@
     "runtime doctor",
     "runtime env",
     "runtime run",
-    "runtime rollback"
+    "runtime rollback",
+    "repair plan",
+    "repair run"
   ],
   "platforms": {
     "darwin-arm64": "implemented",
@@ -34,13 +36,31 @@
     "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"],
+    "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"]
+    "results": [
+      "reclaimedBytes",
+      "rollbackRetained",
+      "warnings",
+      "cacheLimitExceeded",
+      "report"
+    ]
   },
   "windowsAgentShell": {
     "contract": 1,
@@ -118,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/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;}

package/lib/extraction.mjs

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {execFileSync} from 'node:child_process';
+import {archiveInventory,validateArchiveName,extractedHash} from './archive-inventory.mjs';
+
+const error=(code,message,extra={})=>Object.assign(new Error(message),{code,...extra});
+export function archiveNames(text){
+ const names=text.split('\n').map(n=>n.replace(/\r$/,'')).filter(Boolean);
+ if(!names.length||names.length>200000)throw error('UNSAFE_ARCHIVE','Empty or excessive archive inventory');
+ for(const n of names){const normalized=n.replaceAll('\\','/');if(/^[a-zA-Z]:|^\/|^\\|[\0\r\n]/.test(n)||normalized.split('/').includes('..'))throw error('UNSAFE_ARCHIVE','Unsafe archive entry');}
+ return [...new Set(names)];
+}
+function inspectTree(root){
+ function walk(dir){for(const x of fs.readdirSync(dir,{withFileTypes:true})){
+  const f=path.join(dir,x.name),s=fs.lstatSync(f);
+  if(s.isSymbolicLink()){const link=fs.readlinkSync(f),resolved=path.resolve(path.dirname(f),link);if(path.isAbsolute(link)||!resolved.startsWith(root+path.sep))throw error('UNSAFE_ARCHIVE','Escaping archive symlink');}
+  else if(s.isDirectory())walk(f);else if(!s.isFile())throw error('UNSAFE_ARCHIVE','Unsupported archive file type');
+ }}walk(root);
+}
+export function extractChecked(archive,dest,{tar,attempts=3,report=()=>{},inventory=archiveInventory,execute=execFileSync,delay=ms=>Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),0,0,ms)}={}){
+ if(!Number.isInteger(attempts)||attempts<1||attempts>3)throw error('INVALID_ARGUMENT','Extraction attempts must be 1..3');
+ const cwd=path.dirname(path.resolve(archive)),source=path.basename(archive),root=path.resolve(dest),target=path.relative(cwd,root);
+ const entries=inventory(archive);for(const e of entries)validateArchiveName(e.name);const names=entries.map(e=>e.name);
+ fs.mkdirSync(root);let missing=names,lastError;
+ const absent=()=>entries.filter(e=>{try{const file=path.join(root,e.name),s=fs.lstatSync(file);if(e.type==='Directory')return !s.isDirectory();if(e.type==='SymbolicLink')return !s.isSymbolicLink()||e.link!==undefined&&fs.readlinkSync(file)!==e.link;if(!s.isFile())return true;return e.size!==undefined&&e.type!=='Link'&&s.size!==e.size||!!e.sha256&&extractedHash(file)!==e.sha256;}catch(e){if(['ENOENT','ENOTDIR','EPERM','EBUSY','EACCES'].includes(e.code))return true;throw e;}}).map(e=>e.name);
+ for(let attempt=1;attempt<=attempts;attempt++){
+  // A previous partial extraction must not provide an escaping link for retry.
+  inspectTree(root);
+  try{
+   if(attempt===1||!missing.length||missing.length>32||missing.some(n=>/[^\x20-\x7e]/.test(n)))execute(tar,['-xf',source,'-C',target],{cwd,stdio:'pipe'});
+   else{
+    // One entry at a time also keeps Windows argv bounded for long inventories.
+    for(const n of missing)execute(tar,['-xf',source,'-C',target,'--',n],{cwd,stdio:'pipe'});
+   }
+   lastError=null;
+  }catch(e){lastError=e;}
+  inspectTree(root);report('正在核对解压文件大小与内容校验和');missing=absent();
+  if(!missing.length&&!lastError)return {entries:names.length,attempts:attempt};
+  if(attempt<attempts){report(`解压验证未完成：${missing.length} 项缺失或内容不符，重试 ${attempt}/${attempts-1}`);delay(attempt*500);}
+ }
+ throw error(missing.length?'UNPACK_INCOMPLETE':'UNPACK_FAILED',`解压验证失败，${missing.length} 项缺失或内容不符；可能被占用或被安全软件拦截。示例：${missing.slice(0,5).join(', ')||'tar 未正常退出'}`,{missing:missing.slice(0,30),missingCount:missing.length,stage:root,tarExit:lastError?.status??null});
+}

package/lib/file-operations.mjs

@@ -0,0 +1,22 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Reserve a new directory atomically, then copy its children. This avoids the
+// Windows Node 24.22 strict cp(existing empty directory) incompatibility while
+// still refusing an existing destination and every existing child.
+export function copyNewDirectory(source,target,{onCreate=()=>{},copy=fs.cpSync}={}){
+ fs.mkdirSync(target);
+ try{onCreate();for(const name of fs.readdirSync(source))copy(path.join(source,name),path.join(target,name),{recursive:true,force:false,errorOnExist:true,dereference:false,verbatimSymlinks:true});}
+ catch(e){try{removeNewTreeSync(target);}catch{e.partialTarget=target;}throw e;}
+}
+// Do not invoke native recursive rmSync: older Windows runtimes can terminate
+// the process on sharing violations instead of returning a JavaScript error.
+export function removeNewTreeSync(file){
+ const st=fs.lstatSync(file);
+ if(st.isDirectory()&&!st.isSymbolicLink()){for(const n of fs.readdirSync(file))removeNewTreeSync(path.join(file,n));fs.rmdirSync(file);}
+ else fs.unlinkSync(file);
+}
+export async function removeTemporary(file,{report=()=>{}}={}){
+ try{await fs.promises.rm(file,{recursive:true,force:true,maxRetries:3,retryDelay:200});return true;}
+ catch(e){report(`临时目录被占用，保留供 repair 检查：${file}`);return false;}
+}

package/lib/maintenance.mjs

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {paths,locked,rejectLinks,running,fail} from './manager.mjs';
+
+const uuid='[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}';
+function readJSON(f){try{return JSON.parse(fs.readFileSync(f,'utf8'));}catch{return null;}}
+export function lockStatus(p,{alive=pid=>{try{process.kill(pid,0);return true;}catch(e){return e.code==='ESRCH'?false:null;}}}={}){
+ const file=path.join(p.manager,'operation.lock');
+ if(!fs.existsSync(file))return {exists:false};
+ rejectLinks(file);const s=fs.statSync(file),v=readJSON(file),valid=Number.isSafeInteger(v?.pid)&&v.pid>0;
+ return {exists:true,pid:valid?v.pid:null,time:typeof v?.time==='string'?v.time:null,alive:valid?alive(v.pid):null,fingerprint:{ino:s.ino,size:s.size,mtimeMs:s.mtimeMs}};
+}
+export function incompleteTransactions(p){return fs.existsSync(p.manager)?fs.readdirSync(p.manager).filter(n=>/^transaction-.*\.json$/.test(n)&&!n.endsWith('.complete.json')&&!fs.existsSync(path.join(p.manager,n.replace('.json','.complete.json')))):[];}
+function size(file){const s=fs.lstatSync(file);if(s.isSymbolicLink())return s.size;if(s.isFile())return s.size;if(!s.isDirectory())return 0;return fs.readdirSync(file).reduce((n,x)=>n+size(path.join(file,x)),0);}
+export function temporaryStages(p){
+ const items=[];
+ for(const dir of [p.manager,path.join(p.root,'runtimes')]){
+  rejectLinks(dir);if(!fs.existsSync(dir))continue;
+  for(const n of fs.readdirSync(dir).filter(n=>/^stage-[A-Za-z0-9_-]+$/.test(n))){const f=path.join(dir,n);const st=fs.lstatSync(f);if(st.isDirectory()&&!st.isSymbolicLink())items.push({path:f,bytes:size(f),kind:'stage'});}
+ }
+ if(fs.existsSync(p.manager))for(const n of fs.readdirSync(p.manager).filter(n=>new RegExp('^temporary-'+uuid+'\\.json$').test(n))){
+  const receipt=path.join(p.manager,n);rejectLinks(receipt);const r=readJSON(receipt),id=n.slice(10,-5),expected=path.join(path.dirname(p.target),'.codex-own-next-'+id);
+  if(r?.package!=='@petercjl/codex-own'||r.kind!=='next'||r.path!==expected||r.target!==p.target||!fs.existsSync(expected))continue;
+  rejectLinks(expected);items.push({path:expected,bytes:size(expected),kind:'next',receipt});
+ }
+ return items;
+}
+export function repairPlan({p=paths(),isRunning=running}={}){
+ const lock=lockStatus(p),pending=incompleteTransactions(p),active=isRunning(p);
+ const reason=pending.length?'INCOMPLETE_TRANSACTION':active.length?'APP_RUNNING':lock.exists&&lock.alive!==false?'LOCK_OWNER_UNCERTAIN_OR_ALIVE':null;
+ return {ok:true,allowed:!reason,reason,lock,pendingTransactions:pending,orphanStages:temporaryStages(p),policy:'only inactive staging and receipted next copies; preserve applications, credentials, conversations, caches and rollback'};
+}
+export async function repairRun({p=paths(),isRunning=running}={}){
+ rejectLinks(p.root);fs.mkdirSync(p.manager,{recursive:true,mode:0o700});
+ const guard=path.join(p.manager,'recovery.lock');rejectLinks(guard);let fd;
+ try{fd=fs.openSync(guard,'wx',0o600);}catch{fail('BUSY','Another recovery is active; inspect recovery.lock before recovery');}
+ try{
+  fs.writeSync(fd,JSON.stringify({pid:process.pid,time:new Date().toISOString()}));const plan=repairPlan({p,isRunning});
+  if(!plan.allowed)fail(plan.reason,'Recovery is deferred; preserve the lock and transaction evidence');
+  let recoveredLock=null;
+  if(plan.lock.exists){const f=path.join(p.manager,'operation.lock'),now=lockStatus(p);if(JSON.stringify(now.fingerprint)!==JSON.stringify(plan.lock.fingerprint)||now.alive!==false)fail('BUSY','Lock changed during recovery');
+   recoveredLock=path.join(p.manager,'recovered-lock-'+crypto.randomUUID()+'.json');fs.renameSync(f,recoveredLock);
+  }
+  return await locked(p,async()=>{
+   const removed=[],warnings=[];let reclaimedBytes=0;
+   for(const item of temporaryStages(p)){
+    rejectLinks(item.path);try{await fs.promises.rm(item.path,{recursive:true,maxRetries:3,retryDelay:200});if(item.receipt)fs.unlinkSync(item.receipt);removed.push(item.path);reclaimedBytes+=item.bytes;}
+    catch(e){warnings.push({path:item.path,code:e.code||'CLEANUP_FAILED'});}
+   }
+   return {ok:true,recoveredLock,removed,reclaimedBytes,warnings};
+  },{recovery:true});
+ }finally{fs.closeSync(fd);fs.unlinkSync(guard);}
+}