@hellolynk-ai/codex-plugin 0.2.99 → 0.2.101

package/README.md

@@ -44,15 +44,26 @@ Windows 10/11、Node.js 22.16 或更高版本、PowerShell 7，以及打开过
 ## 安装
 
 1. 打开 [HelloLynk 官网（Official site）](https://hellolynk.com)。新用户注册账号；已有账号登录后，查看自己的公开灵信号。
-2. 在官网或 [GitHub Release](https://github.com/haoyun18881-beep/HelloLynk/releases) 下载 Codex 安装包，完整解压，在包含 `package` 文件夹的目录打开 PowerShell，运行：
+2. 两种装法任选一种。
+
+   用安装包，在官网或 [GitHub Release](https://github.com/haoyun18881-beep/HelloLynk/releases) 下载 Codex 安装包，完整解压，在包含 `package` 文件夹的目录打开 PowerShell，运行：
 
    ```powershell
    node .\package\bin\hellolynk-client-setup.mjs init
    ```
 
+   用 npm，在 PowerShell 运行：
+
+   ```powershell
+   npm install -g @hellolynk-ai/codex-plugin
+   hellolynk-codex init
+   ```
+
 3. 完全退出并重新打开 Codex。
 
-可以把本说明和解压目录交给你的本地 AI，请它帮你安装。
+可以把本说明交给你的本地 AI，请它帮你安装；用安装包时，把解压目录也告诉它。
+
+下文命令按安装包写法给出。用 npm 装的，把 `node .\package\bin\hellolynk-client-setup.mjs` 换成 `hellolynk-codex`，在任意目录运行。
 
 ## 首次连接
 
@@ -76,10 +87,14 @@ node .\package\bin\hellolynk-client-setup.mjs connect --hellolynk-id hellolynk:i
 node .\package\bin\hellolynk-client-setup.mjs setup
 ```
 
+用 npm 装的，先运行 `npm install -g @hellolynk-ai/codex-plugin` 装上新版，再运行 `hellolynk-codex setup`。
+
 ## 卸载
 
 在包含 `package` 文件夹的目录运行 `node .\package\bin\hellolynk-client-setup.mjs uninstall`。账号、联系人和聊天记录留在这台电脑上，重新安装后不用重新连接。
 
+用 npm 装的，运行 `hellolynk-codex uninstall`，再运行 `npm uninstall -g @hellolynk-ai/codex-plugin`。
+
 ## 求助
 
 运行 `node .\package\bin\hellolynk-client-setup.mjs doctor` 检查安装，把结果和错误码发到 [haoyun18881@gmail.com](mailto:haoyun18881@gmail.com)。

package/bin/hellolynk-client-setup.mjs

@@ -84,6 +84,13 @@ try {
   if (mutating) {
     await prepareFinalClientRoot(locations);
     installed = await installStablePackage({ packageClosure, sourceRelease, locations: packageLocations });
+    if (metadata.client === "codex") {
+      // The invoking updater can still be B255 code. Stop its old cleanup
+      // before switching the binding/cache to a release with process records.
+      const cleanup = await importStableCore(installed.packageRoot, "hellolynk-release-retention.mjs", "hellolynk_release_retention_unavailable");
+      await cleanup.protectRetentionReceipt({ releasesRoot: path.dirname(installed.packageRoot),
+        client: "codex", currentRelease: installed.packageRoot });
+    }
   }
   const activation = await inspectActivation(locations.hostRoot, metadata.profileId);
   // Both public install commands use the actual account state. Native recovery

package/hellolynk-client-pack-manifest.json

@@ -2,7 +2,7 @@
   "contract": "hellolynk-client-npm-pack-manifest-v1",
   "client": "codex",
   "packageName": "@hellolynk-ai/codex-plugin",
-  "version": "0.2.99",
+  "version": "0.2.101",
   "workbench": {
     "path": "plugins/hellolynk-codex/runtime/workbench/hellolynk-workbench-build.json",
     "contract": "hellolynk-shared-workbench-build-v1",
@@ -17,8 +17,8 @@
     },
     {
       "path": "bin/hellolynk-client-setup.mjs",
-      "bytes": 141259,
-      "sha256": "ab6ce9491d9b88856fdc0207b0df3230ed27642d9d206f52341a4f9791622a4e"
+      "bytes": 141769,
+      "sha256": "0bb0706c06bd193cfa37007dd95e3107b52aacb0a7ebaec2249b153ff7dd772b"
     },
     {
       "path": "bin/hellolynk-mcp-config-shape.mjs",
@@ -32,8 +32,8 @@
     },
     {
       "path": "package.json",
-      "bytes": 1712,
-      "sha256": "4d54dcd857f9731f3b7c3fcafc0f5ca2ac110c2290f83802757781e95bfd95ff"
+      "bytes": 1713,
+      "sha256": "3cd83c41e8536877505bf043a77b15fed01a0a7be18978c9835898fb690dfc8e"
     },
     {
       "path": "plugins/hellolynk-codex/.app.json",
@@ -42,8 +42,8 @@
     },
     {
       "path": "plugins/hellolynk-codex/.codex-plugin/plugin.json",
-      "bytes": 1668,
-      "sha256": "f021cc513415dc45e2921f0cc5fcd8675ea40dfc90db7d93710d8408ba3c90f9"
+      "bytes": 1669,
+      "sha256": "dfe2ede67b747c94a7485ecc6150286e3ac73f0fd1cae93357f473feae9ae5e3"
     },
     {
       "path": "plugins/hellolynk-codex/.mcp.json",
@@ -57,8 +57,8 @@
     },
     {
       "path": "plugins/hellolynk-codex/package.json",
-      "bytes": 1029,
-      "sha256": "a060c56c6d97f2874f64006807e66a4ab4d0bbd99fd237faa80d1ebc5955e2e3"
+      "bytes": 1030,
+      "sha256": "5875df8d4163c0a84b3dc30265b1a5e7b977a7c92250aae013d3b513b3640c40"
     },
     {
       "path": "plugins/hellolynk-codex/runtime/bootstrap/core/hellolynk-client-account.mjs",
@@ -267,8 +267,8 @@
     },
     {
       "path": "plugins/hellolynk-codex/runtime/core/hellolynk-native-addressing-tools.cjs",
-      "bytes": 19350,
-      "sha256": "252251de855c3fe9c5ebdd54a97ba976a8009f4ac57ec44f492bed8c7fb903de"
+      "bytes": 19443,
+      "sha256": "f4bd81b3d03277e28955a62409383a0c4072c6212567f71425df4e18ece75d63"
     },
     {
       "path": "plugins/hellolynk-codex/runtime/core/hellolynk-native-conversations.mjs",
@@ -318,7 +318,7 @@
     {
       "path": "plugins/hellolynk-codex/runtime/core/hellolynk-neutral-host-process.mjs",
       "bytes": 225161,
-      "sha256": "6d1913e3fb6e35d9a090afde39bf4a1521b17d1620fb09420e507d60af77cce4"
+      "sha256": "af6cb6585baae477f87ee880bd044dffb4c7f71667bfa78bcbf0d4d20e7483af"
     },
     {
       "path": "plugins/hellolynk-codex/runtime/core/hellolynk-neutral-host-store-adapters.mjs",
@@ -342,8 +342,8 @@
     },
     {
       "path": "plugins/hellolynk-codex/runtime/core/hellolynk-release-retention.mjs",
-      "bytes": 10547,
-      "sha256": "68321383ecf73adf55d842c7215f5e0b0fe72851aac292885740be99743e1bd0"
+      "bytes": 20624,
+      "sha256": "9b02a42a510fa5ef4a251b6e675f9ccc60f20b718d17c1617027cd048c5634dd"
     },
     {
       "path": "plugins/hellolynk-codex/runtime/core/hellolynk-runtime-safety.cjs",
@@ -378,12 +378,12 @@
     {
       "path": "plugins/hellolynk-codex/runtime/neutral-host-release-manifest.json",
       "bytes": 13440,
-      "sha256": "bea6d99eb2b763087ed2ffdf2f3d628ab3c0f0ccc28054cf4074a71afa454bf4"
+      "sha256": "5b035cb2d82e7543b801ca9d3b35a36e3f54a7b9aff9afcdf9f479926c537f56"
     },
     {
       "path": "plugins/hellolynk-codex/runtime/neutral-host-release-pin.json",
       "bytes": 146,
-      "sha256": "e96e1871fc4caa3b6a4fa35507fcbaf7a6ed4df7f9fb03bd33441fa6fd455f90"
+      "sha256": "af12ef2162ae5cddfda9707d919e4c7008478da434c581bcc26c8ed01738be11"
     },
     {
       "path": "plugins/hellolynk-codex/runtime/platform/windows/configure-agent.ps1",
@@ -552,8 +552,8 @@
     },
     {
       "path": "plugins/hellolynk-codex/server/codex-neutral-production.mjs",
-      "bytes": 26794,
-      "sha256": "34b865d80d7eb3c8e6986635b158c8583ddddb40bb528c4a75f0a498bdb3e1fb"
+      "bytes": 26960,
+      "sha256": "ffb8e689df1b600bcca85159af8d59f0fad819827f48ba9a218a63dfd7a3daa2"
     },
     {
       "path": "plugins/hellolynk-codex/server/mcp-proxy.mjs",
@@ -607,8 +607,8 @@
     },
     {
       "path": "README.md",
-      "bytes": 3924,
-      "sha256": "d0053d3ae14707103f701a05746690d3c1039cb9ab319d4f80f985f8f4a11478"
+      "bytes": 4536,
+      "sha256": "6876323b3a86b6cce25b84f6c49232553ca4f8b9abd0c12f595a9b3b971f4e76"
     },
     {
       "path": "tools/hellolynk-activate-neutral-host-clients.mjs",

package/hellolynk-client-pack-pin.json

@@ -1,4 +1,4 @@
 {
   "contract": "hellolynk-client-npm-pack-pin-v1",
-  "manifestSha256": "623db3dd1dcfe5697301668a2495752e0aad5007bad47dab542d7e35835a69f4"
+  "manifestSha256": "91fc0e4ecf1d6af962f1b81f193d2898f26f0d7dd71882990cd5b2b829c8e336"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hellolynk-ai/codex-plugin",
-  "version": "0.2.99",
+  "version": "0.2.101",
   "description": "HelloLynk Messaging for Codex: open conversations and let your AI message other people's AI assistants.",
   "homepage": "https://hellolynk.com",
   "repository": {

package/plugins/hellolynk-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "hellolynk-codex",
-  "version": "0.2.99",
+  "version": "0.2.101",
   "description": "HelloLynk 通讯、本地未读提醒与安全文字收发的 Codex 插件。",
   "author": {
     "name": "HelloLynk local project"

package/plugins/hellolynk-codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hellolynk-ai/codex-plugin",
-  "version": "0.2.99",
+  "version": "0.2.101",
   "private": true,
   "type": "module",
   "description": "Project-local HelloLynk Messaging, unread notification, and secure messaging plugin for Codex.",

package/plugins/hellolynk-codex/runtime/core/hellolynk-native-addressing-tools.cjs

@@ -18,7 +18,7 @@ const conversationGuidance = "HelloLynk 是本人授权的 AI 通讯。接着已
 // What every client shows for the shared tools; nativeTool applies it.
 const toolText = Object.freeze({
   hellolynk_reply_authorized_message: { title: "回复来信", description: "接着当前对话的一封来信发送；不接手其他对话。" },
-  hellolynk_send_authorized_message: { title: "发起通信", description: "向本人授权的联系人发起新通信。contact 填对方名字；本人点名了对话时，targetConversationTitle 填完整标题。接着已有来往用 hellolynk_reply_authorized_message。" },
+  hellolynk_send_authorized_message: { title: "发起通信", description: "向本人授权的联系人发起新通信。contact 填对方名字；本人点名了对话时，targetConversationTitle 填完整标题。未指定对话的新通信默认送到对方的 HelloLynk 独立会话；要继续已有来往，用 hellolynk_reply_authorized_message 回复原信。" },
   hellolynk_list_authorized_contacts: { title: "查找联系人", description: queryDescription },
   hellolynk_claim_message: { title: "读取来信", description: "按自动提醒里的 batchId 一次读取整批来信（合计不超过 2 万字）；手动读单条传 localMessageId 和 conversationKey。" },
   hellolynk_list_pending_messages: { title: "待处理来信", description: "列出当前对话等待 AI 处理的来信，不含正文。" },

package/plugins/hellolynk-codex/runtime/core/hellolynk-neutral-host-process.mjs

@@ -34,7 +34,7 @@ export const HELLOLYNK_NEUTRAL_HOST_PROCESS_CONTRACT = "hellolynk-neutral-host-p
 export const HELLOLYNK_NEUTRAL_HOST_DISCOVERY_CONTRACT = "hellolynk-neutral-host-discovery-v1";
 // Raised with every release batch, together with the six client versions. A Host reports it
 // in its health; the higher release stays and the lower one makes room.
-export const HELLOLYNK_HOST_RELEASE_ORDINAL = 10;
+export const HELLOLYNK_HOST_RELEASE_ORDINAL = 14;
 
 const INSTALLATION_LOCK_CONTRACT = "hellolynk-neutral-host-installation-lock-v2";
 const INSTALLATION_LOCK_MAX_BYTES = 4 * 1024;

package/plugins/hellolynk-codex/runtime/core/hellolynk-release-retention.mjs

@@ -7,9 +7,37 @@ import { promisify } from 'node:util';
 const execute = promisify(execFile);
 const clients = ['codex', 'openclaw', 'trae-work', 'workbuddy', 'dsh', 'claude-code'];
 const contract = 'hellolynk-release-retention-v1';
+// Claude starts every HelloLynk process through one stable copy of the entry, so
+// a command line never names the release that process loaded. The entry records
+// it under releases/.claude-code-processes/<pid>.json (see stable-entry.mjs).
+// Cleanup code from before these records reads only a v1 receipt and stops at
+// any other one before deleting, so a client with a stable entry keeps a v2
+// receipt: an older worker that cleans up after an update deletes nothing.
+const ENTRY = { 'claude-code': ['claude-code', 'hellolynk-claude-code.mjs'] };
+const contractWithEntry = 'hellolynk-release-retention-v2';
+// B255 workers understand v2 but do not read Codex process records.
+const codexContract = 'hellolynk-release-retention-v3';
+const PROCESS_CONTRACT = 'hellolynk-release-process-v1';
+const START_TOLERANCE_MS = 15000;
+export const releaseProcessDirectory = (releasesRoot, client) => path.join(releasesRoot, `.${client}-processes`);
 const failure = code => Object.assign(new Error(code), { code });
 const equal = (a, b) => process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
 
+// A cache MCP keeps an installed prepare function in memory. Record its most
+// recent successful binding, even when its command line names only the cache.
+// A checkout/uninstalled fixture has no immutable release to retain.
+export async function recordCodexReleaseProcess(packageRoot) {
+  if (process.platform !== 'win32' || !path.isAbsolute(packageRoot || '')
+    || path.basename(path.dirname(packageRoot)) !== 'releases' || !/^codex-[a-f0-9]{64}$/.test(path.basename(packageRoot))) return;
+  try {
+    const root = await rootPath(path.dirname(packageRoot));
+    const folder = releaseProcessDirectory(root, 'codex');
+    await fs.mkdir(folder, { recursive: true });
+    await writeReceipt(path.join(folder, `${process.pid}.json`), { contract: PROCESS_CONTRACT, pid: process.pid,
+      startedAt: Math.round(performance.timeOrigin), release: path.basename(packageRoot) });
+  } catch { /* A missing record defers cleanup; it must not stop communication. */ }
+}
+
 async function directory(target) {
   const stat = await fs.lstat(target);
   if (!stat.isDirectory() || stat.isSymbolicLink()) throw failure('release_retention_path_invalid');
@@ -56,6 +84,68 @@ export async function runningReleaseNames(releasesRoot) {
   return names;
 }
 
+// The given pids, this installation's stable entry, and Codex cache children:
+// pid, start time and whether it runs the entry. Only processes
+// with a positive pid are listed, and command lines never leave PowerShell.
+export async function entryProcessList(client, releasesRoot, pids = []) {
+  if (!ENTRY[client] && client !== 'codex') return [];
+  if (process.platform !== 'win32') throw failure('release_retention_process_check_unavailable');
+  if (!Array.isArray(pids) || pids.some(pid => !Number.isSafeInteger(pid) || pid <= 0)) throw failure('release_retention_process_check_invalid');
+  const root = await rootPath(releasesRoot);
+  // This installation's entry only, in its given and canonical spellings:
+  // any case, either slash, quoted or not.
+  const literal = value => value.split(/[\\/]+/).map(part => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('[\\\\/]+');
+  const entries = ENTRY[client] ? [...new Set([root, path.resolve(releasesRoot)])].map(value => literal(path.join(path.dirname(value), ...ENTRY[client]))) : [];
+  const pattern = (client === 'codex' ? '(?:^|["\\s\\\\/])(?:\\.[\\\\/])?server[\\\\/]mcp-proxy\\.mjs(?=["\\s]|$)'
+    : `(?<=^|["\\s])(?:${entries.join('|')})(?=["\\s]|$)`).replaceAll("'", "''");
+  // Relative cache entries do not reveal their installation. An older Codex
+  // child without a record conservatively delays this client's cleanup until
+  // it reconnects through a recording release or exits. Other Node apps do not.
+  const parentCheck = client === 'codex' ? "$_.Name -ieq 'node.exe' -and ($codexParents -contains $_.ParentProcessId) -and " : '';
+  const script = `$ErrorActionPreference='Stop'; $wanted=@(${pids.join(',')}); $epoch=[datetime]::new(1970,1,1,0,0,0,[DateTimeKind]::Utc); $all=@(Get-CimInstance Win32_Process); $codexParents=@($all | Where-Object { $_.Name -ieq 'Codex.exe' } | ForEach-Object { $_.ProcessId }); $list=@($all | Where-Object { $_.ProcessId -gt 0 } | ForEach-Object { $entry=[bool](${parentCheck}$_.CommandLine -and [regex]::IsMatch($_.CommandLine,'${pattern}','IgnoreCase')); if ($entry -or ($wanted -contains [int64]$_.ProcessId)) { [pscustomobject]@{ pid=[int64]$_.ProcessId; startedAt=$(if ($_.CreationDate) { [int64](($_.CreationDate.ToUniversalTime() - $epoch).TotalMilliseconds) } else { $null }); entry=$entry } } }); ConvertTo-Json -Compress -InputObject $list`;
+  const shell = path.join(process.env.SystemRoot || process.env.SYSTEMROOT || 'C:\\Windows', 'System32/WindowsPowerShell/v1.0/powershell.exe');
+  const { stdout } = await execute(shell, ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', script],
+    { windowsHide: true, timeout: 15000, maxBuffer: 1024 * 1024 });
+  const list = JSON.parse(stdout.replace(/^\uFEFF/, '').trim() || '[]');
+  if (!Array.isArray(list) || list.some(p => !Number.isSafeInteger(p?.pid) || p.pid <= 0 || typeof p.entry !== 'boolean'
+    || (p.startedAt !== null && !Number.isSafeInteger(p.startedAt)))) throw failure('release_retention_process_check_invalid');
+  return list;
+}
+
+// Releases named by live entry records, and whether a process started through
+// the stable entry has no matching record (one from before records existed).
+// Records of exited or reused pids are removed, so a release can go at the
+// next install once its last process is gone.
+async function entryReleases(releasesRoot, root, client, pattern, dependencies) {
+  if (!ENTRY[client] && client !== 'codex') return { names: [], unregistered: false };
+  const folder = releaseProcessDirectory(root, client);
+  let items = [];
+  try {
+    await directory(folder);
+    items = await fs.readdir(folder, { withFileTypes: true });
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const records = items.filter(item => item.isFile() && /^[1-9]\d{0,9}\.json$/.test(item.name))
+    .map(item => ({ pid: Number(item.name.slice(0, -5)), file: path.join(folder, item.name) }));
+  // The given root too: an entry may be named in the spelling the caller uses, not only the canonical one.
+  const processes = await (dependencies.entryProcesses || entryProcessList)(client, releasesRoot, records.map(record => record.pid));
+  const live = new Map(processes.map(p => [p.pid, p])), names = new Set(), registered = new Set();
+  let unregistered = false;
+  for (const { pid, file } of records) {
+    const alive = live.get(pid), started = Number.isSafeInteger(alive?.startedAt) ? alive.startedAt : null;
+    let record = null;
+    try { record = JSON.parse(await fs.readFile(file, 'utf8')); } catch {}
+    const valid = record?.contract === PROCESS_CONTRACT && record.pid === pid && Number.isSafeInteger(record.startedAt)
+      && typeof record.release === 'string' && pattern.test(record.release);
+    if (valid && started !== null && Math.abs(started - record.startedAt) <= START_TOLERANCE_MS) {
+      registered.add(pid); names.add(record.release);
+    } else if (!alive || (valid && started !== null)) {
+      await fs.rm(file, { force: true }).catch(() => {}); // Exited, or the pid now belongs to a later process.
+    } else unregistered = true; // Live, but its record is still being written or its start time is unknown.
+  }
+  if (processes.some(p => p.entry && !registered.has(p.pid))) unregistered = true;
+  return { names: [...names], unregistered };
+}
+
 // A stopped on-demand task is still a configuration reference. Keeping only
 // live processes can delete its executable before the next client startup.
 export async function configuredReleaseNames(releasesRoot) {
@@ -91,14 +181,7 @@ export async function pruneInstalledReleases({ releasesRoot, client, currentRele
     };
     const current = nameOf(currentRelease);
     const receiptPath = path.join(root, `.${client}-retention.json`);
-    let old = null;
-    try {
-      const stat = await fs.lstat(receiptPath);
-      if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 4096) throw failure('release_retention_receipt_invalid');
-      old = JSON.parse(await fs.readFile(receiptPath, 'utf8'));
-      if (old?.contract !== contract || old.client !== client || !pattern.test(old.current)
-        || old.previous !== null && !pattern.test(old.previous) || old.current === old.previous) throw failure('release_retention_receipt_invalid');
-    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const old = await readReceipt(receiptPath, client, pattern);
     const supplied = previousRelease === null ? null : nameOf(previousRelease);
     const previous = supplied && supplied !== current ? supplied
       : old?.current === current ? old.previous : old?.current || null;
@@ -106,21 +189,68 @@ export async function pruneInstalledReleases({ releasesRoot, client, currentRele
     for (const name of retained) await directory(path.join(root, name));
     const referenced = new Set([...referencedReleases.map(nameOf),
       ...await (dependencies.configuredReleases || configuredReleaseNames)(releasesRoot)]);
-    const running = new Set(await (dependencies.runningReleases || runningReleaseNames)(root));
+    const entry = await entryReleases(releasesRoot, root, client, pattern, dependencies);
+    const running = new Set([...await (dependencies.runningReleases || runningReleaseNames)(root), ...entry.names]);
     // Publish before deleting. An interrupted cleanup can retry the exact same
     // pair on same-version reinstall without accidentally dropping its backup.
-    const temporary = `${receiptPath}.${crypto.randomUUID()}.tmp`;
-    try {
-      await fs.writeFile(temporary, JSON.stringify({ contract, client, current, previous }) + '\n', { flag: 'wx', mode: 0o600 });
-      await fs.rename(temporary, receiptPath);
-    } finally { await fs.unlink(temporary).catch(e => { if (e.code !== 'ENOENT') throw e; }); }
+    await writeReceipt(receiptPath, { contract: receiptContract(client), client, current, previous });
     result.retained = retained;
-    await removeReleases(root, name => pattern.test(name) && !retained.includes(name), referenced, running, result, dependencies);
+    await removeReleases(root, name => pattern.test(name) && !retained.includes(name), referenced, running, result, dependencies, entry.unregistered);
     result.complete = result.deferred.length === 0;
   } catch (error) { result.error = safeCode(error); }
   return result;
 }
 
+// Call before switching the binding/entry. An earlier updater cleans up after
+// setup with its own code. Claude needs v2 to stop pre-B255 workers; Codex needs
+// v3 to stop B255 workers that know only Claude records. Preserve the recorded
+// adoption order and resolve with whether the receipt changed. Throw when that
+// cannot be confirmed, even for a cause that passes before the worker reads the
+// receipt (a file another process holds open): the caller then switches nothing.
+// currentRelease, the release the install starts now, is recorded only when
+// there is no receipt yet.
+export async function protectRetentionReceipt({ releasesRoot, client, currentRelease }) {
+  if (!ENTRY[client] && client !== 'codex') throw failure('release_retention_client_invalid');
+  const root = await rootPath(releasesRoot), pattern = new RegExp(`^${client}-[a-f0-9]{64}$`);
+  const receiptPath = path.join(root, `.${client}-retention.json`);
+  const old = await readReceipt(receiptPath, client, pattern);
+  if (old?.contract === receiptContract(client)) return false;
+  let current = old?.current;
+  if (!current) {
+    if (typeof currentRelease !== 'string' || !path.isAbsolute(currentRelease) || !pattern.test(path.basename(currentRelease))
+      || ![root, path.resolve(releasesRoot)].some(p => equal(path.dirname(path.resolve(currentRelease)), p))) throw failure('release_retention_target_invalid');
+    current = path.basename(currentRelease);
+    await directory(path.join(root, current));
+  }
+  await writeReceipt(receiptPath, { contract: receiptContract(client), client, current, previous: old ? old.previous : null });
+  return true;
+}
+
+const receiptContract = client => client === 'codex' ? codexContract : ENTRY[client] ? contractWithEntry : contract;
+
+async function readReceipt(receiptPath, client, pattern) {
+  let old = null;
+  try {
+    const stat = await fs.lstat(receiptPath);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 4096) throw failure('release_retention_receipt_invalid');
+    old = JSON.parse(await fs.readFile(receiptPath, 'utf8'));
+    if (![contract, contractWithEntry, ...(client === 'codex' ? [codexContract] : [])].includes(old?.contract) || old.client !== client || !pattern.test(old.current)
+      || old.previous !== null && !pattern.test(old.previous) || old.current === old.previous) throw failure('release_retention_receipt_invalid');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error.code ? error : failure('release_retention_receipt_invalid');
+  }
+  return old;
+}
+
+async function writeReceipt(receiptPath, receipt) {
+  const temporary = `${receiptPath}.${crypto.randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temporary, JSON.stringify(receipt) + '\n', { flag: 'wx', mode: 0o600 });
+    await fs.rename(temporary, receiptPath);
+  } finally { await fs.unlink(temporary).catch(e => { if (e.code !== 'ENOENT') throw e; }); }
+}
+
 // Uninstall keeps no release. One a process or scheduled task still uses is
 // left for the next install or uninstall, like any other deferred release.
 export async function removeInstalledReleases({ releasesRoot, client }, dependencies = {}) {
@@ -130,19 +260,27 @@ export async function removeInstalledReleases({ releasesRoot, client }, dependen
     try { await fs.lstat(releasesRoot); } catch (error) { if (error.code === 'ENOENT') return { ...result, complete: true }; throw error; }
     const root = await rootPath(releasesRoot), pattern = new RegExp(`^${client}-[a-f0-9]{64}$`);
     const referenced = new Set(await (dependencies.configuredReleases || configuredReleaseNames)(releasesRoot));
-    const running = new Set(await (dependencies.runningReleases || runningReleaseNames)(root));
-    await removeReleases(root, name => pattern.test(name), referenced, running, result, dependencies);
-    if (!result.deferred.length) await fs.rm(path.join(root, `.${client}-retention.json`), { force: true });
+    const entry = await entryReleases(releasesRoot, root, client, pattern, dependencies);
+    const running = new Set([...await (dependencies.runningReleases || runningReleaseNames)(root), ...entry.names]);
+    await removeReleases(root, name => pattern.test(name), referenced, running, result, dependencies, entry.unregistered);
+    if (!result.deferred.length) {
+      await fs.rm(path.join(root, `.${client}-retention.json`), { force: true });
+      // entryReleases checked above that this is a folder in the releases root.
+      if (ENTRY[client] || client === 'codex') await fs.rm(releaseProcessDirectory(root, client), { recursive: true, force: true });
+    }
     result.complete = result.deferred.length === 0;
   } catch (error) { result.error = safeCode(error); }
   return result;
 }
 
-async function removeReleases(root, selected, referenced, running, result, dependencies) {
+// An unregistered entry process may run any release of its client, so then
+// none is removed until it exits.
+async function removeReleases(root, selected, referenced, running, result, dependencies, unregistered = false) {
   for (const name of await fs.readdir(root)) {
     if (!selected(name)) continue;
     if (referenced.has(name)) { result.deferred.push({ name, reason: 'release_still_referenced' }); continue; }
     if (running.has(name)) { result.deferred.push({ name, reason: 'release_in_use' }); continue; }
+    if (unregistered) { result.deferred.push({ name, reason: 'release_in_use_unregistered' }); continue; }
     try {
       // The final absolute target is a checked direct child of the canonical
       // releases root; never follow a junction inside an obsolete package.

package/plugins/hellolynk-codex/runtime/neutral-host-release-manifest.json

@@ -4,7 +4,7 @@
   "files": [
     {
       "path": "release/package.json",
-      "sha256": "a060c56c6d97f2874f64006807e66a4ab4d0bbd99fd237faa80d1ebc5955e2e3"
+      "sha256": "5875df8d4163c0a84b3dc30265b1a5e7b977a7c92250aae013d3b513b3640c40"
     },
     {
       "path": "neutral-host-bootstrap.mjs",
@@ -52,7 +52,7 @@
     },
     {
       "path": "core/hellolynk-release-retention.mjs",
-      "sha256": "68321383ecf73adf55d842c7215f5e0b0fe72851aac292885740be99743e1bd0"
+      "sha256": "9b02a42a510fa5ef4a251b6e675f9ccc60f20b718d17c1617027cd048c5634dd"
     },
     {
       "path": "core/hellolynk-contact-request-e2ee.mjs",
@@ -168,7 +168,7 @@
     },
     {
       "path": "core/hellolynk-native-addressing-tools.cjs",
-      "sha256": "252251de855c3fe9c5ebdd54a97ba976a8009f4ac57ec44f492bed8c7fb903de"
+      "sha256": "f4bd81b3d03277e28955a62409383a0c4072c6212567f71425df4e18ece75d63"
     },
     {
       "path": "core/hellolynk-native-human-confirmation-broker.mjs",
@@ -188,7 +188,7 @@
     },
     {
       "path": "core/hellolynk-neutral-host-process.mjs",
-      "sha256": "6d1913e3fb6e35d9a090afde39bf4a1521b17d1620fb09420e507d60af77cce4"
+      "sha256": "af6cb6585baae477f87ee880bd044dffb4c7f71667bfa78bcbf0d4d20e7483af"
     },
     {
       "path": "core/hellolynk-neutral-host-store-adapters.mjs",
@@ -344,7 +344,7 @@
     },
     {
       "path": "release/server/codex-neutral-production.mjs",
-      "sha256": "34b865d80d7eb3c8e6986635b158c8583ddddb40bb528c4a75f0a498bdb3e1fb"
+      "sha256": "ffb8e689df1b600bcca85159af8d59f0fad819827f48ba9a218a63dfd7a3daa2"
     },
     {
       "path": "release/server/neutral-host-adapter.mjs",

package/plugins/hellolynk-codex/runtime/neutral-host-release-pin.json

@@ -1,4 +1,4 @@
 {
   "contract": "hellolynk-neutral-host-release-pin-v1",
-  "manifestSha256": "bea6d99eb2b763087ed2ffdf2f3d628ab3c0f0ccc28054cf4074a71afa454bf4"
+  "manifestSha256": "5b035cb2d82e7543b801ca9d3b35a36e3f54a7b9aff9afcdf9f479926c537f56"
 }

package/plugins/hellolynk-codex/server/codex-neutral-production.mjs

@@ -7,6 +7,7 @@ import { discoverNeutralHost } from "./neutral-host-adapter.mjs";
 import { launchPinnedNeutralHostBootstrap, verifyPinnedNeutralHostRuntime } from "../runtime/core/hellolynk-neutral-host-launcher.mjs";
 import { resolveClientAccountRoot } from "../runtime/core/hellolynk-client-account.mjs";
 import { startInstalledClientUpdate } from "../runtime/core/hellolynk-client-update-entry.mjs";
+import { recordCodexReleaseProcess } from "../runtime/core/hellolynk-release-retention.mjs";
 
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const PLUGIN_ROOT = path.dirname(MODULE_DIR);
@@ -216,6 +217,7 @@ async function prepareSelectedRelease(options, verifiedInitial = null) {
     assertReleaseBinding(binding, inspection);
     const release = await loader.activateNeutralHostRelease(inspection);
     if (!release || typeof release.run !== "function") throw codeError("neutral_codex_runner_integrity_invalid");
+    await recordCodexReleaseProcess(path.resolve(releaseRoot, "../.."));
     return Object.freeze({ release, inspection, binding, initialBindingFingerprint,
       releaseRoot, storeRoot, installationStore, protectedStore,
       runnerBinding: (root) => currentRunnerBinding(storeRoot, root, binding, initialBindingFingerprint) });