helloagents 3.0.21 → 3.0.22

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.21",
+  "version": "3.0.22",
   "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.21",
+  "version": "3.0.22",
   "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.21-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.22-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)
@@ -645,6 +645,7 @@ Codex is rules-file driven by default.
 - standby creates `~/.codex/helloagents -> ~/.helloagents/helloagents`
 - global mode installs the native local-plugin chain and also loads silent hooks from `~/.codex/hooks.json`
 - Codex hooks only synchronize runtime state and enforce Stop gates; they do not inject HelloAGENTS rules or route text through hook output
+- Codex closeout de-duplicates Stop hooks and native `codex-notify`, so one turn does not notify twice
 - `/goal` remains Codex-native. Enable it explicitly with `helloagents codex goals enable` when long-running plan execution is needed
 - Goal-aware commands resume from `tasks.md`, `contract.json`, and `state_path`; they do not create goals automatically or mark them complete before HelloAGENTS verification and closeout
 
@@ -656,7 +657,7 @@ Run all tests:
 npm test
 ```
 
-The current test suite covers:
+The current suite includes 103 tests and covers:
 
 - install, update, uninstall, cleanup, and mode switching
 - Claude, Gemini, and Codex config merge and restore behavior

package/README_CN.md

@@ -8,7 +8,7 @@
 
 **面向 AI 编码 CLI 的工作流层：技能、知识库、交付检查、更安全的配置写入，以及可恢复的执行流程。**
 
-[![Version](https://img.shields.io/badge/version-3.0.21-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.22-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)
@@ -647,6 +647,7 @@ Codex 默认走规则文件驱动。
 - 标准模式创建 `~/.codex/helloagents -> ~/.helloagents/helloagents`
 - 全局模式安装原生本地插件流程，并同样用 `~/.codex/hooks.json` 加载静默 hooks
 - Codex hooks 只做静默运行态同步和 Stop 门禁，不通过 hook 注入 HelloAGENTS 规则或路由说明
+- Codex 收尾会对 Stop hook 和原生 `codex-notify` 去重，避免同一轮重复通知
 - `/goal` 保持 Codex 原生能力；需要长程执行时，用 `helloagents codex goals enable` 显式启用
 - 感知 goal 的命令从 `tasks.md`、`contract.json` 和 `state_path` 恢复；不会自动创建 goal，也不会在 HelloAGENTS 验证和收尾前标记完成
 
@@ -658,7 +659,7 @@ Codex 默认走规则文件驱动。
 npm test
 ```
 
-当前测试覆盖：
+当前测试共 103 项，覆盖：
 
 - 安装、更新、卸载、清理和模式切换
 - Claude、Gemini、Codex 的配置合并与恢复

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.21",
+  "version": "3.0.22",
   "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.21",
+  "version": "3.0.22",
   "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",

package/scripts/notify-closeout.mjs

