@litfamily/lithermes 1.0.13 → 1.0.14

package/README.md

@@ -1,16 +1,16 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: five armored robots power on one by one, the LitHermes robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: five armored robots power on one by one, the LitHermes robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
 
-<p align="center"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/ascii-readme.svg" width="480" alt="LIT ASCII B mark" /></p>
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/ascii-readme.svg" width="480" alt="LIT ASCII B mark" /></p>
 
 <p align="center">
-<a href="#install"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/badge-version.svg" alt="1.0.13" /></a>
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/badge-license.svg" alt="MIT license" /></a>
+<a href="#install"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/badge-version.svg" alt="1.0.14" /></a>
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/badge-license.svg" alt="MIT license" /></a>
 </p>
 
 <p align="center">
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/docs/guide.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/lucide-book-open.svg" width="16" alt="" /> Guide</a> &nbsp;
-<a href="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition film</a> &nbsp;
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/docs/guide.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/lucide-book-open.svg" width="16" alt="" /> Guide</a> &nbsp;
+<a href="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition film</a> &nbsp;
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
 </p>
 
 # LitHermes
@@ -19,7 +19,7 @@
 
 A plugin for **Hermes Agent**. Add `lit` to a request, and Hermes plans the task, does it, checks it, and leaves a note the next session can pick up.
 
