helloagents 3.0.35 → 3.0.38

package/.claude-plugin/marketplace.json

@@ -9,10 +9,7 @@
     {
       "name": "helloagents",
       "description": "Quality-driven orchestration kernel for AI CLIs: intelligent routing, quality verification, safety guards, and notifications",
-      "source": {
-        "source": "github",
-        "repo": "hellowind777/helloagents"
-      },
+      "source": "./",
       "author": {
         "name": "HelloWind",
         "email": "hellowind777@gmail.com"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.35",
+  "version": "3.0.38",
   "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, unified QA gates, safety guards, and notifications.",
   "author": {
     "name": "HelloWind",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.35",
+  "version": "3.0.38",
   "description": "HelloAGENTS — Quality-driven orchestration kernel for AI CLIs with intelligent routing, unified QA gates, 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.35-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.38-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)
@@ -184,10 +184,12 @@ Long tasks need a small recovery snapshot, but one shared state file is not safe
 
 HelloAGENTS now resolves the current state file from `state_path`:
 
-- with a stable session id: `.helloagents/sessions/<workspace>/<session>/STATE.md`
-- without a stable session id: `.helloagents/sessions/<workspace>/default/STATE.md`
+- with a stable or reusable session id: `.helloagents/sessions/<workspace>/<session>/STATE.md`
+- before a reusable session id is available: `.helloagents/sessions/<workspace>/default/STATE.md`
 
-`<workspace>` is the current Git branch, `detached-<sha>` for a detached HEAD, or `workspace` for non-Git projects. `.helloagents/sessions/active.json` only records the active session index.
+`<workspace>` is the current Git branch, `detached-<sha>` for a detached HEAD, or `workspace` for non-Git projects. `<session>` is the current project-local session token. `.helloagents/sessions/active.json` only keeps the latest active workspace/session mapping plus alias bridges, so the same CLI session stays in one directory and `/resume` can reuse it.
+
+For project-local sessions, HelloAGENTS first uses stable host identifiers such as `sessionId`, `conversationId`, `threadId`, or `HELLOAGENTS_NOTIFY_SESSION_ID`. If the host only exposes a window or terminal id such as `WT_SESSION`, `TERM_SESSION_ID`, or `WINDOWID`, HelloAGENTS uses it only as a lightweight alias bridge and reuses the mapped session first instead of fanning out duplicate directories.
 
 `STATE.md` records where the current workflow stopped. It is not a universal memory file for every conversation. Codex `/goal` does not replace `state_path`, `turn-state`, or local evidence files; it only handles long-running continuation on the Codex side.
 
@@ -198,14 +200,19 @@ HelloAGENTS does not treat “tests passed” and “task complete” as the sam
 Runtime state now stays intentionally small:
 
 - `.helloagents/sessions/<workspace>/<session>/STATE.md`
+- `.helloagents/sessions/<workspace>/<session>/runtime.json`
 - `.helloagents/sessions/active.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/qa-review.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/advisor.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/visual.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/closeout.json`
+- optional `.helloagents/sessions/<workspace>/<session>/events.jsonl`
 - `~/.codex/.helloagents/notify-state.json` for Codex-native closeout de-duplication only
 
-`turn-state`, route context, and the artifact index are stored inside `STATE.md` metadata instead of a separate `capsule.json`. `events.jsonl` is opt-in trace output, not a default runtime file.
+`STATE.md` only keeps the human-readable recovery snapshot. `runtime.json` is machine-only and keeps the minimal runtime state. `artifacts/*.json` stays limited to structured receipts. `events.jsonl` remains opt-in trace output and stays off by default.
+Project-local `STATE.md` is now materialized more lazily, and legacy root-level `.helloagents/artifacts/*.log` files are cleaned up automatically instead of growing as a second history system.
+
+Standard runtime evidence and transient runtime state now expire after 72 hours. Long-running Codex goal flows still keep their 720-hour upper bound where the workflow explicitly needs it.
 
 Delivery gate, guard, and QA gate messages use action-oriented wording such as processing path, closeout action, and visual validation action, so blocked flows show what to do next without turning executable steps into optional suggestions. Final closeout also enforces a single HelloAGENTS wrapper, so one reply does not emit duplicate closeout headers.
 That wrapper is now reserved for direct final-user delivery only. Intermediate reports, delegated task results, and sub-agent replies stay natural, and sub-agent stop hooks reject wrapped closeout replies.
@@ -304,7 +311,7 @@ If you omit `--standby` or `--global`, HelloAGENTS first reuses the tracked/dete
 
 ### npm and one-shot script entries
 
-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`. For install, an omitted mode is treated as `standby`. For update, cleanup, uninstall, and branch switching, an omitted mode is forwarded unchanged so HelloAGENTS can reuse the tracked or detected mode for that CLI first. For a custom tarball or package spec, set `HELLOAGENTS_PACKAGE` instead of `HELLOAGENTS_BRANCH`. For a guaranteed refresh of an already installed package, prefer `npm explore -g helloagents -- npm run sync-hosts -- ...` after the package command.
+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`. For install, an omitted mode is treated as `standby`. For update, cleanup, uninstall, and branch switching, an omitted mode is forwarded unchanged so HelloAGENTS can reuse the tracked or detected mode for that CLI first. If you do not provide `HELLOAGENTS`, the one-shot install scripts now behave like plain package install: they install or update the package only and do not auto-deploy any host CLI. For a custom tarball or package spec, set `HELLOAGENTS_PACKAGE` instead of `HELLOAGENTS_BRANCH`. For a guaranteed refresh of an already installed package, prefer `npm explore -g helloagents -- npm run sync-hosts -- ...` after the package command.
 
 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`. Codex hooks use standalone `~/.codex/hooks.json` instead of adding large hook blocks to `config.toml`, and Codex global plugin roots plus plugin cache now link back to that same stable runtime root.
 
@@ -405,7 +412,7 @@ $env:HELLOAGENTS="codex:standby"; $env:HELLOAGENTS_ACTION="cleanup"; irm https:/
 $env:HELLOAGENTS="gemini"; $env:HELLOAGENTS_ACTION="uninstall"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex
 ```
 
-The shell and PowerShell wrappers now parse `HELLOAGENTS` once, clear lifecycle env before update, branch switching, and uninstall, and then run one explicit sync or cleanup path.
+The shell and PowerShell wrappers now parse `HELLOAGENTS` once, keep plain package install/update behavior when no target is specified, clear lifecycle env before update, branch switching, and uninstall, and then run one explicit sync or cleanup path.
 
 ### Branch switching
 
@@ -442,12 +449,12 @@ npm uninstall -g helloagents
 | Gemini CLI | native extension install | managed by Gemini extension system |
 | Codex CLI | native local-plugin chain | `~/.agents/plugins/marketplace.json`, `~/plugins/helloagents/ -> ~/.helloagents/helloagents`, `~/.codex/plugins/cache/local-plugins/helloagents/local/ -> ~/.helloagents/helloagents`, `~/.codex/config.toml`, `~/.codex/hooks.json`, `~/.codex/helloagents -> ~/.helloagents/helloagents` |
 
-In global mode, HelloAGENTS now attempts the host-native install commands automatically. If a host command is unavailable, run the same commands manually:
+In global mode, HelloAGENTS now attempts the host-native install commands automatically. For Claude Code, the marketplace should be added from the Git URL so the plugin source stays on HTTPS and avoids an SSH-only clone during installation. If a host command is unavailable, run the same commands manually:
 
 ```text
-/plugin marketplace add hellowind777/helloagents
+/plugin marketplace add https://github.com/hellowind777/helloagents.git
 /plugin install helloagents@helloagents
-gemini extensions install https://github.com/hellowind777/helloagents
+helloagents install gemini --global
 ```
 
 For Claude Code, the CLI also tries the equivalent `claude plugin marketplace add ...` and `claude plugin install ...` commands. The marketplace is named `helloagents`, and the plugin is also named `helloagents`, so the install target is `helloagents@helloagents`. Restart the host CLI after a global install.
@@ -502,6 +509,7 @@ Runtime state and evidence remain local to the working project:
 
 - `state_path`
 - `.helloagents/sessions/active.json`
+- `.helloagents/sessions/<workspace>/<session>/runtime.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/*.json`
 
 ### Temporary sessions outside project-local storage
@@ -512,9 +520,9 @@ For read-only work with no local output, if neither the current directory nor it
 ~/.helloagents/runtime/<scope-key>/
 ```
 
-This only stores short-lived `STATE.md` and `artifacts/`. Optional `events.jsonl` trace files are only written when trace mode is enabled. It is not project knowledge. Expired transient sessions are removed by TTL cleanup.
+This only stores short-lived `STATE.md`, `runtime.json`, and `artifacts/`. Optional `events.jsonl` trace files are only written when trace mode is enabled. It is not project knowledge. Expired transient sessions are removed by TTL cleanup.
 
-Once the task creates or modifies local files, or otherwise leaves local output in the current project, HelloAGENTS creates the project-local `.helloagents/sessions/.../STATE.md` automatically instead of keeping that task only in the user-level transient runtime.
+Once the task creates or modifies local files, or otherwise leaves local output in the current project, HelloAGENTS creates the project-local `.helloagents/sessions/<workspace>/<session>/STATE.md` automatically instead of keeping that task only in the user-level transient runtime.
 
 ### Knowledge creation rules
 
@@ -677,7 +685,7 @@ The current suite covers:
 - Codex `/goal` feature toggles, long-running route context, and goal-aware command contracts
 - `helloagents doctor`
 - project storage and `repo-shared` behavior
-- session-scoped `state_path`, runtime signals, and evidence
+- workspace-session scoped `state_path`, runtime signals, and evidence
 - runtime injection, routing, guard, verification, visual evidence, delivery gates, closeout de-duplication, sub-agent wrapper and notification suppression, and successful-mode tracking after native install failures
 - README and skill contract alignment
 

package/README_CN.md

@@ -8,7 +8,7 @@
 
 **面向 AI 编码 CLI 的工作流层：技能、知识库、交付检查、更安全的配置写入，以及可恢复的执行流程。**
 
-[![Version](https://img.shields.io/badge/version-3.0.35-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.38-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)
@@ -184,10 +184,12 @@ HelloAGENTS 可以在 `.helloagents/` 下创建和维护项目知识库。
 
 HelloAGENTS 现在只从 `state_path` 解析当前状态文件：
 
-- 宿主提供稳定会话标识时：`.helloagents/sessions/<workspace>/<session>/STATE.md`
-- 宿主未提供稳定会话标识时：`.helloagents/sessions/<workspace>/default/STATE.md`
+- 宿主提供稳定会话标识或可复用会话标识时：`.helloagents/sessions/<workspace>/<session>/STATE.md`
+- 暂时还拿不到可复用会话标识时：`.helloagents/sessions/<workspace>/default/STATE.md`
 
-`<workspace>` 是当前 Git 分支、detached HEAD 的 `detached-<sha>`，或非 Git 项目的 `workspace`。`.helloagents/sessions/active.json` 只记录当前活跃会话索引。
+`<workspace>` 是当前 Git 分支、detached HEAD 的 `detached-<sha>`，或非 Git 项目的 `workspace`。`<session>` 是当前项目本地会话标识。`.helloagents/sessions/active.json` 只保留最近一次活跃的工作区/会话映射和 alias 桥接，这样同一个 CLI 会话会稳定落在同一个目录里，`/resume` 也能复用它。
+
+对于项目本地会话目录，HelloAGENTS 会优先使用稳定宿主标识，如 `sessionId`、`conversationId`、`threadId` 或 `HELLOAGENTS_NOTIFY_SESSION_ID`。如果宿主只能提供 `WT_SESSION`、`TERM_SESSION_ID`、`WINDOWID` 这类窗口或终端标识，HelloAGENTS 只把它们当作轻量 alias 桥接，并优先复用已映射的会话目录，而不是继续分裂出重复目录。
 
 `STATE.md` 只记录当前工作流做到哪里，不承担所有对话的统一记忆。Codex `/goal` 也不替代 `state_path`、`turn-state` 或本地证据文件；它只负责 Codex 侧的长程续跑。
 
@@ -198,14 +200,19 @@ HelloAGENTS 不把“命令通过”和“任务完成”简单画等号。交
 运行态现在尽量收敛，只保留真正有用的文件：
 
 - `.helloagents/sessions/<workspace>/<session>/STATE.md`
+- `.helloagents/sessions/<workspace>/<session>/runtime.json`
 - `.helloagents/sessions/active.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/qa-review.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/advisor.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/visual.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/closeout.json`
+- 可选 `.helloagents/sessions/<workspace>/<session>/events.jsonl`
 - 仅用于 Codex 原生收尾去重的 `~/.codex/.helloagents/notify-state.json`
 
-`turn-state`、路由上下文和 artifact 索引都写进 `STATE.md` 的元数据，不再单独生成 `capsule.json`。`events.jsonl` 改为可选 trace 输出，默认不写。
+`STATE.md` 只保留给人看的恢复快照。`runtime.json` 只给机器用，只保存极少量运行态。`artifacts/*.json` 只保留结构化收据。`events.jsonl` 仍是可选 trace 输出，默认不写。
+项目本地 `STATE.md` 现在会更晚创建；旧版残留的项目根 `.helloagents/artifacts/*.log` 也会自动清理，不再继续充当第二套历史系统。
+
+标准运行态证据和临时运行态现在默认 72 小时过期。只有工作流明确需要的长程 Codex goal 链路，才继续保留 720 小时上限。
 
 交付门控、守卫和 QA gate 提示使用执行性表述，例如处理路径、收尾动作和视觉验收动作。阻塞流程会说明下一步要做什么，而不是把可执行步骤写成泛化建议。最终回复还会强制只保留一个 HelloAGENTS 外层块，避免同一条回复重复输出完成标题。
 这个外层格式现在只保留给直接面向最终用户的终局交付。中间汇报、委派任务结果和子代理回复都保持自然输出；子代理结束钩子也会拦截错误的外层收尾格式。
@@ -304,7 +311,7 @@ helloagents codex goals enable
 
 ### npm 和一键脚本入口
 
-当你不想依赖更新过程中的 `helloagents` 可执行文件时，用 npm 或一键脚本。`HELLOAGENTS=目标[:模式]` 中，目标支持 `all`、`claude`、`gemini`、`codex`；模式支持 `standby`、`global`。用于安装时，省略模式按 `standby` 处理；用于更新、清理、卸载和切换分支时，省略模式会原样下传，让 HelloAGENTS 先复用该 CLI 已记录或检测到的模式。若要安装自定义 tarball 或包规格，用 `HELLOAGENTS_PACKAGE`，不要写 `HELLOAGENTS_BRANCH`。对于已经装好的包，如需确保宿主一定刷新，优先在包命令后显式执行一次 `npm explore -g helloagents -- npm run sync-hosts -- ...`。
+当你不想依赖更新过程中的 `helloagents` 可执行文件时，用 npm 或一键脚本。`HELLOAGENTS=目标[:模式]` 中，目标支持 `all`、`claude`、`gemini`、`codex`；模式支持 `standby`、`global`。用于安装时，省略模式按 `standby` 处理；用于更新、清理、卸载和切换分支时，省略模式会原样下传，让 HelloAGENTS 先复用该 CLI 已记录或检测到的模式。如果未提供 `HELLOAGENTS`，一键安装脚本现在会保持“只装包/只升级包”的默认语义，不会自动部署任何宿主 CLI。若要安装自定义 tarball 或包规格，用 `HELLOAGENTS_PACKAGE`，不要写 `HELLOAGENTS_BRANCH`。对于已经装好的包，如需确保宿主一定刷新，优先在包命令后显式执行一次 `npm explore -g helloagents -- npm run sync-hosts -- ...`。
 
 宿主配置使用稳定的 `helloagents-js` 入口和运行根目录 `~/.helloagents/helloagents`，Node 全局包路径变化不会破坏受管 hooks 或 Codex `notify`。Codex hooks 使用独立 `~/.codex/hooks.json`，不把大段配置写入 `config.toml`；Codex 全局插件根目录和插件缓存也会回链到这个稳定运行根目录。
 
@@ -405,7 +412,7 @@ $env:HELLOAGENTS="codex:standby"; $env:HELLOAGENTS_ACTION="cleanup"; irm https:/
 $env:HELLOAGENTS="gemini"; $env:HELLOAGENTS_ACTION="uninstall"; irm https://raw.githubusercontent.com/hellowind777/helloagents/main/install.ps1 | iex
 ```
 
-Shell 和 PowerShell 一键脚本现在都会先解析一次 `HELLOAGENTS`，再在更新、切分支和卸载前清掉生命周期环境变量，然后只走一条显式同步或清理链路。
+Shell 和 PowerShell 一键脚本现在都会先解析一次 `HELLOAGENTS`；未指定目标时保持普通包安装/升级语义；在更新、切分支和卸载前清掉生命周期环境变量，然后只走一条显式同步或清理链路。
 
 ### 分支切换
 
@@ -442,12 +449,12 @@ npm uninstall -g helloagents
 | Gemini CLI | 原生扩展安装 | 由 Gemini 扩展系统管理 |
 | Codex CLI | 原生本地插件流程 | `~/.agents/plugins/marketplace.json`、`~/plugins/helloagents/ -> ~/.helloagents/helloagents`、`~/.codex/plugins/cache/local-plugins/helloagents/local/ -> ~/.helloagents/helloagents`、`~/.codex/config.toml`、`~/.codex/hooks.json`、`~/.codex/helloagents -> ~/.helloagents/helloagents` |
 
-全局模式下，HelloAGENTS 会自动尝试宿主原生命令。若宿主命令不可用，再手动执行：
+全局模式下，HelloAGENTS 会自动尝试宿主原生命令。对 Claude Code，marketplace 应使用 Git URL 添加，这样插件安装阶段会继续走 HTTPS，不会落回 SSH-only clone。若宿主命令不可用，再手动执行：
 
 ```text
-/plugin marketplace add hellowind777/helloagents
+/plugin marketplace add https://github.com/hellowind777/helloagents.git
 /plugin install helloagents@helloagents
-gemini extensions install https://github.com/hellowind777/helloagents
+helloagents install gemini --global
 ```
 
 Claude Code 会自动尝试等价的 `claude plugin marketplace add ...` 和 `claude plugin install ...` 命令。marketplace 名称和插件名称都是 `helloagents`，所以安装目标是 `helloagents@helloagents`。全局安装后需要重启宿主 CLI。
@@ -506,6 +513,7 @@ Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。
 
 - `state_path`
 - `.helloagents/sessions/active.json`
+- `.helloagents/sessions/<workspace>/<session>/runtime.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/*.json`
 
 ### 项目本地存储之外的临时会话
@@ -516,9 +524,9 @@ Codex 全局模式由 HelloAGENTS 通过本地插件路径自动安装。
 ~/.helloagents/runtime/<scope-key>/
 ```
 
-这里仅保存短期的 `STATE.md` 和 `artifacts/`。`events.jsonl` 只有在启用 trace 时才会写入，不作为默认运行态文件。它也不属于项目知识库。过期临时会话会按 TTL 清理。
+这里仅保存短期的 `STATE.md`、`runtime.json` 和 `artifacts/`。`events.jsonl` 只有在启用 trace 时才会写入，不作为默认运行态文件。它也不属于项目知识库。过期临时会话会按 TTL 清理。
 
-一旦任务会创建或修改本地文件，或会在当前项目留下本地输出，HelloAGENTS 就会自动创建项目本地 `.helloagents/sessions/.../STATE.md`，而不是只停留在用户级临时运行态。
+一旦任务会创建或修改本地文件，或会在当前项目留下本地输出，HelloAGENTS 就会自动创建项目本地 `.helloagents/sessions/<workspace>/<session>/STATE.md`，而不是只停留在用户级临时运行态。
 
 ### 知识创建规则
 
@@ -681,7 +689,7 @@ npm test
 - Codex `/goal` 功能开关、长程路由上下文和 goal 感知命令契约
 - `helloagents doctor`
 - 项目存储和 `repo-shared`
-- 会话级 `state_path`、运行态信号和证据
+- 工作区+会话级 `state_path`、运行态信号和证据
 - 运行时注入、选路、Guard、验证、视觉证据、交付门控、收尾去重、子代理外层格式与通知静默保护，以及原生安装失败后的模式记录
 - README 与 skill 契约一致性
 

package/bootstrap-lite.md

@@ -221,9 +221,9 @@
 路径: {CWD}/.helloagents/
 所有文件的创建和更新必须按 templates/ 目录中对应模板的格式执行，不可自由发挥格式。
 - `.helloagents/` 表示项目本地存储路径，负责知识、方案、状态与运行态；它不再作为项目是否已初始化的判定信号
-- `state_path` 指向的状态文件始终保留在项目本地 `.helloagents/sessions/{workspace}/{session}/STATE.md`；当前会话的 `turn-state`、路由上下文和 artifact 索引写入这个文件的元数据，`artifacts/*.json` 仅在需要结构化证据时按需生成，`events.jsonl` 仅在显式 trace 模式下写入
-- `state_path` 是状态文件的唯一位置。宿主提供会话标识时，写入 `.helloagents/sessions/{workspace}/{session}/STATE.md`；没有稳定会话标识时，写入 `.helloagents/sessions/{workspace}/default/STATE.md`
-- `{workspace}` 为当前 Git 分支、`detached-{sha}` 或非 Git 项目的 `workspace`；`.helloagents/sessions/active.json` 只记录当前活跃会话索引，避免同一会话被拆成多个目录
+- `state_path` 指向的状态文件始终保留在项目本地 `.helloagents/sessions/{workspace}/{session}/STATE.md`；当前会话的 `turn-state`、路由上下文和 artifact 索引写入同目录 `runtime.json`，`artifacts/*.json` 仅在需要结构化证据时按需生成，`events.jsonl` 仅在显式 trace 模式下写入
+- `state_path` 是状态文件的唯一位置。宿主提供稳定会话标识时，写入 `.helloagents/sessions/{workspace}/{session}/STATE.md`；没有稳定或可复用会话标识时，写入 `.helloagents/sessions/{workspace}/default/STATE.md`
+- `{workspace}` 为当前 Git 分支、`detached-{sha}` 或非 Git 项目的 `workspace`；`.helloagents/sessions/active.json` 只记录最近一次活跃的工作区/会话映射与 alias 桥接，避免同一 CLI 会话被拆成多个目录
 - 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定这些文件一定实际位于当前工作树中
 templates/ 查找路径（按优先级；首次确定模板根目录后，本会话复用）：
 按上文 `~command` 路由中的相同技能根目录规则确定；确定根目录后读取其中的 `templates/`。
@@ -292,4 +292,3 @@ Tier 3 — 深入特定模块时读取：
 
 ### 项目文件
 根据知识库中的架构描述和模块索引，结合当前任务需求，按需读取相关的项目源码、配置和资源文件。不要一次性读取整个项目，先通过知识库了解项目结构，再有针对性地读取需要的文件。不要把项目级规则文件（`AGENTS.md`、`CLAUDE.md`、`.gemini/GEMINI.md`）当作普通项目文件重复读取。
-

package/bootstrap.md

@@ -290,9 +290,9 @@ hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.m
 路径: {CWD}/.helloagents/
 所有文件的创建和更新必须按 templates/ 目录中对应模板的格式执行，不可自由发挥格式。
 - `.helloagents/` 表示项目本地存储路径，负责知识、方案、状态与运行态；它不再作为项目是否已初始化的判定信号
-- `state_path` 指向的状态文件始终保留在项目本地 `.helloagents/sessions/{workspace}/{session}/STATE.md`；当前会话的 `turn-state`、路由上下文和 artifact 索引写入这个文件的元数据，`artifacts/*.json` 仅在需要结构化证据时按需生成，`events.jsonl` 仅在显式 trace 模式下写入
-- `state_path` 是状态文件的唯一位置。宿主提供会话标识时，写入 `.helloagents/sessions/{workspace}/{session}/STATE.md`；没有稳定会话标识时，写入 `.helloagents/sessions/{workspace}/default/STATE.md`
-- `{workspace}` 为当前 Git 分支、`detached-{sha}` 或非 Git 项目的 `workspace`；`.helloagents/sessions/active.json` 只记录当前活跃会话索引，避免同一会话被拆成多个目录
+- `state_path` 指向的状态文件始终保留在项目本地 `.helloagents/sessions/{workspace}/{session}/STATE.md`；当前会话的 `turn-state`、路由上下文和 artifact 索引写入同目录 `runtime.json`，`artifacts/*.json` 仅在需要结构化证据时按需生成，`events.jsonl` 仅在显式 trace 模式下写入
+- `state_path` 是状态文件的唯一位置。宿主提供稳定会话标识时，写入 `.helloagents/sessions/{workspace}/{session}/STATE.md`；没有稳定或可复用会话标识时，写入 `.helloagents/sessions/{workspace}/default/STATE.md`
+- `{workspace}` 为当前 Git 分支、`detached-{sha}` 或非 Git 项目的 `workspace`；`.helloagents/sessions/active.json` 只记录最近一次活跃的工作区/会话映射与 alias 桥接，避免同一 CLI 会话被拆成多个目录
 - 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定这些文件一定实际位于当前工作树中
 templates/ 查找路径（按优先级；首次确定模板根目录后，本会话复用）：
 按上文相同的技能根目录规则确定；确定根目录后读取其中的 `templates/`。
@@ -361,4 +361,3 @@ Tier 3 — 深入特定模块时读取：
 
 ### 项目文件
 根据知识库中的架构描述和模块索引，结合当前任务需求，按需读取相关的项目源码、配置和资源文件。不要一次性读取整个项目，先通过知识库了解项目结构，再有针对性地读取需要的文件。不要把项目级规则文件（`AGENTS.md`、`CLAUDE.md`、`.gemini/GEMINI.md`）当作普通项目文件重复读取。
-

package/gemini-extension.json

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

package/install.ps1

@@ -16,6 +16,7 @@ $Mode = if ($env:HELLOAGENTS_MODE) { $env:HELLOAGENTS_MODE } else { "" }
 $Branch = if ($env:HELLOAGENTS_BRANCH) { $env:HELLOAGENTS_BRANCH } else { "" }
 $Package = if ($env:HELLOAGENTS_PACKAGE) { $env:HELLOAGENTS_PACKAGE } else { "" }
 $HasExplicitPackage = [bool]$Package
+$HasExplicitTarget = $false
 
 if ($env:HELLOAGENTS) {
     $Parts = $env:HELLOAGENTS.Split(":", 2)
@@ -26,6 +27,8 @@ if ($env:HELLOAGENTS) {
     if (-not $Mode -and $Parts.Count -gt 1) { $Mode = $Parts[1] }
 }
 
+$HasExplicitTarget = [bool]$Target
+
 if (-not $Target) { $Target = "all" }
 $Target = $Target.ToLowerInvariant()
 if ($Mode) { $Mode = $Mode.ToLowerInvariant() }
@@ -107,7 +110,9 @@ function Uninstall-Hosts {
 
 switch ($Action) {
     "install" {
-        Enable-PostinstallDeploy
+        if ($HasExplicitTarget) {
+            Enable-PostinstallDeploy
+        }
         Invoke-Npm -NpmArgs @("install", "-g", $Package)
     }
     "update" {
@@ -119,7 +124,9 @@ switch ($Action) {
                 Invoke-Npm -NpmArgs @("install", "-g", "helloagents")
             }
         }
-        Sync-Hosts
+        if ($HasExplicitTarget) {
+            Sync-Hosts
+        }
     }
     "cleanup" {
         Cleanup-Hosts

package/install.sh

@@ -17,6 +17,7 @@ MODE="${HELLOAGENTS_MODE:-}"
 BRANCH="${HELLOAGENTS_BRANCH:-}"
 PACKAGE="${HELLOAGENTS_PACKAGE:-}"
 HAS_EXPLICIT_PACKAGE=0
+HAS_EXPLICIT_TARGET=0
 if [ -n "$PACKAGE" ]; then
   HAS_EXPLICIT_PACKAGE=1
 fi
@@ -35,6 +36,10 @@ if [ -n "${HELLOAGENTS:-}" ]; then
   MODE="${MODE:-$SPEC_MODE}"
 fi
 
+if [ -n "$TARGET" ]; then
+  HAS_EXPLICIT_TARGET=1
+fi
+
 TARGET="${TARGET:-all}"
 TARGET="$(printf '%s' "$TARGET" | tr '[:upper:]' '[:lower:]')"
 MODE="$(printf '%s' "$MODE" | tr '[:upper:]' '[:lower:]')"
@@ -128,7 +133,9 @@ enable_postinstall_deploy() {
 
 case "$ACTION" in
   install)
-    enable_postinstall_deploy
+    if [ "$HAS_EXPLICIT_TARGET" -eq 1 ]; then
+      enable_postinstall_deploy
+    fi
     npm install -g "$PACKAGE"
     ;;
   update)
@@ -137,7 +144,9 @@ case "$ACTION" in
     else
       npm update -g helloagents || npm install -g helloagents
     fi
-    sync_hosts
+    if [ "$HAS_EXPLICIT_TARGET" -eq 1 ]; then
+      sync_hosts
+    fi
     ;;
   cleanup)
     cleanup_hosts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.35",
+  "version": "3.0.38",
   "type": "module",
   "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, unified QA gates, safety guards, and notifications.",
   "author": "HelloWind",

package/scripts/cli-doctor-codex.mjs

@@ -1,5 +1,6 @@
 import { spawnSync } from 'node:child_process'
 import { existsSync, realpathSync } from 'node:fs'
+import { platform } from 'node:os'
 import { join } from 'node:path'
 
 import { CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_CONFIG_HEADER, CODEX_PLUGIN_NAME } from './cli-codex.mjs'
@@ -147,8 +148,9 @@ function summarizeNativeCodexDoctorOutput(payload = {}) {
 }
 
 function inspectNativeCodexDoctor(runtime) {
+  const command = platform() === 'win32' ? 'codex.cmd' : 'codex'
   try {
-    const result = spawnSync('codex', ['doctor', '--json'], {
+    const result = spawnSync(command, ['doctor', '--json'], {
       cwd: process.cwd(),
       env: {
         ...process.env,
@@ -158,6 +160,7 @@ function inspectNativeCodexDoctor(runtime) {
       },
       encoding: 'utf-8',
       timeout: 20_000,
+      shell: platform() === 'win32',
       windowsHide: true,
     })
 

package/scripts/cli-doctor.mjs

@@ -106,8 +106,8 @@ function suggestDoctorFix(host, status, trackedMode) {
     return `helloagents update ${host}${trackedMode && trackedMode !== 'none' ? ` --${trackedMode}` : ''}`
   }
   if (status === 'manual-plugin') {
-    if (host === 'claude') return '/plugin marketplace add hellowind777/helloagents; /plugin install helloagents@helloagents'
-    if (host === 'gemini') return 'gemini extensions install https://github.com/hellowind777/helloagents'
+    if (host === 'claude') return '/plugin marketplace add https://github.com/hellowind777/helloagents.git; /plugin install helloagents@helloagents'
+    if (host === 'gemini') return 'helloagents install gemini --global'
   }
   if (status === 'not-installed') {
     return `helloagents install ${host} --standby`
@@ -176,7 +176,7 @@ function inspectGeminiDoctor(settings) {
   const detectedMode = normalizeDoctorMode(runtime.detectHostMode(host))
   const geminiDir = join(runtime.home, '.gemini')
   const geminiSettings = safeJson(join(geminiDir, 'settings.json')) || {}
-  const expectedHooks = readExpectedHooks('hooks.json', '${extensionPath}')
+  const expectedHooks = readExpectedHooks('hooks-gemini.json', '${extensionPath}')
   const checks = {
     carrierMarker: (safeRead(join(geminiDir, 'GEMINI.md')) || '').includes('HELLOAGENTS_START'),
     carrierContentMatch: extractManagedCarrierContent(join(geminiDir, 'GEMINI.md'))

package/scripts/cli-hosts.mjs

@@ -65,7 +65,7 @@ export function installGeminiStandby(home, pkgRoot) {
   createLink(pkgRoot, join(geminiDir, 'helloagents'));
 
   const settingsPath = join(geminiDir, 'settings.json');
-  const hooksData = loadHooksWithCliEntry(pkgRoot, 'hooks.json', '${extensionPath}');
+  const hooksData = loadHooksWithCliEntry(pkgRoot, 'hooks-gemini.json', '${extensionPath}');
   if (hooksData) mergeSettingsHooks(settingsPath, hooksData);
 
   return true;

package/scripts/cli-lifecycle-hosts.mjs

@@ -1,4 +1,5 @@
 import { spawnSync } from 'node:child_process'
+import { platform } from 'node:os'
 
 import {
   installClaudeStandby,
@@ -17,23 +18,50 @@ import { getHostLabel } from './cli-host-detect.mjs'
 
 const CLAUDE_COMMAND = process.env.HELLOAGENTS_CLAUDE_CMD || 'claude'
 const GEMINI_COMMAND = process.env.HELLOAGENTS_GEMINI_CMD || 'gemini'
-const CLAUDE_MARKETPLACE = 'hellowind777/helloagents'
+const CLAUDE_MARKETPLACE = 'https://github.com/hellowind777/helloagents.git'
 const CLAUDE_PLUGIN = 'helloagents@helloagents'
-const GEMINI_EXTENSION = 'https://github.com/hellowind777/helloagents'
+
+function normalizeCommand(command = '') {
+  return String(command || '').trim()
+}
+
+function commandCandidates(command = '') {
+  const normalized = normalizeCommand(command)
+  if (!normalized) return []
+
+  if (platform() !== 'win32') return [normalized]
+
+  const candidates = new Set([normalized])
+  if (!/\.(cmd|bat|exe|ps1)$/i.test(normalized)) {
+    candidates.add(`${normalized}.cmd`)
+    candidates.add(`${normalized}.exe`)
+  }
+  return [...candidates]
+}
 
 function runHostCommand(command, args) {
-  const needsShell = process.platform === 'win32' && /\.cmd$/i.test(command)
-  const result = spawnSync(command, args, {
-    encoding: 'utf-8',
-    errors: 'replace',
-    shell: needsShell,
-    windowsHide: true,
-  })
-  const errorMessage = result.error?.message || ''
+  const attempts = commandCandidates(command)
+  let lastResult = null
+
+  for (const candidate of attempts) {
+    const needsShell = process.platform === 'win32' && /\.(cmd|bat)$/i.test(candidate)
+    const result = spawnSync(candidate, args, {
+      encoding: 'utf-8',
+      errors: 'replace',
+      shell: needsShell,
+      windowsHide: true,
+    })
+    lastResult = result
+    if (!result.error || !['ENOENT', 'EINVAL'].includes(result.error.code)) {
+      break
+    }
+  }
+
+  const errorMessage = lastResult?.error?.message || ''
   return {
-    ok: result.status === 0,
-    missing: result.error?.code === 'ENOENT',
-    output: `${result.stdout || ''}${result.stderr || ''}${errorMessage}`.trim(),
+    ok: lastResult?.status === 0,
+    missing: ['ENOENT', 'EINVAL'].includes(lastResult?.error?.code || ''),
+    output: `${lastResult?.stdout || ''}${lastResult?.stderr || ''}${errorMessage}`.trim(),
   }
 }
 
@@ -60,8 +88,8 @@ function installClaudeGlobalPlugin() {
   return { ok: install.ok, output: install.output || add.output }
 }
 
-function installGeminiGlobalExtension() {
-  return runHostCommand(GEMINI_COMMAND, ['extensions', 'install', GEMINI_EXTENSION])
+function installGeminiGlobalExtension(runtimeRoot) {
+  return runHostCommand(GEMINI_COMMAND, ['extensions', 'link', runtimeRoot])
 }
 
 function removeClaudeGlobalPlugin() {
@@ -150,18 +178,18 @@ function installHostGlobal(runtime, host) {
       installClaudeGlobalPlugin(),
       '已自动安装 Claude Code 插件；重启 Claude Code 后生效',
       'Claude Code plugin installed automatically; restart Claude Code to apply',
-      'Claude Code 插件自动安装失败，请在 Claude Code 中执行: /plugin marketplace add hellowind777/helloagents；/plugin install helloagents@helloagents',
-      'Claude Code plugin auto-install failed. Run inside Claude Code: /plugin marketplace add hellowind777/helloagents; /plugin install helloagents@helloagents',
+      'Claude Code 插件自动安装失败，请在 Claude Code 中执行: /plugin marketplace add https://github.com/hellowind777/helloagents.git；/plugin install helloagents@helloagents',
+      'Claude Code plugin auto-install failed. Run inside Claude Code: /plugin marketplace add https://github.com/hellowind777/helloagents.git; /plugin install helloagents@helloagents',
     )
   }
   if (host === 'gemini') {
     uninstallGeminiStandby(runtime.home)
     return buildNativeResult(
-      installGeminiGlobalExtension(),
+      installGeminiGlobalExtension(runtime.pkgRoot),
       '已自动安装 Gemini CLI 扩展；重启 Gemini CLI 后生效',
       'Gemini CLI extension installed automatically; restart Gemini CLI to apply',
-      'Gemini CLI 扩展自动安装失败，请手动执行: gemini extensions install https://github.com/hellowind777/helloagents',
-      'Gemini CLI extension auto-install failed. Run manually: gemini extensions install https://github.com/hellowind777/helloagents',
+      `Gemini CLI 扩展自动安装失败，请手动执行: gemini extensions link ${runtime.pkgRoot}`,
+      `Gemini CLI extension auto-install failed. Run manually: gemini extensions link ${runtime.pkgRoot}`,
     )
   }
   uninstallCodexStandby(runtime.home)

package/scripts/cli-messages.mjs

@@ -21,9 +21,9 @@ function codexGlobalStatus({ home, msg }) {
 
 function pluginCommands() {
   return [
-    '    Claude Code:  /plugin marketplace add hellowind777/helloagents',
+    '    Claude Code:  /plugin marketplace add https://github.com/hellowind777/helloagents.git',
     '                  /plugin install helloagents@helloagents',
-    '    Gemini CLI:   gemini extensions install https://github.com/hellowind777/helloagents',
+    '    Gemini CLI:   helloagents install gemini --global',
   ].join('\n')
 }
 

package/scripts/cli-runtime-root.mjs

@@ -1,4 +1,4 @@
-import { mkdtempSync, realpathSync, renameSync } from 'node:fs'
+import { copyFileSync, existsSync, mkdtempSync, realpathSync, renameSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 
 import { copyEntries, ensureDir, removeIfExists } from './cli-utils.mjs'
@@ -63,6 +63,13 @@ function retryTransientFs(operation) {
   throw lastError
 }
 
+function materializeGeminiHooks(root) {
+  const source = join(root, 'hooks', 'hooks-gemini.json')
+  const target = join(root, 'hooks', 'hooks.json')
+  if (!existsSync(source)) return
+  copyFileSync(source, target)
+}
+
 /** Sync package runtime files into the stable root without copying repo-only files. */
 export function syncRuntimeRoot(sourceRoot, runtimeRoot) {
   const source = resolve(sourceRoot)
@@ -77,6 +84,7 @@ export function syncRuntimeRoot(sourceRoot, runtimeRoot) {
 
   try {
     copyEntries(source, staging, RUNTIME_ROOT_ENTRIES)
+    materializeGeminiHooks(staging)
     retryTransientFs(() => {
       removeIfExists(target)
       renameSync(staging, target)

package/scripts/notify-sound.mjs

@@ -24,7 +24,8 @@ export function buildWindowsSoundCommand(filePath = '') {
 }
 
 function playWindows(filePath) {
-  const result = spawnSync('powershell', [
+  const command = process.platform === 'win32' ? 'powershell.exe' : 'powershell'
+  const result = spawnSync(command, [
     '-NoProfile',
     '-c',
     buildWindowsSoundCommand(filePath),

package/scripts/notify.mjs

@@ -349,6 +349,10 @@ function attachTurnSession(payload = {}, cwd = payload.cwd || process.cwd()) {
     allowPpidFallback: !isProjectRuntimeActive(cwd),
   });
   if (!sessionId || payload.sessionId) return payload;
+  const aliasSource = String(process.env.HELLOAGENTS_NOTIFY_SESSION_ID || process.env.WT_SESSION || process.env.TERM_SESSION_ID || process.env.WINDOWID || '').trim();
+  if (aliasSource) {
+    return { ...payload, sessionId, _helloagentsSessionAlias: aliasSource };
+  }
   return { ...payload, sessionId };
 }