@@ -0,0 +1,213 @@
+import { createHash } from 'node:crypto'
+import { closeSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+import { getRuntimeEvidencePath, readRuntimeEvidence, writeRuntimeEvidence } from './runtime-artifacts.mjs'
+
+export const CODEX_CLOSEOUT_EVIDENCE_FILE = 'codex-native-stop.json'
+const CODEX_CLOSEOUT_LOCK_FILE = 'codex-native-stop.lock'
+const WEAK_KEY_TTL_MS = 10_000
+const LOCK_STALE_MS = 120_000
+
+function getTurnId(payload = {}) {
+  return String(payload.turnId || payload.turn_id || payload['turn-id'] || '').trim()
+}
+
+function getSessionId(payload = {}) {
+  return String(payload.sessionId || payload.session_id || payload['session-id'] || '').trim()
+}
+
+function normalizeMessage(message = '') {
+  return String(message || '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 240)
+}
+
+function hashValue(value = '') {
+  return createHash('sha1').update(String(value)).digest('hex').slice(0, 16)
+}
+
+function uniqueKeys(values = []) {
+  return Array.from(new Set(values.filter(Boolean)))
+}
+
+function readLockPayload(lockPath) {
+  try {
+    return JSON.parse(readFileSync(lockPath, 'utf-8'))
+  } catch {
+    return null
+  }
+}
+
+function isLockStale(lockPath, now = Date.now()) {
+  try {
+    const stat = statSync(lockPath)
+    return now - stat.mtimeMs > LOCK_STALE_MS
+  } catch {
+    return false
+  }
+}
+
+function writeLockFile(lockPath, payload) {
+  mkdirSync(dirname(lockPath), { recursive: true })
+  const fd = openSync(lockPath, 'wx')
+  try {
+    writeFileSync(fd, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8')
+  } finally {
+    closeSync(fd)
+  }
+}
+
+function releaseLockFile(lockPath) {
+  try {
+    unlinkSync(lockPath)
+  } catch {}
+}
+
+function intersects(left = [], right = []) {
+  if (!left.length || !right.length) return false
+  const rightSet = new Set(right)
+  return left.some((item) => rightSet.has(item))
+}
+
+export function buildCodexCloseoutSnapshot({ payload = {}, turnState = null } = {}) {
+  const turnId = getTurnId(payload)
+  const sessionId = getSessionId(payload)
+  const message = normalizeMessage(
+    payload.lastAssistantMessage
+    || payload.last_assistant_message
+    || payload['last-assistant-message']
+    || '',
+  )
+  const messageHash = message ? hashValue(message) : ''
+
+  const strongKeys = uniqueKeys([
+    turnId ? `turn:${turnId}` : '',
+    turnState?.key && turnState?.updatedAt
+      ? `state:${turnState.key}:${turnState.updatedAt}`
+      : '',
+  ])
+  const weakKeys = uniqueKeys([
+    sessionId && messageHash ? `session-message:${sessionId}:${messageHash}` : '',
+    !sessionId && messageHash ? `message:${messageHash}` : '',
+  ])
+
+  return {
+    turnId,
+    sessionId,
+    messageHash,
+    strongKeys,
+    weakKeys,
+  }
+}
+
+export function matchesCodexCloseoutEvidence(evidence, snapshot, now = Date.now()) {
+  if (!evidence || typeof evidence !== 'object') return false
+
+  const strongKeys = Array.isArray(evidence.strongKeys) ? evidence.strongKeys : []
+  const weakKeys = Array.isArray(evidence.weakKeys) ? evidence.weakKeys : []
+  if (intersects(snapshot.strongKeys, strongKeys)) return true
+
+  const currentHasStrong = snapshot.strongKeys.length > 0
+  const evidenceHasStrong = strongKeys.length > 0
+  if (currentHasStrong && evidenceHasStrong) return false
+
+  const updatedAt = Date.parse(evidence.updatedAt || '')
+  if (!Number.isFinite(updatedAt) || now - updatedAt > WEAK_KEY_TTL_MS) return false
+  return intersects(snapshot.weakKeys, weakKeys)
+}
+
+/**
+ * Try to claim the current Codex closeout so Stop and native notify handle one turn only once.
+ */
+export function beginCodexCloseoutClaim(cwd, { payload = {}, turnState = null, source = '' } = {}) {
+  const snapshot = buildCodexCloseoutSnapshot({ payload, turnState })
+  const lockPath = getRuntimeEvidencePath(cwd, CODEX_CLOSEOUT_LOCK_FILE, { payload })
+  const evidencePath = getRuntimeEvidencePath(cwd, CODEX_CLOSEOUT_EVIDENCE_FILE, { payload })
+  const now = Date.now()
+  const lockPayload = {
+    source,
+    pid: process.pid,
+    createdAt: new Date(now).toISOString(),
+    turnId: snapshot.turnId,
+    sessionId: snapshot.sessionId,
+  }
+
+  try {
+    writeLockFile(lockPath, lockPayload)
+  } catch (error) {
+    if (error?.code === 'EEXIST' && isLockStale(lockPath, now)) {
+      releaseLockFile(lockPath)
+      try {
+        writeLockFile(lockPath, lockPayload)
+      } catch (retryError) {
+        if (retryError?.code !== 'EEXIST') throw retryError
+      }
+    } else if (error?.code !== 'EEXIST') {
+      throw error
+    }
+  }
+
+  const lockOwner = readLockPayload(lockPath)
+  if (
+    !lockOwner
+    || lockOwner.createdAt !== lockPayload.createdAt
+    || lockOwner.source !== source
+    || lockOwner.pid !== process.pid
+  ) {
+    return {
+      claimed: false,
+      reason: 'busy',
+      snapshot,
+      evidencePath,
+    }
+  }
+
+  const evidence = readRuntimeEvidence(cwd, CODEX_CLOSEOUT_EVIDENCE_FILE, { payload })
+  if (matchesCodexCloseoutEvidence(evidence, snapshot, now)) {
+    releaseLockFile(lockPath)
+    return {
+      claimed: false,
+      reason: 'duplicate',
+      snapshot,
+      evidencePath,
+    }
+  }
+
+  return {
+    claimed: true,
+    cwd,
+    payload,
+    source,
+    lockPath,
+    evidencePath,
+    snapshot,
+  }
+}
+
+/**
+ * Persist the handled closeout fingerprint and release the in-flight lock.
+ */
+export function finalizeCodexCloseoutClaim(claim, meta = {}) {
+  if (!claim?.claimed) return
+
+  try {
+    if (meta.handled !== false) {
+      writeRuntimeEvidence(claim.cwd, CODEX_CLOSEOUT_EVIDENCE_FILE, {
+        version: 2,
+        updatedAt: new Date().toISOString(),
+        source: meta.source || claim.source || '',
+        turnKind: meta.turnKind || '',
+        event: meta.event || '',
+        turnId: claim.snapshot.turnId,
+        sessionId: claim.snapshot.sessionId,
+        messageHash: claim.snapshot.messageHash,
+        strongKeys: claim.snapshot.strongKeys,
+        weakKeys: claim.snapshot.weakKeys,
+      }, { payload: claim.payload })
+    }
+  } finally {
+    releaseLockFile(claim.lockPath)
+  }
+}

package/scripts/notify.mjs

@@ -7,6 +7,7 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { playSound as _playSound, desktopNotify as _desktopNotify } from './notify-ui.mjs';
+import { beginCodexCloseoutClaim, finalizeCodexCloseoutClaim } from './notify-closeout.mjs';
 import { resolveNotificationSource } from './notify-source.mjs';
 import { buildCompactionContext, buildInjectContext, buildRouteInstruction, buildSemanticRouteInstruction, resolveCanonicalCommandSkill } from './notify-context.mjs';
 import { resolveNotifyHost, shouldIgnoreCodexNotifyClient } from './notify-events.mjs';
@@ -16,7 +17,6 @@ import { cleanupProjectSessions } from './project-session-cleanup.mjs';
 import { handleRouteCommand, resolveBootstrapFile } from './notify-route.mjs';
 import { readSettings, readStdinJson, output, suppressedOutput, emptySuppress } from './notify-shared.mjs';
 import { clearRouteContext, getApplicableRouteContext, writeRouteContext } from './runtime-context.mjs';
-import { readRuntimeEvidence, writeRuntimeEvidence } from './runtime-artifacts.mjs';
 import { appendReplayEvent, startReplaySession } from './replay-state.mjs';
 import { clearTurnState, readTurnState } from './turn-state.mjs';
 import { getWorkflowRecommendation } from './workflow-state.mjs';
@@ -38,7 +38,6 @@ const EVENT_NAME = {
   PreCompact: IS_GEMINI ? 'BeforeAgent' : 'PreCompact',
 };
 const RALPH_LOOP_ROUTE_COMMANDS = new Set(['verify', 'loop']);
-const CODEX_NATIVE_STOP_FILE = 'codex-native-stop.json';
 
 const playSound = (event) => _playSound(PKG_ROOT, event);
 const desktopNotify = (event, extra) => _desktopNotify(PKG_ROOT, event, extra);
@@ -140,27 +139,6 @@ function attachTurnSession(payload = {}, cwd = payload.cwd || process.cwd()) {
   return { ...payload, sessionId };
 }
 
-function getCodexTurnId(payload = {}) {
-  return String(payload.turnId || payload.turn_id || payload['turn-id'] || '').trim();
-}
-
-function markCodexNativeStopProcessed(cwd, payload = {}) {
-  if (!IS_CODEX) return;
-  const turnId = getCodexTurnId(payload);
-  if (!turnId) return;
-  writeRuntimeEvidence(cwd, CODEX_NATIVE_STOP_FILE, {
-    turnId,
-    updatedAt: new Date().toISOString(),
-  }, { payload });
-}
-
-function hasCodexNativeStopProcessed(cwd, payload = {}) {
-  const turnId = getCodexTurnId(payload);
-  if (!turnId) return false;
-  const evidence = readRuntimeEvidence(cwd, CODEX_NATIVE_STOP_FILE, { payload });
-  return evidence?.turnId === turnId;
-}
-
 function readMainTurnState(cwd, payload = {}) {
   const turnState = readTurnState(cwd, { payload });
   return turnState?.role === 'main' ? turnState : null;
@@ -175,6 +153,43 @@ function shouldProcessCloseout(turnState) {
   return false;
 }
 
+function processTurnCloseout(payload, turnPayload, turnState, settings = getSettings()) {
+  const cwd = turnPayload.cwd || process.cwd();
+
+  if (runTurnStopGate(turnPayload)) {
+    if (turnState && turnState.kind !== 'complete') consumeMainTurnState(cwd, turnState, turnPayload);
+    return { blocked: true };
+  }
+
+  if (!turnState) {
+    notifyByLevel('complete', buildNotifyExtra(turnPayload), settings);
+    clearRouteContext({ cwd, payload: turnPayload });
+    return { blocked: false };
+  }
+
+  if (turnState.kind !== 'complete') {
+    consumeMainTurnState(cwd, turnState, turnPayload);
+    clearRouteContext({ cwd, payload: turnPayload });
+    return { blocked: false };
+  }
+
+  if (runRalphLoop(turnPayload, { turnState })) {
+    consumeMainTurnState(cwd, turnState, turnPayload);
+    notifyByLevel('warning', buildNotifyExtra(payload), settings);
+    return { blocked: true };
+  }
+  if (runDeliveryGate(turnPayload)) {
+    consumeMainTurnState(cwd, turnState, turnPayload);
+    notifyByLevel('warning', buildNotifyExtra(payload), settings);
+    return { blocked: true };
+  }
+
+  notifyByLevel('complete', buildNotifyExtra(payload), settings);
+  consumeMainTurnState(cwd, turnState, turnPayload);
+  clearRouteContext({ cwd, payload: turnPayload });
+  return { blocked: false };
+}
+
 function cmdPreCompact() {
   const payload = readPayloadFromStdin();
   const cwd = payload.cwd || process.cwd();
@@ -275,37 +290,29 @@ function cmdStop() {
   const payload = readPayloadFromStdin();
   const cwd = payload.cwd || process.cwd();
   const turnPayload = attachTurnSession(payload, cwd);
-  if (IS_CODEX && hasCodexNativeStopProcessed(cwd, turnPayload)) {
-    emptySuppress();
-    return;
-  }
   const turnState = readMainTurnState(cwd, turnPayload);
-  if (runTurnStopGate(turnPayload)) {
-    if (turnState && turnState.kind !== 'complete') consumeMainTurnState(cwd, turnState, turnPayload);
-    markCodexNativeStopProcessed(cwd, turnPayload);
-    return;
-  }
-  const shouldProcess = shouldProcessCloseout(turnState);
-  if (shouldProcess && runRalphLoop(turnPayload, { turnState })) {
-    consumeMainTurnState(cwd, turnState, turnPayload);
-    notifyByLevel('warning', buildNotifyExtra(payload));
-    markCodexNativeStopProcessed(cwd, turnPayload);
-    return;
-  }
-  if (shouldProcess && runDeliveryGate(turnPayload)) {
-    consumeMainTurnState(cwd, turnState, turnPayload);
-    notifyByLevel('warning', buildNotifyExtra(payload));
-    markCodexNativeStopProcessed(cwd, turnPayload);
+  const closeoutClaim = IS_CODEX
+    ? beginCodexCloseoutClaim(cwd, { payload: turnPayload, turnState, source: 'stop' })
+    : null;
+  if (IS_CODEX && !closeoutClaim?.claimed) {
+    emptySuppress();
     return;
   }
 
-  const settings = getSettings();
-  if (shouldProcess || !turnState) {
-    notifyByLevel('complete', buildNotifyExtra(payload), settings);
+  let handled = false;
+  let result = { blocked: false };
+  try {
+    result = processTurnCloseout(payload, turnPayload, turnState, getSettings());
+    handled = true;
+  } finally {
+    finalizeCodexCloseoutClaim(closeoutClaim, {
+      handled,
+      source: 'stop',
+      event: 'stop',
+      turnKind: turnState?.kind || '',
+    });
   }
-  consumeMainTurnState(cwd, turnState, turnPayload);
-  clearRouteContext({ cwd, payload: turnPayload });
-  markCodexNativeStopProcessed(cwd, turnPayload);
+  if (result.blocked) return;
   emptySuppress();
 }
 
@@ -333,39 +340,27 @@ function cmdCodexNotify() {
     return;
   }
   if (type !== 'agent-turn-complete') return;
-  if (hasCodexNativeStopProcessed(cwd, turnPayload)) return;
 
   const turnState = readMainTurnState(cwd, turnPayload);
-  if (runTurnStopGate(turnPayload)) {
-    if (turnState && turnState.kind !== 'complete') consumeMainTurnState(cwd, turnState, turnPayload);
-    return;
-  }
-  if (!turnState) {
-    notifyByLevel('complete', buildNotifyExtra(data), getSettings());
-    clearRouteContext({ cwd, payload: turnPayload });
-    return;
-  }
-  if (turnState.kind !== 'complete') {
-    consumeMainTurnState(cwd, turnState, turnPayload);
-    clearRouteContext({ cwd, payload: turnPayload });
-    return;
-  }
+  const closeoutClaim = beginCodexCloseoutClaim(cwd, {
+    payload: turnPayload,
+    turnState,
+    source: 'codex-notify',
+  });
+  if (!closeoutClaim.claimed) return;
 
-  const settings = getSettings();
-  if (runRalphLoop(turnPayload, { turnState })) {
-    consumeMainTurnState(cwd, turnState, turnPayload);
-    notifyByLevel('warning', buildNotifyExtra(data), settings);
-    return;
-  }
-  if (runDeliveryGate(turnPayload)) {
-    consumeMainTurnState(cwd, turnState, turnPayload);
-    notifyByLevel('warning', buildNotifyExtra(data), settings);
-    return;
+  let handled = false;
+  try {
+    processTurnCloseout(data, turnPayload, turnState, getSettings());
+    handled = true;
+  } finally {
+    finalizeCodexCloseoutClaim(closeoutClaim, {
+      handled,
+      source: 'codex-notify',
+      event: type,
+      turnKind: turnState?.kind || '',
+    });
   }
-
-  notifyByLevel('complete', buildNotifyExtra(data), settings);
-  consumeMainTurnState(cwd, turnState, turnPayload);
-  clearRouteContext({ cwd, payload: turnPayload });
 }
 
 switch (cmd) {