From 5a0efda99252f3ecbbbedde42693b0c222a3674d Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Thu, 3 Sep 2026 09:32:25 -0700 Subject: [PATCH] review-fix(comments): restore reviewer-named rationale blocks (#4926, #81335, #54220/#56747, #100436, #5057/#6252/#10370/#4665) --- agent/copilot_acp_client.py | 2 +- agent/transports/codex_app_server.py | 3 ++- cli.py | 3 ++- gateway/platforms/base.py | 26 ++++++++++++++++++++------ gateway/run_busy.py | 7 ++++++- gateway/run_shutdown.py | 2 +- hermes_cli/_subprocess_compat.py | 9 ++++++--- hermes_cli/commands.py | 6 +++++- hermes_cli/gateway.py | 5 ++++- hermes_cli/gateway_windows.py | 8 +++++--- hermes_state.py | 15 +++++++++++---- 11 files changed, 63 insertions(+), 23 deletions(-) diff --git a/agent/copilot_acp_client.py b/agent/copilot_acp_client.py index 902b25092e..c32fc6478c 100644 --- a/agent/copilot_acp_client.py +++ b/agent/copilot_acp_client.py @@ -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, diff --git a/agent/transports/codex_app_server.py b/agent/transports/codex_app_server.py index 5d1ed418aa..03912a7ebc 100644 --- a/agent/transports/codex_app_server.py +++ b/agent/transports/codex_app_server.py @@ -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( diff --git a/cli.py b/cli.py index 0363da0528..8026de3d0e 100644 --- a/cli.py +++ b/cli.py @@ -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: diff --git a/gateway/platforms/base.py b/gateway/platforms/base.py index de4a3982cd..aa1acac24c 100644 --- a/gateway/platforms/base.py +++ b/gateway/platforms/base.py @@ -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 diff --git a/gateway/run_busy.py b/gateway/run_busy.py index a332b66504..f200e640e4 100644 --- a/gateway/run_busy.py +++ b/gateway/run_busy.py @@ -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") diff --git a/gateway/run_shutdown.py b/gateway/run_shutdown.py index 75121e9025..be40f06b47 100644 --- a/gateway/run_shutdown.py +++ b/gateway/run_shutdown.py @@ -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" diff --git a/hermes_cli/_subprocess_compat.py b/hermes_cli/_subprocess_compat.py index 7f57ae2097..c4e0729890 100644 --- a/hermes_cli/_subprocess_compat.py +++ b/hermes_cli/_subprocess_compat.py @@ -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`. """ diff --git a/hermes_cli/commands.py b/hermes_cli/commands.py index a2a610e60f..b37ac4d89f 100644 --- a/hermes_cli/commands.py +++ b/hermes_cli/commands.py @@ -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 diff --git a/hermes_cli/gateway.py b/hermes_cli/gateway.py index d7059cbc3d..90728a21c5 100644 --- a/hermes_cli/gateway.py +++ b/hermes_cli/gateway.py @@ -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] = {} diff --git a/hermes_cli/gateway_windows.py b/hermes_cli/gateway_windows.py index e292c90168..a561c7c376 100644 --- a/hermes_cli/gateway_windows.py +++ b/hermes_cli/gateway_windows.py @@ -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() diff --git a/hermes_state.py b/hermes_state.py index 586d975bee..95453ba582 100644 --- a/hermes_state.py +++ b/hermes_state.py @@ -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