+ lHj(PRt^RIHt^RIt^RIt^RIt^RIHt^RIH t ^RI H t ^RI H t HtHtHtHt]]]]3,tRtRtRR ltR R ltR R ltRRltRRlt!RR4t]!4tRRltRR/RRllt RRlt!RRlt"RRlt#R R!lt$R"R#lt%.R$Ot&R#)%aCross-agent file state coordination. Prevents mangled edits when concurrent subagents (same process, same filesystem) touch the same file: B writes a file A already read, so A's next write would clobber B's changes. Complements the single-agent path-overlap check in ``agent.tool_dispatch_helpers._should_parallelize_tool_batch``. A process-wide ``FileStateRegistry`` tracks per-agent read stamps, the global last writer and a per-path lock; every method is a no-op under ``HERMES_DISABLE_FILE_STATE_GUARD=1``. ) annotationsN) defaultdict)contextmanager)Path)DictIterableListOptionalTupleicV^8dQhRR/#returnbool)formats"5/home/ubuntu/.hermes/hermes-agent/tools/file_state.py __annotate__rsPP4Pcd\PPRR4P4R8H#)HERMES_DISABLE_FILE_STATE_GUARD1)osenvirongetstriprrr _disabledrs& ::>>;R @ F F HC OOrcV^8dQhRR/#r r)rs"rrr#src\4#)zTrue when the user switched the read-before-write guard off; the file tools then warn instead of refusing stale/unread write_file overwrites.)rrrrguard_disabledr #s  ;rc V^8dQhRRRR/#)r resolvedstrrOptional[float]r)rs"rrr)sS_rcf\PPV4# \dR#i;iN)rpathgetmtimeOSError)r"s&r_mtime_or_noner*)s.ww)) s ! 00c V^8dQhRRRR/#)r tsfloatrr#r)rs"rrr0s999#9rcX\P!R\P!V44#)z%H:%M:%S)timestrftime localtime)r,s&r_fmt_tsr20s ==T^^B%7 88rc V^8dQhRRRR/#)r capintrNoner)rs"rrr5s  # $ rc\\V4V, 4FOp\V\4'dVP 4K,VP \ \ V444KQ R# \\3dR#i;i)zPop entries until *container* is within *cap* (sets: arbitrary; dicts: oldest by insertion order). An eviction only costs one redundant re-send or staleness check.N) rangelen isinstancesetpopnextiter StopIterationKeyError) containerr4_s&& r _evict_oldestrC5se3y>C' ( )S))  d4 ?34 ) x(   s&A1#A11BBc]tRt^BtRtRRlt]RRl4tRRltRR R R /R R llt R R /RRllt RRlt RRlt RRlt RRltRRltRtR #)FileStateRegistryz4Process-wide coordinator for cross-agent file edits.cV^8dQhRR/#r rr6r)rs"rrFileStateRegistry.__annotate__Es,,$,rc \\4Vn/Vn/Vn/Vn\ P!4Vn\ P!4Vn R#r&) rdict_reads _last_writer _path_locks_path_lock_users threadingLock _meta_lock _state_lockselfs&r__init__FileStateRegistry.__init__EsC7B47H :<6802#..*$>>+rcV^8dQhRR/#)r r"r#r)rs"rrrHNs99#9rc # "VP;_uu_4VPPV\P!44pVP P V^4^,VP V&RRR4XP4RxVP4VP;_uu_4VP V,^, pV'dW0P V&M8VP PVR4VPPVR4RRR4R# +'giL;i +'giR#;i TP4TP;_uu_4TP T,^, pT'dY0P T&M8TP PTR4TPPTR4RRR4i +'gii;i;i5i)zPer-path lock: threads on the same path serialize, different paths proceed. The lock entry is dropped once the last holder/waiter exits.N) rQrM setdefaultrOrPrNracquirereleaser<)rTr"lockuserss&& r lock_pathFileStateRegistry.lock_pathMs____##..x9IJD.2.C.C.G.GRS.TWX.XD ! !( +  9  LLN--h7!;6;))(3))--h=$$((48 !_! LLN--h7!;6;))(3))--h=$$((48 !sgHA D,7HE$H8A*D?" H, D< 7H? E H%G>8A*G+ " G>+ G; 6G>>Hc 0V^8dQhRRRRRRRRRRR R /#) r task_idr#r"mtimer-nowpartialrrr6r)rs"rrrHas899c9S99U9UY9^b9rc ~VPV,p\V4V\V43Wb&\V\4R#)zCaller holds ``_state_lock``.N)rKr-rrC_MAX_PATHS_PER_AGENT)rTrar"rbrcrd agent_readss&&&&&& r_stampFileStateRegistry._stampas2kk'* !&usDM B k#78rrdFrbNc ,V^8dQhRRRRRRRRRR /#) r rar#r"rdrrbr$rr6r)rs"rrrHgs8HH3H#H4H*H6:Hrc  \4'dR#Vf \V4MTpVfR#VP;_uu_4VPWV\P!4V4RRR4R# +'giR#;ir&)rr*rRrhr/)rTrar"rdrbs&&&$$r record_readFileStateRegistry.record_readgsW ;; ,1Mx(u =      KK5$))+w G   s (A00 B c(V^8dQhRRRRRRRR/#)r rar#r"rbr$rr6r)rs"rrrHqs) > ># > > >[_ >rc  ^\4'dR#Vf \V4MTpVfR#\P!4pVP;_uu_4W3VPV&\ VP\ 4VPWW4R4RRR4R# +'giR#;i)zRecord a successful write: global last-writer AND this agent's own read stamp (a write is an implicit read of the current content).NF)rr*r/rRrLrC_MAX_GLOBAL_WRITERSrh)rTrar"rbrcs&&&$ r note_writeFileStateRegistry.note_writeqs ;; ,1Mx(u = iik    +2.D  h ' $++-@ A KK5u =   s >B B, c$V^8dQhRRRRRR/#)r rar#r"r Optional[str]r)rs"rrrHs&0F0F30F#0F-0Frc  .\4'dR#VP;_uu_4VPPV/4PV4pVPPV4pRRR4XfXfR#\ V4pVfR#XeHVwrgWa8wd>Vf V RV: R2#V^,pWx8d"V RV: R\ V4 R\ V4 R2#Ve Vwrp WY8wdV R2#V 'dV R2#R#V R 2# +'giL;i) zModel-facing warning if this write would be stale, else ``None``. Severity order: sibling wrote after our read > mtime drift / partial read > never read.Nz" was modified by sibling subagent zg but this agent never read it. Read the file before writing to avoid overwriting the sibling's changes.z at u% — after this agent's last read at z". Re-read the file before writing.zs was modified since you last read it on disk (external edit or unrecorded writer). Re-read the file before writing.zz was last read with offset/limit pagination (partial view). Read the remaining pages, or use patch, before overwriting it.zS was not read by this agent. Read the file first so you can write an informed edit.)rrRrKrrLr*r2) rTrar"stamp last_writer current_mtime writer_tid writer_tsread_ts read_mtime_read_tsrds &&& r check_staleFileStateRegistry.check_stalesc ;;    KKOOGR044X>E++//9K =[0&x0    "$/ !J$=#*$F%.)112  (&#*$F%.WY-?,@A55'>'@##J0R^O**1-(ACy  s&B*,B*4B*<B** B: c V^8dQhRRRR/#r rar#rz list[str]r)rs"rrrHs==3=9=rc \4'd.#VP;_uu_4\VPP V/4P 44uuRRR4# +'giR#;i)z#Resolved paths this agent has read.N)rrRrrKrkeys)rTras&&r known_readsFileStateRegistry.known_readssI ;;I     499;<   s 3A%% A6 c V^8dQhRRRR/#)r rar#rr6r)rs"rrrHs ) )3 )4 )rc  LVP;_uu_4VPPVR4VPP 4UUUu.uFwpwr4W18XgKVNK upppFpVPVK RRR4R#uupppi +'giR#;i)aKRelease read stamps and writer claims owned by a task after its lifecycle ends. A finished task is not a concurrent sibling: leaving its writer claims behind makes the next run of the same job (a fresh ``cron::`` id) refuse to write the same scratch path as "modified by sibling subagent" hours after the writer exited.N)rRrKr<rLr)rTrarry_tss&& r forget_taskFileStateRegistry.forget_tasks     KKOOGT *484E4E4K4K4Mg4M0A0 Q[Qfaa4Mg%%a(h g  s#;B B "B (B B B# cV^8dQhRR/#rGr)rs"rrrHs**t*rc VP;_uu_4VPP4VPP4RRR4VP;_uu_4VP P4VP P4RRR4R# +'giLc;i +'giR#;i)z)Reset all state. Intended for tests only.N)rRrKclearrLrQrMrNrSs&rrFileStateRegistry.clears~     KK       # # %___    " " $  ! ! ' ' )_ __s5B%&5B8% B5 8 C )rLrQrNrMrKrR)__name__ __module__ __qualname____firstlineno____doc__rUrr^rhrlrqr~rrrr__static_attributes__rrrrErEBsg>,99&9 H%H-1H >RV >0Fd = )**rrEcV^8dQhRR/#)r rrEr)rs"rrrs'rc\#r&) _registryrrr get_registryrs rrdFc(V^8dQhRRRRRRRR/#) r rar#resolved_or_path str | Pathrdrrr6r)rs"rrrs/KKK KKY]KrcH\PV\V4VR7R#))rdN)rrlr#)rarrds&&$rrlrls '3'7#8'Jrc$V^8dQhRRRRRR/#)r rar#rrrr6r)rs"rrrs!999z9d9rcD\PV\V44R#r&)rrqr#rars&&rrqrqs #&6"78rc$V^8dQhRRRRRR/#)r rar#rrrrtr)rs"rrrs&AAA A}Arc@\PV\V44#r&)rr~r#rs&&rr~r~s  #.>*? @@rcV^8dQhRR/#)r rrr)rs"rrrs66 6rc>\P\V44#r&)rr^r#)rs&rr^r^s   s#34 55rc(V^8dQhRRRRRRRR/#) r rr#rr-rzIterable[str | Path]rrr)rs"rrrs0VV#VV?SVXlVrc j\PYVUu.uFp\V4NK up4#uupir&)rrr#)rrrrs&&& rrrs+  ! !/e=Tec!fe=T UU=Ts0 c V^8dQhRRRR/#rr)rs"rrrs****rc,\PV4#r&)rr)ras&rrrs   ))r)rEr~rrr^rqrlr)'r __future__rrrOr/ collectionsr contextlibrpathlibrtypingrrrr r tupler-r ReadStamprfrprr r*r2rCrErrrlrqr~r^rr__all__rrrrs#  #%88 %$ % P  9 W*W*t    KuK9A6V* r