KiJK UdZddlZddlZddlZddlZddlZddlmZddlm Z ddl m Z m Z m Z mZejeZe dz ZgdZeded eejd d Zeed <d ZdedefdZdededefdZedfde edededede eedef dZ dedede efdZ!dedefdZ"GddZ#de e dedefdZ$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_TIMEOUTiP working_dirreturnctt|}tj|dd}t|z S)z6Deterministic shadow repo path: sha256(abs_path)[:16].N)strrresolvehashlibsha256encode hexdigestCHECKPOINT_BASE)rabs_pathdir_hashs 5/home/ubuntu/hermes-agent/tools/checkpoint_manager.py_shadow_repo_pathrHs\4 $$,,..//H~hoo//00::<|j|vr5t dd||j| || | fS#tj$r?d|dd|} t | d d d | fcYSt $r4t d d|d Yd St"$rM} t dd|| d d d t | 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. gitT)capture_outputtextr-r*cwdrz(Git command failed: %s (rc=%d) stderr=%s zgit timed out after zs: )exc_infoFzGit executable not found: %s)Fr6z git not foundz#Unexpected git error running %s: %sN)r+listset subprocessrunrrr returncodestdoutstripstderrloggererrorjoinTimeoutExpiredFileNotFoundError Exception) r,rrr-r.r*cmdresultokr<r>msgexcs r_run_gitrJZs ; , ,C 'DJJ C-6# D%%--//00     ! #$$&&$$&& f'/BBB LL: v0&   66!!  $@W@@#@@ S4 (((b#~ *** 3SXXc]]T RRR))) ### :CHHSMM3Y] ^^^b#c(("""""""#s,CC==A G 9G GAGGGcV|dz rdS|ddtdg||\}}}|sd|Stgd||tgd|||d z }|d |d z d t d zd |dz t t|d zd t d||dS)z@Initialise shadow repo if needed. Returns error string or None.HEADNT)parentsexist_okinitzShadow repo init failed: )configz user.emailz hermes@local)rPz user.namezHermes Checkpointinfo)rNexclude zutf-8)encodingHERMES_WORKDIRz(Initialised checkpoint repo at %s for %s) existsmkdirrJ write_textrADEFAULT_EXCLUDESrrrr?debug)rrrG_errinfo_dirs r_init_shadow_repor^sZf$$&&tdT2226(K==JB3 103000 5 5 5{KPPP 9 9 9; TTTV#H NNDN!!! %% "##d*W&##// D   % % ' '((4/'0 LL;[+VVV 4rpathcd} t|dD]}|dz }|tkr|cSn#ttf$rYnwxYw|S)z;Quick file count estimate (stops early if over _MAX_FILES).r*)rrglob _MAX_FILESPermissionErrorOSError)r_countr[s r_dir_file_countrhs E d!!#&&  A QJEz!! "  W %     Ls7>>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)rlrmr8_checkpointed_dirs_git_available)selfrlrms r__init__zCheckpointManager.__init__s+ *,/EE.2rrNc8|jdS)zAReset per-turn dedup. Call at the start of each agent iteration.N)rpclear)rrs rnew_turnzCheckpointManager.new_turns %%'''''rautorreasonch|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. rLFrrrrrrN)rr@rZz$pre-rollback snapshot (restoring to ).checkoutz--rrzRestore failed: rz --format=%sz-1unknownT)r restored_torx directoryfile)rrrrrVrJrr)rrrrrrrrGr[r\restore_targetr<ok2 reason_outrxrFs rrestorezCheckpointManager.restorebsd;''//1122"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 rc:t|}|r|}n|j}hd}|jkr .hg.gitgo.modpom.xml Cargo.toml package.jsonpyproject.tomlGemfileMakefilec3FK|]}|z VdSro)rV).0rchecks r z=CheckpointManager.get_working_dir_for_path..s399AEAI%%''999999r)rris_dirparentanyr)rrrr_ candidatemarkersrs @rget_working_dir_for_pathz*CheckpointManager.get_working_dir_for_pathsI&&(( ;;== $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|dg||tdz\}}}|std|dStd|||||dS)z*Take a snapshot. Returns True on success.zCheckpoint init failed: %sFz#Checkpoint skipped: >%d files in %sr~rrrzCheckpoint git-add failed: %s)rrrrbrz$Checkpoint skipped: no changes in %scommitz-mz--allow-empty-messagezCheckpoint commit failed: %szCheckpoint taken in %s: %sT) rr^r?rZrhrdrJr_prune) rrrrxrr\rGr[rrs rrzCheckpointManager._takes";//  44   LL5s ; ; ;5 ; ' '* 4 4 LL> K X X X5 DM6; q8H   As  LL8# > > >5 ( + + +  !"    1   LL? M M M5 tV%< = K)9   As  LL7 = = =5 1;GGG FK(((trrc tgd||\}}}|sdS t|}n#t$rYdSwxYw||jkrdStgd||\}}}td||jdS)z:Keep only the last max_snapshots commits via orphan reset.)rev-listz--countrLN)rz --reverserLz--skip=0z --max-count=1z)Checkpoint repo has %d commits (limit %d))rJr ValueErrorrmr?rZ)rrrrrGr<r[rg cutoff_hashs rrzCheckpointManager._prunes + + +[+  FA  F KKEE    FF  D& & & F&      K  @%I[\\\\\s - ;;)Frk)rN)rwro)__name__ __module__ __qualname____doc__boolrrsrvrrrrr staticmethodrrrrrrrrrrjrjs  333S3333((((""S"#"4""""H*C*DJ****X 1C 1 1 1 1 1\ 1+ + #+ $+ + + + Z5535S5S5TX5555n##:11c1d1111f]$]S]T]]]]]]rrjrc "|sd|Sd|dg}t|dD]\}}|d}d|vr}|ddddd dd d }|ddd}|d |}|d d}|dd}|dd} |rd|d|dkrdndd|d| d } nd} |d|d|dd|d|d| |d|d|dd|S)z+Format checkpoint list for display to user.zNo checkpoints found for u📸 Checkpoints for z: rbrT+r-Nr4rrrz (z filesr6z, +z/-rz z. rrxz4 /rollback restore to checkpoint Nz> /rollback diff preview changes since checkpoint NzC /rollback restore a single file from checkpoint NrS) enumeratergetrrA) r rlinesicptsdatefilesinsdelers rformat_checkpoint_listrs 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)%rrloggingr&r{r9pathlibrhermes_constantsrtypingrrrr getLoggerrr?rrYmaxminrgetenvr__annotations__rdrrdictr+tuplerJr^rhrjrrrrrs( ,,,,,,,,,,,,,,,,,,  8 $ $ "/##m30CCCCC  2Mt(T(T$U$UVVWW cWWW &3&4&&&&$ST .2 +#+# s)+#+#+# +# "#c(+ +#  +#+#+#+#\4chsm8 # #    "P]P]P]P]P]P]P]P]f T ssr