sjTfdZddlmZddlZddlZddlZddlZddlZddlm Z ddl m Z m Z m Z ejeZGddeZejdZejd ZdIdZehdZehdZdZdZedZeddhZdJdZehdZdZ ejdZ!dZ"dZ#e e$ge e$fZ%dKd Z&dLd$Z'dMd%Z(dNd&Z)dId'Z*dMd(Z+dOd+Z,dPd.Z-dd/dQd1Z.dRd3Z/dSd5Z0dTd7Z1dUd8Z2dd9dVd@Z3dddAdWdBZ4dXdCZ5dYdDZ6 dZd[dHZ7dS)\u~Gateway lifecycle guard for cron job creation (#30719). An agent running inside a gateway can schedule a cron job that calls ``hermes gateway restart`` (or ``launchctl kickstart ai.hermes.gateway`` or ``systemctl restart hermes-gateway``). When the cron fires, the gateway dies, the supervisor (launchd KeepAlive / systemd Restart=) revives it, auto-resume picks up the offending session, and the resumed turn re-runs the same logic — a SIGTERM-respawn loop every ~10 seconds until manually broken. This module rejects cron job specs whose prompt or script contains a direct shell-level gateway-lifecycle command. It is enforced at ``cron.jobs.create_job`` so it fires on every job-creation path: the ``hermes cron create`` CLI subcommand AND the agent's ``cronjob`` model tool (which calls ``create_job`` directly, bypassing the CLI layer). The pattern is intentionally command-shaped: it anchors on a concrete command identifier (``hermes gateway``, ``launchctl ... hermes-gateway``, ``systemctl ... hermes-gateway``, ``pkill`` against the gateway) so it cannot fire on prose. A cron ``prompt`` is fed to a future LLM, not a shell, so an over-broad substring match on English ("Kong API gateway autoscaling and restart behavior") would produce a high false-positive rate without preventing the actual foot-gun, which requires a real command shape. This is a defence-in-depth layer. ``tools/terminal_tool.py`` blocks direct commands and shell scripts they reference when ``_HERMES_GATEWAY=1``. It also rejects ``launchctl submit`` in gateway sessions because launchd treats that primitive as a persistent KeepAlive job, not a one-shot task. ``hermes gateway stop|restart`` separately refuse to self-target from inside the gateway. Blocking cron specs at creation time as well means the agent gets an immediate, informative rejection instead of scheduling a job that will only fail (silently) when it fires. ) annotationsN)Path)CallableIteratorOptionalceZdZdZdS)GatewayLifecycleBlockedzARaised when a cron job spec contains a gateway-lifecycle command.N)__name__ __module__ __qualname____doc__8/home/agent/.hermes/hermes-agent/cron/lifecycle_guard.pyr r 1sKKKKrr a8(?i)(?:hermes\s+gateway\s+(?:restart|stop))|(?:launchctl\s+(?:kickstart|unload|load|stop|restart|submit|bootstrap)\b[^\n]*\bhermes[.\-]?gateway)|(?:systemctl\s+(?:-\S+\s+)*(?:restart|stop|start)\b[^\n]*\bhermes[.\-]?gateway)|(?:p?kill\b[^\n]*\bhermes\b[^\n]*\bgateway)|(?:p?kill\b[^\n]*\bgateway\b[^\n]*\bhermes)z \\\r?\n[ \t]*textstrreturnboolc|sdStd|}tt|S)zCReturn True if *text* contains a gateway lifecycle command pattern.F )_SHELL_LINE_CONTINUATIONsubr_GATEWAY_LIFECYCLE_PATTERNsearchr normalizeds r"contains_gateway_lifecycle_commandrbsA u)--c488J *11*== > >>r>shkshzshbashdash>+O+o-O-oi;&|()zMobile Documents CloudStoragepathrcb|jtfdtDS)a8Return True for paths inside a macOS FileProvider-backed subtree. ``O_NONBLOCK`` does not make regular-file reads non-blocking. Opening an evicted FileProvider placeholder below ``~/Library/Mobile Documents`` (iCloud Drive) or ``~/Library/CloudStorage`` (Dropbox / OneDrive / Google Drive and other third-party providers) can therefore wait indefinitely for hydration. The lifecycle guard runs before a terminal command's timeout starts, so it must identify this boundary from path metadata and fail closed without opening the file. c3RK|]!\}}||dz dko|tvV"dS)LibraryN)_CLOUD_PLACEHOLDER_MARKERS).0indexpartpartss r z-_is_cloud_placeholder_path..sZ E4  eaiI%L$2L*Lr)r3any enumerate)r*r3s @r_is_cloud_placeholder_pathr7xsL JE $U++  r> agrgackgreppsqlegrepfgrepsqlite3 journalctl)`z$(z<(z>(z\!zB\|\s*&?\s*(?:sudo\s+)?(?:sh|bash|dash|ksh|zsh|xargs|eval|source)\b)sELFsMZsssssicommandIterator[list[str]]c#K|dd}|p|gD]} tj|dd}d|_d|_t |}n#t $rYDwxYwg}|D]:}|r!t|tkr |r|Vg}%| |;|r|VdS)zEYield shell-tokenized command segments, honoring quotes and comments.z\ Tr(posixpunctuation_chars#N) replace splitlinesshlexwhitespace_split commenterslist ValueErrorset_CONTROL_CHARSappend)rBrlinelexertokenssegmenttokens r_iter_command_segmentsrYs,,J%%''7J< K")E &*E ""E %[[FF    H   " "E U~55!!MMM G NN5 ! ! ! !  MMM-s4A(( A54A5rW list[str] Optional[int]cbt|D]\}}tjd|r|cSdS)z?Return the executable token index after simple env assignments.z^[A-Za-z_][A-Za-z0-9_]*=N)r6rematch)rWr1rXs r_command_token_indexr_sC!'** u 8/ 7 7   4rct|D]`}t|}|t||jdkr.||dzd}|r|ddvrdSadS)aDetect an executed ``launchctl submit``/``bootstrap``, not quoted text. Label-independent by design: the label of a submitted/bootstrapped job is chosen by whoever writes it, so a neutral name (``ai.hermes.svc-reload-tmp``) defeats any label-anchored regex (#62891, second reproduction). Both verbs register a NEW persistent launchd job (``submit`` jobs get KeepAlive semantics; ``bootstrap`` loads an arbitrary plist), which is never safe to do from inside the gateway process. N launchctlr-r>submit bootstrapTF)rYr_rnamelower)rBrWr1 argumentss r!contains_launchctl_submit_commandrgs*'22$W-- =     $ 3 3 ,I Yq\//115LLLtt 5rcBg}d}|p|gD]}t|r||3 t j|dd}d|_d|_t|}n%#t$r||YwxYwg}g}|D]_}|rFt|tkr.||||gg}J||`||g} |D]} | st| } | t| | j tvrh| | dzd} td| DsBd}| | d| dz| d | D| | |d | |s|Sd |S) uReplace data-sink executables' arguments with a neutral placeholder. The lifecycle regex is command-shaped, but it cannot tell an EXECUTED ``systemctl restart hermes-gateway`` from the same characters appearing as *data* — a grep/rg pattern, a journalctl filter, a SQL string literal passed to sqlite3/psql. Those diagnostics commands were being rejected (false positives blocking legitimate cron prompts), e.g.:: grep -c 'systemctl restart hermes-gateway' /var/log/syslog sqlite3 db "SELECT msg FROM log WHERE msg LIKE '%systemctl restart hermes-gateway%'" This masker shell-tokenizes each line and, for command segments whose executable is a known data sink (``_DATA_SINK_EXECUTABLES``), replaces every argument with ``arg``. The caller then re-runs the lifecycle regex on the masked text: a match that survives masking sits OUTSIDE any data argument and is a real command. Strictly fail-closed: masking is skipped (leaving the original, regex-matching text in place) whenever the line pipes into a shell or interpreter, any argument carries an execution-capable marker (substitution, sqlite3 ``.``-commands, psql ``\!``), or the line cannot be tokenized at all. Masking can therefore only ever ALLOW a command the plain regex would have blocked — never block one it would have allowed — so it runs solely as a second-pass exemption check. FTr(rFrINr-c3K|]9dptfdtDV:dS).c3 K|]}|vV dSNr)r0markerarguments rr4z6_mask_data_sink_arguments...+s(UU&6X-UUUUUUrN) startswithr5_UNSAFE_DATA_ARG_MARKERS)r0rns @rr4z,_mask_data_sink_arguments..)sn!'',,VUUUU.0s""<"BX%X%X#EAIKK0 %. #GNN7;UQY;#7888NN"<"<)"<"<"<<<< NN7 # # # #'**++++  99Y  s4BB'&B'ct|sdStd|}tt|S)uOLifecycle-regex scan that exempts matches living inside data arguments. Two-pass: the cheap regex first (the overwhelmingly common no-match case pays nothing extra); on a raw match, re-scan with data-sink arguments masked out. Only a match that survives masking — i.e. one in actual command position — blocks. Fr)rrrr~rs r+_lifecycle_command_scan_with_data_exemptionr9sE .d 3 3u)--c488J -.G .S.S T TTrc>t|pt|S)zCPure-string direct scans: lifecycle regex (data-exempted) + submit.)rrg)rBs r_direct_lifecycle_scanrGs' 6   4 *7 3 34r candidateOptional[Path]c|rd|vrdS t|S#tttf$rYdSwxYw)uSanitize a tokenized path candidate at the ingestion boundary. Candidate tokens come from shlex-splitting arbitrary command text — including text recursively decoded from binaries or remote reads — so they can carry NUL bytes or other junk no real filesystem path can contain. Every OS-facing ``Path`` operation downstream (``expanduser``, ``os.open``, ``resolve``) raises a *different* exception for the same junk (``ValueError: embedded null byte``, ``RuntimeError: Could not determine home directory`` when HOME is unset under launchd, OSError for over-long paths). Rejecting here — once, before any OS call — is the whole-class fix; catching per-syscall was the whack-a-mole that produced #76762, #77703, #77780, and #78256. Returns ``None`` for candidates that cannot be a real path (nothing to scan), otherwise the ``expanduser()``-expanded ``Path``. N)r expanduserrP RuntimeErrorOSError)rs r_expand_candidate_pathrNsa" )++tI))+++  g .tts +AAcwd Optional[str]ct|}|dS|s8 t|ptj|z }n#t$rYdSwxYw|Srl)r is_absoluterrr)rrr*s r_resolve_terminal_script_pathrgsz !) , ,D |t      )txzz**T1DD   44  Ks%A AArIterator[Path]c#Kt|D]Y}t|}|||}t|j}|dvr6t ||dzkrt ||dz|}||Vk|t vr||dzd}d}|t |krD||} | dkr|dz }n0| dvrn+| tvr|dz };| dr|dz }V |t |kr&||dvrt |||}||V| d r/d |vs| d rt ||}||V[dS) z9Yield scripts executed directly or through a POSIX shell.N>sourcerjr-rz---c --command-/)z.shz.bashz.zsh) rYr_rrdlenr_SHELL_EXECUTABLES_SHELL_OPTIONS_WITH_VALUESrostripendswith) rBrrWr1 executableexecutable_nameresolvedrf arg_indexrns r_iter_referenced_shell_scriptsrts *'221#1#$W-- = U^ z**/ o - -7||eai''89KSQQ'"NNN  0 0 0 ,IIc)nn,,$Y/t##NI222999NI&&s++NI3y>>))i .BK//999MsSS'"NNN    C  #j  J$7$78P$Q$Q 8SII'"NNNc1#1#r Iterator[str]c#Kt|D]r}t|}|!t||jtvr5||dzd}t |ddD]\}}|dvr||dzVnsdS)zDYield code passed through ``sh|bash|... -c`` for recursive scanning.Nr-r)rYr_rrdrr6)rBrWr1rfrrns r_iter_shell_command_payloadsrs)'22$W-- =D005=OOO EAIKK( #,Yss^#<#<   Ix... A ..../ r script_pathc t|}|(|rt|jSn#t$rYnwxYwdS)zHReturn the directory *script_path* resolves to, handling relative names.N)_resolve_script_pathrrparent Exception)rr*s r_resolve_script_directoryrsa #K00   0 0 2 2 t{## #      4s8< A A tuple[Optional[str], bool]ct|rdS |d}n#ttf$r|}YnwxYwt|rdStjt tddz} t j||}n#ttf$rYdSwxYw t j|}tj |j sGtj |j r t j |dS t j |dSt j|t}|t"sd|vr t j |dSt%|t&krMt j|t&dzt%|z }|sn||z }t%|t&kMn%#t$rYt j |dSwxYwt j |n#t j |wxYwd|vrdSt%|t&krdS|d d dfS) uReturn ``(text, unsafe)`` using bounded, regular-file-only reads. This is the shared choke point for every local script read the guard performs (the terminal walk in ``_contains_unsafe_gateway_action`` AND the cron-script scan in ``_read_script_for_scanning``), so the cloud-placeholder refusal lives here: a FileProvider path must never be opened — not even to discover whether the file is hydrated — because an evicted placeholder's ``open()`` can hang preflight indefinitely (#88052). The lexical check covers direct cloud paths; the resolved check covers local launchers that are symlinks into a cloud subtree. NTFstrict O_NONBLOCKrNFr-utf-8rJerrors)r7resolverrPosO_RDONLYgetattropenfstatstatS_ISREGst_modeS_ISDIRcloseread_BINARY_SNIFF_BYTESro_BINARY_MAGIC_PREFIXESr_MAX_REFERENCED_SCRIPT_BYTESdecode)r*rflags descriptormetadatadatachunks r_read_referenced_scriptrs"$''z<1 MiB multibyte file truncated at the byte cap decodes to fewer characters than bytes, and a character-count check would scan the truncated text instead of failing closed. Enforced here rather than inside each callback so the guarantee holds for every callback, not just the ones we hardened. rrrrJrrF)rencoder)rs r_sanitize_remote_script_textrsR" { ~~{ 4;;wy; 1 1225QQQz ;r)read_remote_scriptdepthintvisited set[Path]rOptional[_ReadRemoteScriptFn]ct|rdS|tkrdSt|D]}t|||dz||rdSt ||D]}t |rdS |d}n#ttf$r|}YnwxYwt |rdS||vr\| |t|\}} | rdS|/|-t|t|\}} | rdS|stt|p|} t|| |dz||rdSdS)NTr-rrrrrFr)r_MAX_REFERENCED_SCRIPT_DEPTHr_contains_unsafe_gateway_actionrr7rrrPaddrrrr) rBrrrrpayloadrr script_textunsafe script_dirs rrr.sg&&t ,,,t/88 * !)1     44 6g3GGG..  &k 2 2 44 #"**%*88HH$ # # ##HHH  # &h / / 44 w    H5kBB V  44  #5#A #?""3{#3#344## K tt  /s8}}==D * !)1     44  5s1BBB)rrc t||dt|S#t$r_tdd t |cYS#t$r#t |pt|cYcYSwxYwwxYw)uFDetect lifecycle/submit commands, including bounded nested scripts. Total by construction: this function returns a verdict for *every* input and never raises. The direct scans below are pure string operations; the referenced-script walk touches the filesystem, remote backends, and shlex on arbitrary decoded bytes, so it is best-effort defense-in-depth — any unexpected failure inside it is logged and treated as "walk found nothing" rather than crashing the caller. This is the contract #76762 established ("a guarded path must never crash the guard") enforced at the boundary instead of per-syscall: a guard crash propagates out of ``tools/terminal_tool.py`` and breaks every terminal command until the gateway restarts (#77780, #78256), which is strictly worse than either verdict. rrzRlifecycle guard referenced-script walk failed; falling back to direct-scan verdictT)exc_info)rrQrloggerwarningrrrg)rBrrs r7contains_gateway_lifecycle_command_or_referenced_scriptrws*<. EE1      <<< 2     <)'22 2 2 2 < < <6<27;; < < < < <  </scripts/`` and only accepts absolute paths as-is. We MUST mirror that here so the guard scans the file that will actually run — otherwise a job whose script lives at the scheduler's real location (``~/.hermes/scripts/restart.sh``) but is passed as the bare name ``restart.sh`` would read as a nonexistent relative path and silently scan prompt-only content, letting the command through. Returns ``None`` for values that cannot be a real path (NUL bytes, unexpandable ``~``) — the same ingestion contract as ``_expand_candidate_path``; such a value can never name a file the scheduler would execute, so there is nothing to scan. r)get_hermes_homeNscripts)hermes_constantsrrrrr)rrraws rrrs 100000  - -C {t    9,s22 ' "tt sAAAc\t|}|dSt|\}}|rdS|pdS)aRead a cron script with the bounded terminal-script scanner. Non-regular or oversized inputs fail closed by returning a lifecycle-shaped sentinel, while missing/unreadable/unresolvable paths remain empty so ordinary scheduler path validation can report them. NrEzhermes gateway restart)rr)rrrrs r_read_script_for_scanningrsG$K00Hr1(;;K (''  "rpromptscriptNonec|pd}d}|rt|}|^ |d}n#ttf$r|}YnwxYwt |st |rt d|duo |jdk}t|}|r|d|}|rt|}n$|rt|nd}t||}|rt d dS) aERaise ``GatewayLifecycleBlocked`` if *prompt* or *script* contains a gateway-lifecycle command pattern. ``prompt`` is scanned directly. ``script``, when supplied, is read from disk and concatenated for the scan. Both are considered together so a job cannot slip through by splitting the command across the prompt and the script. Callers should let the exception propagate when they want the create to fail with a ``ValueError``-shaped error (the agent's ``cronjob`` tool surfaces this as a tool error; the CLI prints it in red and exits 1). rEFNra<Blocked: the cron script lives on a cloud-synced path (iCloud Drive / ~/Library/CloudStorage). Opening an evicted FileProvider placeholder can hang the guard's preflight scan indefinitely, so it is refused without being read. Move the script to a local, non-cloud path (e.g. ~/.hermes/scripts/) and recreate the job.z.pyrtraBlocked: cron job contains a gateway lifecycle command or persistent launchctl submit operation. This is blocked to prevent agent-driven SIGTERM-respawn loops under launchd/systemd supervision (#30719). Run `hermes gateway restart` from a shell outside the running gateway instead.) rrrrPr7r suffixrrrr) rrcombined python_scriptresolved_script real_scriptrrrs rcheck_gateway_lifecyclersj |HM 4.v66  & .-55U5CC Z( . . .-  .)/:: >X?? .F(t3W8NRW8W /77  4"33k33H =XFF:@J.v666d H     % +     s2AA)rrrr)r*rrr)rBrrrC)rWrZrr[)rBrrr)rrrr)rrrr)rrrrrr)rBrrrrr)rBrrr)rrrr)r*rrr)rrrr) rBrrrrrrrrrrr)rBrrrrrrr)rrrr)rrrrrl)rrrrrr)8r __future__rloggingrr]rLrpathlibrtypingrrr getLoggerr rrPr compilerrr frozensetrrrrrRr/r7rvrprurrr_ReadRemoteScriptFnrYr_rgr~rrrrrrrrrrrrrrrrrrs!!F#""""" //////////  8 $ $LLLLLjLLL(RZ4N&2:&677????YCCCDD&Y'?'?'?@@* 7##'Y(:N'KLL2#RRR:"rzI uhsm348*H H H H V U U U U44442     7#7#7#7#7#7#t    K9K9K9K9\@9= FFFFFFX8< -<-<-<-<-<-