helloagents 3.0.35 → 3.0.37

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.37",
   "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.37",
   "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.37-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)
@@ -189,6 +189,8 @@ HelloAGENTS now resolves the current state file from `state_path`:
 
 `<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.
 
+For project-local sessions, HelloAGENTS now only uses stable host identifiers such as `sessionId`, `conversationId`, `threadId`, or `HELLOAGENTS_NOTIFY_SESSION_ID`. It no longer uses terminal/window ids such as `WT_SESSION`, `TERM_SESSION_ID`, or `WINDOWID` to create extra project session 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.
 
 ### 6) Verification and delivery evidence
@@ -206,6 +208,9 @@ Runtime state now stays intentionally small:
 - `~/.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.
+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 +309,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 +410,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 +447,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.

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.37-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)
@@ -189,6 +189,8 @@ HelloAGENTS 现在只从 `state_path` 解析当前状态文件：
 
 `<workspace>` 是当前 Git 分支、detached HEAD 的 `detached-<sha>`，或非 Git 项目的 `workspace`。`.helloagents/sessions/active.json` 只记录当前活跃会话索引。
 
+对于项目本地会话目录，HelloAGENTS 现在只使用稳定宿主标识，如 `sessionId`、`conversationId`、`threadId` 或 `HELLOAGENTS_NOTIFY_SESSION_ID`。它不再使用 `WT_SESSION`、`TERM_SESSION_ID`、`WINDOWID` 这类终端或窗口标识去额外生成项目会话目录。
+
 `STATE.md` 只记录当前工作流做到哪里，不承担所有对话的统一记忆。Codex `/goal` 也不替代 `state_path`、`turn-state` 或本地证据文件；它只负责 Codex 侧的长程续跑。
 
 ### 6）验证与交付证据
@@ -206,6 +208,9 @@ HelloAGENTS 不把“命令通过”和“任务完成”简单画等号。交
 - 仅用于 Codex 原生收尾去重的 `~/.codex/.helloagents/notify-state.json`
 
 `turn-state`、路由上下文和 artifact 索引都写进 `STATE.md` 的元数据，不再单独生成 `capsule.json`。`events.jsonl` 改为可选 trace 输出，默认不写。
+项目本地 `STATE.md` 现在会更晚创建；旧版残留的项目根 `.helloagents/artifacts/*.log` 也会自动清理，不再继续充当第二套历史系统。
+
+标准运行态证据和临时运行态现在默认 72 小时过期。只有工作流明确需要的长程 Codex goal 链路，才继续保留 720 小时上限。
 
 交付门控、守卫和 QA gate 提示使用执行性表述，例如处理路径、收尾动作和视觉验收动作。阻塞流程会说明下一步要做什么，而不是把可执行步骤写成泛化建议。最终回复还会强制只保留一个 HelloAGENTS 外层块，避免同一条回复重复输出完成标题。
 这个外层格式现在只保留给直接面向最终用户的终局交付。中间汇报、委派任务结果和子代理回复都保持自然输出；子代理结束钩子也会拦截错误的外层收尾格式。
