i?{ UdZddlZddlZddlZddlZddlZddlZddlmZddl m Z ddl m Z m Z mZmZejeZe dz ZgdZeded eejd d Zeed <d ZejdZdedeefdZdededeefdZ dedefdZ!dedefdZ"dedede#fdZ$edfde ededededeeede%f dZ&dededeefdZ'dedefd Z(Gd!d"Z)de e d#edefd$Z*d%Z+dedeefd&Z,dede-fd'Z. d1d*ed+e/d,eede eeffd-Z0 d2d*ed/ed+e/d,eede ee1ff d0Z2dS)3uL Checkpoint Manager — Transparent filesystem snapshots via shadow git repos. Creates automatic snapshots of working directories before file-mutating operations (write_file, patch), triggered once per conversation turn. Provides rollback to any previous checkpoint. This is NOT a tool — the LLM never sees it. It's transparent infrastructure controlled by the ``checkpoints`` config flag or ``--checkpoints`` CLI flag. Architecture: ~/.hermes/checkpoints/{sha256(abs_dir)[:16]}/ — shadow git repo HEAD, refs/, objects/ — standard git internals HERMES_WORKDIR — original dir path info/exclude — default excludes The shadow repo uses GIT_DIR + GIT_WORK_TREE so no git state leaks into the user's project directory. N)Path)get_hermes_home)DictListOptionalSet checkpoints)z node_modules/zdist/zbuild/z.envz.env.*z .env.localz .env.*.localz __pycache__/z*.pycz*.pyoz .DS_Storez*.logz.cache/z.next/z.nuxt/z coverage/z.pytest_cache/z.venv/zvenv/z.git/ <HERMES_CHECKPOINT_TIMEOUT30 _GIT_TIMEOUTiPz^[0-9a-fA-F]{4,64}$ commit_hashreturnc|r|sdS|drd|St|sd|SdS)zValidate a commit hash to prevent git argument injection. Returns an error string if invalid, None if valid. Values starting with '-' would be interpreted as git flags (e.g., '--patch', '-p') instead of revision specifiers. zEmpty commit hash-z/Invalid commit hash (must not start with '-'): z4Invalid commit hash (expected 4-64 hex characters): N)strip startswith_COMMIT_HASH_REmatch)rs =/home/ubuntu/.hermes/hermes-agent/tools/checkpoint_manager.py_validate_commit_hashrLst #k//11#""c""QPPPP   - -VUkUUU 4 file_path working_dirc"|r|sdStj|rd|St |}||z } ||n#t$rd|cYSwxYwdS)zValidate a file path to prevent path traversal outside the working directory. Returns an error string if invalid, None if valid. zEmpty file pathz/File path must be relative, got absolute path: z7File path escapes the working directory via traversal: N)rospathisabs_normalize_pathresolve relative_to ValueError)rr abs_workdirresolveds r_validate_file_pathr&\s !IOO--!   w}}YONNNN!+..Ki'0022HW[)))) WWWVVVVVVW 4s$A::B  B  path_valuecht|S)z;Return a canonical absolute path for checkpoint operations.)r expanduserr!)r's rr r ts(    & & ( ( 0 0 2 22rctt|}tj|dd}t |z S)z6Deterministic shadow repo path: sha256(abs_path)[:16].N)strr hashlibsha256encode hexdigestCHECKPOINT_BASE)rabs_pathdir_hashs r_shadow_repo_pathr4ysP?;//00H~hoo//00::<`` — ignore ``~/.gitconfig`` (git 2.32+). * ``GIT_CONFIG_SYSTEM=`` — ignore ``/etc/gitconfig`` (git 2.32+). * ``GIT_CONFIG_NOSYSTEM=1`` — legacy belt-and-suspenders for older git. The shadow repo still has its own per-repo config (user.email, user.name, commit.gpgsign=false) set in ``_init_shadow_repo``. GIT_DIR GIT_WORK_TREEGIT_INDEX_FILEN GIT_NAMESPACE GIT_ALTERNATE_OBJECT_DIRECTORIESGIT_CONFIG_GLOBALGIT_CONFIG_SYSTEM1GIT_CONFIG_NOSYSTEM)r renvironcopyr,popdevnull)r5rnormalized_working_direnvs r_git_envrFs"-[99 *//  C%%C N566CGG d###GGOT"""GG .555 "zC!zC!$C Jrargstimeoutallowed_returncodesc t|}|sJd|}tdddgt |z|dd|fS|sJd|}tdddgt |z|dd|fSt|t|}dgt |z}|p t} tj |dd||t| } | j d k} | j } | j} | s>| j |vr5td d|| j | | | | fS#tj$r?d |d d|}t|ddd|fcYSt"$r} t%| dd}|dkr6tdd|dYd} ~ dSd|}tdd||ddd|fcYd} ~ Sd} ~ wt&$rM} tdd|| dddt| fcYd} ~ Sd} ~ wwxYw)a4Run a git command against the shadow repo. Returns (ok, stdout, stderr). ``allowed_returncodes`` suppresses error logging for known/expected non-zero exits while preserving the normal ``ok = (returncode == 0)`` contract. Example: ``git diff --cached --quiet`` returns 1 when changes exist. zworking directory not found: zGit command skipped: %s (%s) gitFz&working directory is not a directory: T)capture_outputtextrHrEcwdrz(Git command failed: %s (rc=%d) stderr=%szgit timed out after zs: )exc_infofilenameNzGit executable not found: %s)FrMz git not foundz,Git command failed before execution: %s (%s)z#Unexpected git error running %s: %s)r existsloggererrorjoinlistis_dirrFr,set subprocessrun returncodestdoutrstderrTimeoutExpiredFileNotFoundErrorgetattr Exception)rGr5rrHrIrDmsgrEcmdresultokr]r^excmissing_targets r_run_gitrisA-[99 ! ( ( * *F.DFF 3SXXugT >R5S5SUXYYYb#~ ! ( ( * *O7MOO 3SXXugT >R5S5SUXYYYb#~ ;$: ; ; < >AAc eZdZdZddedefdZdd Zdd ed edefd Z d ede e fdZ e dede ddfdZd edede fdZdd ededede fdZdedefdZd ed edefdZded eddfdZdS)CheckpointManageraManages automatic filesystem checkpoints. Designed to be owned by AIAgent. Call ``new_turn()`` at the start of each conversation turn and ``ensure_checkpoint(dir, reason)`` before any file-mutating tool call. The manager deduplicates so at most one snapshot is taken per directory per turn. Parameters ---------- enabled : bool Master switch (from config / CLI flag). max_snapshots : int Keep at most this many checkpoints per directory. F2enabled max_snapshotscV||_||_t|_d|_dSN)rrrY_checkpointed_dirs_git_available)selfrrs r__init__zCheckpointManager.__init__#s+ *,/EE.2rrNc8|jdS)zAReset per-turn dedup. Call at the start of each agent iteration.N)rclear)rs rnew_turnzCheckpointManager.new_turn-s %%'''''rautorreasoncD|jsdS|j -- .`` (or a specific file) which restores tracked files without moving HEAD — safe and reversible. Parameters ---------- file_path : str, optional If provided, restore only this file instead of the entire directory. Returns dict with success/error info. FrrkrrrrrN)rrUr{z$pre-rollback snapshot (restoring to ).checkoutz--rrzRestore failed: rz --format=%sz-1unknownT)r restored_tor directoryfile) rr,r r&r4rSrirr)rrrrrrpath_errrrfr|r}restore_targetr]ok2 reason_outrres rrestorezCheckpointManager.restores)55  9$x88 8ok2233  =*9g>>H =#(8<<<"7++'')) Z$/XYY Y { +VW  As n$/Vk/V/V/Vadalhlmm m 7U;rPQr?UUUVVV'08S" dN ; G\A%5   FC  _$/G#/G/GRUR]Y]^^ ^& M4 5vw  Z #1 &rr?     '&F6N rct|}|r|}n|j}hd}|jkr .hg.gitgo.modpom.xml Cargo.toml package.jsonpyproject.tomlGemfileMakefilec3FK|]}|z VdSr)rS).0rchecks r z=CheckpointManager.get_working_dir_for_path..s399AEAI%%''999999r)r rXparentanyr,)rrr candidatemarkersrs @rget_working_dir_for_pathz*CheckpointManager.get_working_dir_for_pathsy)) ;;== $II IGGGu|##999999999 "5zz!LEu|## 9~~rct|}t||}|rtd|dSt |t kr#tdt |dSt ddg||tdz\}}}|std|dSt gd ||d h \}}}|rtd |dSt d d|ddg||tdz\}}}|std|dStd|||||dS)z*Take a snapshot. Returns True on success.zCheckpoint init failed: %sFz#Checkpoint skipped: >%d files in %srrrrzCheckpoint git-add failed: %s)rrrrrz$Checkpoint skipped: no changes in %scommitz-mz--allow-empty-messagez --no-gpg-signzCheckpoint commit failed: %szCheckpoint taken in %s: %sT) r4rrTr{rrrir_prune) rrrrr}rfr|rrs rrzCheckpointManager._take$s";//  44   LL5s ; ; ;5 ; ' '* 4 4 LL> K X X X5 DM6; q8H   As  LL8# > > >5 ( + + +  !"    1   LL? M M M5  tV% restore to checkpoint Nz> /rollback diff preview changes since checkpoint NzC /rollback restore a single file from checkpoint Nrs) enumeratergetrrV) r rlinesicptsdatefilesinsdelers rformat_checkpoint_listrqs 769666 3Y 3 3 3 4E;**OO2  _ "99#q!'',,Q/55c::1=bqbABk?((--a0D2B**ff\1%%vvk1%%  QQQEQJJSSBQQ3QQ$QQQDDD M!MMr,/MM2MMHMtMMNNNN LLHIII LLQRRR LLVWWW 99U  rz .last_prunec |dz dS#ttf$rYdSwxYw)zJRead ``HERMES_WORKDIR`` from a shadow repo, or None if missing/unreadable.rwrtruN) read_textrrUnicodeDecodeError)r5s r_read_workdir_markerrsX..9979KKQQSSS ' (tts*-AAcd} |dD]4} |j}||kr|}%#t$rY1wxYwn#t$rYnwxYw|S)uReturn newest mtime across the shadow repo (walks objects/refs/HEAD). We walk instead of trusting the directory mtime because git's pack operations can leave the top-level dir untouched while refs/objects inside get updated. Best-effort — returns 0.0 on any error. r)rrst_mtimer)r5newestprs r_shadow_repo_newest_mtimersF  ""3''  A FFHH%v::F            Ms1A!>A A A A  A AATretention_daysdelete_orphanscheckpoint_basec|pt}dddddd}|s|Sd}|dkrddl}||dzz }|D]}|s|dz s0|dxxdz cc<d}|r4t |} | !t | sd }|#|dkrt|} | dkr| |krd }| td | d D} n#t$rd} YnwxYw tj ||d xx| z cc<|d kr|dxxdz cc<n|dxxdz cc<td||j| P#t$r<} |dxxdz cc<td|j| Yd} ~ d} ~ wwxYw|S)uDelete stale/orphan shadow repos under ``checkpoint_base``. A shadow repo is deleted when either: * ``delete_orphans=True`` and its ``HERMES_WORKDIR`` path no longer exists on disk (the original project was deleted / moved); OR * its newest in-repo mtime is older than ``retention_days`` days. Returns a dict with counts ``{"scanned", "deleted_orphan", "deleted_stale", "errors", "bytes_freed"}``. Never raises — maintenance must never block interactive startup. rscanneddeleted_orphan deleted_staleerrors bytes_freedrNiQrkr%rorphanstalec3pK|]1}||jV2dSr)is_filerst_size)rrs rrz$prune_checkpoints..s:QQAQYY[[Qqvvxx'QQQQQQrrr)r&r'z(Pruned %s checkpoint repo: %s (%d bytes)r(z&Failed to prune checkpoint repo %s: %s)r1rStimeiterdirrXrrrsumrrrrmtreerTr{namewarning) r r!r"baserecutoff_timechildrworkdirrsizergs rprune_checkpointsr;s$  -oD F ;;== F 66&V&V||~~  &&((  yQ $  "*511Gd7mm&:&:&<&<! >nq00.u55Fzzfvoo  >  QQS1A1AQQQQQDD   DDD  V M% = ! ! !T ) ! ! !!!'(((A-(((('''1,''' LLCVUZY] ^ ^ ^ ^ V V V 8    !    NNCUZQT U U U U U U U U V Ms+,D00 D?>D?A-F22 G8<1G33G8min_interval_hourscddl}|pt}ddi} |s dddddd|d<|S|tz }|}|ra t |d} || z |d zkrd |d<|Sn#ttf$rYnwxYwt||| } | |d< | t|dn2#t$r%} t d | Yd} ~ nd} ~ wwxYw| d | dz} | dkr3td| | d | d| ddz nD#t$r7} td| t| |d<Yd} ~ nd} ~ wwxYw|S)aIdempotent wrapper around ``prune_checkpoints`` for startup hooks. Writes ``CHECKPOINT_BASE/.last_prune`` on completion so subsequent calls within ``min_interval_hours`` short-circuit. Designed to be called once per CLI/gateway process startup; the marker keeps costs bounded regardless of how many times hermes is invoked per day. Returns ``{"skipped": bool, "result": prune_checkpoints-dict, "error": optional str}``. rNskippedFr$rertruiT)r r!r"z+Could not write checkpoint prune marker: %sr&r'zWcheckpoint auto-maintenance: pruned %d repo(s) (%d orphan, %d stale), reclaimed %.1f MBr)iz&checkpoint auto-maintenance failed: %srU)r/r1rS_PRUNE_MARKER_NAMEfloatrrrr#r;ryr,rTr{rqrbr4) r r=r!r"r7r5outmarkernowlast_tsrergtotals rmaybe_auto_prune_checkpointsrGsN   -oD'/C+ {{}} AACMJ**jjll ==??   0 0' 0 B B H H J JKK=#5#<<<%)C NJ=Z(    #))     H  M   c#hh  9 9 9 9 M M M LLF L L L L L L L L M'(6/+BB 199 KK;'('}%5        ?EEE3xxG   Jsl F2F'AB0/F0CFCF$DF D3D.)F.D33A F G -F==G)rTN)rr<TN)3rr-loggingrrrrZpathlibrhermes_constantsrtypingrrrr getLoggerrrTr1rzmaxminrgetenvr__annotations__rcompilerr,rr&r r4dictrFtuplerirrrrr@rrArrr;objectrGrrrrUs2( ,,,,,,,,,,,,,,,,,,  8 $ $ "/##m30CCCCC  2Mt(T(T$U$UVVWW cWWW "*344 s x}     3SXc]0333333 &3&4&&&&$STL .2 :#:# s):#:#:# :# "#c(+ :#  :#:#:#:#z 4 c hsm    F # #    "[][][][][][][][]| T ssl#dx}4E,&*JJJJd^J #s(^ JJJJ\ &* AAAAAd^ A  #v+ AAAAAAr