ei_ \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*dS)%uL 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/div/.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)rrUryz$pre-rollback snapshot (restoring to ).checkoutz--rrzRestore failed: rz --format=%sz-1unknownT)r restored_tor directoryfile) rr,r r&r4rSrirr)rrrrrrpath_errrrfrzr{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) r4r}rTryrrrir_prune) rrrrr{rfrzrrs 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  r)+rr-loggingrrrrZpathlibrhermes_constantsrtypingrrrr getLoggerrrTr1rxmaxminrgetenvr__annotations__rcompilerr,rr&r r4dictrFtuplerir}rrrrrrrs( ,,,,,,,,,,,,,,,,,,  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 ssr