helloagents 3.0.16-beta.1 → 3.0.17-beta.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.16-beta.1",
+  "version": "3.0.17-beta.1",
   "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": {
     "name": "HelloWind",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.16-beta.1",
+  "version": "3.0.17-beta.1",
   "description": "HelloAGENTS — Quality-driven orchestration kernel for AI CLIs with intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": {
     "name": "HelloWind",

package/README.md

@@ -8,7 +8,7 @@
 
 **A workflow layer for AI coding CLIs: skills, project knowledge, delivery checks, safer config writes, and resumable execution.**
 
-[![Version](https://img.shields.io/badge/version-3.0.16-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.17-orange.svg)](./package.json)
 [![npm](https://img.shields.io/npm/v/helloagents.svg)](https://www.npmjs.com/package/helloagents)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](./package.json)
 [![Skills](https://img.shields.io/badge/skills-14-6366f1.svg)](./skills)
@@ -30,7 +30,7 @@
 ## Contents
 
 - [What HelloAGENTS Does](#what-helloagents-does)
-- [What Changed Since v3.0.15](#what-changed-since-v3015)
+- [What Changed Since v3.0.16](#what-changed-since-v3016)
 - [Core Features](#core-features)
 - [Quick Start](#quick-start)
 - [CLI Management](#cli-management)
@@ -77,17 +77,15 @@ HelloAGENTS adds a workflow layer on top of Claude Code, Gemini CLI, and Codex C
 | Completion is vague | Natural language says “done” | Delivery checks use state, evidence, and verification |
 | Config writes are risky | CLI files can drift | Install, update, cleanup, and doctor flows check managed files |
 
-## What Changed Since v3.0.15
+## What Changed Since v3.0.16
 
-These are the main user-visible changes in `v3.0.16`, compared with `v3.0.15 beta`:
+These are the main user-visible changes in `v3.0.17`, compared with `v3.0.16 beta`:
 
-- Codex notifications now handle both Codex TUI and `codex exec` completion events, so turn-state gates, delivery checks, and completion notifications stay consistent across Codex entrypoints.
-- Codex on Windows now writes the managed notify command through the command shim, reducing failures caused by direct script paths or shell-specific resolution.
-- Runtime configuration reads now reuse the current session cache when available, reducing repeated `~/.helloagents/helloagents.json` reads while preserving explicit refresh behavior.
-- Persistent carrier files no longer snapshot user settings; runtime injection and final output formatting resolve current settings at execution time.
-- Install tracking is stricter after partial host setup, so `helloagents update --all` can preserve each CLI’s detected or tracked mode more reliably.
-- UI rule boundaries are clearer: the shared UI baseline is the minimum quality line, and `hello-ui` adds concrete design, implementation, and visual validation rules in global mode, activated projects, or explicit UI workflows.
-- One-shot installers now support `HELLOAGENTS_ACTION=cleanup` for host cleanup without uninstalling the package.
+- Managed host configuration now uses `helloagents-js.cmd` as the single stable entrypoint across Windows, macOS, and Linux.
+- Codex `notify` now writes `notify = ["helloagents-js.cmd", "codex-notify"]`, so a synced `config.toml` no longer needs OS-specific command names.
+- Claude Code and Gemini CLI standby hooks now use the same managed entrypoint as Codex, keeping host configuration wording and behavior consistent.
+- The package exposes `helloagents-js.cmd` as an npm bin alias while keeping the runtime command path independent of Node global package locations.
+- Runtime-root refresh now retries transient Windows filesystem rename errors, reducing occasional update/install failures when files are still being released.
 
 ## Core Features
 
@@ -235,10 +233,10 @@ The CLI manages host files explicitly:
 npm install -g helloagents
 ```
 
-If another executable named `helloagents` already exists in your `PATH`, use the stable alias:
+If another executable named `helloagents` already exists in your `PATH`, use the stable managed-entry alias:
 
 ```bash
-helloagents-js
+helloagents-js.cmd
 ```
 
 By default, `postinstall` installs the package command, initializes `~/.helloagents/helloagents.json`, and syncs runtime files to `~/.helloagents/helloagents`. No host CLI is deployed unless you set `HELLOAGENTS=target[:mode]`, such as `HELLOAGENTS=codex:global`.
@@ -316,7 +314,7 @@ If you omit `--standby` or `--global`, HelloAGENTS first reuses the tracked/dete
 
 Use these when you do not want to depend on the `helloagents` binary being available during package updates. In `HELLOAGENTS=target[:mode]`, target can be `all`, `claude`, `gemini`, or `codex`; mode can be `standby` or `global`, and defaults to `standby`.
 
-Host configs use the stable `helloagents-js` entrypoint and runtime root `~/.helloagents/helloagents`, so Node global package paths can change without breaking managed hooks or Codex `notify`.
+Host configs use the stable `helloagents-js.cmd` entrypoint and runtime root `~/.helloagents/helloagents`, so Node global package paths can change without breaking managed hooks or Codex `notify`. The same managed `config.toml` works across Windows, macOS, and Linux.
 
 #### npm commands
 
@@ -643,7 +641,7 @@ Codex is rules-file driven by default.
 
 - standby writes `~/.codex/AGENTS.md`
 - standby writes a managed `model_instructions_file = "~/.codex/AGENTS.md"`
-- standby writes a managed `notify = ["helloagents-js", "codex-notify"]` command for closeout notification
+- standby writes a managed `notify = ["helloagents-js.cmd", "codex-notify"]` command for closeout notification
 - standby creates `~/.codex/helloagents -> ~/.helloagents/helloagents`
 - global mode installs the native local-plugin chain
 - HelloAGENTS does not enable Codex hooks by default

package/README_CN.md

@@ -8,7 +8,7 @@
 
 **面向 AI 编码 CLI 的工作流层：技能、知识库、交付检查、更安全的配置写入，以及可恢复的执行流程。**
 
-[![Version](https://img.shields.io/badge/version-3.0.16-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.17-orange.svg)](./package.json)
 [![npm](https://img.shields.io/npm/v/helloagents.svg)](https://www.npmjs.com/package/helloagents)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](./package.json)
 [![Skills](https://img.shields.io/badge/skills-14-6366f1.svg)](./skills)
@@ -30,7 +30,7 @@
 ## 目录
 
 - [HelloAGENTS 做什么](#helloagents-做什么)
-- [相对 v3.0.15 的真实变化](#相对-v3015-的真实变化)
+- [相对 v3.0.16 的真实变化](#相对-v3016-的真实变化)
 - [核心功能](#核心功能)
 - [快速开始](#快速开始)
 - [CLI 管理](#cli-管理)
@@ -77,17 +77,15 @@ HelloAGENTS 叠加在 Claude Code、Gemini CLI 和 Codex CLI 之上，帮助模
 | 完成态模糊 | 自然语言说“完成” | 按状态、证据和验证结果交付 |
 | 配置容易漂移 | CLI 文件可能不一致 | 安装、更新、清理和 doctor 会检查受管文件 |
 
-## 相对 v3.0.15 的真实变化
+## 相对 v3.0.16 的真实变化
 
-下面是当前 `v3.0.16` 相对 `v3.0.15 beta` 的主要可见变化：
+下面是当前 `v3.0.17` 相对 `v3.0.16 beta` 的主要可见变化：
 
-- Codex 通知现在同时覆盖 Codex TUI 与 `codex exec` 的完成事件，turn-state 门控、交付检查和完成通知在不同入口下保持一致。
-- Windows 下的 Codex 受管通知命令改用命令 shim，减少直接脚本路径或 shell 解析差异导致的失败。
-- 运行时配置读取会优先复用当前会话缓存，减少重复读取 `~/.helloagents/helloagents.json`，同时保留显式刷新行为。
-- 持久 carrier 文件不再快照用户设置；运行时注入和最终输出格式在执行时解析当前配置。
-- 部分宿主安装成功后，安装追踪更严格，`helloagents update --all` 可以更可靠地保留每个 CLI 的检测模式或追踪模式。
-- UI 规则边界更清晰：共享 UI 基线是最低质量线；在全局模式、已激活项目或显式 UI 工作流中，`hello-ui` 补充具体设计、实现和视觉验收规则。
-- 一键安装脚本新增 `HELLOAGENTS_ACTION=cleanup`，可只清理宿主集成而不卸载包。
+- 受管宿主配置统一使用 `helloagents-js.cmd` 作为 Windows、macOS 和 Linux 三端稳定入口。
+- Codex `notify` 统一写入 `notify = ["helloagents-js.cmd", "codex-notify"]`，同步同一份 `config.toml` 时不再需要区分系统。
+- Claude Code 与 Gemini CLI 的标准模式 hooks 也使用同一受管入口，与 Codex 的配置行为和文档表述保持一致。
+- npm 包新增 `helloagents-js.cmd` bin alias，同时保持运行命令不依赖 Node 全局包的实际安装路径。
+- 稳定运行根目录刷新增加 Windows 临时文件系统重试，减少文件释放延迟导致的偶发更新/安装失败。
 
 ## 核心功能
 
@@ -235,10 +233,10 @@ CLI 显式管理宿主文件：
 npm install -g helloagents
 ```
 
-如果系统里已经有别的 `helloagents` 可执行文件，可以使用稳定别名：
+如果系统里已经有别的 `helloagents` 可执行文件，可以使用稳定的受管入口别名：
 
 ```bash
-helloagents-js
+helloagents-js.cmd
 ```
 
 默认情况下，`postinstall` 会安装包命令、初始化 `~/.helloagents/helloagents.json`，并把运行时文件同步到 `~/.helloagents/helloagents`。如果希望 npm 在安装或更新后直接部署，设置 `HELLOAGENTS=目标[:模式]`，例如 `HELLOAGENTS=codex:global`。
@@ -316,7 +314,7 @@ helloagents doctor codex --json
 
 当你不想依赖更新过程中的 `helloagents` 可执行文件时，用 npm 或一键脚本。`HELLOAGENTS=目标[:模式]` 中，目标支持 `all`、`claude`、`gemini`、`codex`；模式支持 `standby`、`global`，省略时默认 `standby`。
 
-宿主配置使用稳定的 `helloagents-js` 入口和运行根目录 `~/.helloagents/helloagents`，Node 全局包路径变化不会破坏受管 hooks 或 Codex `notify`。
+宿主配置使用稳定的 `helloagents-js.cmd` 入口和运行根目录 `~/.helloagents/helloagents`，Node 全局包路径变化不会破坏受管 hooks 或 Codex `notify`。同一份受管 `config.toml` 可在 Windows、macOS 和 Linux 之间同步。
 
 #### npm 命令
 
@@ -645,7 +643,7 @@ Codex 默认走规则文件驱动。
 
 - 标准模式写入 `~/.codex/AGENTS.md`
 - 标准模式写入受管 `model_instructions_file = "~/.codex/AGENTS.md"`
-- 标准模式写入受管 `notify = ["helloagents-js", "codex-notify"]` 命令用于收尾通知
+- 标准模式写入受管 `notify = ["helloagents-js.cmd", "codex-notify"]` 命令用于收尾通知
 - 标准模式创建 `~/.codex/helloagents -> ~/.helloagents/helloagents`
 - 全局模式安装原生本地插件流程
 - HelloAGENTS 默认不启用 Codex hooks

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.16-beta.1",
+  "version": "3.0.17-beta.1",
   "description": "Quality-driven orchestration kernel for AI CLIs",
   "contextFileName": "bootstrap.md",
   "author": "HelloWind",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.16-beta.1",
+  "version": "3.0.17-beta.1",
   "type": "module",
   "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": "HelloWind",
@@ -13,6 +13,7 @@
   "bin": {
     "helloagents": "cli.mjs",
     "helloagents-js": "cli.mjs",
+    "helloagents-js.cmd": "cli.mjs",
     "helloagents-turn-state": "scripts/turn-state-cli.mjs"
   },
   "scripts": {

package/scripts/cli-codex-config.mjs

@@ -7,9 +7,7 @@ import {
 export const CODEX_PLUGIN_CONFIG_HEADER = '[plugins."helloagents@local-plugins"]'
 export const CODEX_MANAGED_TOML_COMMENT = '# helloagents-managed'
 export const CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH = '~/.codex/AGENTS.md'
-export const CODEX_MANAGED_NOTIFY_COMMAND = process.platform === 'win32'
-  ? 'helloagents-js.cmd'
-  : 'helloagents-js'
+export const CODEX_MANAGED_NOTIFY_COMMAND = 'helloagents-js.cmd'
 export const CODEX_MANAGED_NOTIFY_VALUE = `["${CODEX_MANAGED_NOTIFY_COMMAND}", "codex-notify"]`
 
 function normalizePath(value = '') {
@@ -33,11 +31,7 @@ export function isManagedCodexModelInstruction(line = '') {
 
 export function isManagedCodexNotify(line = '') {
   const value = String(line || '').replace(/\\/g, '/')
-  return value.includes(CODEX_MANAGED_TOML_COMMENT)
-    || (
-      value.includes('helloagents-js')
-      && value.includes('codex-notify')
-    )
+  return value.includes(CODEX_MANAGED_NOTIFY_VALUE)
 }
 
 export function isManagedCodexBackupInstruction(line = '') {

package/scripts/cli-messages.mjs

@@ -87,7 +87,7 @@ HelloAGENTS v${pkgVersion} — The orchestration kernel for AI CLIs
 ${msg('安装', 'Install')}:
   npm install -g helloagents  ${msg('（安装命令并同步稳定运行根目录；CLI 部署需显式执行 helloagents install ...）', '(installs the command and syncs the stable runtime root; deploy to CLIs explicitly with helloagents install ...)')}
   HELLOAGENTS=codex:global npm install -g helloagents
-  helloagents-js             ${msg('（稳定别名，避免与系统中同名可执行文件冲突）', '(stable alias to avoid conflicts with system executables of the same name)')}
+  helloagents-js.cmd         ${msg('（受管宿主配置的跨平台稳定入口）', '(cross-platform stable entrypoint for managed host configs)')}
 
 ${msg('模式切换', 'Mode switching')}:
   helloagents --global     ${msg('全局模式（自动尝试 Claude/Gemini 插件或扩展；Codex 自动装原生本地插件）', 'Global mode (auto-attempts Claude/Gemini plugins or extensions; native local plugin auto-install for Codex)')}

package/scripts/cli-runtime-root.mjs

@@ -43,6 +43,26 @@ function samePath(left, right) {
   return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b
 }
 
+function wait(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+}
+
+function retryTransientFs(operation) {
+  let lastError
+  for (let attempt = 0; attempt < 6; attempt += 1) {
+    try {
+      return operation()
+    } catch (error) {
+      lastError = error
+      if (!['EPERM', 'EBUSY', 'ENOTEMPTY'].includes(error?.code) || attempt === 5) {
+        throw error
+      }
+      wait(40 * (attempt + 1))
+    }
+  }
+  throw lastError
+}
+
 /** Sync package runtime files into the stable root without copying repo-only files. */
 export function syncRuntimeRoot(sourceRoot, runtimeRoot) {
   const source = resolve(sourceRoot)
@@ -57,8 +77,10 @@ export function syncRuntimeRoot(sourceRoot, runtimeRoot) {
 
   try {
     copyEntries(source, staging, RUNTIME_ROOT_ENTRIES)
-    removeIfExists(target)
-    renameSync(staging, target)
+    retryTransientFs(() => {
+      removeIfExists(target)
+      renameSync(staging, target)
+    })
     return { synced: true, root: target }
   } catch (error) {
     removeIfExists(staging)

package/scripts/cli-utils.mjs

@@ -132,9 +132,9 @@ export function cleanSettingsHooks(settingsPath, cleanPermissions = false) {
 
 function rewriteHookCommandToCli(command = '', pathVar = '') {
   const replacements = new Map([
-    [`node "${pathVar}/scripts/notify.mjs"`, 'helloagents-js notify'],
-    [`node "${pathVar}/scripts/guard.mjs"`, 'helloagents-js guard'],
-    [`node "${pathVar}/scripts/ralph-loop.mjs"`, 'helloagents-js ralph-loop'],
+    [`node "${pathVar}/scripts/notify.mjs"`, 'helloagents-js.cmd notify'],
+    [`node "${pathVar}/scripts/guard.mjs"`, 'helloagents-js.cmd guard'],
+    [`node "${pathVar}/scripts/ralph-loop.mjs"`, 'helloagents-js.cmd ralph-loop'],
   ]);
 
   let next = command;