+ WjuRt^RIt^RIt^RIt^RIt^RIt^RIt^RIt^RIt^RI t ^RI H t H t ^RI Ht^RIHtHtHt^RIHt^RIHt^RIHtHtHtHtHtHt]P<!]4t RR lt!R R lt"R R lt#RRlt$RRlt%RRlt&] RRl4t'RRlt(RRlt)RRlt*RRlt+R&RRllt,R R!lt-R&R"R#llt.R&R$R%llt/R#)'aSQLite-safe restore and archive-member publish plumbing for backups. Owns the restore side of ``hermes_cli.backup``: the page-copy SQLite restore (``_safe_restore_db`` plus the foreign-holder scan) and the zip-member publish helpers used by ``hermes import`` and ``/snapshot restore``. Backup *creation* (``run_backup``, full-zip writing) stays in ``hermes_cli.backup``, which composes these helpers. N)closingcontextmanagerPath)ListOptionalTuple)read_only_db_uri) _safe_copy_db)_preserve_file_mode_preserve_file_owner_restore_file_mode_restore_file_owneratomic_replacemkstemp_besidec\V^8dQhR\R\\\,,/#)db_pathreturn)rrlistint)formats"MC:\Users\johnn\AppData\Local\hermes\hermes-agent\hermes_cli\backup_restore.py __annotate__r s#++T+htCy.A+c\PPR4'gR#RRlpV!\P!V44pW"R,VR,0p.p\P !4p\P !R4FpVP4'gK\V4pWu8XdK.RV R 2p\P !V4p T F@p \P!T R T 24p T!T 4T9gK.TPT4K K V# \dKi;i \dKji;i \dR#i;i) uPIDs of OTHER processes holding *db_path* or its WAL/SHM open. Linux-only ``/proc//fd`` scan (no psutil dependency), preserving the kernel's ``(deleted)`` suffix so an already-unlinked sidecar generation — the #90950 split-brain fingerprint — still counts as held. Returns ``None`` when the scan is unavailable (non-Linux, or /proc unreadable); callers must treat ``None`` as "unknown", not as "no holders". linuxNc0V^8dQhR\R\/#rpathrstr)rs"rr-_foreign_db_holder_pids..__annotate__,s    rc\PP\PPVP R444#)z (deleted))osrnormcaseabspath removesuffix)rs&r _canonical+_foreign_db_holder_pids.._canonical,s4ww GGOOD--l; <  r-wal-shmz/procz/proc/z/fd/) sysplatform startswithr$fspathgetpidlistdirisdigitrOSErrorreadlinkappend) rr( canonical_dbwatchedpidsown_pidpid_strpidfd_dirfdsfdtargets & r_foreign_db_holder_pidsrA s= << " "7 + + bii01LF2L64IJGD))+zz'*G??$$g,C~cU#&F jj([[F81RD)9:Ff%0KK$+* K    saAE?D!ED36 EE! D0,E/D00E3 E>EEE EEcFV^8dQhR\R\\,/#rdstr)rr)rs"rrrNsdx~rcbVP4'd;VP4PpV^8d\P RVV4R#VP 4'dVP RR7#T# \\3d"p\P RY4Rp?R#Rp?ii;i)agWritable auth-store path whose lock and publish name the same underlying file. A file symlink is resolved so refresh writers and restore take the same auth.lock. A hard-linked auth.json cannot be atomically replaced without splitting a deliberately shared store into two inodes, so that topology fails closed instead of silently breaking credential sharing. zjRefusing auth.json restore to %s: it has %d hard links; atomic replacement would split a shared auth storeNF)strictzCRefusing auth.json restore to %s: cannot resolve store identity: %s) existsstatst_nlinkloggererror is_symlinkresolver4 RuntimeError)rDlinksexcs& r_auth_restore_targetrQNs ::<<HHJ''Eqy 6  ,/NN,<,\TPR 4\4'g\ PR T4R#\TPR4\4'gx\TPR4\4'gS\TPR 4\4'd.TR ,pR T9d R TR ,/M/pRTR T'dR MR/p^RI H pH pHp^RIHp \#T4p T fR#T!T R7;_uu_4T!T 4p T !Y+4p T!YR7RRR4R# \\\ 3d"p\ PRY4Rp?R#Rp?ii;i +'giR#;i \$d"p\ PRY4Rp?R#Rp?ii;i)zRestore auth.json without rolling back a live single-use OAuth generation. The live read and final write share the canonical auth-store lock, so a concurrent refresh cannot land between preservation and publish. z utf-8-sig)encodingz&Refusing auth.json restore from %s: %sNFz>Refusing auth.json restore from %s: top level is not an object providerscredential_poolsystemszARefusing auth.json restore from %s: unrecognized auth-store shape nous_portalnousactive_provider)_auth_store_lock_load_auth_store_save_auth_store)5merge_snapshot_auth_preserving_live_single_use_grants) target_pathTzFailed to restore %s safely: %s)jsonloads read_textr4 ValueError UnicodeErrorrJrK isinstancedictgethermes_cli.authr_r`rahermes_cli.auth_oauth_grantsrbrQ Exception) rTrDsnapshot_storerPr[rYr_r`rarbr@ live_storerestoreds && r_restore_auth_jsonrrfs CMM;M$GH nd + + UWZ[>%%k2D99 n(():;T B B n((3T : : XZ]^ ~))+6 = =>--.?@$GG ~)))4d ; ; +8E8PVW]34VX   v  XX &c* > & 1 1)&1JLH X : 2 Y Z . =sHL2 1   6AsS&G:HH,H HH&HH H HH I )II c<V^8dQhR\R\R\/#rSrU)rs"rrrs!$Tdrc \^RIHpHp^RIHpV!V4pVR,'g \ P RWR,4R#V!VP4PVP4P.4;_uu_4\W4;_uu_4p\Wa4uuRRR4uuRRR4# +'giM;iRRR4R# +'giR#;i T\\P3d"p\ P RT4Rp?R#Rp?ii;i) a Restore only while holding the destination authority's maintenance reservation. Returns ``False``, without touching *dst*, when *src* fails the SQLite integrity check, when the runtime owns the profile, or when a canonical ``state.db`` epoch floor cannot be proven. OwnershipConflictexclusive_maintenanceverify_sqlite_integrityvalidz#Refusing SQLite restore from %s: %smessageFNz%s)gateway.runtime_ownershiprvrwhermes_cli.backupryrJrKabsoluteparentrM_restore_epoch_source_restore_db_pagesr4sqlite3Error)rTrDrvrwry source_checkpreparedrPs&& r_safe_restore_dbrsS9 +3/L   :CiAXY "CLLN$9$93;;=;O;O#P Q Q&s00H(710R Q000R Q Q Q w 6 T3sUAC.C B< ' C1 C.< C CC. C+ %C.+C..D+ D&&D+c0V^8dQhR\R\/#rrr)rs"rrrs)))#)rcVP4'g^#\\P!\ V4RR74;_uu_4pVP R4P 4'g RRR4^#VP R4P 4pV'd\V^,4M^uuRRR4# +'giR#;i)Turiz6SELECT 1 FROM sqlite_master WHERE name='runtime_epoch'Nz1SELECT epoch FROM runtime_epoch WHERE singleton=1)rGrrconnectr executefetchoner)rconnrows& r_restore_epochrs ;;== !1$!7TB C Ct||TU^^`` D CllNOXXZ!s3q6{q D C C Cs 'C<&C#C C c0V^8dQhR\R\/#rCr)rs"rrrsDSrc\V4# \\P\3dp\RT R24ThRp?ii;i)z+Cannot read the canonical runtime epoch at z; refusing in-place restore. Use `hermes sessions recover --source --output ` to salvage transcripts into a separate output.N)rr4rrrg)rDrPs& r_restore_destination_epochrsPc"" W]]J /9#?= =   s A=Ac0V^8dQhR\R\/#)rrTrDr)rs"rrrst$rc #"VPR8wd&VP4PR8wdVxR#\V4pV\V48:dVxR#\P !RVP R7;_uu_4p\V4R, p\W4'g \R4h\\P!V44;_uu_4pVPR4VPRV34VP4RRR4VPVP!4P"4VxRRR4R# +'giLG;i +'giR#;i5i)a Stage an epoch floor into the image BEFORE publishing it atomically. Updating the destination after backup() would leave a crash window that reuses an older worker epoch. Never modify the user's source snapshot. Full restores retain all admissions/worker receipts; normal startup advances this floor and reconciles started work to unknown, not replayable queued work. An unreadable destination cannot prove its epoch floor: use transcript salvage into a separate output rather than silently restoring with a recycled epoch. state.dbNz.restore-epoch-)prefixdirz3Unable to stage a restore with a safe runtime epochzCREATE TABLE IF NOT EXISTS runtime_epoch ( singleton INTEGER PRIMARY KEY CHECK (singleton = 1), epoch INTEGER NOT NULL CHECK (epoch > 0), instance_id TEXT NOT NULL)zINSERT INTO runtime_epoch VALUES(1,?, 'offline-restore') ON CONFLICT(singleton) DO UPDATE SET epoch=excluded.epoch, instance_id=excluded.instance_id)namerMrrtempfileTemporaryDirectoryrrr r4rrrrcommitchmodrHst_mode)rTrDfloorworkrrs&& rrrs xx:#++-"4"4 "B  &s +E s##   $ $,=3:: N NRV: *S++OP P W__X. / /4 LLX Y LL46;X ? KKM0 sxxz))* O N0 / O N Ns7BE5AE!5E 5E! E5 E E!! E2 , E5c<V^8dQhR\R\R\/#rSrU)rs"rrrs&||4|d|t|rc |Rp\P!\V44pVPR4\P!\V4RR7pVPV4VP4VP4VP4PpVPV4R# \Pd!p\ P RY4Rp?LRp?ii;i TP4i;i \d"p\ PRY4Rp?R#Rp?ii;i \P\\3Edp\ PRYT4TeKTP4M8 \Pd!p\ P RY4Rp?MRp?ii;i^R IHpHp\'T4p T 'd\ P)R Y4Rp?R #T!TR R 7;_uu_4TP*RTP, R2, p \.P0!Y 4TP3RR7RF5p TP5TP,T ,4P3RR7K7 \.P6!\T 4\T44RRR4M +'giM;iRp?R# Td&p \ P)RY4Rp ? Rp?R #Rp ? i\\3d'p \ P)RYT 4Rp ? Rp?R #Rp ? ii;iRp?ii;i)uRestore a SQLite database from snapshot *src* into live *dst*. Uses SQLite's backup() API to write snapshot pages into the live database file, preserving the file's inode and WAL state so that any other process still holding the DB open (gateway, dashboard, another CLI session) sees the restored data on the next read — instead of continuing to serve stale cached pages from a replaced inode. The old approach was ``unlink() + move()``, which replaced the file under any live connection. SQLite connections cache pages in per-connection page caches keyed by inode; after an unlink+move the old inode still existed (the live connection held a reference), so that connection continued serving the pre-restore data while new connections saw the restored snapshot — a partial/inconsistent state (issue #65942). By writing pages through the backup API the file inode is preserved, the WAL journal is updated correctly, and all connections (old and new) converge on the restored data. Falls back to the unlink+move approach on failure ONLY when no other process or in-process connection holds the file: replacing the inode under a live holder is the #90950 split-brain, so that branch fails closed (returns ``False``) and the caller reports the file as skipped. Callers go through ``_safe_restore_db``, which validates *src* and holds the maintenance reservation and epoch floor around this publication. NzPRAGMA wal_checkpoint(TRUNCATE)z,Pre-restore WAL checkpoint of %s skipped: %sTrz %s: %sz1Closing %s before the fallback restore failed: %s)LiveConnectionErroroffline_file_accesszpRefusing unlink+move restore of %s: process(es) %s still hold the database or its WAL open. Stop them and retry.Fzunlink+move restore of)what.z .snap_restore) missing_okzkRefusing unlink+move restore of %s: %s Close the in-process database handles (or restart Hermes) and retry.z-Fallback restore also failed for %s -> %s: %s)r*r+z-journal)rrr!rrrJdebugr backupcloserHrrr4warningrghermes_cli.sqlite_safe_readrrrArKrrshutilcopy2unlink with_namemove) rTrDdst_connrPsrc_connmode close_excrrholderstmp_sidecar_suffixexc2s && rrrs:.2H^??3s8, S   > ???#3C#8dC  OOH % NN  e88:%%D IIdO!}} S LLG R R S NN   e NNY[^ d d e MM7J /GDcPST   b == b PRUaa b 6 -c2G N %S/GHHjjQsxxj #>> S& d +(DOMM#((_"<=DDPTDU(D CHc#h/!IHHH""  LLB  5$  LLH#TX Y5 KGsD2B6!D2C.( D2 +D6C+ C&!D2&C++D2.DD2 D/D*$D2*D//D22!L;L6/F?L6F5F0+L60F55 L6)K0KB.J90 K9 K KL3K9/L69L3 L3 L.$L6.L33L66L;cfV^8dQhR\PR\\\3,/#rzfr)zipfileZipFiletuplerVr!)rs"rrrps'W__tSy1ArcVP4pV'gR#0Rmp\4pVF1p\V4PpWR9gK VP V4K3 V'gR#R#)zDCheck that a zip looks like a Hermes backup. Returns (ok, reason). )Fzzip archive is empty>.envr config.yaml)FzZzip does not appear to be a Hermes backup (no config.yaml, .env, or state databases found))T)namelistsetrradd)rnamesmarkersfoundnbasenames& r_validate_backup_ziprpse KKME ,,2G EE 7<<   IIh     OrcDV^8dQhR\PR\/#r)rrr!)rs"rrrsw3rcVP4Uu.uFqPR4'dKVNK ppV'gR#VUu.uFp\V4PNK ppVUu0uFp\ V4^8gKV^,kK pp\ V4^8Xd!VP 4pVR9d VR,#R#uupiuupiuupi)zDetect if the zip has a common directory prefix wrapping all entries. Some tools zip as `.hermes/config.yaml` instead of `config.yaml`. Returns the prefix to strip (empty string if none). r,r>hermes.hermes)rendswithrpartslenpop)rrr parts_listp first_partsrs& r_detect_prefixrs  = 1ZZ_QQ E = *//A$q'--J/",:As1vz41Q44K: ;1" * *C<   > 0;sCCC*C  C c:V^8dQhR\\,/#)rr)rr)rs"rrrs rc\P!^?4p\P!V4RT(,# \dR#i;i)uReturn the mode ``open(path, "wb")`` gives a file it has to create. ``tempfile.mkstemp`` always creates at 0600, so staging an import through a temp file would tighten every *newly created* file to owner-only — the same hazard ``utils._restore_file_mode`` documents for Docker/NAS volume mounts that rely on broader permissions. The umask can only be read by setting it, so this is resolved once per import rather than once per member. The probe installs a *restrictive* mask rather than 0 so that anything another thread creates inside the two-syscall window is owner-only, never world-writable. Returns ``None`` if the umask cannot be read, in which case the caller leaves mkstemp's mode alone. Ni)r$umaskr4)currents r_default_new_file_modersC((5/  G8  s,8 AAc vV^8dQhR\PR\R\R\\ ,RR/#rrmemberr@ new_file_moderNrrr!rrr)rs"rrrsIbbb b bC= b  brc \V4p\V4pVfTpM-V\P\P,(,p\ VRVP R, R2RR7wrg\P!VR4;_uu_4pVeS\\R4'd'\P!VP4V4M\P!Wt4VPV4;_uu_4p \P!W4RRR4VP!4\P"!VP44RRR4\%\'Wr44p \)W4\+W4R# +'giLx;i +'giLO;i \,d+\P.!T4h \0dhi;ii;i)u- Restore one zip member onto *target* with no truncation window. ``open(target, "wb")`` truncates the user's existing file to zero *before* any replacement bytes exist. A Ctrl-C, an ENOSPC, a corrupt member, or a crash between the truncate and the write therefore leaves that file empty with nothing behind it — during ``hermes import``, which is the disaster-recovery path a user reaches for *because* they already lost something. Staging into the target's own directory and publishing with a rename means the target only ever moves from its old contents to the complete new contents. ``atomic_replace`` rather than a bare ``os.replace``: it resolves a symlinked target first, so a deployment that links ``config.yaml`` into a dotfiles repo keeps the link instead of having it silently swapped for a regular file (GitHub #16743), and it falls back to copy/fsync/unlink on ``EXDEV``/``EBUSY`` for cross-device and bind-mount installs. That fallback uses ``shutil.copyfile``, which does truncate in place, so on the cross-device path the guarantee above degrades to today's behaviour rather than improving on it; closing that belongs in ``utils.atomic_replace``, where every atomic writer in the repo would benefit, not here. Permission bits *and* ownership are carried across the replace so routing through mkstemp does not change the file the caller would otherwise have produced. ``os.replace`` swaps in a temp file owned by the *writing* user, so without the chown a ``sudo hermes import`` would silently re-own every restored file to root — on the disaster-recovery path, and on exactly the Docker/NAS installs ``utils._restore_file_owner`` documents. Both concerns delegate to the shared ``utils`` helpers rather than being re-derived here. The temp file is removed on any failure so a partial import leaves no residue. The one bit of the old file *not* carried across is setuid/setgid. The replacement bytes come out of the zip, so preserving those would let an archive take over the identity an existing privileged file executes as — and unlike the other ``utils`` writers, which re-serialize content this process produced, the trust boundary here is an untrusted archive. The mask is applied once, before the temp file is chmod'd, so neither the pre-replace ``fchmod`` nor the post-replace restore can re-elevate the target. NrNPNz.partial)rsuffixwbfchmod)r r rHS_ISUIDS_ISGIDrrr$fdopenhasattrrfilenoropenr copyfileobjflushfsyncrrrr BaseExceptionrr4) rrr@rrownerr?tmp_namerDrT real_paths &&&& r_extract_member_atomicallyrsgb v &D  (E | $,,-.."&1V[[5E4Fa1HQ[\LB YYr4 C 2x((IIcjjlD1HHX,C""3,! IIK HHSZZ\ "!!"9: I-9+!! 0   IIh      sa1F-A0FF >/54@<< ?@IIKAN<< ?@IIKAN8}c(m+  == MM9j 1  s5!B.A!C .CC C>*D=C>>DDc vV^8dQhR\PR\R\R\\ ,RR/#rr)rs"rrr6sB ) ) )  )  )C= )  )rc6^RIHpHpV!VP4PVP 4P.4;_uu_4\ WW#4RRR4R# +'giR#;i Tdp\\T44ThRp?ii;i)rruN) r|rvrwr~rrM_import_db_member_exclusiver4r!)rrr@rrvrwrPs&&&& r_import_db_memberr6sq S) "FOO$5$<$N>U>U#V W W 'F JX W W W )c#hS()s6AA7 A#A7# A4 .A74A77B>BBc vV^8dQhR\PR\R\R\\ ,RR/#rr)rs"rrrDsINNN N NC= N  Nrc VP4'g\\V4pV'd;\VP RRP R\ V444 R24h\ WW#4R#\V4p\V4p\P!\VP4RVPR, R2RR 7wrx\P!VR 4;_uu_4p VPV4;_uu_4p \ P"!W4RRR4V P%4\P&!V P)44RRR4\+\-V4V4'g;^R IHp V !\-V44R ,'g \R 4h\R4h\3W&4\5W%4\P6!V4R# +'giL;i +'giL;i \dR#i;i \P6!T4i \dii;i;i)uPublish a SQLite ``.db`` member onto *target* without replacing its inode. ``_extract_member_atomically`` publishes with a rename. For an ordinary file that is the safest write available; for a live SQLite database it is the #65942 / #90950 corruption class. A gateway, dashboard, or WebUI process holding the database open keeps its descriptor on the now-unlinked inode: it goes on serving pre-import pages and writing sessions that no other process will ever see, and any sidecar WAL left beside the new file describes the database that was just unlinked. Nothing fails, so nothing is reported — the sessions simply are not there afterwards (issue #100960). ``hermes import`` is the disaster-recovery path, so that failure mode lands on users who have already lost something once. Route the member through the same ``_safe_restore_db`` page copy that ``/snapshot restore`` has used since #65942: the live inode is preserved, every open connection converges on the imported data, and the sidecars are handled there. Raises ``OSError`` when the database could not be replaced safely, so the caller reports a skipped file instead of counting a silent success. z) was deleted but is still open in PID(s) z, c38"TFp\V4xK R#5iNr ).0r<s& r ._import_db_member_exclusive..gsA#SXXszs; publishing a new file would leave them writing an invisible database. Stop those processes and re-run the import.Nrrz .dbimport)rrrrrxrzz[the archived database failed its integrity check; the existing database was left untouched.zlive-safe restore refused or failed; the existing database was left untouched. Stop the gateway/dashboard processes holding it open and re-run the import.)rGrAr4rjoinsortedrr r rmkstempr!rr$rrrrrrrrrr}ryrr r) rrr@rrrrr?rrDrTrys &&&& rrrDs4 ==?? *&1 ;;-H99AAABChh  #2vE v &D  (E##  6;;s+;*{LB YYr4 CC""3,! IIK HHSZZ\ " ! X77 A+4>:7CC3.  F*6(  IIh /!! 6     IIh    ss H+G7G$ rs   .((12   8 $+\07t4)B|~60*bJ2 )NNr