߲j UdZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddl m Z m Z mZddlmZej$dZdZdZeZd ed <e j2ZeZd ed <e j2ZeZd ed <e j2ZeZd ed <e j2Z eZ!d ed<e j2Z"eZ#ded<e j2Z$dZ%dRdZ&dSdZ'dTdZ(dUdZ)dTdZ*dTdZ+dTdZ,dVdWdZdRdZ-dXdZ.dRdZ/Gddej`Z1e2hdZ3iZ4d ed!<e j2Z5eZ6d ed"<e j2Z7eZ8d ed#<e j2Z9dYdZd$Z:dYd[d%Z;d\d&Zd)d*d+d_d,Z?d`d-Z@dad.ZAdTd/ZBd*d0dbd1ZCdRd2ZDd3d4d5d6ZEe d ejd7fe$dejd8fed ejd9fed ejd:fe"dejd;fed ejdfd?ZHdcd@ZId*dAdddBZJdedCZKejeIdDZMejeIdEZNddFdGdHdIZOdJedK<eOjDcic]\}}|| c}}ZQdLedM<dGZRdfdNZSdgdOZTd)dPdhdQZUycc}}w)izSQLite journal-mode and PRAGMA policy for state.db (split from hermes_state). Patchable helpers are looked up as module globals at call time, so tests patch ``hermes_state_wal.``. ) annotationsN)AnyDictOptional)is_sqlite_wal_reset_vulnerable hermes_state)zlocking protocolznot authorizeddisk i/o errorizset[str]_wal_fallback_warned_paths!_wal_delete_fallback_failed_paths_wal_probe_unknown_paths_wal_reset_bug_warned_paths_delete_overridden_warned_pathsset_journal_upgrade_warned_pathsucould not verify journal mode before applying configured journal_mode=delete (database is locked — possible concurrent openers); refusing to downgrade a database this process does not exclusively ownch|r/|d*t|djjSdS)zFLower-cased mode from a ``PRAGMA journal_mode`` row, ``""`` if no row.r)strstriplower)rows 5/home/ubuntu/.hermes/hermes-agent/hermes_state_wal.py_mode_from_rowr8s2*-#a&2D3s1v;    $ $ &L"LctdD]{} |jdj}|r|dnd}t|tr |jd}|)t |jj cSdcStjdy#tj$rB}dt |j vrYd}~y|}tjdYd}~d}~wwxYw#t$rYywxYw) a"Read the journal mode from the DB header; ``None`` if undeterminable (new DB, or PRAGMA failed) -> callers take their fail-closed "refuse to downgrade" branch. ``disk i/o error`` can be transient on virtualized block devices (XFS on cloud hosts), so it is retried a few times first.PRAGMA journal_moder N皙?rasciiz:_on_disk_journal_mode: retries exhausted on disk read (%s))rangeexecutefetchonesqlite3OperationalErrorrrtimesleep isinstancebytesdecodeUnicodeDecodeErrorrloggerdebug)conn_rexclast_excmodes r_on_disk_journal_moder1=s1XG ,,45>>@Cs1v$ dE " {{7+-1,tjtj 5|j |dddyy#1swYyxYw)zABest-effort PRAGMA on macOS only (no-op elsewhere, never raises).darwinN)sysplatform contextlibsuppressr"r#r )r,pragmas r_darwin_pragmar<_sM ||x  !9!9 : ! LL  ! !  ! !s AAct|dy)uEnable ``PRAGMA checkpoint_fullfsync`` on macOS. Apple's ``fsync(2)`` guarantees neither data-on-platter nor ordering, so without ``F_FULLFSYNC`` a launchd shutdown can turn a "durable" checkpoint into a malformed ``state.db``. Checkpoint boundaries only (~+0.1 ms/commit vs ~+4 ms for ``fullfsync=1``). During a launchd *system* shutdown/reboot the OS page cache is dropped (effectively a power-loss event for in-flight pages), so a WAL checkpoint whose ``fsync()`` "reported" durable may never have hit the platter — corrupting ``state.db`` with a malformed image. This is the trigger in issue #30636 ("SIGTERM during launchd shutdown under high load"), distinct from a plain in-session kill (which the page cache survives and SQLite recovers from). zPRAGMA checkpoint_fullfsync=1Nr<r,s r_apply_macos_checkpoint_barrierr@fs489rct|dy)zEnforce ``PRAGMA synchronous=FULL`` on macOS: with NORMAL a WAL checkpoint racing process termination leaves half-written btree pages (``btreeInitPage error 11``). Called after every WAL activation so a prior NORMAL never sticks.zPRAGMA synchronous=FULLNr>r?s r_enforce_macos_synchronous_fullrBts423rcFt|t|t|y)zGThe settings every WAL activation carries: size limit + macOS barriers.N)r4r@rBr?s r_apply_wal_companionsrD{s$#D)#D)rcDt|tjS|S)uTrue when the linked SQLite has the WAL-reset bug (3.7.0–3.51.2; fixed 3.51.3+, backports 3.50.7 / 3.44.6). Pre-WAL libraries are safe. https://sqlite.org/wal.html#walresetbug)_is_sqlite_wal_reset_vulnerabler"sqlite_version_info) version_infos rrrs# +,J^7+F+F qqdp qqrc tjtjd5}|j dj }dddr|dt|dSdS#1swY xYw#tj $rYywxYw)zCReturn ``sqlite_source_id()``, or an empty string when unavailable.z:memory:zSELECT sqlite_source_id()Nrr)r9closingr"connectr r!Errorrr,rs rsqlite_source_idrNs    ; < G,,:;DDFC G#a&"43s1v;<"<  G G ==s((A5 A) A5)A2.A55B  B c |jdj}t|xr|dduxrt|ddkDS#tj t tf$rYywxYw)zWhether the file already holds pages (existing vs brand-new DB); lock-free header read. Fail-quiet False: the only caller gates a warning on this and an unknown-answer warning would fire on every fresh database.zPRAGMA page_countrNF)r r!boolintr"rL TypeError ValueErrorrMs r_database_has_contentrTsell./88:CyCSV4/CCAK!OC MM9j 1sAAA)(A)c ddlm}|xsijdi}t|tr|jddnd}t|t r|jjnd}|dvr|SdS#t $rYywxYw)zThe configured ``database.journal_mode`` (``wal`` default; ``delete`` for filesystems without WAL-safe durability: macOS virtiofs, NFS, SMB). Invalid values fail safe to ``wal``.r)load_config_readonlydatabase journal_modewalr)rYdelete) hermes_cli.configrVgetr&dict Exceptionrrr)rVrWrawr0s rresolve_journal_moder`s:(*0b55j"E5?$5Ohll>51UZ#-S#"6399;   BD,,47%7 sAA?? B  B ceZdZdZy)WalUnsupportedErrora@Raised by :func:`apply_wal_with_fallback` under ``require_wal=True`` when the filesystem cannot provide WAL (SQLITE_PROTOCOL raised, or macOS-NFS silent refusal) or the on-disk mode cannot be verified (probe blocked by a concurrent opener). Subclasses ``OperationalError`` so DB-init handlers still catch it.N)__name__ __module__ __qualname____doc__rrrbrbsTrrb>9p2000.l9p2000.u fuse.virtiofs9p9p2000virtiofszDict[str, bool]_cross_vm_fs_cache_cross_vm_warned_paths#_cross_vm_existing_wal_warned_pathscJ t|ddd5}|jj}dddd\}}D]}|j d\}}} |j } t | d ks| s9| d } d | vr!| jd d jd} || k(s$|j| jddzst | |kDst | | j d}}|jS#1swYxYw#t$rYywxYw)zffstype of the longest mount point that is a prefix of ``directory`` (``""`` if unreadable / no match).rzutf-8replace)encodingerrorsNr)rz - r\zlatin-1ignoreunicode_escape/r) openread splitlinesOSError partitionsplitlenencoder( startswithrstripr) directorymountinfo_pathfhlinesbest_len best_fstypelinefieldsr-tailparts mount_points r_mountinfo_fstypers( .# J +bGGI((*E +#Hk J../4  u:> Ah ; %,,YAHHIYZK  #y';';K#t j$r(} d t| jvr| }Yd} ~ od} ~ wwxYwt| dk(r|ccYd}~Sntd vr|rt t||t | t!d n~#t j$rh} t#d||  tjdj} n#t j$rd} YnwxYw| xsdcYd} ~ cYd}~Sd} ~ wwxYwYd}~yd}~wwxYw)zIFlip a non-WAL, non-vulnerable connection to WAL, or fall back to DELETE.NrYc8r tty)NrY)_log_journal_mode_upgrade_oncerD)r,rrupgrading_existing_dbsr_wal_activatedz#_enable_wal.._wal_activatedFs *8\ Bd#rzPRAGMA journal_mode=WALz0journal_mode=WAL refused without raising (still rrZc3&K|]}|v ywNrg).0markermsgs r z_enable_wal..[sEV6S=Esr rr)rYNrwal_delete_fallback_failedrrreturnr)rTrr r!rb_log_wal_fallback_oncer"r#rrany_WAL_INCOMPAT_MARKERSrr$r%r1rr)r,rrrrr0 silent_excr.r-r retry_exc delete_exc read_backrrs`` ` @@rrr@s+)4n9NnShimSn =dll+DENNPQ 5=!# #(+[\`[ccd)ef  x4x   # #0#hnnE/DEE  s "1X  4 ,,'@AJJLC//'s9~/C/C/EE#C  "#&%/)++  ! &- 7  %c#h/S 8x- ) %dH 5'' ) 2Hc: N *4<<8M+N+W+W+YZ ++   ( ( ( )a0s3B$BH<AH78DH7E+E H7EH7,H<24H7' F43H74H/H*(G?>H*?HH*HH*H/ H7$H<*H//H77H<cp |jdj}|r|dt|dnd}|jd t|jd|jtjtj5|jd|dddS#tjt t f$rd}YwxYw#1swYSxYw#tjtj5|jd|dddw#1swYwxYwxYw)aExecute ``PRAGMA journal_mode=`` without waiting on other openers. The ONLY place a non-WAL journal-mode switch may be issued. ``busy_timeout=0`` turns SQLite's exclusivity requirement into a concurrent-opener detector: leaving WAL needs exclusive access, so if ANY other connection holds the DB the pragma fails immediately with ``database is locked`` instead of sneaking the flip between a writer's transactions (how uncheckpointed WAL commits die). Callers must treat a raised ``OperationalError`` as "not exclusively owned: leave the mode alone", never as retryable. Returns the reported mode, ``""`` if no row.zPRAGMA busy_timeoutrNzPRAGMA busy_timeout=0zPRAGMA journal_mode=zPRAGMA busy_timeout=) r r!rQr"r#rRrSrr9r:)r,r0rprevious_timeouts rrrs ll01::<*-#a&2D3s1v;! LL()Ddll-A$+HIRRTU  !9!9 : D LL/0@/AB C D D  $ $i <  D DZ !9!9 : D LL/0@/AB C D D DsA6B5 *C'C5 CCC$ '$D5 D) D5)D2 .D5cPt|}|rt|r td|yyy)aG#110848: the fresh-DB cross-VM refusal never sees a DB that was already WAL before the check existed (or was created on a native volume and then moved). Keeping WAL is right (never live-downgrade); staying silent is not. Both the vulnerable-SQLite and the regular already-WAL paths return early, so both must call this.cross_vm_fs_existing_walN)rrr)r,rs rrrs+"$'G'0,g61wr)rct|}|dk(r1t|d|r t|t|t |y|*|rt j tt|ddyd} t|d}|r t|t|d y #t j $r\}|rdt|jvsd t|jvrt|dd|xsd cYd}~SYd}~d}~wwxYw) uAvoid enabling WAL when the linked SQLite has the WAL-reset bug. Already-WAL on disk: keep WAL (no live downgrade) and warn. Mode unreadable (probe blocked by a concurrent opener): not provably exclusive — leave it and warn; treating "could not read" as "not WAL" once flipped a live WAL state.db to DELETE under a writer, destroying its uncheckpointed commits. Otherwise set DELETE without waiting out openers and warn; an explicit operator request additionally verifies SQLite accepted DELETE.rYT)kept_walN)r indeterminaterrlockedbusyrZF) r1_log_wal_reset_bug_oncerrrDr"r#rrrrr)r,rrcurrentrr.s rrrs$D)G%48  28 <)$/d# **+DE E4tL F'*4:!&)Hu5   # #'   s3x~~' '6SX^^5E+E #Ht4 P&h &,F's1 BD+A D7DDc ddlm}m}m}||}||}|dvrd|dS|dk(rd|dS|S#t$rYywxYw) zhRepair hint matching what ``hermes update`` can actually do for this install type. See #75153. r)detect_install_methodget_project_root%recommended_update_command_for_method>gitunknownz>Hermes-managed installs can repair the embedded runtime with ``dockerz!update the container image with `zdinstall a Python build bundled with SQLite 3.51.3+ (or backports 3.50.7 / 3.44.6) and restart Hermes)r[rrrr^)rrrmethodcmds r_wal_reset_repair_hintrsr vtt&'7'9:3F; ' 'STWSXXYZ Z=Cx=O23%q9XUXX vuvs(8 88 AAujournal mode could not be verified or exclusively switched (database is locked — possible concurrent openers); leaving the journal mode untouched (no live downgrade under concurrent openers)u\is already in WAL mode — leaving WAL in place (no live downgrade under concurrent openers)z1using journal_mode=DELETE instead of enabling WAL)rrrZu %s: linked SQLite %s (interpreter %s) is vulnerable to the WAL-reset corruption bug (https://sqlite.org/wal.html#walresetbug) — %s. Upgrade to SQLite 3.51.3+ (or backports 3.50.7 / 3.44.6); %s. See `hermes doctor`. This warning fires once per process per database.a%s: on-disk journal_mode was %s and has been switched to WAL. This rewrites the database header and persists after this process exits. If %s was a deliberate choice (for example the mitigation for the SQLite WAL-reset bug, or a WAL-unsafe filesystem), setting it with PRAGMA on the file will not survive -- every open re-applies the configured mode. Set `database.journal_mode: delete` in config.yaml to make it stick. This message fires once per process per database.u%s: WAL journal_mode unsupported on this filesystem (%s) — falling back to journal_mode=DELETE (slower rollback-journal mode; reduces concurrency but works on NFS/SMB/FUSE/ZFS). See https://www.sqlite.org/wal.html for details. This message fires once per process per database.u%s: both WAL and DELETE journal_mode failed (WAL: %s; DELETE: %s) — continuing with the connection's current journal mode (reads/writes still work). Typically seen on APFS external SSDs under heavy contention. This message fires once per process per database.a%s: database.journal_mode=delete is configured but the on-disk database is already WAL; keeping WAL (a live downgrade under open connections can corrupt the DB). To apply journal_mode=DELETE, stop every Hermes process using this database and run `hermes sessions set-journal-mode delete` (add `--db PATH` for a store other than state.db). This message fires once per process per database.aY%s: could not verify the on-disk journal mode (database is locked / busy); not issuing a journal-mode set-pragma while another connection may hold the file (it could unlink the -wal/-shm sidecars that connection still uses). Leaving the file untouched; this connection inherits the on-disk mode. This message fires once per process per database.u%s: database directory is on a cross-VM filesystem (virtiofs/9p — typical for Docker Desktop / OrbStack / Podman host bind mounts). SQLite WAL shared-memory is not coherent across the VM boundary and can silently corrupt the database, so journal_mode=DELETE is used instead. To restore WAL concurrency, move the database onto a native volume (e.g. a named Docker volume) instead of a host bind mount. This message fires once per process per database.uo%s: existing WAL-mode database is on a cross-VM filesystem (virtiofs/9p — typical for Docker Desktop / OrbStack / Podman host bind mounts). SQLite WAL shared-memory is not coherent across the VM boundary and concurrent writers can silently corrupt the database. Hermes does not live-downgrade an on-disk WAL database. Fix one of two ways: stop every Hermes process using this database and run `hermes sessions set-journal-mode delete` (set `database.journal_mode: delete` in config.yaml to keep it), or move the database onto a native volume (e.g. a named Docker volume). This message fires once per process per database.) wal_reset_bugjournal_upgrade wal_fallbackrdelete_overriddenrrrct|\}}}}t|}|5||vr dddy|j|dddtj|||gd|Dy#1swY)xYw)zEmit ``_ONCE_LOGS[kind]`` once per (process, db_label). Callable *args* are resolved only after the dedupe check, so install-method probes run once.Nc3DK|]}t|r|n|ywr)callable)ras rrz_log_once../s*S(1+131+D*Ss ) _ONCE_LOGSglobalsaddr*log)kindrargslockset_namelevelmessageseens rrr&s{&0%5"D(E7 9X D  t    JJugxT*Sd*ST sA&A&&A/)rct|rdn|rdnd}td|tjtj |t y)zHLog once per (process, db_label) about the WAL-reset vulnerability path.rrrZrN)_WAL_RESET_BUG_ACTIONSrr"sqlite_versionr7 executabler)rrractions rrr2s4 #}OX`*fn oF ox)?)?QWYoprc td|||y)zCSingle WARNING per (process, db_label) about a non-WAL -> WAL flip.rN)r)r previous_modes rrr8s =-Hrrrr)OFFNORMALFULLEXTRAzDict[str, int]_SYNCHRONOUS_LEVELSzDict[int, str]_SYNCHRONOUS_NAMESct|tr|durdSdSt|tr |tvr|SdSt |j }|j tvrt|j Stjtt5t|tvr t|ndcdddS#1swYyxYw)zMap ``database.synchronous`` (``OFF``/``NORMAL``/``FULL``/``EXTRA`` any case, or ``0``-``3``) to its PRAGMA integer; None for anything else so the caller warns and leaves the level untouched (guessing at durability is worse).FrN) r&rPrQrrrupperrr9r:rRrS) raw_valuetexts rresolve_synchronous_levelr Hs)T"&q0D0)S!%);;yEE y>   !D zz|**"4::<00   Y 3FI);;s4yFFF s CC c\t|x}tjd||ytjdk(r(|t krtjd|t |ytjtj5|jd|dddy#1swYyxYw)uSet ``PRAGMA synchronous`` from config, never below FULL on macOS. Kept out of the integer loop in :func:`apply_database_pragmas`: this PRAGMA decides whether a commit is on the platter, so an unrecognised value must not fall through to "SQLite default" the way a bad ``cache_size`` can. Darwin floor: this runs after :func:`_enforce_macos_synchronous_full`, so a configured ``NORMAL`` would silently undo the btree protection — raising is allowed, lowering is refused out loud.Nz]%s: ignoring unrecognized database.synchronous=%r (expected OFF, NORMAL, FULL, EXTRA, or 0-3)r6z%s: refusing database.synchronous=%s on macOS; keeping FULL. Darwin's fsync() does not guarantee write ordering, so a lower level readmits the half-written btree pages FULL exists to prevent.zPRAGMA synchronous=) r r*warningr7r8_SYNCHRONOUS_FULLrr9r:r"r#r )r,rrrs r_apply_synchronous_pragmar Ys+955>v , ||xE,=$=%&.0B50I K    W55 64 *5'23444s B""B+rc ddlm}m}|}dD]w}||d|dx} t t |j }tjtj5|jd|d |dddy||dd dx}t!||| yy#t$rYywxYw#ttf$rtjd|||YwxYw#1swYxYw) ahApply optional performance and WAL-sizing PRAGMAs from ``config.yaml``. Journal mode is NOT handled here (owned by :func:`apply_wal_with_fallback`). ``database:`` keys: ``cache_size`` (negative = KiB, positive = pages), ``mmap_size`` (bytes, 0 = off), ``temp_store`` (0-3), ``wal_autocheckpoint`` (pages), ``journal_size_limit`` (bytes), ``synchronous`` (unset leaves the compile-time default, which differs between bundled/distro/Homebrew builds). Best-effort: failures are ignored so DB init never breaks on a malformed section. Applied to ALL connection types: writer, read_only, WAL readers.r)cfg_getrVN) cache_size mmap_size temp_storewal_autocheckpointjournal_size_limitrW)defaultz'%s: ignoring non-integer database.%s=%rzPRAGMA = synchronousr)r[rrVr^rQrrrRrSr*r r9r:r"r#r r ) r,rrrVcfg pragma_namervalueraw_synchronouss rapply_database_pragmasrms C"$m :  j+tL LI U  I,,./E !9!9 : : LL7;-q8 9 : : :#3 M4PP]!$(K^ :&  NNDhP[]f g   : :s.B+"B:+C'+ B76B7:'C$#C$'C0 r)r,sqlite3.Connectionr Optional[str])r,rrNone)r,rr;rrr r)rHzOptional[tuple]rrP)r,rrrP)z/proc/self/mountinfo)rrrrrr)rrrrrrP)rrrrP)r,rrr)rrrr)r,rrrrrPrr) r,rrrrrPrrrr)r,rr0rrr)r,rrrrrPrr)rrrrrrrr )rrrrPrrPrr )rrrrrr )rrrz Optional[int])r,rrrrrrr )r,rrrrr )Vrf __future__rr9 functoolsloggingrr"r7 threadingr$typingrrrhermes_cli.sqlite_runtimerrF getLoggerr*rr3rr __annotations__Lock_wal_fallback_warned_lockr _wal_delete_fallback_failed_lockr _wal_probe_unknown_lockr _wal_reset_bug_warned_lockr_delete_overridden_warned_lockr_journal_upgrade_warned_lockrrr1r4r<r@rBrDrNrTr`r#rb frozensetrrnrro_cross_vm_warned_lockrp"_cross_vm_existing_wal_warned_lockrrrrrrrrrrrrWARNINGERRORrrrrpartialrrritemsrr r r r)kvs00rr9s #   &&g   > *Q((+uH,*INN,/2e!83#19>>#3 &)U(*()..*(+X-+Y^^-,/E1!/!1%(Us*-y~~/8 M 0@! :4*r = 8T'22Tcd&(O(()..*#&5(& (03#X5%3Y^^%5".M JTin@BFIXD*7hm#L v&!oA 12OQXQ`Q` UV 56UW^WfWf < =/0Lgmm ij $DEhjqjyjy  H #I9:[]d]j]j XY 23Mw [\ *+CW__ !"DEjlslyly  !_9 x UUZq I +**9nE):):):9FY)Z&/01aRS&T^T7J7P7P7R%Stq!ad%SNS"4(ISLS&Ts( K