review-fix(comments): restore reviewer-named rationale blocks (#4926, #81335, #54220/#56747, #100436, #5057/#6252/#10370/#4665)

This commit is contained in:
Teknium
2026-09-03 09:32:25 -07:00
parent fb14bc4e11
commit 5a0efda992
11 changed files with 63 additions and 23 deletions
+1 -1
View File
@@ -301,7 +301,7 @@ class CopilotACPClient:
"HERMES_COPILOT_ACP_COMMAND / HERMES_COPILOT_ACP_ARGS to a working pair."
)
try:
from hermes_cli._subprocess_compat import windows_hide_flags # hide the Windows console flash; pipes intact
from hermes_cli._subprocess_compat import windows_hide_flags # hide the Windows console flash (#56747); pipes intact for the ACP wire
proc = subprocess.Popen(
[self._acp_command] + self._acp_args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+2 -1
View File
@@ -69,7 +69,8 @@ class CodexAppServerClient:
# Codex emits tracing to stderr; default WARN keeps it quiet for users.
spawn_env.setdefault("RUST_LOG", "warn")
# Hide the console flash on Windows; stdio pipes stay intact.
# Hide the console the codex child would otherwise flash on Windows (#56747).
# Hide-only — stdio pipes stay intact for the app-server wire.
from hermes_cli._subprocess_compat import windows_hide_flags
self._proc = subprocess.Popen(
+2 -1
View File
@@ -3199,7 +3199,8 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin, CLITuiMix
from hermes_cli._subprocess_compat import windows_hide_flags
result = subprocess.run(
exec_cmd, shell=True, capture_output=True, text=True, encoding="utf-8", errors="replace",
timeout=30, env=build_subprocess_env(), creationflags=windows_hide_flags(),
timeout=30, env=build_subprocess_env(),
creationflags=windows_hide_flags(), # no console flash on Windows (#56747)
)
output = result.stdout.strip() or result.stderr.strip()
if output:
+20 -6
View File
@@ -1766,7 +1766,9 @@ class BasePlatformAdapter(ABC):
self._fatal_error_code: Optional[str] = None
self._fatal_error_message: Optional[str] = None
self._fatal_error_handler: Optional[Callable[["BasePlatformAdapter"], Awaitable[None] | None]] = None
# Strong refs to shielded fatal-error handler tasks (asyncio keeps only weak refs).
# Strong refs to shielded fatal-error handler tasks that outlive their carrier task
# (asyncio keeps only weak refs); without them the loop can GC the detached handler
# mid-flight — the "handler killed mid-flight" class (#81335).
self._detached_fatal_tasks: set = set()
# Lock takeover armed only for the initial connect of ``gateway run --replace``.
self._platform_lock_takeover_allowed = self._platform_lock_takeover_attempted = False
@@ -1992,10 +1994,15 @@ class BasePlatformAdapter(ABC):
return
result = handler(self)
if asyncio.iscoroutine(result):
# Detached + shielded: often awaited from an adapter-owned task that the handler's
# ``disconnect()`` cancels; unshielded, the handler died mid-flight (adapter popped
# but never queued for reconnect). Strong ref so the loop can't GC it.
# Detached + shielded: often awaited from an adapter-owned task (e.g. Telegram
# ``_polling_error_task``) that the gateway fatal handler's ``disconnect()``
# cancels; unshielded, the handler died mid-flight — adapter popped from the
# gateway map but never queued for background reconnect, leaving a zombie
# gateway with no platforms and no pending retries (#81335).
task = asyncio.ensure_future(result)
# Strong ref: asyncio only keeps weak refs to tasks ("save a reference ... to
# avoid a task disappearing mid-execution"); matches
# GatewayRunner._handle_adapter_fatal_error.
_tasks = _lazy_attr(self, "_detached_fatal_tasks", set)
_tasks.add(task)
task.add_done_callback(_tasks.discard)
@@ -3340,7 +3347,11 @@ class BasePlatformAdapter(ABC):
async def _handle_message_while_active(self, event: MessageEvent, session_key: str) -> None:
"""Route a message that arrived while ``session_key`` is busy: bypass
commands / clarify replies dispatch inline, everything else is queued."""
# Bypass commands run inline: queued they'd leak as user text (/new) or deadlock (/approve).
# Bypass commands run inline: queued they'd leak as user text (/new) or deadlock
# (/approve, /deny — the agent is blocked on Event.wait). Dispatch inline by
# calling the message handler directly and sending the response. Do NOT use
# _process_message_background — it manages session lifecycle and its cleanup
# races with the running task (split-brain, see PR #4926).
cmd = event.get_command()
from hermes_cli.commands import (is_interrupt_then_dispatch, should_bypass_active_session)
if should_bypass_active_session(cmd):
@@ -3357,7 +3368,10 @@ class BasePlatformAdapter(ABC):
logger.error("[%s] Command '/%s' dispatch failed: %s", self.name, cmd, e, exc_info=True)
return
# Clarify bypass: while blocked on clarify_tool the next message must reach the
# text-intercept.
# text-intercept so numeric/exact/"Other" answers resolve it and unblock the agent.
# Otherwise it lands in _pending_messages as a follow-up turn and the answer is
# discarded. Same shape as the /approve deadlock fix (PR #4926): agent thread
# blocked on Event.wait, message must reach the resolver before being a new turn.
if not cmd and event.allow_gateway_control:
try:
from tools import clarify_gateway as _clarify_mod
+6 -1
View File
@@ -700,7 +700,12 @@ class GatewayBusySessionMixin:
"""Dispatch a recognized slash command while an agent is running.
Order: ``busy_handler`` (mid-run variant) → ``busy_policy == "dispatch"`` (normal handler)
→ catch-all reject text. Rejecting beats interrupt + discard (a zero-char response).
→ catch-all reject text. Rejecting is required rather than falling through to
interrupt + discard: commands like /model, /reasoning, /voice, /insights, /title,
/resume, /retry, /undo, /compress, /usage, /reload-mcp, /sethome, /reset (all
registered as Discord slash commands) would interrupt the agent AND get silently
discarded by the slash-command safety net, producing a zero-char response.
See #5057, #6252, #10370.
"""
name = cmd_def.name
policy = getattr(cmd_def, "busy_policy", "reject")
+1 -1
View File
@@ -1061,7 +1061,7 @@ class GatewayShutdownMixin:
watcher_env = GatewayShutdownMixin._restart_watcher_env()
project_root = Path(__file__).resolve().parent.parent
# Console python under CREATE_NO_WINDOW: nothing flashes. NOT pythonw.exe — a console-less
# watcher makes every console-subsystem descendant allocate a visible conhost.
# watcher makes every console-subsystem descendant allocate a visible conhost (#54220/#56747).
watcher_python = sys.executable
venv_dir = Path(watcher_env.get("VIRTUAL_ENV") or project_root / "venv")
site_packages = venv_dir / "Lib" / "site-packages"
+6 -3
View File
@@ -112,12 +112,13 @@ def resolve_node_command(name: str, argv: Sequence[str]) -> list[str]:
# to exist on stdlib subprocess for older Pythons or non-Windows builds.
_CREATE_NEW_PROCESS_GROUP = 0x00000200
# DETACHED_PROCESS (0x00000008) is intentionally NOT part of any flag bundle — do not re-add it
# (the recurring console-flash bug): (1) MSDN: CREATE_NO_WINDOW "is ignored if used with either
# (the recurring console-flash bug #54220 / #56747): (1) MSDN: CREATE_NO_WINDOW "is ignored if used with either
# CREATE_NEW_CONSOLE or DETACHED_PROCESS"; (2) a DETACHED_PROCESS child has NO console, so every
# console-subsystem descendant (git, gh, cmd, node, powershell, …) allocates its own — a visible
# flash per spawn, including inside third-party libraries no per-site sweep can reach. A
# CREATE_NO_WINDOW child instead OWNS a hidden console all descendants inherit (A/B verified on
# Windows 11 by the desktop backend fix).
# Windows 11 by the desktop backend fix, commit aa2ae36c3f: with per-site hide flags neutered,
# naive git/gh/cmd spawns don't flash under a hidden-console parent and do under a console-less one).
_CREATE_NO_WINDOW = 0x08000000
# Escape any Win32 job object the parent belongs to. Without this a detached child inherits the
# parent's job, and when that parent (Electron, Tauri, Windows Terminal, the Desktop bootstrap
@@ -131,7 +132,9 @@ def windows_detach_flags() -> int:
Pair with the default ``start_new_session=False`` (POSIX uses ``start_new_session=True``).
CREATE_NEW_PROCESS_GROUP stops Ctrl+C propagating; CREATE_NO_WINDOW gives the child a hidden
console descendants inherit; CREATE_BREAKAWAY_FROM_JOB escapes Electron/Tauri job objects. A
console descendants (git, gh, cmd, node, …) inherit so they don't flash — deliberately replacing
the old DETACHED_PROCESS approach, which re-created the per-descendant console-flash bug
(#54220/#56747) at every spawn; CREATE_BREAKAWAY_FROM_JOB escapes Electron/Tauri job objects. A
job that forbids breakaway yields PermissionError from Popen — callers catch OSError and fall
back to :func:`windows_detach_flags_without_breakaway`.
"""
+5 -1
View File
@@ -403,7 +403,11 @@ def is_interrupt_then_dispatch(command_name: str | None) -> bool:
def should_bypass_active_session(command_name: str | None) -> bool:
"""True for any resolvable slash command: every recognized command is dispatched mid-run
(Guard-2 handler or the "busy" catch-all), never queued — gateway.run's safety net discards
command text reaching the pending queue, so a queued /model would vanish."""
command text reaching the pending queue, so a queued mid-run /model (or /reasoning, /voice,
/insights, /title, /resume, /retry, /undo, /compress, /usage, /reload-mcp, /sethome, /reset)
would silently interrupt the agent AND get discarded — a zero-char response. See issue
#5057 / PRs #6252, #10370, #4665. ACTIVE_SESSION_BYPASS_COMMANDS remains the subset with
explicit Level-2 handlers; the rest fall through to the catch-all."""
return resolve_command(command_name) is not None if command_name else False
+4 -1
View File
@@ -859,7 +859,10 @@ def _spawn_gateway_restart_watcher(old_pid: int, run_argv: list[str]) -> bool:
return False
from hermes_cli._subprocess_compat import windows_detach_flags_without_breakaway, windows_detach_popen_kwargs
# Windows: normalize the interpreter and capture a stable cwd + env overlay (HERMES_HOME,
# Windows: ``run_argv`` leads with the venv's console ``python.exe`` — the interpreter we want:
# the watcher respawns it under CREATE_NO_WINDOW detach flags so the gateway owns one hidden
# console all descendants inherit and nothing flashes (#54220/#56747). The spec helper
# normalizes the interpreter and captures a stable cwd + env overlay (HERMES_HOME,
# VIRTUAL_ENV, PYTHONPATH) so the respawn doesn't depend on the watcher's cwd. No-op on POSIX.
respawn_cwd = ""
respawn_env_overlay: dict[str, str] = {}
+5 -3
View File
@@ -168,7 +168,8 @@ def _current_profile_cli_args() -> list[str]:
def _launch_elevated_gateway_command(command: str, extra_args: list[str] | None = None) -> bool:
"""Launch an elevated gateway subcommand via UAC and return True on handoff. The child is console
``python.exe`` with ``SW_HIDE``: it owns one hidden console its subprocesses (schtasks, taskkill)
inherit — no visible window and no per-descendant conhost flashes (pythonw.exe re-created them)."""
inherit — no visible window and no per-descendant conhost flashes (the console-less pythonw.exe
alternative re-created #54220/#56747 for every descendant)."""
_assert_windows()
args = ["-m", "hermes_cli.main", *_current_profile_cli_args(), "gateway", command, *(extra_args or [])]
params = subprocess.list2cmdline(args)
@@ -326,7 +327,7 @@ def _build_gateway_vbs_script(python_path: str, working_dir: str, hermes_home: s
Run via ``wscript.exe``, not ``cmd.exe``: at logon Windows broadcasts CTRL_CLOSE_EVENT to console
groups, killing a cmd-hosted gateway with STATUS_CONTROL_C_EXIT, which Task Scheduler treats as a
user cancel (``RestartOnFailure`` never fires). wscript has no console; python.exe runs with window
style 0 so descendants inherit one hidden console instead of flashing their own.
style 0 so descendants inherit one hidden console instead of flashing their own (#54220/#56747).
"""
python_exe_path, venv_dir, extra_pythonpath = _resolve_detached_python(python_path)
# list2cmdline gives CreateProcess-correct quoting for WScript.Shell.Run.
@@ -573,7 +574,8 @@ def _spawn_detached(script_path: Path | None = None) -> int:
"""Launch the gateway as a fully detached background process (``script_path`` is ignored; kept
for API symmetry). Spawns python.exe directly — a cmd.exe shim inherits the parent console and
gets reaped when the shell exits. Flags: CREATE_NEW_PROCESS_GROUP (no Ctrl+C from our group),
CREATE_NO_WINDOW (hidden console descendants inherit, so nothing flashes), CREATE_BREAKAWAY_FROM_JOB
CREATE_NO_WINDOW (hidden console descendants inherit, so nothing flashes — #54220/#56747; the old
DETACHED_PROCESS made every descendant spawn flash), CREATE_BREAKAWAY_FROM_JOB
(escape a parent Job Object — some Windows Terminal versions wrap children in one)."""
_assert_windows()
argv, working_dir, env_overlay = _build_gateway_argv()
+11 -4
View File
@@ -191,9 +191,13 @@ DEFAULT_DB_PATH = _IMPORT_DEFAULT_DB_PATH = get_hermes_home() / "state.db"
# Back off from read-only opens after one fails: not per query, but short enough that
# transient fd pressure doesn't strand the read pool.
_READ_OPEN_RETRY_SECONDS = 60.0
# Transient SQLITE_IOERR retry budget for READ-ONLY opens: a WAL writer's checkpoint/reset/
# frame flush surfaces "disk I/O error" to a concurrent mode=ro reader for a millisecond-wide
# window (ro cannot do the -shm recovery). Never for writable opens: there an IOERR is real.
# Transient SQLITE_IOERR retry budget for READ-ONLY opens (#100436): a WAL writer's checkpoint/
# reset/frame flush surfaces "disk I/O error" to a concurrent mode=ro reader for a millisecond-
# wide window — the ro connection cannot perform WAL recovery because recovery writes the -shm
# index, which mode=ro refuses. The writer closes the window on its own, so a few short retries
# make the open succeed instead of 500-ing the whole /api/sessions poll (or any other ro opener).
# Deliberately NOT for writable opens: a writer owns the transition, so an IOERR there is a real
# storage/fd problem. A persistent IOERR still exhausts the budget and propagates.
_READ_ONLY_IOERR_RETRY_ATTEMPTS, _READ_ONLY_IOERR_RETRY_BACKOFF_S = 3, 0.05
@@ -552,7 +556,10 @@ class SessionDB(
raise
return
except sqlite3.OperationalError as ioerr:
# Transient SQLITE_IOERR window (see _READ_ONLY_IOERR_RETRY_ATTEMPTS).
# In-flight WAL checkpoint/reset/frame-flush on the writer side can surface
# SQLITE_IOERR to a mode=ro reader (it can't do the -shm recovery the read
# needs). Closes in milliseconds: retry a bounded number of times before
# classifying the store as failed (#100436; see _READ_ONLY_IOERR_RETRY_ATTEMPTS).
transient = _DISK_IO_ERROR_MARKER in str(ioerr).lower()
if attempt >= _READ_ONLY_IOERR_RETRY_ATTEMPTS or not transient:
raise