-**[Full guide, skills gallery and A/B results on GitHub](https://github.com/wjgoarxiv/lithermes#readme)** · [한국어](https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/README_Ko-KR.md)
+**[Full guide and skills gallery on GitHub](https://github.com/wjgoarxiv/lithermes#readme)** · [한국어](https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/README_Ko-KR.md)
 
 ## Install
 
@@ -84,25 +84,9 @@ On a Telegram gateway, use `/lit_loop` and `/lit_plan`. Every skill also loads b
 - To stop every version check, set `NO_UPDATE_NOTIFIER=1` or `LITHERMES_NO_UPDATE_CHECK=1`. Any value counts for these variables. The GitHub page explains the update step in full.
 - LitHermes decides where a request goes; Hermes Agent still runs the model.
 
-## Does it help?
+## Automatic handoff
 
-Ten casual one-line Korean prompts were each run once in Hermes Agent v0.21.3 with `gpt-6-sol` at reasoning `high`, as written and with ` lit` added at the end. A blind judge compared each pair in both orders, and the maintainer made the final call.
-
-| Task | Prompt | Final verdict | Blind judge (same round) |
-|---|---|---|---|
-| S1 · Terminal to-do CLI | 터미널에서 쓰는 할 일 관리 CLI 만들어줘 | Tie | Baseline won |
-| S2 · API server bugs | 이 API 서버 가끔 이상하게 동작하는데 고쳐줘 | Tie | Tie |
-| S3 · Budget dashboard (UI round) | 개인 가계부 대시보드 웹페이지 만들어줘 | **LitHermes won** | LitHermes won |
-| S4 · Café landing page (UI round) | 동네 카페 브랜드 랜딩페이지 만들어줘 | **LitHermes won** | LitHermes won |
-| S5 · Report and slides from sources (office round) | sources 폴더 자료로 보고서랑 발표자료 만들어줘 | **LitHermes won** | LitHermes won |
-| S6 · Node 22→24 research | Node 22에서 24로 올릴 때 달라지는 거 조사해줘 | **LitHermes won** | Tie |
-| S7 · Order, payment and shipping diagram | 주문-결제-배송 서비스 구조도 그려줘 | **LitHermes won** | LitHermes won |
-| S8 · Quarterly results deck (office round) | 분기 실적 발표자료 만들어줘 | **LitHermes won** | Baseline won |
-| S9 · New product plan (office round) | 신제품 기획서 써줘 | **LitHermes won** | LitHermes won |
-| S11 · Meeting-room booking web app (UI round) | 회의실 예약 웹앱 만들어줘 | **LitHermes won** | Tie |
-| Total | | **8 won, 2 tied, 0 lost** | 5 won, 3 tied, 2 lost |
-
-The judge preferred the baseline in S1 and S8. What each side produced, the screenshots, and the notes on which tasks came from later rounds are on GitHub. The motion cover at the top was made with the LitFamily motion skill. That skill (`lit-typographic-motion` here) was rebuilt after its first A/B and has no A/B result yet.
+This is off by default, and the percent is yours to choose. `/lit-handoff auto on 60` (any whole number from 1 to 99) makes LitHermes ask the model for a handoff on the first message after a model call passes 60% of the context window, and then tell you to run `/compact`. A plugin cannot start compaction on Hermes, so you run it, or Hermes compacts on its own threshold. After compaction the handoff comes back as a short digest. `/lit-handoff auto off` and `/lit-handoff auto status` do what they say, and `LITHERMES_AUTO_HANDOFF=1` with `LITHERMES_AUTO_HANDOFF_PERCENT` sets it from the environment. The [GitHub README](https://github.com/wjgoarxiv/lithermes#automatic-handoff) lists which steps are automatic and how to pick a percent that Hermes' own compaction leaves alone.
 
 ## Optional: Jev skill hint
 
@@ -130,7 +114,7 @@ npx --package @litfamily/lithermes -- lithermes uninstall --yes
 
 ## Learn more
 
-- [Full README on GitHub](https://github.com/wjgoarxiv/lithermes#readme): the skills gallery, the A/B results with screenshots, and how it works
+- [Full README on GitHub](https://github.com/wjgoarxiv/lithermes#readme): the skills gallery and how it works
 - [Operating guide](https://github.com/wjgoarxiv/lithermes/blob/main/docs/guide.md): commands, models, skins and troubleshooting
 - [Changelog](https://github.com/wjgoarxiv/lithermes/blob/main/CHANGELOG.md) · [Contributing](https://github.com/wjgoarxiv/lithermes/blob/main/CONTRIBUTING.md) · [Security](https://github.com/wjgoarxiv/lithermes/blob/main/SECURITY.md) · [Support](https://github.com/wjgoarxiv/lithermes/blob/main/SUPPORT.md)
 

package/README_Ko-KR.md

@@ -1,16 +1,16 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 다섯 로봇 패널이 차례로 켜지고, LitHermes 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 다섯 로봇 패널이 차례로 켜지고, LitHermes 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
 
-<p align="center"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/ascii-readme.svg" width="480" alt="LIT ASCII B 마크" /></p>
+<p align="center"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/ascii-readme.svg" width="480" alt="LIT ASCII B 마크" /></p>
 
 <p align="center">
-<a href="#설치"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/badge-version.svg" alt="1.0.13" /></a>
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/badge-license.svg" alt="MIT license" /></a>
+<a href="#설치"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/badge-version.svg" alt="1.0.14" /></a>
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/badge-license.svg" alt="MIT license" /></a>
 </p>
 
 <p align="center">
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/docs/guide.ko.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/lucide-book-open.svg" width="16" alt="" /> 안내</a> &nbsp;
-<a href="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition 영상</a> &nbsp;
-<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/docs/guide.ko.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/lucide-book-open.svg" width="16" alt="" /> 안내</a> &nbsp;
+<a href="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition 영상</a> &nbsp;
+<a href="https://github.com/wjgoarxiv/lithermes/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
 </p>
 
 # LitHermes
@@ -19,7 +19,7 @@
 
 **Hermes Agent**용 플러그인입니다. 요청에 `lit`을 붙이면 Hermes가 작업을 계획하고, 실행하고, 확인한 뒤 다음 세션이 이어받을 기록을 남깁니다.
 
-**[전체 안내, 스킬 갤러리, A/B 결과는 GitHub에서](https://github.com/wjgoarxiv/lithermes/blob/main/README_Ko-KR.md)** · [English](https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.13/README.md)
+**[전체 안내와 스킬 갤러리는 GitHub에서](https://github.com/wjgoarxiv/lithermes/blob/main/README_Ko-KR.md)** · [English](https://cdn.jsdelivr.net/npm/@litfamily/lithermes@1.0.14/README.md)
 
 ## 설치
 
@@ -83,25 +83,9 @@ Telegram gateway에서는 `/lit_loop`와 `/lit_plan`을 쓰세요. 모든 스킬
 - 버전 확인을 모두 멈추려면 `NO_UPDATE_NOTIFIER=1` 또는 `LITHERMES_NO_UPDATE_CHECK=1`을 설정하세요. 이 변수들은 어떤 값이든 똑같이 적용됩니다. 업데이트 과정의 자세한 설명은 GitHub 문서에 있습니다.
 - 요청을 어디로 보낼지는 LitHermes가 정하고, 모델은 여전히 Hermes Agent가 돌립니다.
 
-## 정말 도움이 되나요?
+## 자동 핸드오프
 
-가볍게 쓴 한국어 한 줄 요청 10개를 각각 원문 그대로 한 번, 끝에 ` lit`을 붙여 한 번, 이렇게 두 번씩 Hermes Agent v0.21.3, `gpt-6-sol`, 추론 `high`로 실행했습니다. 블라인드 판정자가 두 결과를 순서를 바꿔 비교했고, 최종 판정은 메인테이너가 내렸습니다.
-
-| 작업 | 요청 | 최종 판정 | 블라인드 판정(같은 라운드) |
-|---|---|---|---|
-| S1 · 터미널 할 일 CLI | 터미널에서 쓰는 할 일 관리 CLI 만들어줘 | 무승부 | 기준선 승 |
-| S2 · API 서버 버그 | 이 API 서버 가끔 이상하게 동작하는데 고쳐줘 | 무승부 | 무승부 |
-| S3 · 가계부 대시보드 (UI 라운드) | 개인 가계부 대시보드 웹페이지 만들어줘 | **LitHermes 승** | LitHermes 승 |
-| S4 · 카페 랜딩페이지 (UI 라운드) | 동네 카페 브랜드 랜딩페이지 만들어줘 | **LitHermes 승** | LitHermes 승 |
-| S5 · 자료 기반 보고서와 발표자료 (오피스 라운드) | sources 폴더 자료로 보고서랑 발표자료 만들어줘 | **LitHermes 승** | LitHermes 승 |
-| S6 · Node 22→24 조사 | Node 22에서 24로 올릴 때 달라지는 거 조사해줘 | **LitHermes 승** | 무승부 |
-| S7 · 주문·결제·배송 구조도 | 주문-결제-배송 서비스 구조도 그려줘 | **LitHermes 승** | LitHermes 승 |
-| S8 · 분기 실적 발표자료 (오피스 라운드) | 분기 실적 발표자료 만들어줘 | **LitHermes 승** | 기준선 승 |
-| S9 · 신제품 기획서 (오피스 라운드) | 신제품 기획서 써줘 | **LitHermes 승** | LitHermes 승 |
-| S11 · 회의실 예약 웹앱 (UI 라운드) | 회의실 예약 웹앱 만들어줘 | **LitHermes 승** | 무승부 |
-| 합계 | | **8승 2무 0패** | 5승 3무 2패 |
-
-판정자는 S1과 S8에서 기준선을 골랐습니다. 양쪽이 만든 결과물과 스크린샷, 그리고 각 작업이 어느 라운드에서 나왔는지는 GitHub에서 확인할 수 있습니다. 맨 위 모션 표지는 LitFamily 모션 스킬로 만들었습니다. 이 스킬(여기서는 `lit-typographic-motion`)은 첫 A/B 이후 다시 만들어졌고, 아직 A/B 결과가 없습니다.
+기본값은 꺼짐이고, 퍼센트는 직접 고릅니다. `/lit-handoff auto on 60`(1에서 99 사이의 정수)을 실행하면, 모델 호출 하나가 컨텍스트 창의 60%를 넘은 뒤 첫 메시지에서 LitHermes가 모델에게 핸드오프를 요청하고 `/compact`를 실행하라고 알려 줍니다. Hermes에서는 플러그인이 압축을 시작할 수 없으므로, 사용자가 직접 실행하거나 Hermes가 자체 기준으로 압축합니다. 압축 뒤에는 핸드오프가 짧은 요약으로 돌아옵니다. `/lit-handoff auto off`와 `/lit-handoff auto status`는 이름 그대로 동작하고, 환경에서는 `LITHERMES_AUTO_HANDOFF=1`과 `LITHERMES_AUTO_HANDOFF_PERCENT`로 설정합니다. 어느 단계가 자동이고 Hermes 자체 압축과 겹치지 않는 퍼센트를 어떻게 고르는지는 [GitHub README](https://github.com/wjgoarxiv/lithermes/blob/main/README_Ko-KR.md#자동-핸드오프)에 있습니다.
 
 ## 선택 기능: Jev 스킬 힌트
 
@@ -129,7 +113,7 @@ npx --package @litfamily/lithermes -- lithermes uninstall --yes
 
 ## 더 알아보기
 
-- [GitHub의 전체 README](https://github.com/wjgoarxiv/lithermes/blob/main/README_Ko-KR.md): 스킬 갤러리, 스크린샷이 있는 A/B 결과, 작동 방식
+- [GitHub의 전체 README](https://github.com/wjgoarxiv/lithermes/blob/main/README_Ko-KR.md): 스킬 갤러리와 작동 방식
 - [운영 안내](https://github.com/wjgoarxiv/lithermes/blob/main/docs/guide.ko.md): 명령, 모델, 스킨, 문제 해결
 - [변경 기록](https://github.com/wjgoarxiv/lithermes/blob/main/CHANGELOG.md) · [기여](https://github.com/wjgoarxiv/lithermes/blob/main/CONTRIBUTING.md) · [보안](https://github.com/wjgoarxiv/lithermes/blob/main/SECURITY.md) · [지원](https://github.com/wjgoarxiv/lithermes/blob/main/SUPPORT.md)
 

package/assets/lithermes-plugin/README.md

@@ -135,6 +135,35 @@ CLI/plugin name, not the npm package name.
   timestamp to Hermes home `lithermes/jev-last-<session hash>.json` (mode 0600,
   atomic), one file per session, removed when the session ends. Neither file is
   written through a symlink.
+- Optional automatic handoff (`auto_handoff.py`), off by default. The user
+  switches it on with `/lit-handoff auto on <percent>` (plain text reply, no
+  model call; `auto off` and `auto status` likewise) or with
+  `LITHERMES_AUTO_HANDOFF=1` plus `LITHERMES_AUTO_HANDOFF_PERCENT`; the
+  environment wins over the saved value, any flag value other than `1` keeps it
+  off, and a percent that is not a whole number from 1 to 99 leaves it off with a
+  doctor warning. There is no built-in percent: `on` without a number reuses the
+  last saved one and asks when none exists. The switch is saved in Hermes home
+  `lithermes/auto-handoff.json` (mode 0600, atomic, never written through a
+  symlink). `post_api_request` reads the prompt size of each model call
+  (`usage.prompt_tokens`, else input plus cache read plus cache write) over the
+  model's context window (`model.context_length` from the Hermes config, else
+  the host's own lookup, bounded to 3 seconds) and keeps the latest reading per
+  session in memory. Crossing the percent marks one pending directive;
+  `pre_llm_call` delivers it on the next turn, merged through the post-edit
+  composition so the byte budget keeps it whole. The directive names the bundled
+  lit-handoff source, asks for an `auto-handoff-id:` line in the file and for
+  the one plain line `Handoff saved. Run /compact now.` (`/compress` on Hermes
+  0.17, which has no `/compact`). A plugin cannot start compaction here. After
+  the user compacts, or Hermes compacts on its own, the next `pre_llm_call`
+  sees a new `_compressed_summary` message, and loads a digest (Current State
+  and Next Steps, at most 1,400 bytes, redacted and escaped) of `HANDOFF.md` or
+  `.handoff/HANDOFF.md`, but only when the file carries this session's id, was
+  written after the directive and is a regular file. Anything else gets a
+  one-line refusal. It fires once per crossing, never for delegate children,
+  and forgets a session when it ends. Status and doctor print `Automatic
+  handoff: ...` and warn when the percent is at or above the estimate of
+  Hermes' own compaction point (the `compression` settings, the small-window
+  floor and the token cap when the running host has them).
 - The `post_tool_call` hook is an observer — Hermes discards its return value — so
   it records the paths a completed `write_file` / `patch` call mutated and
   `pre_llm_call` renders them on the next turn. A source-code edit names

package/assets/lithermes-plugin/__init__.py

@@ -7,6 +7,7 @@ import re
 from pathlib import Path
 from typing import Any
 
+from . import auto_handoff
 from . import core
 from . import bounded_work
 from . import bounded_work_tools
@@ -316,6 +317,23 @@ def _merge_knowledge(
     return result
 
 
+def _auto_handoff_block(kwargs: dict[str, Any]) -> str:
+    """The opt-in automatic-handoff directive or reload for this turn, or an empty string.
+
+    It rides with the post-edit route so the bounded composition keeps it whole,
+    and a failure here never costs the turn its other context.
+    """
+    try:
+        return auto_handoff.pre_llm_call(
+            session_id=kwargs.get("session_id"),
+            user_message=kwargs.get("user_message"),
+            conversation_history=kwargs.get("conversation_history"),
+            platform=kwargs.get("platform"),
+        )
+    except Exception:  # noqa: BLE001 - advisory only
+        return ""
+
+
 def _pre_llm_call(**kwargs: Any) -> dict[str, str] | None:
     """Compose the Litwork directive and the active-litgoal snapshot.
 
@@ -333,6 +351,9 @@ def _pre_llm_call(**kwargs: Any) -> dict[str, str] | None:
         kwargs.get("session_id"), kwargs.get("user_message"), kwargs.get("turn_id")
     )
     post_edit = core.consume_rules_context(**kwargs)
+    auto_handoff_block = _auto_handoff_block(kwargs)
+    if auto_handoff_block:
+        post_edit = f"{auto_handoff_block}\n\n{post_edit}" if post_edit else auto_handoff_block
     workspace = kwargs.get("workspace")
     knowledge_context = knowledge.query(workspace, str(kwargs.get("user_message") or ""))
     base = core.pre_llm_call(**kwargs)
@@ -593,6 +614,7 @@ def _release_bounded_session(**kwargs: Any) -> None:
     session_id = raw_session_id if isinstance(raw_session_id, str) else ""
     bounded_work.release_bounded_session(session_id)
     jev_hint.release_session(session_id)
+    auto_handoff.release_session(session_id)
     # A finalized/reset session must not leave its rule dedup ledger behind: the
     # next session reusing the id would see every rule as "already injected".
     core.release_rules_session(session_id)
@@ -708,8 +730,8 @@ def register(ctx) -> None:
     ctx.register_command(
         "lit-handoff",
         _command_handler(ctx, handoff.command_lit_handoff),
-        description="Create or update a verified LitHermes continuation handoff",
-        args_hint="[focus]",
+        description="Create or update a verified LitHermes continuation handoff, or set the automatic handoff",
+        args_hint="[focus] | auto on <percent> | auto off | auto status",
     )
     ctx.register_command(
         "lit-scientific-visualization",

package/assets/lithermes-plugin/auto_handoff.py

@@ -0,0 +1,679 @@
+"""Opt-in automatic handoff for Hermes sessions.
+
+Off by default. The user turns it on with ``/lit-handoff auto on <percent>`` or
+with ``LITHERMES_AUTO_HANDOFF=1`` plus ``LITHERMES_AUTO_HANDOFF_PERCENT``. The
+percent is always the user's own: there is no built-in value, and a value that
+is not a whole number from 1 to 99 leaves the feature off.
+
+How it works on this host, step by step:
+
+1. ``post_api_request`` reports the prompt size of every model call. The plugin
+   divides it by the model's context window and keeps the latest reading per
+   session. Crossing the user's percent marks one pending directive.
+2. ``pre_llm_call`` is the only hook whose return value reaches the model, so
+   the directive rides on the next user turn. It asks the model to write the
+   handoff with the bundled lit-handoff procedure, to put a one-time id line in
+   the file, and to tell the user to run the compact command.
+3. A plugin cannot start compaction on Hermes. The user runs it, or Hermes
+   compacts on its own threshold. The next ``pre_llm_call`` notices the new
+   compaction summary in the history and loads a bounded digest of the handoff,
+   but only if the file carries this session's id and was written after the
+   directive. Anything else is refused.
+
+The feature fires once per crossing of the percent, never inside a tool call,
+and never for delegate children. State is kept in memory per session; only the
+user's switch and last percent persist, in Hermes home ``lithermes/``.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import html
+import importlib
+import json
+import os
+import re
+import secrets
+import stat
+import threading
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+try:
+    from .core_runtime import assert_within_isolation, get_hermes_home, utc_now
+    from .provider_metrics import _nonnegative_int, _value
+    from .redaction import redact_text
+    from .rules import constants as _RULE_CONSTANTS
+    from .session_context import is_delegate_child_platform
+except (ImportError, ModuleNotFoundError):
+    from core_runtime import assert_within_isolation, get_hermes_home, utc_now  # type: ignore
+    from provider_metrics import _nonnegative_int, _value  # type: ignore
+    from redaction import redact_text  # type: ignore
+    from rules import constants as _RULE_CONSTANTS  # type: ignore
+    from session_context import is_delegate_child_platform  # type: ignore
+
+
+FLAG = "LITHERMES_AUTO_HANDOFF"
+PERCENT_ENV = "LITHERMES_AUTO_HANDOFF_PERCENT"
+SESSION_ENV = "HERMES_SESSION_ID"
+SETTINGS_FILE = "auto-handoff.json"
+ROUTE = "/lit-handoff auto"
+SOURCE_ROOT = Path(__file__).resolve().parent / "vendor" / "handoff"
+SOURCE_SKILL = SOURCE_ROOT / "SKILL.md"
+SOURCE_TEMPLATE = SOURCE_ROOT / "templates" / "HANDOFF.md"
+MAX_TRACKED_SESSIONS = 256
+MAX_SETTINGS_BYTES = 4096
+MAX_HANDOFF_READ_BYTES = 64 * 1024
+MAX_HANDOFF_FILE_BYTES = 2 * 1024 * 1024
+MAX_DIGEST_BYTES = 1400
+MAX_DIGEST_LINES = 10
+MAX_DIGEST_LINE_CHARS = 200
+HOST_LOOKUP_SECONDS = 3.0
+FAILED_LOOKUP_RETRY_SECONDS = 60.0
+CLOCK_SLACK_SECONDS = 2.0
+HANDOFF_CANDIDATES = ("HANDOFF.md", ".handoff/HANDOFF.md")
+PERCENT_RULE = "a whole number from 1 to 99"
+_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)
+_PERCENT = re.compile(r"[0-9]{1,2}")
+_BARE_HANDOFF = re.compile(r"^\s*handoff\s*$", re.IGNORECASE)
+_HEADING = re.compile(r"^#{1,4}\s*(.+?)\s*$")
+_WANTED_SECTIONS = (("current state", "Current State"), ("next steps", "Next Steps"))
+_LOCK = threading.RLock()
+_SESSIONS: dict[str, dict[str, Any]] = {}
+_WINDOWS: dict[tuple[str, str, str], tuple[int | None, float]] = {}
+_LAST_SESSION: list[str] = [""]
+
+
+@dataclass(frozen=True)
+class Setting:
+    on: bool
+    percent: int | None
+    flag_source: str
+    percent_source: str
+    warnings: tuple[str, ...]
+
+
+def _reset_for_tests() -> None:
+    with _LOCK:
+        _SESSIONS.clear()
+        _WINDOWS.clear()
+        _LAST_SESSION[0] = ""
+
+
+def parse_percent(text: Any) -> int | None:
+    """Return the percent for a whole number from 1 to 99, else None."""
+    value = str(text or "").strip()
+    if value.endswith("%"):
+        value = value[:-1]
+    if not _PERCENT.fullmatch(value):
+        return None
+    number = int(value)
+    return number if 1 <= number <= 99 else None
+
+
+# ---- the user's switch -----------------------------------------------------
+
+def settings_path() -> Path:
+    return get_hermes_home() / "lithermes" / SETTINGS_FILE
+
+
+def _read_saved() -> tuple[dict[str, Any], str]:
+    """Return the saved switch and, when the file is damaged, one warning."""
+    blank: dict[str, Any] = {"enabled": False, "percent": None, "exists": False}
+    try:
+        fd = os.open(settings_path(), os.O_RDONLY | _NOFOLLOW)
+    except OSError:
+        return blank, ""
+    try:
+        with os.fdopen(fd, "rb") as handle:
+            raw = handle.read(MAX_SETTINGS_BYTES + 1)
+        data = json.loads(raw[:MAX_SETTINGS_BYTES].decode("utf-8"))
+    except (OSError, ValueError, UnicodeDecodeError):
+        return blank, "the saved setting file could not be read, so automatic handoff stays off"
+    if not isinstance(data, dict):
+        return blank, "the saved setting file could not be read, so automatic handoff stays off"
+    enabled = data.get("enabled") is True
+    percent = data.get("percent")
+    if percent is None:
+        return {"enabled": enabled, "percent": None, "exists": True}, ""
+    if isinstance(percent, bool) or not isinstance(percent, int) or not 1 <= percent <= 99:
+        return {"enabled": enabled, "percent": None, "exists": True}, (
+            f"the saved percent is not {PERCENT_RULE}, so automatic handoff stays off"
+        )
+    return {"enabled": enabled, "percent": percent, "exists": True}, ""
+
+
+def _write_saved(enabled: bool, percent: int | None) -> None:
+    path = settings_path()
+    assert_within_isolation(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.{threading.get_ident()}.tmp")
+    payload = {"enabled": enabled, "percent": percent, "updated": utc_now().isoformat()}
+    try:
+        with contextlib.suppress(OSError):
+            temporary.unlink()
+        fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | _NOFOLLOW, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle, sort_keys=True)
+        # os.replace swaps a symlink planted at the final path instead of writing through it.
+        os.replace(temporary, path)
+    except OSError:
+        with contextlib.suppress(OSError):
+            temporary.unlink()
+        raise
+
+
+def resolve(env: Mapping[str, str] | None = None) -> Setting:
+    """Combine the environment and the saved switch into the effective setting.
+
+    The environment wins when it names a value, so a shell profile can pin the
+    feature; the saved value fills in otherwise. No percent is ever invented.
+    """
+    values = os.environ if env is None else env
+    saved, saved_warning = _read_saved()
+    warnings: list[str] = []
+
+    raw_flag = (values.get(FLAG) or "").strip()
+    if raw_flag:
+        enabled, flag_source = raw_flag == "1", "environment"
+    else:
+        enabled, flag_source = bool(saved["enabled"]), ("saved" if saved["exists"] else "default")
+
+    raw_percent = (values.get(PERCENT_ENV) or "").strip()
+    if raw_percent:
+        percent, percent_source = parse_percent(raw_percent), "environment"
+        if percent is None:
+            warnings.append(f"{PERCENT_ENV} is {raw_percent[:20]!r}, which is not {PERCENT_RULE}, so automatic handoff stays off")
+    else:
+        percent = saved["percent"]
+        percent_source = "saved" if percent is not None else "none"
+        if saved_warning:
+            warnings.append(saved_warning)
+
+    if enabled and percent is None and not warnings:
+        warnings.append(f"it is switched on but no percent is chosen; run {ROUTE} on <percent>")
+    return Setting(enabled and percent is not None, percent, flag_source, percent_source, tuple(warnings))
+
+
+def parse_route(raw_args: str) -> str | None:
+    """Return the text after ``auto`` when the route's first word is exactly ``auto``."""
+    parts = str(raw_args or "").strip().split(None, 1)
+    if not parts or parts[0].lower() != "auto":
+        return None
+    return parts[1].strip() if len(parts) > 1 else ""
+
+
+def _shown(value: Any) -> str:
+    return redact_text(str(value))[:20]
+
+
+def run_command(rest: str, env: Mapping[str, str] | None = None, session_id: str = "") -> str:
+    """Handle ``/lit-handoff auto on <percent> | on | off | status`` as plain text."""
+    values = os.environ if env is None else env
+    tokens = str(rest or "").split()
+    sub = tokens[0].lower() if tokens else "status"
+    if sub == "status" and len(tokens) <= 1:
+        return _status_text(values, session_id)
+    if sub == "off" and len(tokens) == 1:
+        return _command_off(values)
+    if sub == "on" and len(tokens) <= 2:
+        return _command_on(values, tokens[1] if len(tokens) == 2 else "")
+    return f"Usage: {ROUTE} on <percent> | off | status"
+
+
+def _command_off(values: Mapping[str, str]) -> str:
+    saved, _ = _read_saved()
+    try:
+        _write_saved(False, saved["percent"])
+    except (OSError, RuntimeError) as exc:
+        return f"Could not save the setting ({type(exc).__name__}); nothing changed."
+    lines = ["Automatic handoff is off."]
+    if saved["percent"] is not None:
+        lines.append(f"Your last percent, {saved['percent']}%, is remembered for the next time you turn it on.")
+    if (values.get(FLAG) or "").strip() == "1":
+        lines.append(f"{FLAG}=1 is set in your environment, so it stays on until you unset that variable.")
+    return " ".join(lines)
+
+
+def _command_on(values: Mapping[str, str], argument: str) -> str:
+    saved, _ = _read_saved()
+    if argument:
+        percent = parse_percent(argument)
+        if percent is None:
+            return f"{_shown(argument)!r} is not {PERCENT_RULE}. Nothing changed."
+    elif saved["percent"] is not None:
+        percent = saved["percent"]
+    else:
+        return (
+            f"Which percent should trigger it? Run {ROUTE} on <percent> with {PERCENT_RULE}. "
+            "LitHermes has no built-in value and will not pick one for you."
+        )
+    try:
+        _write_saved(True, percent)
+    except (OSError, RuntimeError) as exc:
+        return f"Could not save the setting ({type(exc).__name__}); nothing changed."
+    lines = [
+        f"Automatic handoff is ON at {percent}%. Once a model call passes {percent}% of the context window, "
+        f"your next message carries a request to write a handoff, and you then run {_compact_command()}. "
+        "It starts with your next message."
+    ]
+    flag = (values.get(FLAG) or "").strip()
+    if flag and flag != "1":
+        lines.append(f"{FLAG}={_shown(flag)} is set in your environment, which keeps it off until you unset that variable.")
+    environment_percent = (values.get(PERCENT_ENV) or "").strip()
+    if environment_percent:
+        lines.append(f"{PERCENT_ENV}={_shown(environment_percent)} is set in your environment and wins over the saved {percent}%; unset it to use {percent}%.")
+    lines.append(_host_comparison(resolve(values))[0])
+    return "\n".join(lines)
+
+
+def _status_text(values: Mapping[str, str], session_id: str) -> str:
+    setting = resolve(values)
+    if setting.on:
+        head = f"Automatic handoff: ON at {setting.percent}% (percent from your {setting.percent_source} setting)"
+    elif setting.warnings:
+        head = f"Automatic handoff: off ({'; '.join(setting.warnings)})"
+    else:
+        head = "Automatic handoff: off"
+    lines = [head]
+    if setting.on:
+        lines.append(_reading_line(session_id or (values.get(SESSION_ENV) or "").strip() or _LAST_SESSION[0]))
+        lines.append(_host_comparison(setting)[0])
+    return "\n".join(lines)
+
+
+def _reading_line(session_id: str) -> str:
+    with _LOCK:
+        state = _SESSIONS.get(session_id)
+        reading = dict(state) if state else {}
+    if not reading or reading.get("used") is None:
+        return "Last reading in this session: no reading yet"
+    if reading.get("percent") is None:
+        return "Last reading in this session: unavailable (the model's context window is unknown)"
+    return (
+        f"Last reading in this session: {reading['percent']:.0f}% "
+        f"({reading['used']:,} of {reading['window']:,} tokens)"
+    )
+
+
+def status_line(env: Mapping[str, str] | None = None) -> str:
+    setting = resolve(env)
+    if setting.on:
+        return f"Automatic handoff: on at {setting.percent}%"
+    if setting.warnings:
+        return f"Automatic handoff: off ({'; '.join(setting.warnings)})"
+    return "Automatic handoff: off"
+
+
+def doctor_line(env: Mapping[str, str] | None = None) -> tuple[str, str]:
+    """Return (tag, text) for doctor: NOTE when off, WARN when it cannot work as chosen."""
+    setting = resolve(env)
+    if setting.warnings and not setting.on:
+        return "WARN", f"Automatic handoff: off ({'; '.join(setting.warnings)})"
+    if not setting.on:
+        return "NOTE", "Automatic handoff: off"
+    point, reason = host_estimate()
+    if point is None:
+        return "OK", f"Automatic handoff: on at {setting.percent}% ({reason}; no comparison with Hermes' own compaction point)"
+    if setting.percent >= round(point):
+        return "WARN", (
+            f"Automatic handoff: on at {setting.percent}%, but Hermes compacts at about {point:.0f}% of the window, "
+            "so Hermes compacts first; choose a lower percent"
+        )
+    return "OK", f"Automatic handoff: on at {setting.percent}% (Hermes compacts at about {point:.0f}% of the window)"
+
+
+def _host_comparison(setting: Setting) -> tuple[str, bool]:
+    """Say where Hermes' own compaction sits next to the user's percent; True when it wins."""
+    point, reason = host_estimate()
+    if point is None:
+        return f"Hermes' own compaction point: unavailable ({reason})", False
+    if setting.percent >= round(point):
+        return (
+            f"Heads up: Hermes compacts at about {point:.0f}% of the window, so it compacts first and "
+            "no handoff is written. Choose a lower percent.",
+            True,
+        )
+    return f"Hermes' own compaction point is about {point:.0f}% of the window, above yours.", False
+
+
+# ---- the host's own compaction point ---------------------------------------
+
+def _host_config() -> dict[str, Any]:
+    try:
+        path = get_hermes_home() / "config.yaml"
+        if path.stat().st_size > 1024 * 1024:
+            return {}
+        yaml = importlib.import_module("yaml")
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except Exception:  # noqa: BLE001 - a config we cannot read only removes the comparison
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _host_facts() -> dict[str, Any]:
+    """Read the running host's own compaction defaults; empty outside Hermes."""
+    facts: dict[str, Any] = {}
+    with contextlib.suppress(Exception):
+        module = importlib.import_module("agent.context_compressor")
+        facts["floor"] = (int(module._SMALL_CTX_WINDOW_LIMIT), float(module._SMALL_CTX_THRESHOLD_PERCENT))
+    with contextlib.suppress(Exception):
+        defaults = importlib.import_module("hermes_cli.config_defaults").DEFAULT_CONFIG["compression"]
+        if isinstance(defaults, dict):
+            facts["compression"] = dict(defaults)
+    return facts
+
+
+def _ratio(value: Any) -> float | None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return float(value) if 0 < value <= 1 else None
+
+
+def host_trigger_percent(
+    window: int,
+    compression: Mapping[str, Any],
+    model: str,
+    floor: tuple[int, float] | None = None,
+) -> float | None:
+    """Estimate where Hermes' own compaction starts, as a percent of the window.
+
+    Follows the documented compression settings: the ratio (with a per-model
+    override and the small-window floor when the host has one) and the absolute
+    token cap. Returns None when compression is switched off.
+    """
+    if compression.get("enabled") is False:
+        return None
+    ratio = _ratio(compression.get("threshold")) or 0.50
+    overrides = compression.get("model_thresholds")
+    if isinstance(overrides, Mapping) and model:
+        keys = [key for key in overrides if isinstance(key, str) and key and key.lower() in model.lower()]
+        if keys:
+            best = max(keys, key=len)
+            ratio = _ratio(overrides[best]) or ratio
+    if floor is not None and window < floor[0]:
+        ratio = max(ratio, floor[1])
+    trigger = int(window * ratio)
+    cap = compression.get("threshold_tokens")
+    if isinstance(cap, int) and not isinstance(cap, bool) and cap > 0:
+        trigger = min(trigger, cap, window)
+    return trigger * 100 / window
+
+
+def _bounded(function: Callable[[], Any], seconds: float = HOST_LOOKUP_SECONDS) -> Any:
+    """Run a host lookup that may touch the network, giving up after a few seconds."""
+    box: list[Any] = [None]
+
+    def work() -> None:
+        with contextlib.suppress(Exception):
+            box[0] = function()
+
+    thread = threading.Thread(target=work, daemon=True)
+    thread.start()
+    thread.join(seconds)
+    return box[0]
+
+
+def _host_context_length(model: str, base_url: str, provider: str) -> int | None:
+    """Ask the running Hermes for the model's context window; None outside a host."""
+    function = importlib.import_module("agent.model_metadata").get_model_context_length
+    value = function(model, base_url or "", provider=provider or "")
+    return value if isinstance(value, int) and not isinstance(value, bool) and value > 0 else None
+
+
+def _context_window(model: str, base_url: str, provider: str, config: Mapping[str, Any] | None = None) -> int | None:
+    key = (model, base_url, provider)
+    now = time.monotonic()
+    with _LOCK:
+        cached = _WINDOWS.get(key)
+        if cached and (cached[0] is not None or cached[1] > now):
+            return cached[0]
+    section = (config if config is not None else _host_config()).get("model")
+    section = section if isinstance(section, Mapping) else {}
+    configured = section.get("context_length")
+    window: int | None = None
+    if isinstance(configured, int) and not isinstance(configured, bool) and configured > 0:
+        if not section.get("default") or section.get("default") == model:
+            window = configured
+    if window is None and model:
+        found = _bounded(lambda: _host_context_length(model, base_url, provider))
+        window = found if isinstance(found, int) and found > 0 else None
+    with _LOCK:
+        while len(_WINDOWS) >= MAX_TRACKED_SESSIONS:
+            _WINDOWS.pop(next(iter(_WINDOWS)), None)
+        _WINDOWS[key] = (window, now + FAILED_LOOKUP_RETRY_SECONDS)
+    return window
+
+
+def host_estimate() -> tuple[float | None, str]:
+    """Estimate Hermes' compaction point for the configured model, or say why not."""
+    config = _host_config()
+    section = config.get("model") if isinstance(config.get("model"), Mapping) else {}
+    model = str(section.get("default") or "")
+    window = _context_window(model, str(section.get("base_url") or ""), str(section.get("provider") or ""), config)
+    if window is None:
+        return None, "the model's context window is unknown (window unknown)"
+    facts = _host_facts()
+    compression = dict(facts.get("compression") or {})
+    user = config.get("compression")
+    if isinstance(user, Mapping):
+        compression.update(user)
+    point = host_trigger_percent(window, compression, model, facts.get("floor"))
+    if point is None:
+        return None, "Hermes compression is switched off"
+    return point, ""
+
+
+def _compact_command() -> str:
+    """The slash command that compacts here; only Hermes 0.19 and later know /compact."""
+    try:
+        resolve_command = importlib.import_module("hermes_cli.commands").resolve_command
+        return "/compact" if resolve_command("compact") else "/compress"
+    except Exception:  # noqa: BLE001 - outside a host the plain wording is the right default
+        return "/compact"
+
+
+# ---- reading the model's context use ----------------------------------------
+
+def _prompt_tokens(usage: Any) -> int | None:
+    if usage is None:
+        return None
+    prompt = _nonnegative_int(_value(usage, "prompt_tokens"))
+    if prompt is not None:
+        return prompt
+    parts = [_nonnegative_int(_value(usage, name)) for name in ("input_tokens", "cache_read_tokens", "cache_write_tokens")]
+    return sum(parts) if all(part is not None for part in parts) else None
+
+
+def _state(session_id: str) -> dict[str, Any]:
+    state = _SESSIONS.get(session_id)
+    if state is None:
+        while len(_SESSIONS) >= MAX_TRACKED_SESSIONS:
+            _SESSIONS.pop(next(iter(_SESSIONS)), None)
+        state = _SESSIONS[session_id] = {
+            "percent": None, "used": None, "window": None,
+            "above": False, "pending": False, "awaiting": False, "dropped": False,
+            "nonce": "", "fired_at": 0.0, "cwd": "", "summary": "",
+        }
+    return state
+
+
+def begin_session(session_id: Any) -> None:
+    with _LOCK:
+        _SESSIONS.pop(str(session_id or ""), None)
+
+
+def release_session(session_id: Any) -> None:
+    begin_session(session_id)
+
+
+def post_api_request(**kwargs: Any) -> None:
+    """Keep the latest context reading and mark a crossing of the user's percent."""
+    setting = resolve()
+    if not setting.on:
+        return None
+    session_id = str(kwargs.get("session_id") or "")
+    if not session_id or is_delegate_child_platform(str(kwargs.get("platform") or "")):
+        return None
+    used = _prompt_tokens(kwargs.get("usage"))
+    if used is None:
+        return None
+    window = _context_window(str(kwargs.get("model") or ""), str(kwargs.get("base_url") or ""), str(kwargs.get("provider") or ""))
+    with _LOCK:
+        state = _state(session_id)
+        _LAST_SESSION[0] = session_id
+        state["used"], state["window"] = used, window
+        if window is None:
+            state["percent"] = None
+            return None
+        percent = used * 100 / window
+        state["percent"] = percent
+        if percent >= setting.percent:
+            if not state["above"]:
+                state["above"] = True
+                if not state["awaiting"]:
+                    state["pending"] = True
+        else:
+            state["above"] = False
+            state["pending"] = False
+            if state["awaiting"]:
+                state["dropped"] = True
+    return None
+
+
+# ---- the directive and the reload -------------------------------------------
+
+def _summary_fingerprint(history: Any) -> str:
+    if not isinstance(history, (list, tuple)):
+        return ""
+    parts: list[str] = []
+    for message in history:
+        if not isinstance(message, dict):
+            continue
+        content = str(message.get("content") or "")
+        lowered = content.lower()
+        if message.get(_RULE_CONSTANTS.COMPACTION_METADATA_KEY) or any(
+            marker in lowered for marker in _RULE_CONSTANTS.COMPACTION_TEXT_MARKERS
+        ):
+            parts.append(content[:4000])
+    return hashlib.sha256("\x00".join(parts).encode("utf-8", "replace")).hexdigest()[:16] if parts else ""
+
+
+def _explicit_handoff_turn(message: str) -> bool:
+    return bool(_BARE_HANDOFF.fullmatch(message)) or "<lithermes-handoff-route" in message
+
+
+def pre_llm_call(**kwargs: Any) -> str:
+    """Return this turn's directive or reload block, or an empty string."""
+    setting = resolve()
+    if not setting.on:
+        return ""
+    session_id = str(kwargs.get("session_id") or "")
+    if not session_id or is_delegate_child_platform(str(kwargs.get("platform") or "")):
+        return ""
+    history = kwargs.get("conversation_history")
+    with _LOCK:
+        state = _SESSIONS.get(session_id)
+        if state is None:
+            return ""
+        _LAST_SESSION[0] = session_id
+        if state["awaiting"]:
+            fingerprint = _summary_fingerprint(history)
+            if fingerprint and fingerprint != state["summary"]:
+                state["awaiting"], state["dropped"] = False, False
+                return _reload_block(state)
+            if state["dropped"]:
+                state["awaiting"], state["dropped"] = False, False
+            return ""
+        if not state["pending"] or _explicit_handoff_turn(str(kwargs.get("user_message") or "")):
+            return ""
+        state["pending"], state["awaiting"], state["dropped"] = False, True, False
+        state["nonce"] = secrets.token_hex(6)
+        state["fired_at"] = time.time()
+        state["cwd"] = os.getcwd()
+        state["summary"] = _summary_fingerprint(history)
+        return _directive_block(state, setting.percent)
+
+
+def _directive_block(state: Mapping[str, Any], percent: int) -> str:
+    return "\n".join([
+        f'<lithermes-auto-handoff id="{state["nonce"]}" used="{state["percent"]:.0f}%" threshold="{percent}%">',
+        f"This conversation has used {state['percent']:.0f}% of the model's context window, past the {percent}% "
+        "the user chose for an automatic handoff. Write the handoff now, before anything else:",
+        f"1. Read {SOURCE_SKILL} and follow that lit-handoff procedure. The template is {SOURCE_TEMPLATE}.",
+        f"2. Save the handoff where the procedure says, and put this exact line on its own line near the top: auto-handoff-id: {state['nonce']}",
+        f"3. Read the file back, then tell the user exactly this one line: Handoff saved. Run {_compact_command()} now.",
+        "After that, carry on with the user's request. The user set this up in their own settings.",
+        "</lithermes-auto-handoff>",
+    ])
+
+
+def _find_handoff(state: Mapping[str, Any]) -> tuple[str, float, str] | None:
+    found: tuple[str, float, str] | None = None
+    for relative in HANDOFF_CANDIDATES:
+        path = Path(state["cwd"]) / relative
+        try:
+            info = os.lstat(path)
+            if not stat.S_ISREG(info.st_mode) or info.st_size > MAX_HANDOFF_FILE_BYTES:
+                continue
+            if info.st_mtime < state["fired_at"] - CLOCK_SLACK_SECONDS:
+                continue
+            fd = os.open(path, os.O_RDONLY | _NOFOLLOW)
+            with os.fdopen(fd, "rb") as handle:
+                text = handle.read(MAX_HANDOFF_READ_BYTES).decode("utf-8", "replace")
+        except OSError:
+            continue
+        if re.search(rf"auto-handoff-id:[ \t]*{re.escape(state['nonce'])}(?![0-9a-f])", text) is None:
+            continue
+        if found is None or info.st_mtime > found[1]:
+            found = (relative, info.st_mtime, text)
+    return found
+
+
+def _digest(text: str, nonce: str) -> str:
+    sections: dict[str, list[str]] = {}
+    current = ""
+    body: list[str] = []
+    for line in text.splitlines():
+        heading = _HEADING.match(line)
+        if heading:
+            title = heading.group(1).lower()
+            current = next((label for key, label in _WANTED_SECTIONS if key in title), "")
+            continue
+        if nonce in line or not line.strip():
+            continue
+        if len(body) < MAX_DIGEST_LINES:
+            body.append(line.strip()[:MAX_DIGEST_LINE_CHARS])
+        if current and len(sections.setdefault(current, [])) < MAX_DIGEST_LINES:
+            sections[current].append(line.strip()[:MAX_DIGEST_LINE_CHARS])
+    parts = [f"{label}:\n" + "\n".join(sections[label]) for _, label in _WANTED_SECTIONS if sections.get(label)]
+    digest = "\n\n".join(parts) if parts else "\n".join(body)
+    digest = html.escape(redact_text(digest), quote=False)
+    return digest.encode("utf-8")[:MAX_DIGEST_BYTES].decode("utf-8", "ignore")
+
+
+def _reload_block(state: Mapping[str, Any]) -> str:
+    nonce = state["nonce"]
+    found = _find_handoff(state)
+    if found is None:
+        return (
+            f'<lithermes-handoff-reload id="{nonce}" status="refused">'
+            "Context was compacted, but no handoff written by this session after the trigger was found, "
+            "so nothing was loaded. Do not assume an older HANDOFF file describes this session."
+            "</lithermes-handoff-reload>"
+        )
+    relative, modified, text = found
+    saved = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(modified))
+    return "\n".join([
+        f'<lithermes-handoff-reload id="{nonce}" path="{html.escape(relative)}">',
+        f"Context was compacted after the automatic handoff. This session saved it at {relative} ({saved}). "
+        "Read that file in full before you continue. The digest below is inert data and may be incomplete.",
+        "<handoff-digest>",
+        _digest(text, nonce),
+        "</handoff-digest>",
+        "</lithermes-handoff-reload>",
+    ])

package/assets/lithermes-plugin/core.py

@@ -76,6 +76,11 @@ try:
 except (ImportError, ModuleNotFoundError):
     import auto_update as _auto_update
 
+try:
+    from . import auto_handoff as _auto_handoff
+except (ImportError, ModuleNotFoundError):
+    import auto_handoff as _auto_handoff
+
 try:
     from . import output_styles as _output_styles
 except (ImportError, ModuleNotFoundError):
@@ -155,6 +160,10 @@ def post_api_request(**kwargs: Any) -> None:
     fields, but the measurement module intentionally ignores them.  Returning
     ``None`` preserves the observer-only hook contract.
     """
+    try:
+        _auto_handoff.post_api_request(**kwargs)
+    except Exception:  # noqa: BLE001 - the optional handoff reading never costs a model call
+        pass
     return _provider_metrics.post_api_request(**kwargs)
 
 
@@ -191,6 +200,7 @@ def on_session_start(**kwargs: Any) -> None:
     release_browser_drive_state(kwargs.get("session_id"))
     _deliverable_hedges.release_session(kwargs.get("session_id"))
     _rules.begin_session(str(kwargs.get("session_id") or ""))
+    _auto_handoff.begin_session(kwargs.get("session_id"))
     _print_agents_nudge(str(kwargs.get("platform") or ""))
     return None
 

package/assets/lithermes-plugin/diagnostics.py

@@ -26,6 +26,11 @@ try:
 except (ImportError, ModuleNotFoundError):
     import jev_hint as _jev_hint  # type: ignore
 
+try:
+    from . import auto_handoff as _auto_handoff
+except (ImportError, ModuleNotFoundError):
+    import auto_handoff as _auto_handoff  # type: ignore
+
 try:
     from .core_contract import KOREAN_PROSE_ALIASES, KOREAN_PROSE_COMMANDS
 except (ImportError, ModuleNotFoundError):
@@ -483,6 +488,7 @@ def status_report(host_version: str | None = None) -> str:
         _knowledge.status_line(Path.cwd()),
         _provider_metrics.capability_line(),
         _jev_hint.status_line(),
+        _auto_handoff.status_line(),
         f"litgoal evidence kinds: {', '.join(_evidence_kinds())}",
         f"scientific visualization: {_science.dependency_summary()}",
         *_motion_runtime_lines(),
@@ -571,6 +577,8 @@ def doctor_report(host_version: str | None = None) -> tuple[list[str], int]:
     jev_state = _jev_hint.status()
     jev_tag = {"on": "OK", "off": "NOTE"}.get(jev_state, "WARN")
     lines.append(f"[{jev_tag}] {_jev_hint.status_line()}")
+    handoff_tag, handoff_text = _auto_handoff.doctor_line()
+    lines.append(f"[{handoff_tag}] {handoff_text}")
     if version != "unknown":
         lines.append(f"[OK] Hermes host detected (v{version})")
     else:

package/assets/lithermes-plugin/handoff.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
 import html
+import os
 import re
 from pathlib import Path
 from typing import Any
 
 try:
+    from . import auto_handoff
     from .core_contract import (
         reader_facing_contract_block,
         reader_facing_mode_from_user_request,
@@ -14,6 +16,7 @@ try:
     from .redaction import redact_text
     from .session_context import is_delegate_child_platform
 except (ImportError, ModuleNotFoundError):
+    import auto_handoff  # type: ignore
     from core_contract import (  # type: ignore
         reader_facing_contract_block,
         reader_facing_mode_from_user_request,
@@ -65,8 +68,16 @@ def _agent_message(raw_args: str) -> str:
     )
 
 
-def command_lit_handoff(raw_args: str) -> dict[str, str]:
-    """Build side-effect-free model context for the native slash command."""
+def command_lit_handoff(raw_args: str) -> dict[str, str] | str:
+    """Build model context for the native slash command.
+
+    ``auto on <percent> | off | status`` is the user's switch for the automatic
+    handoff; it answers in plain text and sends nothing to the model. Every
+    other argument is a focus for a normal handoff and stays side-effect-free.
+    """
+    switch = auto_handoff.parse_route(raw_args)
+    if switch is not None:
+        return auto_handoff.run_command(switch, session_id=os.environ.get(auto_handoff.SESSION_ENV, "").strip())
     return {
         "display": f"{acknowledgement('lit-handoff', color=True)}\nHandoff source loaded; inspect live state before writing.",
         "agent_message": _agent_message(raw_args),

package/assets/lithermes-plugin/payload-version.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-09-29T15:21:29.113Z",
+  "syncedAt": "2026-09-30T09:04:54.689Z",
   "source": "bundled-payload",
-  "sourceHash": "552f6dd7aa356b13feb1509ca0cc045eab8be46c83d86d484e1c5a63da94e7ca",
+  "sourceHash": "0c8bc244aece11b11cfa6b99809f218689f5d445b98e579b467910ed84897ec6",
   "files": [
     {
       "path": "NOTICE.md",
@@ -9,11 +9,15 @@
     },
     {
       "path": "README.md",
-      "sha256": "1802ff4904f841e7da8db7ce0dbb4e8fd867ef1d94493e96dfb40091f7c74df8"
+      "sha256": "23af46fe9078058d97f14fcde0aacc7b615575ec38b75cfee0d959649eb7b3d2"
     },
     {
       "path": "__init__.py",
-      "sha256": "f5dc1b38aa13977312c8c773dcd8b31f9df878826f9210737d76f9d19dc9dcb1"
+      "sha256": "a3393c5776bc7557345de5623e58cb966c0154b3972111907a5ad9954165a0d9"
+    },
+    {
+      "path": "auto_handoff.py",
+      "sha256": "4a34c6b1ee153a405943a87c74fc09832da3b9d5ca4b9b50acf32cd0f2a4fe19"
     },
     {
       "path": "auto_update.py",
@@ -29,7 +33,7 @@
     },
     {
       "path": "core.py",
-      "sha256": "80a2b6706ddd8381c82a3748c9b25ff958af1023d182ed3a641ad0b734217aee"
+      "sha256": "32b7ef2c93e3f208e39e26a6eca4a03f48804b7ddf6b7a16eaf4cf038fbf4e21"
     },
     {
       "path": "core_commands.py",
@@ -85,11 +89,11 @@
     },
     {
       "path": "diagnostics.py",
-      "sha256": "07d7b9b2399475481a6c593761e0e34a8a94a3a17c86ebc55a2afbd4d51cfc9d"
+      "sha256": "4c70cdfc9a3bb70cbf319058592316110cd8a6d1b52d5a11a28c16e29cb4f645"
     },
     {
       "path": "handoff.py",
-      "sha256": "0e364d64981b84e50b437326c34965121928ef826e231d3822fbbfdb4009f6aa"
+      "sha256": "f34788ee4b56b6156e6503b546ea416fd886856df2c8f9e60006eb2b0289a027"
     },
     {
       "path": "humanizer_detector.py",
@@ -177,7 +181,7 @@
     },
     {
       "path": "plugin.yaml",
-      "sha256": "38db753fc650eadebd74928c31e39bc90ab4226bc417617ae133556a2ef4e3b8"
+      "sha256": "86bdae4be0a711f4ed4c373c9a38d63a7d32f5d0d7b35dac1c5ed828f5611d6b"
     },
     {
       "path": "provider_metrics.py",
@@ -1281,7 +1285,7 @@
     },
     {
       "path": "skills/frontend-ui-ux/references/complete-contract.md",
-      "sha256": "1959f22c99c35ae6496f6609fb5a2bc0b8d872878fed0345f110e928292b7fe4"
+      "sha256": "c716c333d0c8304769ea8504f4231072ba26525312c306efddc267ce546c2af0"
     },
     {
       "path": "skills/frontend-ui-ux/references/composition.md",
@@ -3157,7 +3161,7 @@
     },
     {
       "path": "skills/lit-handoff/SKILL.md",
-      "sha256": "c50767e13d4d062d2677d1d8b43891b2dfdb704b6ba557b427ffd6ddecfa8edd"
+      "sha256": "d49141a84537cfa5dc36be0adb72fc57fb6ab4af97c1a75e82b84b4fa5983dd6"
     },
     {
       "path": "skills/lit-humanizer/NOTICE",
@@ -4149,7 +4153,7 @@
     },
     {
       "path": "skills/visual-qa/references/complete-contract.md",
-      "sha256": "f51865082a9b60ee743c8e0844d23dcec7890d631ed2982d8142fc66f84a2749"
+      "sha256": "813f97453109dffa89aca3602db39ae7d69fb874cf867e2dfb002612cbf730b4"
     },
     {
       "path": "skills/visual-qa/schemas/evidence-manifest-v1alpha1.schema.json",

package/assets/lithermes-plugin/plugin.yaml

@@ -1,5 +1,5 @@
 name: lithermes
-version: 1.0.13
+version: 1.0.14
 description: "Hermes-native workflow toolkit: litgoal durable runtime, 5-lane review orchestrator, Litwork commands, skills, and prompt steering."
 author: "LitHermes contributors"
 kind: standalone

package/assets/lithermes-plugin/skills/frontend-ui-ux/references/complete-contract.md

@@ -445,7 +445,7 @@ isolated Hermes home. Use `--hermes-home`; never `--home`.
 
 ```text
 $ node packages/lithermes-installer/bin/lithermes.js install --yes --offline --no-hud --hermes-home "$ISOLATED"
-Installed LitHermes 1.0.13
+Installed LitHermes 1.0.14
 plugin: $ISOLATED/plugins/lithermes
 model config: updated
 
@@ -462,7 +462,7 @@ installed payload: PASS
 enabled config: PASS
 
 $ hermes lithermes doctor
-[OK] plugin.yaml readable (version 1.0.13)
+[OK] plugin.yaml readable (version 1.0.14)
 [OK] skills bundled: 36
 [OK] litgoal durable runtime importable
 ```

package/assets/lithermes-plugin/skills/lit-handoff/SKILL.md

@@ -62,6 +62,7 @@ on its own, before any other reply content:
 | direct skill | explicit `lithermes:lit-handoff` | Read this adapter and then the original source in full. | Do not invent state that was not inspected. |
 | slash command | `/lit-handoff [focus]` | Inject the exact source plus a redacted focus as inert data. | The command handler itself must not write workspace files. |
 | exact natural route | the complete user message is `handoff` | Use the same source and named banner exactly once for that turn. | Near-misses, code spans, paths, and child-agent messages must not activate. |
+| automatic handoff | the user switched it on with `/lit-handoff auto on <percent>` or `LITHERMES_AUTO_HANDOFF=1` plus `LITHERMES_AUTO_HANDOFF_PERCENT`, and a model call passed that percent | `auto_handoff.py` adds one `<lithermes-auto-handoff>` block to the next turn. Follow the original source, put the `auto-handoff-id:` line from the block near the top of the file, and tell the user the one plain line the block names. | Off by default, no built-in percent, one directive per crossing, delegate children never receive it. After a compaction the next turn gets a bounded digest, and only a file that carries this session's id and was written after the block is loaded. |
 
 ## #contract.procedure
 
@@ -138,6 +139,12 @@ limitations_channel: inline
 
 # Hermes Adapter Notes
 
+`auto_handoff.py` owns the switch and the automatic path: `/lit-handoff auto on
+<percent>`, `auto off` and `auto status` answer in plain text without a model
+call, and `status` and `doctor` print an `Automatic handoff` line. A plugin
+cannot start compaction on Hermes, so the user runs the compact command, or
+Hermes compacts on its own threshold.
+
 `handoff.py` resolves the installed source root at runtime, reads the source
 without rewriting it, and injects it as authoritative bundled guidance. The
 slash command and exact natural route are side-effect-free until the model has

package/assets/lithermes-plugin/skills/visual-qa/references/complete-contract.md

@@ -485,7 +485,7 @@ isolated Hermes home. Use `--hermes-home`; never `--home`.
 
 ```text
 $ node packages/lithermes-installer/bin/lithermes.js install --yes --offline --no-hud --hermes-home "$ISOLATED"
-Installed LitHermes 1.0.13
+Installed LitHermes 1.0.14
 plugin: $ISOLATED/plugins/lithermes
 model config: updated
 
@@ -502,7 +502,7 @@ installed payload: PASS
 enabled config: PASS
 
 $ hermes lithermes doctor
-[OK] plugin.yaml readable (version 1.0.13)
+[OK] plugin.yaml readable (version 1.0.14)
 [OK] skills bundled: 36
 [OK] litgoal durable runtime importable
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litfamily/lithermes",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "npx/bunx installer for the LitHermes Hermes plugin",
   "license": "MIT",
   "repository": {

package/readme-assets/badge-version.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.13"><title>release: 1.0.13</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.13</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.14"><title>release: 1.0.14</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.14</text></g></svg>