@@ -304,7 +309,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 +410,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 +447,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。

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.35",
+  "version": "3.0.37",
   "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" {

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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.35",
+  "version": "3.0.37",
   "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/project-session-cleanup.mjs

@@ -10,9 +10,11 @@ import {
   writeJsonFileAtomic,
 } from './runtime-scope.mjs'
 import { LONG_RUNNING_TTL_MS } from './runtime-ttl.mjs'
+import { readStateDocument } from './state-document.mjs'
 
 export const PROJECT_SESSION_CLEANUP_COOLDOWN_MS = 10 * 60 * 1000
 export const PROJECT_SESSION_MAX_AGE_MS = LONG_RUNNING_TTL_MS
+const AUTO_CREATED_STATE_MARKER = '由运行时自动创建；后续按实际任务重写'
 
 function removePath(filePath, result, bucket) {
   try {
@@ -23,6 +25,10 @@ function removePath(filePath, result, bucket) {
   }
 }
 
+function isDebugLog(entryName = '') {
+  return /\.log$/i.test(entryName)
+}
+
 function isDirectoryEmptyRecursive(dirPath) {
   const entries = readdirSync(dirPath, { withFileTypes: true })
   if (entries.length === 0) return true
@@ -55,6 +61,15 @@ function hasStateSnapshot(sessionDir) {
   return existsSync(join(sessionDir, 'STATE.md'))
 }
 
+function isAutoCreatedSeedSession(sessionDir) {
+  const statePath = join(sessionDir, 'STATE.md')
+  if (!existsSync(statePath)) return false
+
+  const { metadata, body } = readStateDocument(statePath)
+  if (metadata && typeof metadata === 'object' && Object.keys(metadata).length > 0) return false
+  return String(body || '').includes(AUTO_CREATED_STATE_MARKER)
+}
+
 function readSessionStateMtimeMs(sessionDir) {
   try {
     return statSync(join(sessionDir, 'STATE.md')).mtimeMs
@@ -79,6 +94,32 @@ function cleanupTransientSessionTemps(sessionsDir, result) {
   }
 }
 
+function cleanupLegacyProjectArtifacts(activationDir, result) {
+  const artifactsDir = join(activationDir, 'artifacts')
+  if (!existsSync(artifactsDir)) return
+
+  let removableEntries = []
+  try {
+    removableEntries = readdirSync(artifactsDir, { withFileTypes: true })
+  } catch (error) {
+    result.errors.push(`${artifactsDir}: ${error.message}`)
+    return
+  }
+
+  for (const entry of removableEntries) {
+    if (!entry.isFile() || !isDebugLog(entry.name)) continue
+    removePath(join(artifactsDir, entry.name), result, 'removedLegacyArtifacts')
+  }
+
+  try {
+    if (isDirectoryEmptyRecursive(artifactsDir)) {
+      removePath(artifactsDir, result, 'removedLegacyArtifacts')
+    }
+  } catch (error) {
+    result.errors.push(`${artifactsDir}: ${error.message}`)
+  }
+}
+
 export function cleanupProjectSessions(cwd, { now = Date.now(), minIntervalMs = 0, maxAgeMs = PROJECT_SESSION_MAX_AGE_MS } = {}) {
   const projectRoot = getProjectRoot(cwd)
   const activationDir = getProjectActivationDir(projectRoot)
@@ -90,7 +131,9 @@ export function cleanupProjectSessions(cwd, { now = Date.now(), minIntervalMs =
     removedEmptyDirs: [],
     removedInactiveDirs: [],
     removedNoStateDirs: [],
+    removedSeedDirs: [],
     removedTempFiles: [],
+    removedLegacyArtifacts: [],
     errors: [],
     skipped: false,
   }
@@ -109,6 +152,7 @@ export function cleanupProjectSessions(cwd, { now = Date.now(), minIntervalMs =
   } catch (error) {
     result.errors.push(`${sessionsDir}: ${error.message}`)
   }
+  cleanupLegacyProjectArtifacts(activationDir, result)
 
   for (const workspaceEntry of readdirSync(sessionsDir, { withFileTypes: true })) {
     if (!workspaceEntry.isDirectory()) continue
@@ -124,6 +168,8 @@ export function cleanupProjectSessions(cwd, { now = Date.now(), minIntervalMs =
           removePath(sessionDir, result, 'removedEmptyDirs')
         } else if (!hasStateSnapshot(sessionDir)) {
           removePath(sessionDir, result, 'removedNoStateDirs')
+        } else if (isAutoCreatedSeedSession(sessionDir)) {
+          removePath(sessionDir, result, 'removedSeedDirs')
         } else if (isStaleStateSession(sessionDir, now, maxAgeMs)) {
           removePath(sessionDir, result, 'removedInactiveDirs')
         }

package/scripts/runtime-artifacts.mjs

@@ -7,7 +7,7 @@ import {
   readSessionArtifact,
   writeSessionArtifact,
 } from './session-capsule.mjs'
-import { EVIDENCE_MAX_AGE_MS, LONG_RUNNING_TTL_HOURS } from './runtime-ttl.mjs'
+import { EVIDENCE_MAX_AGE_MS, LONG_RUNNING_TTL_HOURS, STANDARD_RUNTIME_TTL_HOURS } from './runtime-ttl.mjs'
 
 export { EVIDENCE_MAX_AGE_MS }
 
@@ -87,7 +87,7 @@ export function validateEvidenceTimestamp(evidence, now, label) {
       required: true,
       status: 'stale-time',
       evidence,
-      details: [`${label}超过 ${LONG_RUNNING_TTL_HOURS} 小时`],
+      details: [`${label}超过 ${STANDARD_RUNTIME_TTL_HOURS} 小时（长任务上限：${LONG_RUNNING_TTL_HOURS} 小时）`],
     }
   }
   return null

package/scripts/runtime-scope.mjs

@@ -4,7 +4,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync,
 import { dirname, join, normalize, resolve } from 'node:path'
 import { homedir } from 'node:os'
 
-import { resolveSessionToken } from './session-token.mjs'
+import { resolveProjectSessionToken, resolveSessionToken } from './session-token.mjs'
 import { USER_RUNTIME_MAX_AGE_MS } from './runtime-ttl.mjs'
 import { cleanupUserRuntimeRoot, getUserRuntimeRoot } from './runtime-user-cleanup.mjs'
 import { FULL_CARRIER_PROFILE_MARKER } from './cli-utils.mjs'
@@ -323,21 +323,14 @@ function findProjectActivationDir(cwd) {
 
 function resolvePayloadSessionToken(payload = {}) {
   if (payload?._helloagentsSessionAlias) return ''
-  return resolveSessionToken({
+  return resolveProjectSessionToken({
     payload,
     env: {},
-    ppid: 0,
-    allowPpidFallback: false,
   })
 }
 
 function resolveEnvSessionToken(env = process.env) {
-  return resolveSessionToken({
-    payload: {},
-    env,
-    ppid: 0,
-    allowPpidFallback: false,
-  })
+  return resolveProjectSessionToken({ payload: {}, env })
 }
 
 function resolveTransientSessionToken({ payload = {}, env = process.env, ppid = process.ppid } = {}) {
@@ -437,11 +430,21 @@ function chooseProjectSession({ payload, env, activationDir, projectRoot, worksp
   return { session: DEFAULT_STATE_SESSION_TOKEN, sessionMode: 'default' }
 }
 
+function removeLegacyProjectArtifacts(activationDir) {
+  if (!activationDir) return
+  const artifactsDir = join(activationDir, PROJECT_ARTIFACTS_DIR_NAME)
+  if (!existsSync(artifactsDir)) return
+  try {
+    rmSync(artifactsDir, { recursive: true, force: true })
+  } catch {}
+}
+
 export function getProjectSessionScope(cwd, options = {}) {
   const normalizedCwd = normalizePath(cwd || process.cwd())
   const projectRoot = getProjectRoot(normalizedCwd)
   const { payload = {}, env = process.env } = normalizeRuntimeOptions(options)
   const activationDir = getProjectActivationDir(projectRoot)
+  removeLegacyProjectArtifacts(activationDir)
   const workspace = resolveWorkspaceName(projectRoot)
   const { session, sessionMode } = chooseProjectSession({
     payload,

package/scripts/runtime-ttl.mjs

@@ -1,7 +1,10 @@
 export const LONG_RUNNING_TTL_HOURS = 720
 export const LONG_RUNNING_TTL_MS = LONG_RUNNING_TTL_HOURS * 60 * 60 * 1000
 
-export const ROUTE_CONTEXT_TTL_MS = LONG_RUNNING_TTL_MS
-export const TURN_STATE_TTL_MS = LONG_RUNNING_TTL_MS
-export const EVIDENCE_MAX_AGE_MS = LONG_RUNNING_TTL_MS
-export const USER_RUNTIME_MAX_AGE_MS = LONG_RUNNING_TTL_MS
+export const STANDARD_RUNTIME_TTL_HOURS = 72
+export const STANDARD_RUNTIME_TTL_MS = STANDARD_RUNTIME_TTL_HOURS * 60 * 60 * 1000
+
+export const ROUTE_CONTEXT_TTL_MS = STANDARD_RUNTIME_TTL_MS
+export const TURN_STATE_TTL_MS = STANDARD_RUNTIME_TTL_MS
+export const EVIDENCE_MAX_AGE_MS = STANDARD_RUNTIME_TTL_MS
+export const USER_RUNTIME_MAX_AGE_MS = STANDARD_RUNTIME_TTL_MS

package/scripts/session-capsule.mjs

@@ -68,6 +68,21 @@ function getScope(cwd, options = {}) {
   return getRuntimeScope(cwd, normalizedOptions)
 }
 
+function shouldMaterializeSessionState(options = {}) {
+  const normalizedOptions = normalizeOptions(options)
+  if (normalizedOptions.ensureProjectLocal === true) return true
+  if (normalizedOptions.project === true) return true
+  if (normalizedOptions.traceEvents === true) return true
+
+  const payload = normalizedOptions.payload || {}
+  if (payload.traceEvents === true || payload._helloagentsTraceEvents === true) return true
+
+  const raw = String(normalizedOptions.env?.HELLOAGENTS_TRACE_EVENTS || process.env.HELLOAGENTS_TRACE_EVENTS || '')
+    .trim()
+    .toLowerCase()
+  return raw === '1' || raw === 'true' || raw === 'yes'
+}
+
 export function getSessionCapsulePath(cwd = process.cwd(), options = {}) {
   return getScope(cwd, options).statePath
 }
@@ -113,9 +128,10 @@ export function readSessionCapsule(cwd = process.cwd(), options = {}) {
 export function writeSessionCapsule(cwd, capsule, options = {}) {
   const normalizedOptions = normalizeOptions(options)
   const scope = getScope(cwd, normalizedOptions)
+  const shouldMaterialize = shouldMaterializeSessionState(normalizedOptions)
   const currentDocument = readStateDocument(scope.statePath)
   const hasBody = Boolean(currentDocument.body && currentDocument.body.trim())
-  if (!hasBody && normalizedOptions.ensureProjectLocal !== true && !existsSync(scope.statePath)) {
+  if (!hasBody && !shouldMaterialize && !existsSync(scope.statePath)) {
     return {
       ...buildEmptyCapsule(scope),
       ...capsule,
@@ -129,6 +145,14 @@ export function writeSessionCapsule(cwd, capsule, options = {}) {
       updatedAt: new Date().toISOString(),
     }
   }
+  if (!hasBody && shouldMaterialize && !existsSync(scope.statePath)) {
+    ensureProjectLocalRuntime(cwd, {
+      ...normalizedOptions,
+      stateSeed: normalizedOptions.stateSeed && typeof normalizedOptions.stateSeed === 'object'
+        ? normalizedOptions.stateSeed
+        : {},
+    })
+  }
   const nextCapsule = {
     ...buildEmptyCapsule(scope),
     ...capsule,

package/scripts/session-token.mjs

@@ -17,6 +17,19 @@ const PAYLOAD_SESSION_KEYS = [
   'tab',
 ]
 
+const PROJECT_PAYLOAD_SESSION_KEYS = [
+  'sessionId',
+  'session_id',
+  'session',
+  'conversationId',
+  'conversation_id',
+  'conversation',
+  'threadId',
+  'thread_id',
+  'thread-id',
+  'thread',
+]
+
 const ENV_SESSION_KEYS = [
   'HELLOAGENTS_NOTIFY_SESSION_ID',
   'WT_SESSION',
@@ -28,6 +41,10 @@ const ENV_SESSION_KEYS = [
   'TAB_ID',
 ]
 
+const PROJECT_ENV_SESSION_KEYS = [
+  'HELLOAGENTS_NOTIFY_SESSION_ID',
+]
+
 function readStringCandidate(input, key) {
   if (!input || typeof input !== 'object') return ''
   const value = input[key]
@@ -50,23 +67,41 @@ export function sanitizeSessionToken(value = '') {
   return cleaned.slice(0, 8)
 }
 
+function resolveTokenFromKeys(input, keys = []) {
+  for (const key of keys) {
+    const value = sanitizeSessionToken(readStringCandidate(input, key))
+    if (value) return value
+  }
+  return ''
+}
+
 export function resolveSessionToken({
   payload = {},
   env = process.env,
   ppid = process.ppid,
   allowPpidFallback = true,
 } = {}) {
-  for (const key of PAYLOAD_SESSION_KEYS) {
-    const value = sanitizeSessionToken(readStringCandidate(payload, key))
-    if (value) return value
-  }
+  const payloadToken = resolveTokenFromKeys(payload, PAYLOAD_SESSION_KEYS)
+  if (payloadToken) return payloadToken
 
-  for (const key of ENV_SESSION_KEYS) {
-    const value = sanitizeSessionToken(env?.[key] || '')
-    if (value) return value
-  }
+  const envToken = resolveTokenFromKeys(env, ENV_SESSION_KEYS)
+  if (envToken) return envToken
 
   return allowPpidFallback && ppid ? String(ppid) : ''
 }
 
-export { ENV_SESSION_KEYS, PAYLOAD_SESSION_KEYS }
+export function resolveProjectSessionToken({
+  payload = {},
+  env = process.env,
+} = {}) {
+  const payloadToken = resolveTokenFromKeys(payload, PROJECT_PAYLOAD_SESSION_KEYS)
+  if (payloadToken) return payloadToken
+  return resolveTokenFromKeys(env, PROJECT_ENV_SESSION_KEYS)
+}
+
+export {
+  ENV_SESSION_KEYS,
+  PAYLOAD_SESSION_KEYS,
+  PROJECT_ENV_SESSION_KEYS,
+  PROJECT_PAYLOAD_SESSION_KEYS,
+}