helloagents 3.0.23 → 3.0.25

package/scripts/cli-codex.mjs

@@ -1,8 +1,8 @@
 import { join, dirname } from 'node:path';
 import { existsSync } from 'node:fs';
 import {
-  ensureDir, safeRead, safeWrite, removeIfExists,
-  readJsonOrThrow, copyEntries,
+  ensureDir, safeJson, safeRead, safeWrite, removeIfExists,
+  readJsonOrThrow,
   createLink, removeLink, injectMarkedContent, removeMarkedContent,
   cleanSettingsHooks, loadHooksWithCliEntry, mergeSettingsHooks,
 } from './cli-utils.mjs';
@@ -12,6 +12,7 @@ import {
   CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH,
   CODEX_PLUGIN_CONFIG_HEADER,
   installCodexManagedTopLevelConfig,
+  installCodexManagedTuiConfig,
   isManagedCodexBackupInstruction,
   isManagedCodexGoalsFeature,
   isManagedCodexModelInstruction,
@@ -20,12 +21,17 @@ import {
   readCodexGoalsFeatureLine,
   readLegacyCodexHooksFeatureLine,
   removeCodexGoalsFeatureConfig,
+  removeCodexManagedTuiConfig,
   removeLegacyManagedCodexHooksFeatureConfig,
   removeCodexPluginConfig,
   restoreCodexGoalsFeatureConfig,
   restoreCodexTopLevelConfig,
   upsertCodexPluginConfig,
 } from './cli-codex-config.mjs';
+import {
+  cleanupManagedCodexHookTrust,
+  syncManagedCodexHookTrust,
+} from './cli-codex-hooks-state.mjs';
 import {
   readTopLevelTomlLine,
   readTopLevelTomlBlock,
@@ -132,11 +138,14 @@ function writeCodexRuntimeCarrier(filePath, bootstrapPath, settings) {
 function installCodexStandaloneHooks(home, pkgRoot) {
   const hooksData = loadHooksWithCliEntry(pkgRoot, 'hooks-codex.json', '${PLUGIN_ROOT}');
   if (!hooksData) return false;
-  mergeSettingsHooks(join(home, '.codex', CODEX_HOOKS_BASENAME), hooksData);
+  const hooksPath = join(home, '.codex', CODEX_HOOKS_BASENAME);
+  mergeSettingsHooks(hooksPath, hooksData);
+  syncManagedCodexHookTrust(join(home, '.codex', CODEX_CONFIG_BASENAME), hooksPath, safeJson(hooksPath));
   return true;
 }
 
 function cleanupCodexStandaloneHooks(home) {
+  cleanupManagedCodexHookTrust(join(home, '.codex', CODEX_CONFIG_BASENAME));
   cleanSettingsHooks(join(home, '.codex', CODEX_HOOKS_BASENAME));
 }
 
@@ -160,6 +169,7 @@ function cleanupCodexManagedConfig(configPath, { removePluginConfig = false } =
   if (shouldRestoreCodexGoalsFeature) {
     toml = removeCodexGoalsFeatureConfig(toml);
   }
+  toml = removeCodexManagedTuiConfig(toml);
   if (shouldRemoveLegacyCodexHooksFeature) {
     toml = removeLegacyManagedCodexHooksFeatureConfig(toml);
   }
@@ -209,6 +219,7 @@ export function installCodexStandby(home, pkgRoot) {
   toml = installCodexManagedTopLevelConfig(toml, {
     modelInstructionsPath: CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH,
   });
+  toml = installCodexManagedTuiConfig(toml);
   toml = removeLegacyManagedCodexHooksFeatureConfig(toml);
   safeWrite(configPath, toml);
   installCodexStandaloneHooks(home, pkgRoot);
@@ -277,20 +288,15 @@ export function installCodexGlobal(home, pkgRoot) {
   removeIfExists(join(codexDir, 'plugins', 'cache', CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_NAME));
 
   ensureDir(join(home, 'plugins'));
-  ensureDir(installedPluginRoot);
+  ensureDir(dirname(installedPluginRoot));
 
   const settings = readCarrierSettings(home);
-  copyEntries(pkgRoot, pluginRoot, CODEX_RUNTIME_ENTRIES);
-  copyEntries(pkgRoot, installedPluginRoot, CODEX_RUNTIME_ENTRIES);
-  createLink(pluginRoot, join(codexDir, 'helloagents'));
-  writeCodexRuntimeCarrier(
-    join(pluginRoot, CODEX_RUNTIME_CARRIER),
-    join(pluginRoot, 'bootstrap.md'),
-    settings,
-  );
+  createLink(pkgRoot, pluginRoot);
+  createLink(pkgRoot, installedPluginRoot);
+  createLink(pkgRoot, join(codexDir, 'helloagents'));
   writeCodexRuntimeCarrier(
-    join(installedPluginRoot, CODEX_RUNTIME_CARRIER),
-    join(installedPluginRoot, 'bootstrap.md'),
+    join(pkgRoot, CODEX_RUNTIME_CARRIER),
+    join(pkgRoot, 'bootstrap.md'),
     settings,
   );
   const homeCarrierPath = join(codexDir, CODEX_RUNTIME_CARRIER);
@@ -304,6 +310,7 @@ export function installCodexGlobal(home, pkgRoot) {
   toml = installCodexManagedTopLevelConfig(toml, {
     modelInstructionsPath: CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH,
   });
+  toml = installCodexManagedTuiConfig(toml);
   toml = removeLegacyManagedCodexHooksFeatureConfig(toml);
   toml = upsertCodexPluginConfig(toml);
   safeWrite(configPath, toml);

package/scripts/cli-doctor-codex.mjs

@@ -9,6 +9,11 @@ import {
   readCodexHooksFeatureLine,
   readLegacyCodexHooksFeatureLine,
 } from './cli-codex-config.mjs'
+import {
+  buildManagedCodexHookTrustEntries,
+  readCodexHookStateSections,
+} from './cli-codex-hooks-state.mjs'
+import { getStableRuntimeRoot } from './cli-runtime-root.mjs'
 import { buildRuntimeCarrier } from './cli-runtime-carrier.mjs'
 import { readTopLevelTomlLine } from './cli-toml.mjs'
 import { loadHooksWithCliEntry, safeJson, safeRead } from './cli-utils.mjs'
@@ -101,6 +106,8 @@ function appendCodexStandbyIssues(runtime, issues, checks) {
   if (!checks.codexHooksFeature) issues.push(buildDoctorIssue(runtime, 'codex-hooks-feature-disabled', 'Codex hooks 功能被显式关闭', 'Codex hooks feature is explicitly disabled'))
   if (!checks.standaloneHooks) issues.push(buildDoctorIssue(runtime, 'standby-hooks-missing', 'standby `~/.codex/hooks.json` 缺少 HelloAGENTS hooks', 'Standby `~/.codex/hooks.json` is missing HelloAGENTS hooks'))
   if (checks.standaloneHooks && !checks.standaloneHooksMatch) issues.push(buildDoctorIssue(runtime, 'standby-hooks-drift', 'standby `~/.codex/hooks.json` 与当前 hooks-codex.json 不一致', 'Standby `~/.codex/hooks.json` differs from the current hooks-codex.json'))
+  if (checks.standaloneHooks && !checks.managedHookTrust) issues.push(buildDoctorIssue(runtime, 'standby-hook-trust-missing', 'standby `config.toml` 缺少 HelloAGENTS hooks trust', 'Standby `config.toml` is missing HelloAGENTS hook trust metadata'))
+  if (checks.standaloneHooks && checks.managedHookTrust && !checks.managedHookTrustMatch) issues.push(buildDoctorIssue(runtime, 'standby-hook-trust-drift', 'standby hooks trust 与当前 hooks 定义不一致', 'Standby hook trust metadata differs from the current hooks definition'))
   if (checks.pluginRoot || checks.pluginCache || checks.marketplaceEntry || checks.pluginEnabled) {
     issues.push(buildDoctorIssue(runtime, 'standby-global-residue', 'standby 模式下仍残留 global 插件文件或配置', 'Global plugin artifacts still remain while Codex is in standby mode'))
   }
@@ -109,9 +116,11 @@ function appendCodexStandbyIssues(runtime, issues, checks) {
 function appendCodexGlobalIssues(runtime, issues, checks, pluginVersion, cacheVersion) {
   if (!checks.carrierMarker) issues.push(buildDoctorIssue(runtime, 'global-home-carrier-missing', 'global `~/.codex/AGENTS.md` 缺少 HelloAGENTS 规则内容', 'Global `~/.codex/AGENTS.md` is missing the HelloAGENTS carrier'))
   if (checks.carrierMarker && !checks.carrierContentMatch) issues.push(buildDoctorIssue(runtime, 'global-home-carrier-drift', 'global `~/.codex/AGENTS.md` 与当前全局模式规则不一致', 'Global `~/.codex/AGENTS.md` differs from the current global rules'))
-  if (!checks.globalHomeLink) issues.push(buildDoctorIssue(runtime, 'global-read-root-link-missing', 'global `~/.codex/helloagents` 链接缺失或未指向当前插件根目录', 'Global `~/.codex/helloagents` link is missing or does not point to the current plugin root'))
+  if (!checks.globalHomeLink) issues.push(buildDoctorIssue(runtime, 'global-read-root-link-missing', 'global `~/.codex/helloagents` 链接缺失或未指向稳定运行根目录', 'Global `~/.codex/helloagents` link is missing or does not point to the stable runtime root'))
   if (!checks.pluginRoot) issues.push(buildDoctorIssue(runtime, 'global-plugin-root-missing', 'global 插件根目录缺失', 'Global plugin root is missing'))
   if (!checks.pluginCache) issues.push(buildDoctorIssue(runtime, 'global-plugin-cache-missing', 'global 插件缓存目录缺失', 'Global plugin cache directory is missing'))
+  if (checks.pluginRoot && !checks.pluginRootLink) issues.push(buildDoctorIssue(runtime, 'global-plugin-root-link-drift', 'global 插件根目录未链接到稳定运行根目录', 'Global plugin root does not link to the stable runtime root'))
+  if (checks.pluginCache && !checks.pluginCacheLink) issues.push(buildDoctorIssue(runtime, 'global-plugin-cache-link-drift', 'global 插件缓存未链接到稳定运行根目录', 'Global plugin cache does not link to the stable runtime root'))
   if (checks.pluginRoot && !checks.pluginCarrierMatch) issues.push(buildDoctorIssue(runtime, 'global-plugin-carrier-drift', 'global 插件根目录中的 AGENTS.md 与当前全局模式规则不一致', 'Global plugin AGENTS.md differs from the current global rules'))
   if (checks.pluginCache && !checks.pluginCacheCarrierMatch) issues.push(buildDoctorIssue(runtime, 'global-plugin-cache-carrier-drift', 'global 插件缓存中的 AGENTS.md 与当前全局模式规则不一致', 'Global plugin cache AGENTS.md differs from the current global rules'))
   if (!checks.marketplaceEntry) issues.push(buildDoctorIssue(runtime, 'global-marketplace-missing', 'global marketplace 条目缺失', 'Global marketplace entry is missing'))
@@ -123,9 +132,10 @@ function appendCodexGlobalIssues(runtime, issues, checks, pluginVersion, cacheVe
   if (!checks.codexHooksFeature) issues.push(buildDoctorIssue(runtime, 'codex-hooks-feature-disabled', 'Codex hooks 功能被显式关闭', 'Codex hooks feature is explicitly disabled'))
   if (!checks.standaloneHooks) issues.push(buildDoctorIssue(runtime, 'global-hooks-missing', 'global `~/.codex/hooks.json` 缺少 HelloAGENTS hooks', 'Global `~/.codex/hooks.json` is missing HelloAGENTS hooks'))
   if (checks.standaloneHooks && !checks.standaloneHooksMatch) issues.push(buildDoctorIssue(runtime, 'global-hooks-drift', 'global `~/.codex/hooks.json` 与当前 hooks-codex.json 不一致', 'Global `~/.codex/hooks.json` differs from the current hooks-codex.json'))
+  if (checks.standaloneHooks && !checks.managedHookTrust) issues.push(buildDoctorIssue(runtime, 'global-hook-trust-missing', 'global `config.toml` 缺少 HelloAGENTS hooks trust', 'Global `config.toml` is missing HelloAGENTS hook trust metadata'))
+  if (checks.standaloneHooks && checks.managedHookTrust && !checks.managedHookTrustMatch) issues.push(buildDoctorIssue(runtime, 'global-hook-trust-drift', 'global hooks trust 与当前 hooks 定义不一致', 'Global hook trust metadata differs from the current hooks definition'))
   if (pluginVersion && !checks.pluginVersionMatch) issues.push(buildDoctorIssue(runtime, 'global-plugin-version-drift', 'global 插件根目录版本与当前包版本不一致', 'Global plugin root version does not match the current package version'))
   if (cacheVersion && !checks.pluginCacheVersionMatch) issues.push(buildDoctorIssue(runtime, 'global-plugin-cache-version-drift', 'global 插件缓存版本与当前包版本不一致', 'Global plugin cache version does not match the current package version'))
-  if (checks.homeLink) issues.push(buildDoctorIssue(runtime, 'global-standby-link-residue', 'global 模式下仍残留 standby home 链接', 'Standby home link still remains while Codex is in global mode'))
 }
 
 function buildCodexChecks(runtime, settings, trackedMode, detectedMode) {
@@ -133,7 +143,10 @@ function buildCodexChecks(runtime, settings, trackedMode, detectedMode) {
   const codexConfig = safeRead(join(codexDir, 'config.toml')) || ''
   const pluginRoot = join(runtime.home, 'plugins', CODEX_PLUGIN_NAME)
   const pluginCacheRoot = join(codexDir, 'plugins', 'cache', CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_NAME, 'local')
+  const runtimeRoot = safeRealTarget(getStableRuntimeRoot(runtime.home)) || normalizePath(getStableRuntimeRoot(runtime.home))
   const homeLinkTarget = safeRealTarget(join(codexDir, 'helloagents'))
+  const pluginRootTarget = safeRealTarget(pluginRoot)
+  const pluginCacheTarget = safeRealTarget(pluginCacheRoot)
   const expectedHomeCarrier = (detectedMode === 'global' || (detectedMode === 'none' && trackedMode === 'global'))
     ? 'bootstrap.md'
     : 'bootstrap-lite.md'
@@ -141,6 +154,12 @@ function buildCodexChecks(runtime, settings, trackedMode, detectedMode) {
   const marketplace = safeJson(join(runtime.home, '.agents', 'plugins', 'marketplace.json')) || {}
   const modelInstructionsLine = readTopLevelTomlLine(codexConfig, 'model_instructions_file')
   const expectedHooks = readExpectedHooks(runtime, 'hooks-codex.json', '${PLUGIN_ROOT}')
+  const expectedHookTrust = buildManagedCodexHookTrustEntries(join(codexDir, 'hooks.json'), codexHooks)
+  const managedHookTrust = new Map(
+    readCodexHookStateSections(codexConfig)
+      .filter((section) => section.managed)
+      .map((section) => [section.key, section.trustedHash]),
+  )
   const hooksFeatureLine = readCodexHooksFeatureLine(codexConfig)
   const goalsFeatureLine = readCodexGoalsFeatureLine(codexConfig)
   const legacyHooksFeatureLine = readLegacyCodexHooksFeatureLine(codexConfig)
@@ -151,7 +170,7 @@ function buildCodexChecks(runtime, settings, trackedMode, detectedMode) {
       carrierContentMatch: normalizeText((safeRead(join(codexDir, 'AGENTS.md')) || '').match(/<!-- HELLOAGENTS_START -->([\s\S]*?)<!-- HELLOAGENTS_END -->/)?.[1] || '')
         === readExpectedCarrierContent(runtime, expectedHomeCarrier, settings),
       homeLink: homeLinkTarget === (safeRealTarget(runtime.pkgRoot) || normalizePath(runtime.pkgRoot)),
-      globalHomeLink: homeLinkTarget === (safeRealTarget(pluginRoot) || normalizePath(pluginRoot)),
+      globalHomeLink: homeLinkTarget === runtimeRoot,
       modelInstructionsFile: !!modelInstructionsLine,
       modelInstructionsPathMatch: !!modelInstructionsLine && normalizePath(modelInstructionsLine).includes(`"${CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH}"`),
       codexNotify: codexConfig.includes('codex-notify'),
@@ -162,8 +181,12 @@ function buildCodexChecks(runtime, settings, trackedMode, detectedMode) {
       legacyCodexHooksFeature: Boolean(legacyHooksFeatureLine),
       standaloneHooks: JSON.stringify(codexHooks.hooks || {}).includes('helloagents'),
       standaloneHooksMatch: managedHooksMatch(codexHooks.hooks || {}, expectedHooks),
+      managedHookTrust: expectedHookTrust.every((entry) => managedHookTrust.has(entry.key)),
+      managedHookTrustMatch: expectedHookTrust.every((entry) => managedHookTrust.get(entry.key) === entry.trustedHash),
       pluginRoot: existsSync(pluginRoot),
       pluginCache: existsSync(pluginCacheRoot),
+      pluginRootLink: pluginRootTarget === runtimeRoot,
+      pluginCacheLink: pluginCacheTarget === runtimeRoot,
       pluginCarrierMatch: normalizeText(safeRead(join(pluginRoot, 'AGENTS.md')) || '') === readExpectedCarrierContent(runtime, 'bootstrap.md', settings),
       pluginCacheCarrierMatch: normalizeText(safeRead(join(pluginCacheRoot, 'AGENTS.md')) || '') === readExpectedCarrierContent(runtime, 'bootstrap.md', settings),
       marketplaceEntry: Array.isArray(marketplace.plugins) && marketplace.plugins.some((plugin) => plugin?.name === CODEX_PLUGIN_NAME),

package/scripts/cli-host-detect.mjs

@@ -6,6 +6,7 @@ import {
   CODEX_PLUGIN_KEY,
   CODEX_PLUGIN_NAME,
 } from './cli-codex.mjs'
+import { getStableRuntimeRoot } from './cli-runtime-root.mjs'
 import { safeJson, safeRead } from './cli-utils.mjs'
 
 const HOST_ALIASES = new Map([
@@ -68,19 +69,18 @@ function detectCodexMode(home) {
   const codexHomeLink = join(codexDir, 'helloagents')
   const codexConfig = safeRead(join(codexDir, 'config.toml')) || ''
   const marketplace = safeRead(join(home, '.agents', 'plugins', 'marketplace.json')) || ''
-  const globalPluginRoot = normalizePath(join(home, 'plugins', CODEX_PLUGIN_NAME))
+  const runtimeRoot = normalizePath(getStableRuntimeRoot(home))
   const codexHomeLinkTarget = safeRealTarget(codexHomeLink)
   if (
     existsSync(join(home, 'plugins', CODEX_PLUGIN_NAME))
     || existsSync(join(codexDir, 'plugins', 'cache', CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_NAME))
     || marketplace.includes(`"name": "${CODEX_PLUGIN_NAME}"`)
     || codexConfig.includes(CODEX_PLUGIN_KEY)
-    || codexHomeLinkTarget === globalPluginRoot
   ) {
     return 'global'
   }
   if (
-    (existsSync(codexHomeLink) && codexHomeLinkTarget !== globalPluginRoot)
+    (existsSync(codexHomeLink) && codexHomeLinkTarget === runtimeRoot)
     || hasHelloagentsMarker(join(codexDir, 'AGENTS.md'))
     || codexConfig.includes('codex-notify')
     || codexConfig.includes('HelloAGENTS')

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.cmd         ${msg('（受管宿主配置的跨平台稳定入口）', '(cross-platform stable entrypoint for managed host configs)')}
+  helloagents-js             ${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-utils.mjs

@@ -35,6 +35,7 @@ export function copyEntries(sourceRoot, targetRoot, entries) {
 export function createLink(target, linkPath) {
   removeLink(linkPath);
   try {
+    ensureDir(dirname(linkPath));
     symlinkSync(target, linkPath, IS_WIN ? 'junction' : 'dir');
     return true;
   } catch { return false; }
@@ -132,9 +133,9 @@ export function cleanSettingsHooks(settingsPath, cleanPermissions = false) {
 
 function rewriteHookCommandToCli(command = '', pathVar = '') {
   const replacements = new Map([
-    [`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'],
+    [`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'],
   ]);
 
   let next = command;

package/scripts/delivery-gate.mjs

@@ -5,6 +5,7 @@
  * or when the plan artifacts are incomplete enough that delivery is not trustworthy.
  */
 import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
 import { getAdvisorEvidenceStatus } from './advisor-state.mjs'
 import { getCloseoutEvidenceStatus } from './closeout-state.mjs'
 import { getAdvisorRequirement, getVisualValidationRequirement } from './plan-contract.mjs'
@@ -129,11 +130,15 @@ function collectGateIssues(planEntries, verificationStatus, reviewStatus, adviso
   return issues
 }
 
-function main() {
-  let data = {}
+function readStdinJson() {
   try {
-    data = JSON.parse(readFileSync(0, 'utf-8'))
-  } catch {}
+    return JSON.parse(readFileSync(0, 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+export function evaluateDeliveryGate(data = {}) {
   const cwd = data.cwd || process.cwd()
   const workflowOptions = { payload: data }
   const snapshot = getWorkflowSnapshot(cwd, workflowOptions)
@@ -146,8 +151,7 @@ function main() {
     ...workflowOptions,
   })
   if (gatePlans.length === 0) {
-    process.stdout.write(JSON.stringify({ suppressOutput: true }))
-    return
+    return { suppressOutput: true }
   }
 
   const advisorRequirements = gatePlans.map((entry) => getAdvisorRequirement(entry.contract))
@@ -177,15 +181,20 @@ function main() {
 
   const issues = collectGateIssues(gatePlans, verificationStatus, reviewStatus, advisorStatus, visualStatus, closeoutStatus)
   if (issues.length === 0) {
-    process.stdout.write(JSON.stringify({ suppressOutput: true }))
-    return
+    return { suppressOutput: true }
   }
 
-  process.stdout.write(JSON.stringify({
+  return {
     decision: 'block',
     reason: buildDeliveryBlockReason(issues, recommendation, buildDeliveryGateHint(cwd, workflowOptions)),
     suppressOutput: true,
-  }))
+  }
 }
 
-main()
+function main() {
+  process.stdout.write(JSON.stringify(evaluateDeliveryGate(readStdinJson())))
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main()
+}

package/scripts/notify-closeout.mjs

@@ -5,6 +5,7 @@ import { dirname } from 'node:path'
 import { getRuntimeEvidencePath, readRuntimeEvidence, writeRuntimeEvidence } from './runtime-artifacts.mjs'
 
 export const CODEX_CLOSEOUT_EVIDENCE_FILE = 'codex-native-stop.json'
+export const CODEX_QUICK_NOTIFY_EVIDENCE_FILE = 'codex-quick-notify.json'
 const CODEX_CLOSEOUT_LOCK_FILE = 'codex-native-stop.lock'
 const WEAK_KEY_TTL_MS = 10_000
 const LOCK_STALE_MS = 120_000
@@ -110,8 +111,7 @@ export function matchesCodexCloseoutEvidence(evidence, snapshot, now = Date.now(
   if (intersects(snapshot.strongKeys, strongKeys)) return true
 
   const currentHasStrong = snapshot.strongKeys.length > 0
-  const evidenceHasStrong = strongKeys.length > 0
-  if (currentHasStrong && evidenceHasStrong) return false
+  if (currentHasStrong) return false
 
   const updatedAt = Date.parse(evidence.updatedAt || '')
   if (!Number.isFinite(updatedAt) || now - updatedAt > WEAK_KEY_TTL_MS) return false
@@ -211,3 +211,23 @@ export function finalizeCodexCloseoutClaim(claim, meta = {}) {
     releaseLockFile(claim.lockPath)
   }
 }
+
+export function writeCodexQuickNotifyEvidence(cwd, { payload = {}, turnState = null, event = '' } = {}) {
+  const snapshot = buildCodexCloseoutSnapshot({ payload, turnState })
+  return writeRuntimeEvidence(cwd, CODEX_QUICK_NOTIFY_EVIDENCE_FILE, {
+    version: 1,
+    updatedAt: new Date().toISOString(),
+    event,
+    turnId: snapshot.turnId,
+    sessionId: snapshot.sessionId,
+    messageHash: snapshot.messageHash,
+    strongKeys: snapshot.strongKeys,
+    weakKeys: snapshot.weakKeys,
+  }, { payload })
+}
+
+export function hasCodexQuickNotifyEvidence(cwd, { payload = {}, turnState = null } = {}) {
+  const snapshot = buildCodexCloseoutSnapshot({ payload, turnState })
+  const evidence = readRuntimeEvidence(cwd, CODEX_QUICK_NOTIFY_EVIDENCE_FILE, { payload })
+  return matchesCodexCloseoutEvidence(evidence, snapshot)
+}

package/scripts/notify-route.mjs

@@ -38,6 +38,7 @@ function routeExplicitCommand({
   appendReplayEvent,
   buildRouteInstruction,
   suppress,
+  recordReplayEvents,
 }) {
   const cmdMatch = prompt.match(/^~(\w+)/)
   if (!cmdMatch) return false
@@ -50,14 +51,16 @@ function routeExplicitCommand({
     sourceSkillName: skillName,
     payload,
   })
-  appendReplayEvent(cwd, {
-    host,
-    event: 'command_route_selected',
-    source: 'route',
-    skillName: canonicalSkillName,
-    sourceSkillName: skillName,
-    payload,
-  })
+  if (recordReplayEvents !== false) {
+    appendReplayEvent(cwd, {
+      host,
+      event: 'command_route_selected',
+      source: 'route',
+      skillName: canonicalSkillName,
+      sourceSkillName: skillName,
+      payload,
+    })
+  }
   suppress(buildRouteInstruction({
     skillName,
     extraRules: buildHelpExtraRules(skillName),
@@ -84,6 +87,7 @@ export function handleRouteCommand({
   getWorkflowRecommendation,
   suppress,
   emptySuppress,
+  recordReplayEvents = true,
 }) {
   const prompt = (payload.prompt || '').trim()
   const cwd = payload.cwd || process.cwd()
@@ -105,6 +109,7 @@ export function handleRouteCommand({
     appendReplayEvent,
     buildRouteInstruction,
     suppress,
+    recordReplayEvents,
   })) {
     return
   }
@@ -112,13 +117,15 @@ export function handleRouteCommand({
   const bootstrapFile = resolveBootstrapFile(cwd, settings, host)
   if (bootstrapFile === 'bootstrap.md') {
     clearRouteContext({ cwd, payload })
-    appendReplayEvent(cwd, {
-      host,
-      event: 'semantic_route_prompted',
-      source: 'route',
-      recommendation: getWorkflowRecommendation(cwd, { payload }),
-      payload,
-    })
+    if (recordReplayEvents !== false) {
+      appendReplayEvent(cwd, {
+        host,
+        event: 'semantic_route_prompted',
+        source: 'route',
+        recommendation: getWorkflowRecommendation(cwd, { payload }),
+        payload,
+      })
+    }
     suppress(buildSemanticRouteInstruction(cwd, payload))
     return
   }

package/scripts/notify-sound.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { platform } from 'node:os'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const PKG_ROOT = join(__dirname, '..')
+const PLAT = platform()
+
+function shellQuote(value = '') {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`
+}
+
+export function resolveSoundPath(event = '', pkgRoot = PKG_ROOT) {
+  const filePath = join(pkgRoot, 'assets', 'sounds', `${event}.wav`)
+  return existsSync(filePath) ? filePath : ''
+}
+
+export function buildWindowsSoundCommand(filePath = '') {
+  return `(New-Object System.Media.SoundPlayer '${String(filePath || '').replace(/'/g, "''")}').PlaySync()`
+}
+
+function playWindows(filePath) {
+  const result = spawnSync('powershell', [
+    '-NoProfile',
+    '-c',
+    buildWindowsSoundCommand(filePath),
+  ], {
+    encoding: 'utf-8',
+    windowsHide: true,
+  })
+
+  if (result.error) throw result.error
+  if (result.status !== 0) {
+    throw new Error((result.stderr || result.stdout || 'PowerShell sound playback failed').trim())
+  }
+}
+
+function playMac(filePath) {
+  const result = spawnSync('afplay', [filePath], {
+    encoding: 'utf-8',
+  })
+  if (result.error) throw result.error
+  if (result.status !== 0) {
+    throw new Error((result.stderr || result.stdout || 'afplay failed').trim())
+  }
+}
+
+function playLinux(filePath) {
+  const script = `if command -v aplay >/dev/null 2>&1; then aplay -q ${shellQuote(filePath)}; elif command -v paplay >/dev/null 2>&1; then paplay ${shellQuote(filePath)}; else printf '\\a'; fi`
+  const result = spawnSync('sh', ['-c', script], {
+    encoding: 'utf-8',
+  })
+  if (result.error) throw result.error
+  if (result.status !== 0) {
+    throw new Error((result.stderr || result.stdout || 'Linux sound playback failed').trim())
+  }
+}
+
+export function playSoundEvent(event = '', pkgRoot = PKG_ROOT) {
+  const soundPath = resolveSoundPath(event, pkgRoot)
+  if (!soundPath) {
+    process.stderr.write('\x07')
+    return false
+  }
+
+  if (PLAT === 'win32') {
+    playWindows(soundPath)
+    return true
+  }
+  if (PLAT === 'darwin') {
+    playMac(soundPath)
+    return true
+  }
+
+  playLinux(soundPath)
+  return true
+}
+
+function main() {
+  const event = process.argv[2] || 'complete'
+  try {
+    playSoundEvent(event)
+  } catch {
+    process.stderr.write('\x07')
+  }
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main()
+}

package/scripts/notify-ui.mjs

@@ -5,7 +5,7 @@
 import { platform } from 'node:os';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
 
 const PLAT = platform();
 
@@ -55,33 +55,65 @@ function resolveWav(pkgRoot, event) {
   return existsSync(p) ? p : null;
 }
 
-function runSync(command, args) {
+function resolveSoundHelper(pkgRoot) {
+  const helperPath = join(pkgRoot, 'scripts', 'notify-sound.mjs');
+  return existsSync(helperPath) ? helperPath : '';
+}
+
+function runDetached(command, args) {
   try {
-    const result = spawnSync(command, args, {
+    const child = spawn(command, args, {
       stdio: 'ignore',
+      detached: true,
       windowsHide: true,
     });
-    return !result.error && result.status === 0;
+    child.on('error', () => {});
+    child.unref();
+    return true;
   } catch {
     return false;
   }
 }
 
-export function playSound(pkgRoot, event) {
+function shellQuote(value = '') {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`
+}
+
+function runSoundHelper(pkgRoot, event, mode = 'background') {
+  const helperPath = resolveSoundHelper(pkgRoot);
+  if (!helperPath) return false;
+
+  if (mode === 'blocking') {
+    try {
+      execFileSync(process.execPath, [helperPath, event], {
+        stdio: 'ignore',
+        windowsHide: true,
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  return runDetached(process.execPath, [helperPath, event]);
+}
+
+export function playSound(pkgRoot, event, options = {}) {
   if (DISABLE_OS_NOTIFICATIONS) return;
   const wav = resolveWav(pkgRoot, event);
   if (!wav) { process.stderr.write('\x07'); return; }
+  if (runSoundHelper(pkgRoot, event, options.mode === 'blocking' ? 'blocking' : 'background')) return;
   try {
     if (PLAT === 'win32') {
-      runSync('powershell', [
+      runDetached('powershell', [
         '-NoProfile',
         '-c',
         `(New-Object Media.SoundPlayer '${wav.replace(/'/g, "''")}').PlaySync()`,
       ]);
     } else if (PLAT === 'darwin') {
-      runSync('afplay', [wav]);
+      runDetached('afplay', [wav]);
     } else {
-      if (!runSync('aplay', ['-q', wav]) && !runSync('paplay', [wav])) process.stderr.write('\x07');
+      runDetached('sh', ['-c', `if command -v aplay >/dev/null 2>&1; then aplay -q ${shellQuote(wav)}; elif command -v paplay >/dev/null 2>&1; then paplay ${shellQuote(wav)}; else printf '\\a'; fi`]);
     }
   } catch { process.stderr.write('\x07'); }
 }
@@ -124,16 +156,16 @@ export function desktopNotify(pkgRoot, event, extra) {
   try {
     if (PLAT === 'win32') {
       const iconPath = join(pkgRoot, 'assets', 'icons', 'icon.png').replace(/\//g, '\\');
-      runSync('powershell', ['-NoProfile', '-c', buildWindowsToastScript(notification, iconPath)]);
+      runDetached('powershell', ['-NoProfile', '-c', buildWindowsToastScript(notification, iconPath)]);
     } else if (PLAT === 'darwin') {
       const subtitle = notification.sourceLabel
         ? ` subtitle "${escapeAppleScriptText(notification.sourceLabel)}"`
         : '';
-      runSync('osascript', ['-e',
+      runDetached('osascript', ['-e',
         `display notification "${escapeAppleScriptText(notification.message)}" with title "${escapeAppleScriptText(notification.title)}"${subtitle}`],
       );
     } else {
-      if (!runSync('notify-send', [notification.title, notification.body])) process.stderr.write('\x07');
+      runDetached('sh', ['-c', `if command -v notify-send >/dev/null 2>&1; then notify-send ${shellQuote(notification.title)} ${shellQuote(notification.body)}; else printf '\\a'; fi`]);
     }
   } catch { process.stderr.write('\x07'); }
 }