@litfamily/litcodex 1.0.40 → 1.0.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/README-Ko-KR.md +11 -11
  2. package/README.md +11 -11
  3. package/dist/install/auto-handoff-doctor.js +14 -8
  4. package/marketplace/plugins/litcodex/.codex-plugin/plugin.json +1 -1
  5. package/marketplace/plugins/litcodex/components/auto-update/dist/extensions-notice.js +13 -2
  6. package/marketplace/plugins/litcodex/components/auto-update/dist/shown-notices.d.ts +6 -0
  7. package/marketplace/plugins/litcodex/components/auto-update/dist/shown-notices.js +63 -0
  8. package/marketplace/plugins/litcodex/components/auto-update/package.json +1 -1
  9. package/marketplace/plugins/litcodex/components/comment-checker/package.json +1 -1
  10. package/marketplace/plugins/litcodex/components/git-bash/package.json +1 -1
  11. package/marketplace/plugins/litcodex/components/lit-loop/dist/auto-handoff-settings.d.ts +7 -4
  12. package/marketplace/plugins/litcodex/components/lit-loop/dist/auto-handoff-settings.js +38 -22
  13. package/marketplace/plugins/litcodex/components/lit-loop/dist/auto-handoff.js +7 -5
  14. package/marketplace/plugins/litcodex/components/lit-loop/dist/hook-cli.js +7 -0
  15. package/marketplace/plugins/litcodex/components/lit-loop/dist/run-end.d.ts +22 -0
  16. package/marketplace/plugins/litcodex/components/lit-loop/dist/run-end.js +93 -0
  17. package/marketplace/plugins/litcodex/components/lit-loop/dist/workflow-map.d.ts +2 -0
  18. package/marketplace/plugins/litcodex/components/lit-loop/dist/workflow-map.js +3 -1
  19. package/marketplace/plugins/litcodex/components/lit-loop/package.json +1 -1
  20. package/marketplace/plugins/litcodex/components/lsp/package.json +1 -1
  21. package/marketplace/plugins/litcodex/components/rules/package.json +1 -1
  22. package/marketplace/plugins/litcodex/components/start-work-continuation/package.json +1 -1
  23. package/marketplace/plugins/litcodex/components/telemetry/package.json +1 -1
  24. package/marketplace/plugins/litcodex/components/wikify-knowledge/package.json +1 -1
  25. package/node_modules/@litcodex/lit-loop/README.md +4 -4
  26. package/node_modules/@litcodex/lit-loop/dist/auto-handoff-settings.d.ts +7 -4
  27. package/node_modules/@litcodex/lit-loop/dist/auto-handoff-settings.js +38 -22
  28. package/node_modules/@litcodex/lit-loop/dist/auto-handoff.js +7 -5
  29. package/node_modules/@litcodex/lit-loop/dist/hook-cli.js +7 -0
  30. package/node_modules/@litcodex/lit-loop/dist/run-end.d.ts +22 -0
  31. package/node_modules/@litcodex/lit-loop/dist/run-end.js +93 -0
  32. package/node_modules/@litcodex/lit-loop/dist/workflow-map.d.ts +2 -0
  33. package/node_modules/@litcodex/lit-loop/dist/workflow-map.js +3 -1
  34. package/node_modules/@litcodex/lit-loop/package.json +1 -1
  35. package/package.json +2 -2
  36. package/readme-assets/badge-version.svg +1 -1
package/README-Ko-KR.md CHANGED
@@ -1,12 +1,12 @@
1
- <p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.40/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.40/readme-assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 일곱 머신의 칸이 차례로 켜지고, 셋째 칸의 LitCodex 머신이 주황 바이저와 테두리를 밝힌 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
1
+ <p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.41/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.41/readme-assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 일곱 머신의 칸이 차례로 켜지고, 셋째 칸의 LitCodex 머신이 주황 바이저와 테두리를 밝힌 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
2
2
 
3
3
  <p align="center">
4
- <a href="#설치"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.40/readme-assets/badge-version.svg" alt="1.0.40" /></a>
5
- <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.40/readme-assets/badge-license.svg" alt="MIT license" /></a>
4
+ <a href="#설치"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.41/readme-assets/badge-version.svg" alt="1.0.41" /></a>
5
+ <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.41/readme-assets/badge-license.svg" alt="MIT license" /></a>
6
6
  </p>
7
7
 
8
8
  <p align="center">
9
- <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage-Ko-KR.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.40/readme-assets/lucide-book-open.svg" width="16" alt="" /> 문서</a> &nbsp; <a href="#설치">설치</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.40/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.40/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
9
+ <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage-Ko-KR.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.41/readme-assets/lucide-book-open.svg" width="16" alt="" /> 문서</a> &nbsp; <a href="#설치">설치</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.41/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.41/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
10
10
  </p>
11
11
 
12
12
  # LitCodex
@@ -23,12 +23,12 @@
23
23
  Node.js 22 이상과 Codex CLI가 필요합니다.
24
24
 
25
25
  ```sh
26
- npm exec --yes --package @litfamily/litcodex@1.0.40 -- litcodex install
26
+ npm exec --yes --package @litfamily/litcodex@1.0.41 -- litcodex install
27
27
  ```
28
28
 
29
29
  설치기는 어떤 모델이 이끌지, 어떤 모델이 거들지, 답변 스타일은 무엇으로 할지 묻고, 쓰려는 내용을 먼저 보여 준 뒤
30
30
  `~/.codex/config.toml`에서 자기가 관리하는 항목만 고칩니다. 계획만 먼저 보려면
31
- `npm exec --yes --package @litfamily/litcodex@1.0.40 -- litcodex --dry-run install`을 실행하고, 묻는 단계 없이
31
+ `npm exec --yes --package @litfamily/litcodex@1.0.41 -- litcodex --dry-run install`을 실행하고, 묻는 단계 없이
32
32
  설치하려면 `install` 뒤에 `--yes`를 붙이세요.
33
33
 
34
34
  ```sh
@@ -39,7 +39,7 @@ litcodex install
39
39
  전역으로 설치하면 영상 스킬이 쓸 도구를 미리 준비하느라 버전이 고정된 파일 몇 개를 내려받습니다. 무엇을 받는지와
40
40
  건너뛰는 방법은 [설치 안내](https://github.com/wjgoarxiv/litcodex/blob/main/docs/install-Ko-KR.md#전역-명령으로-쓰기)에 있습니다.
41
41
 
42
- > 전역 설치가 없다면 `npm exec --yes --package @litfamily/litcodex@1.0.40 -- litcodex <command>` 형식을 사용하세요.
42
+ > 전역 설치가 없다면 `npm exec --yes --package @litfamily/litcodex@1.0.41 -- litcodex <command>` 형식을 사용하세요.
43
43
 
44
44
  ## 첫 작업
45
45
 
@@ -118,8 +118,8 @@ cx="${CODEX_HOME:-$HOME/.codex}"; [ -f "$cx/skills/lit-docx/SKILL.md" ] && print
118
118
  - Codex에 플러그인·훅·에이전트가 등록되고 `~/.codex/config.toml`의 관리 항목이 갱신됩니다. 관련 없는 Codex
119
119
  설정은 그대로 둡니다.
120
120
  - 프로젝트마다 `.litcodex/lit-loop/` 아래에 로컬 기록이 생기며, Git과 패키지에서는 제외됩니다.
121
- - [자동 핸드오프](https://github.com/wjgoarxiv/litcodex/blob/main/docs/auto-handoff-Ko-KR.md)는 선택 기능이며
122
- 기본값은 꺼짐입니다.
121
+ - [자동 핸드오프](https://github.com/wjgoarxiv/litcodex/blob/main/docs/auto-handoff-Ko-KR.md)는 기본으로 켜져 있고
122
+ 컨텍스트 창의 80%에서 동작하며, `lit-handoff auto off`로 끌 수 있습니다.
123
123
  - 테스트, 픽스처, 테스트 헬퍼, Vitest 설정은 저장소에만 있습니다. npm 패키지와 설치된 마켓플레이스 플러그인에는
124
124
  들어가지 않습니다.
125
125
 
@@ -133,7 +133,7 @@ cx="${CODEX_HOME:-$HOME/.codex}"; [ -f "$cx/skills/lit-docx/SKILL.md" ] && print
133
133
  ## 확인, 문제 해결, 제거
134
134
 
135
135
  ```sh
136
- npm exec --yes --package @litfamily/litcodex@1.0.40 -- litcodex doctor
136
+ npm exec --yes --package @litfamily/litcodex@1.0.41 -- litcodex doctor
137
137
  ```
138
138
 
139
139
  `litcodex doctor`는 등록·훅·설정·호스트 기능을, `litcodex loop doctor`는 현재 프로젝트의 루프 상태를 확인합니다.
@@ -141,7 +141,7 @@ npm exec --yes --package @litfamily/litcodex@1.0.40 -- litcodex doctor
141
141
  [문제 해결](https://github.com/wjgoarxiv/litcodex/blob/main/README-Ko-KR.md#문제-해결)에 있습니다.
142
142
 
143
143
  ```sh
144
- npm exec --yes --package @litfamily/litcodex@1.0.40 -- litcodex uninstall
144
+ npm exec --yes --package @litfamily/litcodex@1.0.41 -- litcodex uninstall
145
145
  ```
146
146
 
147
147
  플러그인과 LitCodex가 관리하는 설정을 지우고, 관련 없는 설정은 그대로 둡니다.
package/README.md CHANGED
@@ -1,12 +1,12 @@
1
- <p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.40/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.40/readme-assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: seven armored machines power on bay by bay, the LitCodex machine in the third bay wakes with a glowing orange visor and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
1
+ <p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.41/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.41/readme-assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: seven armored machines power on bay by bay, the LitCodex machine in the third bay wakes with a glowing orange visor and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
2
2
 
3
3
  <p align="center">
4
- <a href="#install"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.40/readme-assets/badge-version.svg" alt="1.0.40" /></a>
5
- <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.40/readme-assets/badge-license.svg" alt="MIT license" /></a>
4
+ <a href="#install"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.41/readme-assets/badge-version.svg" alt="1.0.41" /></a>
5
+ <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.41/readme-assets/badge-license.svg" alt="MIT license" /></a>
6
6
  </p>
7
7
 
8
8
  <p align="center">
9
- <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.40/readme-assets/lucide-book-open.svg" width="16" alt="" /> Docs</a> &nbsp; <a href="#install">Install</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.40/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.40/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
9
+ <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/usage.md"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.41/readme-assets/lucide-book-open.svg" width="16" alt="" /> Docs</a> &nbsp; <a href="#install">Install</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/docs/assets/readme/ignition-film.mp4"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.41/readme-assets/lucide-play.svg" width="16" alt="" /> Ignition</a> &nbsp; <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.41/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
10
10
  </p>
11
11
 
12
12
  # LitCodex
@@ -24,12 +24,12 @@ today's stopped.
24
24
  You need Node.js 22 or later and Codex CLI.
25
25
 
26
26
  ```sh
27
- npm exec --yes --package @litfamily/litcodex@1.0.40 -- litcodex install
27
+ npm exec --yes --package @litfamily/litcodex@1.0.41 -- litcodex install
28
28
  ```
29
29
 
30
30
  The installer asks which model leads, which model helps and which output style you like, shows what it is
31
31
  about to write, and changes only the keys it manages in `~/.codex/config.toml`. To see the plan first, run
32
- `npm exec --yes --package @litfamily/litcodex@1.0.40 -- litcodex --dry-run install`. To skip the
32
+ `npm exec --yes --package @litfamily/litcodex@1.0.41 -- litcodex --dry-run install`. To skip the
33
33
  questions, add `--yes` after `install`.
34
34
 
35
35
  ```sh
@@ -41,7 +41,7 @@ A global install also gets the video skill's tools ready with a few pinned downl
41
41
  [install guide](https://github.com/wjgoarxiv/litcodex/blob/main/docs/install.md#a-global-command) lists them
42
42
  and shows how to skip them.
43
43
 
44
- > Without a global install, use `npm exec --yes --package @litfamily/litcodex@1.0.40 -- litcodex <command>`.
44
+ > Without a global install, use `npm exec --yes --package @litfamily/litcodex@1.0.41 -- litcodex <command>`.
45
45
 
46
46
  ## First task
47
47
 
@@ -121,8 +121,8 @@ LitCodex skill folders to `~/.codex/litcodex-backups/<date>/` first. Versions up
121
121
  - Codex gets the plugin, hooks and agents, plus the managed keys in `~/.codex/config.toml`. Your unrelated
122
122
  Codex settings stay as they are.
123
123
  - Each project gets local records under `.litcodex/lit-loop/`, kept out of Git and packages.
124
- - [Automatic handoff](https://github.com/wjgoarxiv/litcodex/blob/main/docs/auto-handoff.md) is optional and
125
- off by default.
124
+ - [Automatic handoff](https://github.com/wjgoarxiv/litcodex/blob/main/docs/auto-handoff.md) is on by default
125
+ at 80% of the context window; `lit-handoff auto off` turns it off.
126
126
  - Tests, fixtures, test helpers and the Vitest configuration live only in the repository. Neither the npm
127
127
  package nor the installed marketplace plugin includes them.
128
128
 
@@ -137,7 +137,7 @@ rather have neither, set `LITCODEX_NO_UPDATE_CHECK=1`. A doctor run that failed,
137
137
  ## Check, fix, remove
138
138
 
139
139
  ```sh
140
- npm exec --yes --package @litfamily/litcodex@1.0.40 -- litcodex doctor
140
+ npm exec --yes --package @litfamily/litcodex@1.0.41 -- litcodex doctor
141
141
  ```
142
142
 
143
143
  `litcodex doctor` checks registration, hooks, config and host capabilities; `litcodex loop doctor` checks
@@ -145,7 +145,7 @@ the current project's loop state. If `lit` does nothing, run doctor and check th
145
145
  in Codex. More fixes are under [troubleshooting](https://github.com/wjgoarxiv/litcodex#troubleshooting).
146
146
 
147
147
  ```sh
148
- npm exec --yes --package @litfamily/litcodex@1.0.40 -- litcodex uninstall
148
+ npm exec --yes --package @litfamily/litcodex@1.0.41 -- litcodex uninstall
149
149
  ```
150
150
 
151
151
  This removes the plugin and the config LitCodex manages, and leaves your other settings alone.
@@ -1,10 +1,13 @@
1
- // Doctor view of the opt-in automatic handoff. The hook side lives in the lit-loop component
1
+ // Doctor view of the automatic handoff, which is on by default. The hook side lives in the lit-loop component
2
2
  // (`auto-handoff-settings.ts`); this file reads the same environment variables and the same
3
- // `.litcodex/auto-handoff/settings.json`, and mirrors its rules so the installer never imports hook code.
3
+ // `.litcodex/auto-handoff/settings.json`, and mirrors its rules (and its default percent) so the installer never
4
+ // imports hook code.
4
5
  import { join } from "node:path";
5
6
  import { readRootSettings } from "../config-migration/root-settings.js";
6
7
  const FLAG_ENV = "LITCODEX_AUTO_HANDOFF";
7
8
  const PERCENT_ENV = "LITCODEX_AUTO_HANDOFF_PERCENT";
9
+ /** Mirror of DEFAULT_AUTO_HANDOFF_PERCENT in the lit-loop component. */
10
+ const DEFAULT_PERCENT = 80;
8
11
  const HOST_KEY = "model_post_turn_compact_threshold_percent";
9
12
  const KEY_LINE = new RegExp(`^\\s*${HOST_KEY}\\s*=\\s*(\\d+)\\s*(?:#.*)?$`, "mu");
10
13
  /** The marker line `lit-handoff auto on` writes directly above the key; only a key under it is managed. */
@@ -61,7 +64,7 @@ function readIfPresent(fs, path) {
61
64
  }
62
65
  export function inspectAutoHandoff(fs, env, projectRoot, codexHome) {
63
66
  const warnings = [];
64
- let storedEnabled = false;
67
+ let storedEnabled = true;
65
68
  let storedPercent = null;
66
69
  const rawSettings = readIfPresent(fs, join(projectRoot, ".litcodex", "auto-handoff", "settings.json"));
67
70
  if (rawSettings !== null) {
@@ -76,6 +79,8 @@ export function inspectAutoHandoff(fs, env, projectRoot, codexHome) {
76
79
  }
77
80
  }
78
81
  catch {
82
+ storedEnabled = false;
83
+ storedPercent = null;
79
84
  warnings.push(".litcodex/auto-handoff/settings.json could not be read, so automatic handoff stays off.");
80
85
  }
81
86
  }
@@ -90,11 +95,12 @@ export function inspectAutoHandoff(fs, env, projectRoot, codexHome) {
90
95
  if (envInvalid) {
91
96
  warnings.push(`${PERCENT_ENV}=${shown(rawPercent)} is not a whole number from 1 to 99, so automatic handoff stays off.`);
92
97
  }
93
- const percent = envInvalid ? null : (envPercent ?? storedPercent);
94
- const source = flag === "1" || flag === "0" || envPercent !== null ? "environment" : enabled ? "command" : "default";
95
- if (enabled && !envInvalid && percent === null) {
96
- warnings.push(`Automatic handoff is on but has no percent. Run "lit-handoff auto on <percent>" or set ${PERCENT_ENV}.`);
97
- }
98
+ const percent = envInvalid ? null : (envPercent ?? storedPercent ?? (enabled ? DEFAULT_PERCENT : null));
99
+ let source = "command";
100
+ if (flag === "1" || flag === "0" || envPercent !== null)
101
+ source = "environment";
102
+ else if (enabled && storedPercent === null)
103
+ source = "default";
98
104
  const active = enabled && percent !== null;
99
105
  const projectConfig = readIfPresent(fs, join(projectRoot, ".codex", "config.toml"));
100
106
  if (!active || percent === null) {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "litcodex",
3
- "version": "1.0.40",
3
+ "version": "1.0.41",
4
4
  "author": {
5
5
  "name": "LitCodex Authors"
6
6
  },
@@ -3,9 +3,12 @@
3
3
  // `litcodex install` writes the notice to <LITCODEX_DATA_ROOT or ~/.litcodex>/extensions-notice.json when it lands a
4
4
  // new payload. This SessionStart hook claims the file with a rename, so two sessions starting together cannot both
5
5
  // show it, deletes it, and returns the text for the hook's user-visible systemMessage. Anything malformed is dropped.
6
+ // Every later install writes the same text again, so the hash of each text that was shown goes into the "already
7
+ // shown" record (shown-notices.ts) and the same text is claimed and dropped without being shown a second time.
6
8
  import { readFileSync, renameSync, rmSync } from "node:fs";
7
9
  import { homedir } from "node:os";
8
- import { join } from "node:path";
10
+ import { dirname, join } from "node:path";
11
+ import { markShown, noticeHash, wasShown } from "./shown-notices.js";
9
12
  const NOTICE_SCHEMA_VERSION = 1;
10
13
  const MAX_NOTICE_CHARS = 2000;
11
14
  export function extensionsNoticePath(env) {
@@ -26,7 +29,15 @@ export function takeExtensionsNotice(env = process.env) {
26
29
  if (parsed.schemaVersion !== NOTICE_SCHEMA_VERSION || typeof parsed.message !== "string")
27
30
  return undefined;
28
31
  const message = parsed.message.replace(/[^\P{Cc}\n]/gu, "").trim();
29
- return message.length === 0 ? undefined : message.slice(0, MAX_NOTICE_CHARS);
32
+ if (message.length === 0)
33
+ return undefined;
34
+ const text = message.slice(0, MAX_NOTICE_CHARS);
35
+ const dataRoot = dirname(path);
36
+ const hash = noticeHash(text);
37
+ if (wasShown(dataRoot, hash))
38
+ return undefined;
39
+ markShown(dataRoot, hash);
40
+ return text;
30
41
  }
31
42
  catch {
32
43
  return undefined;
@@ -0,0 +1,6 @@
1
+ export declare function noticeHash(text: string): string;
2
+ export declare function shownNoticesPath(dataRoot: string): string;
3
+ /** True only when a well-formed line of the record carries this hash. */
4
+ export declare function wasShown(dataRoot: string, hash: string): boolean;
5
+ /** Append one line. Never throws and never writes through a symlink or past the cap. */
6
+ export declare function markShown(dataRoot: string, hash: string, now?: number): void;
@@ -0,0 +1,63 @@
1
+ // The "already shown" record: one line per notice text LitCodex itself has printed, kept in the data root beside
2
+ // the notice it guards (`<LITCODEX_DATA_ROOT or ~/.litcodex>/shown-notices.jsonl`).
3
+ //
4
+ // A line is `{"hash":"<16 hex>","at":<ms>}`: a hash of the whitespace-normalised text and the time it was shown,
5
+ // never the text. The file is append-only and capped, and every problem reads as "not shown yet", so a missing,
6
+ // corrupt, oversized, symlinked or unwritable record changes nothing: the notice appears exactly as it did before
7
+ // the record existed.
8
+ import { createHash } from "node:crypto";
9
+ import { closeSync, constants, lstatSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
10
+ import { join } from "node:path";
11
+ const LEDGER_FILE = "shown-notices.jsonl";
12
+ /** About 3,000 lines. Past this nothing is read or appended, which is the same as having no record. */
13
+ const MAX_LEDGER_BYTES = 64 * 1024;
14
+ const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
15
+ export function noticeHash(text) {
16
+ return createHash("sha256").update(text.replace(/\s+/gu, " ").trim()).digest("hex").slice(0, 16);
17
+ }
18
+ export function shownNoticesPath(dataRoot) {
19
+ return join(dataRoot, LEDGER_FILE);
20
+ }
21
+ /** True only when a well-formed line of the record carries this hash. */
22
+ export function wasShown(dataRoot, hash) {
23
+ try {
24
+ const path = shownNoticesPath(dataRoot);
25
+ const stat = lstatSync(path, { throwIfNoEntry: false });
26
+ if (stat === undefined || !stat.isFile() || stat.size > MAX_LEDGER_BYTES)
27
+ return false;
28
+ for (const line of readFileSync(path, "utf8").split("\n")) {
29
+ try {
30
+ const entry = JSON.parse(line);
31
+ if (typeof entry === "object" && entry !== null && entry.hash === hash)
32
+ return true;
33
+ }
34
+ catch {
35
+ // a corrupt line is skipped
36
+ }
37
+ }
38
+ return false;
39
+ }
40
+ catch {
41
+ return false;
42
+ }
43
+ }
44
+ /** Append one line. Never throws and never writes through a symlink or past the cap. */
45
+ export function markShown(dataRoot, hash, now = Date.now()) {
46
+ try {
47
+ const path = shownNoticesPath(dataRoot);
48
+ mkdirSync(dataRoot, { recursive: true });
49
+ const stat = lstatSync(path, { throwIfNoEntry: false });
50
+ if (stat !== undefined && (!stat.isFile() || stat.size >= MAX_LEDGER_BYTES))
51
+ return;
52
+ const fd = openSync(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | NO_FOLLOW, 0o600);
53
+ try {
54
+ writeSync(fd, `${JSON.stringify({ hash, at: now })}\n`);
55
+ }
56
+ finally {
57
+ closeSync(fd);
58
+ }
59
+ }
60
+ catch {
61
+ // the notice was already shown; losing the record only means it may show again
62
+ }
63
+ }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/auto-update",
3
- "version": "1.0.40",
3
+ "version": "1.0.41",
4
4
  "description": "LitCodex foreground update barrier for the SessionStart and management lifecycles.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/comment-checker",
3
- "version": "1.0.40",
3
+ "version": "1.0.41",
4
4
  "description": "LitCodex Comment-Checker hook: flags low-value / AI-slop comments introduced by edits.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/git-bash",
3
- "version": "1.0.40",
3
+ "version": "1.0.41",
4
4
  "description": "LitCodex Git-Bash hook: reminds Windows sessions to prefer the git_bash MCP before the built-in shell.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -2,6 +2,8 @@ export declare const AUTO_HANDOFF_FLAG_ENV = "LITCODEX_AUTO_HANDOFF";
2
2
  export declare const AUTO_HANDOFF_PERCENT_ENV = "LITCODEX_AUTO_HANDOFF_PERCENT";
3
3
  export declare const AUTO_HANDOFF_DIR = ".litcodex/auto-handoff";
4
4
  export declare const AUTO_HANDOFF_SETTINGS_FILE = "settings.json";
5
+ /** Chosen below Codex's own automatic compaction point, so the handoff is written before the host compacts. */
6
+ export declare const DEFAULT_AUTO_HANDOFF_PERCENT = 80;
5
7
  export declare const HOST_COMPACT_KEY = "model_post_turn_compact_threshold_percent";
6
8
  export declare const HOST_COMPACT_BEGIN = "# litcodex automatic handoff (managed by `lit-handoff auto`; `lit-handoff auto off` removes it)";
7
9
  export interface StoredAutoHandoff {
@@ -24,7 +26,7 @@ export declare function parsePercent(raw: string | undefined): number | null;
24
26
  export declare function settingsPath(repoRoot: string): string;
25
27
  /** Read a small regular file; null when missing, a symlink, too large, or unreadable. */
26
28
  export declare function readSmallFile(path: string): string | null;
27
- /** The stored choice; a missing, malformed or hand-edited file reads as "off, no percent". */
29
+ /** The stored choice; a missing file reads as the default (on), a malformed or hand-edited one as "off, no percent". */
28
30
  export declare function readStoredAutoHandoff(repoRoot: string): {
29
31
  stored: StoredAutoHandoff;
30
32
  warning: string | null;
@@ -32,7 +34,7 @@ export declare function readStoredAutoHandoff(repoRoot: string): {
32
34
  /**
33
35
  * Combine the environment with the stored choice. The environment wins when it is set: `=1` turns the
34
36
  * feature on and `=0` turns it off. The percent comes from its variable first, then from the stored
35
- * value. Nothing is active without a valid percent.
37
+ * value, then from the default. An invalid percent variable keeps the feature off.
36
38
  */
37
39
  export declare function resolveAutoHandoff(env: NodeJS.ProcessEnv, stored: StoredAutoHandoff, storedWarning?: string | null): AutoHandoffState;
38
40
  export declare function loadAutoHandoffState(repoRoot: string, env: NodeJS.ProcessEnv): AutoHandoffState;
@@ -65,8 +67,9 @@ export declare function writeProjectCompaction(repoRoot: string, percent: number
65
67
  export declare function removeProjectCompaction(repoRoot: string): ProjectConfigResult;
66
68
  /**
67
69
  * Remove the managed block when the feature is effectively off, however it got there: `lit-handoff auto
68
- * off`, `LITCODEX_AUTO_HANDOFF=0`, a deleted settings file, or a percent that is not valid. Without this the
69
- * block outlives the switch and Codex keeps compacting at that percent with no handoff. Only the marked
70
+ * off`, `LITCODEX_AUTO_HANDOFF=0`, or a percent that is not valid. A deleted settings file puts the feature
71
+ * back on its default percent, which the block no longer matches, so it goes too. Without this the block
72
+ * outlives the switch and Codex keeps compacting at that percent with no handoff. Only the marked
70
73
  * block goes; a key the user wrote by hand is never touched. Never throws.
71
74
  */
72
75
  export declare function clearManagedCompactionWhenOff(repoRoot: string, env: NodeJS.ProcessEnv): ProjectConfigResult;
@@ -1,10 +1,12 @@
1
1
  // src/auto-handoff-settings.ts — the user-controlled switch for automatic handoff.
2
2
  //
3
- // Off by default. The user turns it on with the exact prompt `lit-handoff auto on <percent>` (or sets
4
- // `LITCODEX_AUTO_HANDOFF=1` plus `LITCODEX_AUTO_HANDOFF_PERCENT`), turns it off with
5
- // `lit-handoff auto off`, and reads the state with `lit-handoff auto status`. The percent is never
6
- // hard-coded: `on` without a number reuses the last value the user stored and asks for one when there
7
- // is none. A percent that is not a whole number from 1 to 99 keeps the feature off and is reported.
3
+ // On by default at DEFAULT_AUTO_HANDOFF_PERCENT of the context window, so a long conversation saves its
4
+ // handoff before it is compacted without anyone setting anything up. The one off switch is the exact prompt
5
+ // `lit-handoff auto off` (or `LITCODEX_AUTO_HANDOFF=0`); `lit-handoff auto on <percent>` (or
6
+ // `LITCODEX_AUTO_HANDOFF=1` plus `LITCODEX_AUTO_HANDOFF_PERCENT`) chooses another percent, and
7
+ // `lit-handoff auto status` reads the state. `on` without a number reuses the last value the user stored,
8
+ // else the default. A percent that is not a whole number from 1 to 99 keeps the feature off and is reported,
9
+ // and so does a settings file that cannot be read: the user's choice is unknown, so nothing is assumed.
8
10
  //
9
11
  // Command-set values live in `.litcodex/auto-handoff/settings.json` under the project folder. When the
10
12
  // feature is turned on by command, the same percent is written to the PROJECT `.codex/config.toml` as
@@ -20,11 +22,16 @@ export const AUTO_HANDOFF_FLAG_ENV = "LITCODEX_AUTO_HANDOFF";
20
22
  export const AUTO_HANDOFF_PERCENT_ENV = "LITCODEX_AUTO_HANDOFF_PERCENT";
21
23
  export const AUTO_HANDOFF_DIR = ".litcodex/auto-handoff";
22
24
  export const AUTO_HANDOFF_SETTINGS_FILE = "settings.json";
25
+ /** Chosen below Codex's own automatic compaction point, so the handoff is written before the host compacts. */
26
+ export const DEFAULT_AUTO_HANDOFF_PERCENT = 80;
23
27
  export const HOST_COMPACT_KEY = "model_post_turn_compact_threshold_percent";
24
28
  export const HOST_COMPACT_BEGIN = "# litcodex automatic handoff (managed by `lit-handoff auto`; `lit-handoff auto off` removes it)";
25
29
  const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
26
30
  const MAX_FILE_BYTES = 256 * 1024;
27
- const DEFAULT_STORED = Object.freeze({ enabled: false, percent: null });
31
+ /** No settings file: the product default. */
32
+ const DEFAULT_STORED = Object.freeze({ enabled: true, percent: null });
33
+ /** A settings file that cannot be read: the user's choice is unknown, so the feature stays off. */
34
+ const UNREADABLE_STORED = Object.freeze({ enabled: false, percent: null });
28
35
  /** A whole number from 1 to 99 written as plain digits, else null. */
29
36
  export function parsePercent(raw) {
30
37
  const text = raw?.trim() ?? "";
@@ -61,7 +68,7 @@ export function readSmallFile(path) {
61
68
  closeSync(fd);
62
69
  }
63
70
  }
64
- /** The stored choice; a missing, malformed or hand-edited file reads as "off, no percent". */
71
+ /** The stored choice; a missing file reads as the default (on), a malformed or hand-edited one as "off, no percent". */
65
72
  export function readStoredAutoHandoff(repoRoot) {
66
73
  if (!isAbsolute(repoRoot))
67
74
  return { stored: DEFAULT_STORED, warning: null };
@@ -80,7 +87,7 @@ export function readStoredAutoHandoff(repoRoot) {
80
87
  }
81
88
  catch {
82
89
  return {
83
- stored: DEFAULT_STORED,
90
+ stored: UNREADABLE_STORED,
84
91
  warning: `${AUTO_HANDOFF_DIR}/${AUTO_HANDOFF_SETTINGS_FILE} could not be read, so automatic handoff stays off.`,
85
92
  };
86
93
  }
@@ -92,7 +99,7 @@ function shown(raw) {
92
99
  /**
93
100
  * Combine the environment with the stored choice. The environment wins when it is set: `=1` turns the
94
101
  * feature on and `=0` turns it off. The percent comes from its variable first, then from the stored
95
- * value. Nothing is active without a valid percent.
102
+ * value, then from the default. An invalid percent variable keeps the feature off.
96
103
  */
97
104
  export function resolveAutoHandoff(env, stored, storedWarning = null) {
98
105
  const warnings = [];
@@ -110,11 +117,13 @@ export function resolveAutoHandoff(env, stored, storedWarning = null) {
110
117
  if (envPercentInvalid) {
111
118
  warnings.push(`${AUTO_HANDOFF_PERCENT_ENV}=${shown(rawPercent)} is not a whole number from 1 to 99, so automatic handoff stays off.`);
112
119
  }
113
- const percent = envPercentInvalid ? null : (envPercent ?? stored.percent);
114
- const source = envDecision !== null || envPercent !== null ? "environment" : enabled ? "command" : "default";
115
- if (enabled && !envPercentInvalid && percent === null) {
116
- warnings.push(`Automatic handoff is on but has no percent. Run "lit-handoff auto on <percent>" or set ${AUTO_HANDOFF_PERCENT_ENV}.`);
117
- }
120
+ const fallback = enabled ? DEFAULT_AUTO_HANDOFF_PERCENT : null;
121
+ const percent = envPercentInvalid ? null : (envPercent ?? stored.percent ?? fallback);
122
+ let source = "command";
123
+ if (envDecision !== null || envPercent !== null)
124
+ source = "environment";
125
+ else if (enabled && stored.percent === null)
126
+ source = "default";
118
127
  return { active: enabled && percent !== null, percent, source, warnings };
119
128
  }
120
129
  export function loadAutoHandoffState(repoRoot, env) {
@@ -315,13 +324,17 @@ export function removeProjectCompaction(repoRoot) {
315
324
  }
316
325
  /**
317
326
  * Remove the managed block when the feature is effectively off, however it got there: `lit-handoff auto
318
- * off`, `LITCODEX_AUTO_HANDOFF=0`, a deleted settings file, or a percent that is not valid. Without this the
319
- * block outlives the switch and Codex keeps compacting at that percent with no handoff. Only the marked
327
+ * off`, `LITCODEX_AUTO_HANDOFF=0`, or a percent that is not valid. A deleted settings file puts the feature
328
+ * back on its default percent, which the block no longer matches, so it goes too. Without this the block
329
+ * outlives the switch and Codex keeps compacting at that percent with no handoff. Only the marked
320
330
  * block goes; a key the user wrote by hand is never touched. Never throws.
321
331
  */
322
332
  export function clearManagedCompactionWhenOff(repoRoot, env) {
323
333
  try {
324
- if (!isAbsolute(repoRoot) || loadAutoHandoffState(repoRoot, env).active)
334
+ if (!isAbsolute(repoRoot))
335
+ return "nothing-to-remove";
336
+ const state = loadAutoHandoffState(repoRoot, env);
337
+ if (state.active && state.source !== "default")
325
338
  return "nothing-to-remove";
326
339
  return removeProjectCompaction(repoRoot);
327
340
  }
@@ -354,8 +367,14 @@ function compactionSentence(repoRoot, percent, env) {
354
367
  export function describeAutoHandoff(repoRoot, state, env) {
355
368
  const lines = [];
356
369
  if (state.active && state.percent !== null) {
357
- const origin = state.source === "environment" ? "set by environment variables" : "set by command";
370
+ const origin = state.source === "environment"
371
+ ? "set by environment variables"
372
+ : state.source === "default"
373
+ ? "default"
374
+ : "set by command";
358
375
  lines.push(`Automatic handoff is ON at ${state.percent}% (${origin}).`);
376
+ if (state.source === "default")
377
+ lines.push('Run "lit-handoff auto off" to turn it off.');
359
378
  lines.push(compactionSentence(repoRoot, state.percent, env));
360
379
  }
361
380
  else {
@@ -388,10 +407,7 @@ export function applyAutoHandoffRoute(repoRoot, env, route) {
388
407
  const kept = stored.percent === null ? "" : ` Your last percent (${stored.percent}%) is kept for next time.`;
389
408
  return `Automatic handoff is OFF.${kept}${envNote}`;
390
409
  }
391
- const percent = route.argument === null ? stored.percent : parsePercent(route.argument);
392
- if (route.argument === null && percent === null) {
393
- return "Which percent should trigger the handoff? Run: lit-handoff auto on <percent from 1 to 99> (for example 60).";
394
- }
410
+ const percent = route.argument === null ? (stored.percent ?? DEFAULT_AUTO_HANDOFF_PERCENT) : parsePercent(route.argument);
395
411
  if (percent === null)
396
412
  return `"${shown(route.argument ?? "")}" is not a whole number from 1 to 99. Nothing changed.`;
397
413
  if (!writeStoredAutoHandoff(repoRoot, { enabled: true, percent })) {
@@ -3,9 +3,9 @@
3
3
  // The flow across Codex hooks, each step reading and writing one small per-session record under
4
4
  // `.litcodex/auto-handoff/<session>.json`:
5
5
  //
6
- // Stop reads the context percent from the session transcript. At or above the user's
7
- // percent, once per crossing, it blocks the stop with an instruction to write the
8
- // handoff now and to tell the user one plain line.
6
+ // Stop reads the context percent from the session transcript. At or above the percent in
7
+ // force (the user's, else the default), once per crossing, it blocks the stop with an
8
+ // instruction to write the handoff now and to tell the user one plain line.
9
9
  // PostCompact marks the session as compacted (Codex compacts after the handoff turn when the
10
10
  // project config asks for it, or the user runs /compact).
11
11
  // SessionStart source "compact" (compaction inside a turn) and the next UserPromptSubmit (compaction
@@ -145,7 +145,7 @@ function percentText(value) {
145
145
  export function buildHandoffInstruction(sessionId, percent, threshold, hostCompacts) {
146
146
  const line = hostCompacts ? SAVED_LINE_HOST_COMPACTS : SAVED_LINE_RUN_COMPACT;
147
147
  return [
148
- `Automatic handoff: this conversation has used ${percentText(percent)}% of the context window, past the ${threshold}% the user chose.`,
148
+ `Automatic handoff: this conversation has used ${percentText(percent)}% of the context window, past the ${threshold}% set for automatic handoff.`,
149
149
  "Save the handoff now, before anything else:",
150
150
  `1. Read ${resolveSkillPath("lit-handoff")} in full and follow it to create or refresh the handoff file. Its destination rules pick the file.`,
151
151
  `2. Put this exact line in the handoff file so the next context can find it: ${HANDOFF_MARKER_LABEL} ${sessionId}`,
@@ -176,8 +176,10 @@ export function evaluateAutoHandoffStop(input) {
176
176
  return PASS;
177
177
  if (reading.percent < state.percent) {
178
178
  if (session.phase === "idle" || session.phase === "compacted") {
179
- if (session.lastPercent !== seen.lastPercent)
179
+ // On the default alone nothing is written below the percent, so a project that never gets there stays untouched.
180
+ if (session.lastPercent !== seen.lastPercent && state.source !== "default") {
180
181
  writeSession(input.repoRoot, path, seen);
182
+ }
181
183
  return PASS;
182
184
  }
183
185
  writeSession(input.repoRoot, path, { ...seen, phase: "idle", firedAt: null, firedPercent: null });
@@ -18,6 +18,7 @@ import { detectWaitReason, endLiveStep, recordLiveStepEnd, recordLiveStepStart,
18
18
  import { evaluatePlanPersistence, formatStopBlockOutput, rearmLitPlanIfSatisfied, recordLitPlanActivation, } from "./plan-persistence.js";
19
19
  import { clearActiveRoute, isBareLit, isLitContinue, readActiveRoute, readResumeWork, recordActiveRoute, } from "./reentry.js";
20
20
  import { isBoundaryAnswer, isGoPrompt, takeGo } from "./rewind-go.js";
21
+ import { outcomeFor, recordRunEnd } from "./run-end.js";
21
22
  import { workflowCard } from "./screen-card.js";
22
23
  import { screenColor } from "./screen-status.js";
23
24
  import { recordLiveness } from "./session-liveness.js";
@@ -390,6 +391,12 @@ export async function runStopPlanPersistenceHookCli(stdin, stdout, stderr, repoR
390
391
  : null;
391
392
  const turn = line === null ? null : workflowTurn(scope.cwd, scope.sessionId);
392
393
  const card = turn === null ? null : workflowCard(scope.cwd, scope.sessionId, turn.mode, line, { color: screenColor(env) });
394
+ // The end of a LIT run: remember whether it reported, had nothing to report, or waits on the user.
395
+ const opened = workflowTurn(scope.cwd, scope.sessionId);
396
+ const outcome = opened === null ? null : outcomeFor(line, detectWaitReason(lastMsg));
397
+ if (opened !== null && outcome !== null) {
398
+ recordRunEnd(scope.cwd, scope.sessionId, { mode: opened.mode, outcome }, auto.now);
399
+ }
393
400
  // Codex puts a hook label before the first row, so the card starts on the next one.
394
401
  if (card !== null)
395
402
  stdout.write(`${JSON.stringify({ systemMessage: `\n${card}` })}\n`);
@@ -0,0 +1,22 @@
1
+ export type RunOutcome = "sent" | "nothing" | "waiting";
2
+ export interface RunEnd {
3
+ readonly version: 1;
4
+ readonly at: number;
5
+ readonly session: string;
6
+ readonly mode: string;
7
+ readonly outcome: RunOutcome;
8
+ }
9
+ export declare function runEndPath(repoRoot: string): string;
10
+ /**
11
+ * The outcome for a turn that just closed, or null when the run is not over. `line` is the Stop line
12
+ * `workflowStopLine` made for the recorded turn (null when it made none) and `waitReason` what
13
+ * `detectWaitReason` read from the last assistant message.
14
+ */
15
+ export declare function outcomeFor(line: string | null, waitReason: string | null): RunOutcome | null;
16
+ /** Append one run end. Never throws. */
17
+ export declare function recordRunEnd(repoRoot: string, sessionId: string, entry: {
18
+ readonly mode: string;
19
+ readonly outcome: RunOutcome;
20
+ }, now?: number): void;
21
+ /** Every well-formed run end, oldest first; a corrupt line is skipped and an unreadable file reads as empty. */
22
+ export declare function readRunEnds(repoRoot: string): RunEnd[];
@@ -0,0 +1,93 @@
1
+ // src/run-end.ts — how each LIT run ended: `sent`, `nothing` or `waiting`.
2
+ //
3
+ // The lit-loop Stop hook is the run-end point of a LIT thread: the turn that ignited a LIT skill closes there. It
4
+ // then leaves one line in `.litcodex/run-end/outcomes.jsonl`:
5
+ //
6
+ // sent the turn closed with its summary card, the report LitCodex itself prints
7
+ // waiting the last assistant message asks the user something or reports BLOCKED, so the run waits on a person
8
+ // nothing the Stop has no card to print for the recorded turn
9
+ //
10
+ // A Stop that start-work keeps running (the `⏳ … continuing` line) is not an end and writes nothing, and a
11
+ // session that never ignited LIT writes nothing, so other projects get no `.litcodex` folder. The record is
12
+ // append-only, capped, never written through a symlink, and every failure is silent: the Stop output is the same
13
+ // with or without it.
14
+ import { appendFileSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
15
+ import { join } from "node:path";
16
+ import { plainDirsOrMissing, writeFileAtomic } from "./live-step.js";
17
+ import { normalizeSessionId } from "./state-paths.js";
18
+ import { CONTINUING_MARK } from "./workflow-map.js";
19
+ const RUN_END_DIR = ".litcodex/run-end";
20
+ const RUN_END_FILE = "outcomes.jsonl";
21
+ /** Past this the oldest lines are dropped before the next one is appended. */
22
+ const MAX_BYTES = 32 * 1024;
23
+ const KEEP_LINES = 100;
24
+ const OUTCOMES = ["sent", "nothing", "waiting"];
25
+ export function runEndPath(repoRoot) {
26
+ return join(repoRoot, RUN_END_DIR, RUN_END_FILE);
27
+ }
28
+ /**
29
+ * The outcome for a turn that just closed, or null when the run is not over. `line` is the Stop line
30
+ * `workflowStopLine` made for the recorded turn (null when it made none) and `waitReason` what
31
+ * `detectWaitReason` read from the last assistant message.
32
+ */
33
+ export function outcomeFor(line, waitReason) {
34
+ if (line?.startsWith(CONTINUING_MARK) === true)
35
+ return null;
36
+ if (waitReason !== null)
37
+ return "waiting";
38
+ return line === null ? "nothing" : "sent";
39
+ }
40
+ /** Append one run end. Never throws. */
41
+ export function recordRunEnd(repoRoot, sessionId, entry, now = Date.now()) {
42
+ try {
43
+ const session = normalizeSessionId(sessionId);
44
+ if (session === null || !plainDirsOrMissing(repoRoot, RUN_END_DIR))
45
+ return;
46
+ const path = runEndPath(repoRoot);
47
+ const existing = lstatSync(path, { throwIfNoEntry: false });
48
+ if (existing !== undefined && !existing.isFile())
49
+ return;
50
+ mkdirSync(join(repoRoot, RUN_END_DIR), { recursive: true });
51
+ if (existing !== undefined && existing.size >= MAX_BYTES) {
52
+ const kept = readFileSync(path, "utf8").split("\n").filter(Boolean).slice(-KEEP_LINES);
53
+ writeFileAtomic(path, `${kept.join("\n")}\n`);
54
+ }
55
+ const line = { version: 1, at: now, session, mode: entry.mode, outcome: entry.outcome };
56
+ appendFileSync(path, `${JSON.stringify(line)}\n`);
57
+ }
58
+ catch {
59
+ // The Stop output does not depend on this record.
60
+ }
61
+ }
62
+ /** Every well-formed run end, oldest first; a corrupt line is skipped and an unreadable file reads as empty. */
63
+ export function readRunEnds(repoRoot) {
64
+ try {
65
+ const path = runEndPath(repoRoot);
66
+ const stat = lstatSync(path, { throwIfNoEntry: false });
67
+ if (stat === undefined || !stat.isFile() || stat.size > 4 * MAX_BYTES)
68
+ return [];
69
+ const ends = [];
70
+ for (const line of readFileSync(path, "utf8").split("\n")) {
71
+ try {
72
+ const entry = JSON.parse(line);
73
+ if (typeof entry === "object" &&
74
+ entry !== null &&
75
+ entry["version"] === 1 &&
76
+ typeof entry["at"] === "number" &&
77
+ typeof entry["session"] === "string" &&
78
+ typeof entry["mode"] === "string" &&
79
+ typeof entry["outcome"] === "string" &&
80
+ OUTCOMES.includes(entry["outcome"])) {
81
+ ends.push(entry);
82
+ }
83
+ }
84
+ catch {
85
+ // a corrupt line is skipped
86
+ }
87
+ }
88
+ return ends;
89
+ }
90
+ catch {
91
+ return [];
92
+ }
93
+ }
@@ -87,6 +87,8 @@ export declare function workflowTurn(repoRoot: string, sessionId: string): {
87
87
  mode: string;
88
88
  startedAt: number;
89
89
  } | null;
90
+ /** The Stop line of a turn that start-work keeps running starts with this mark; it is not the end of the run. */
91
+ export declare const CONTINUING_MARK = "\u23F3";
90
92
  /**
91
93
  * The Stop line for a LIT turn, or null when this turn was not a LIT activation. At a start-work
92
94
  * checkpoint the continuation hook keeps the turn going, so the line says so instead of "turn done".
@@ -592,6 +592,8 @@ function continuingWork(repoRoot, sessionId, turnId, stop) {
592
592
  return null;
593
593
  return { done, total: rows.length, next: rows.find((row) => !row.done)?.label ?? null };
594
594
  }
595
+ /** The Stop line of a turn that start-work keeps running starts with this mark; it is not the end of the run. */
596
+ export const CONTINUING_MARK = "⏳";
595
597
  function counted(n, unit) {
596
598
  return `${n} ${unit}${n === 1 ? "" : "s"} ✓`;
597
599
  }
@@ -610,7 +612,7 @@ export function workflowStopLine(repoRoot, sessionId, turnId, stop = NO_STOP_CON
610
612
  const continuing = continuingWork(repoRoot, sessionId, turnId, stop);
611
613
  if (continuing !== null) {
612
614
  const next = continuing.next === null ? null : safeTitle(continuing.next);
613
- const status = `⏳ ${continuing.done}/${continuing.total} tasks ✓ · continuing`;
615
+ const status = `${CONTINUING_MARK} ${continuing.done}/${continuing.total} tasks ✓ · continuing`;
614
616
  return next === null ? status : `${status} ▸ ${next}`;
615
617
  }
616
618
  const signals = readWorkflowSignals(repoRoot, sessionId);
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/lit-loop",
3
- "version": "1.0.40",
3
+ "version": "1.0.41",
4
4
  "description": "LitCodex Lit-Loop runtime: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/lsp",
3
- "version": "1.0.40",
3
+ "version": "1.0.41",
4
4
  "description": "LitCodex LSP hook (inert placeholder): post-edit diagnostics + cache reset, no-op until an LSP daemon is provided.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/rules",
3
- "version": "1.0.40",
3
+ "version": "1.0.41",
4
4
  "description": "LitCodex rules: injects project rule files (AGENTS.md etc.) into model context through lifecycle hooks.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/start-work-continuation",
3
- "version": "1.0.40",
3
+ "version": "1.0.41",
4
4
  "description": "LitCodex Start-Work continuation hook: resumes in-flight start-work state on root Stop.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/telemetry",
3
- "version": "1.0.40",
3
+ "version": "1.0.41",
4
4
  "description": "LitCodex telemetry: a deliberately inert, local-only SessionStart hook (NO network, NO data collection).",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/wikify-knowledge",
3
- "version": "1.0.40",
3
+ "version": "1.0.41",
4
4
  "description": "Local review-gated knowledge records for the LitCodex Wikify surface.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -28,10 +28,10 @@ lit-typographic-motion stub without holding the turn.
28
28
 
29
29
  ## Automatic handoff
30
30
 
31
- This component also carries the opt-in automatic handoff (off by default). The exact prompt
32
- `lit-handoff auto on <percent>` (or `off`, `status`) sets it without reaching the model. The Stop hook then
33
- reads the context percent from the session transcript and, once per crossing, asks the model to save a
34
- handoff. The PostCompact hook, the SessionStart hook (source `compact`) and the next prompt bring the fresh
31
+ This component also carries the automatic handoff, on by default at 80% of the context window. The exact prompt
32
+ `lit-handoff auto off` turns it off, and `lit-handoff auto on <percent>` (or `status`) changes or shows it without
33
+ reaching the model. The Stop hook reads the context percent from the session transcript and, once per crossing,
34
+ asks the model to save a handoff. The PostCompact hook, the SessionStart hook (source `compact`) and the next prompt bring the fresh
35
35
  handoff back once. `src/auto-handoff-settings.ts` holds the switch and the project `.codex/config.toml`
36
36
  line, `src/auto-handoff.ts` holds the crossing and reload logic, and the
37
37
  [automatic handoff page](../../../../docs/auto-handoff.md) explains it for users.
@@ -2,6 +2,8 @@ export declare const AUTO_HANDOFF_FLAG_ENV = "LITCODEX_AUTO_HANDOFF";
2
2
  export declare const AUTO_HANDOFF_PERCENT_ENV = "LITCODEX_AUTO_HANDOFF_PERCENT";
3
3
  export declare const AUTO_HANDOFF_DIR = ".litcodex/auto-handoff";
4
4
  export declare const AUTO_HANDOFF_SETTINGS_FILE = "settings.json";
5
+ /** Chosen below Codex's own automatic compaction point, so the handoff is written before the host compacts. */
6
+ export declare const DEFAULT_AUTO_HANDOFF_PERCENT = 80;
5
7
  export declare const HOST_COMPACT_KEY = "model_post_turn_compact_threshold_percent";
6
8
  export declare const HOST_COMPACT_BEGIN = "# litcodex automatic handoff (managed by `lit-handoff auto`; `lit-handoff auto off` removes it)";
7
9
  export interface StoredAutoHandoff {
@@ -24,7 +26,7 @@ export declare function parsePercent(raw: string | undefined): number | null;
24
26
  export declare function settingsPath(repoRoot: string): string;
25
27
  /** Read a small regular file; null when missing, a symlink, too large, or unreadable. */
26
28
  export declare function readSmallFile(path: string): string | null;
27
- /** The stored choice; a missing, malformed or hand-edited file reads as "off, no percent". */
29
+ /** The stored choice; a missing file reads as the default (on), a malformed or hand-edited one as "off, no percent". */
28
30
  export declare function readStoredAutoHandoff(repoRoot: string): {
29
31
  stored: StoredAutoHandoff;
30
32
  warning: string | null;
@@ -32,7 +34,7 @@ export declare function readStoredAutoHandoff(repoRoot: string): {
32
34
  /**
33
35
  * Combine the environment with the stored choice. The environment wins when it is set: `=1` turns the
34
36
  * feature on and `=0` turns it off. The percent comes from its variable first, then from the stored
35
- * value. Nothing is active without a valid percent.
37
+ * value, then from the default. An invalid percent variable keeps the feature off.
36
38
  */
37
39
  export declare function resolveAutoHandoff(env: NodeJS.ProcessEnv, stored: StoredAutoHandoff, storedWarning?: string | null): AutoHandoffState;
38
40
  export declare function loadAutoHandoffState(repoRoot: string, env: NodeJS.ProcessEnv): AutoHandoffState;
@@ -65,8 +67,9 @@ export declare function writeProjectCompaction(repoRoot: string, percent: number
65
67
  export declare function removeProjectCompaction(repoRoot: string): ProjectConfigResult;
66
68
  /**
67
69
  * Remove the managed block when the feature is effectively off, however it got there: `lit-handoff auto
68
- * off`, `LITCODEX_AUTO_HANDOFF=0`, a deleted settings file, or a percent that is not valid. Without this the
69
- * block outlives the switch and Codex keeps compacting at that percent with no handoff. Only the marked
70
+ * off`, `LITCODEX_AUTO_HANDOFF=0`, or a percent that is not valid. A deleted settings file puts the feature
71
+ * back on its default percent, which the block no longer matches, so it goes too. Without this the block
72
+ * outlives the switch and Codex keeps compacting at that percent with no handoff. Only the marked
70
73
  * block goes; a key the user wrote by hand is never touched. Never throws.
71
74
  */
72
75
  export declare function clearManagedCompactionWhenOff(repoRoot: string, env: NodeJS.ProcessEnv): ProjectConfigResult;
@@ -1,10 +1,12 @@
1
1
  // src/auto-handoff-settings.ts — the user-controlled switch for automatic handoff.
2
2
  //
3
- // Off by default. The user turns it on with the exact prompt `lit-handoff auto on <percent>` (or sets
4
- // `LITCODEX_AUTO_HANDOFF=1` plus `LITCODEX_AUTO_HANDOFF_PERCENT`), turns it off with
5
- // `lit-handoff auto off`, and reads the state with `lit-handoff auto status`. The percent is never
6
- // hard-coded: `on` without a number reuses the last value the user stored and asks for one when there
7
- // is none. A percent that is not a whole number from 1 to 99 keeps the feature off and is reported.
3
+ // On by default at DEFAULT_AUTO_HANDOFF_PERCENT of the context window, so a long conversation saves its
4
+ // handoff before it is compacted without anyone setting anything up. The one off switch is the exact prompt
5
+ // `lit-handoff auto off` (or `LITCODEX_AUTO_HANDOFF=0`); `lit-handoff auto on <percent>` (or
6
+ // `LITCODEX_AUTO_HANDOFF=1` plus `LITCODEX_AUTO_HANDOFF_PERCENT`) chooses another percent, and
7
+ // `lit-handoff auto status` reads the state. `on` without a number reuses the last value the user stored,
8
+ // else the default. A percent that is not a whole number from 1 to 99 keeps the feature off and is reported,
9
+ // and so does a settings file that cannot be read: the user's choice is unknown, so nothing is assumed.
8
10
  //
9
11
  // Command-set values live in `.litcodex/auto-handoff/settings.json` under the project folder. When the
10
12
  // feature is turned on by command, the same percent is written to the PROJECT `.codex/config.toml` as
@@ -20,11 +22,16 @@ export const AUTO_HANDOFF_FLAG_ENV = "LITCODEX_AUTO_HANDOFF";
20
22
  export const AUTO_HANDOFF_PERCENT_ENV = "LITCODEX_AUTO_HANDOFF_PERCENT";
21
23
  export const AUTO_HANDOFF_DIR = ".litcodex/auto-handoff";
22
24
  export const AUTO_HANDOFF_SETTINGS_FILE = "settings.json";
25
+ /** Chosen below Codex's own automatic compaction point, so the handoff is written before the host compacts. */
26
+ export const DEFAULT_AUTO_HANDOFF_PERCENT = 80;
23
27
  export const HOST_COMPACT_KEY = "model_post_turn_compact_threshold_percent";
24
28
  export const HOST_COMPACT_BEGIN = "# litcodex automatic handoff (managed by `lit-handoff auto`; `lit-handoff auto off` removes it)";
25
29
  const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
26
30
  const MAX_FILE_BYTES = 256 * 1024;
27
- const DEFAULT_STORED = Object.freeze({ enabled: false, percent: null });
31
+ /** No settings file: the product default. */
32
+ const DEFAULT_STORED = Object.freeze({ enabled: true, percent: null });
33
+ /** A settings file that cannot be read: the user's choice is unknown, so the feature stays off. */
34
+ const UNREADABLE_STORED = Object.freeze({ enabled: false, percent: null });
28
35
  /** A whole number from 1 to 99 written as plain digits, else null. */
29
36
  export function parsePercent(raw) {
30
37
  const text = raw?.trim() ?? "";
@@ -61,7 +68,7 @@ export function readSmallFile(path) {
61
68
  closeSync(fd);
62
69
  }
63
70
  }
64
- /** The stored choice; a missing, malformed or hand-edited file reads as "off, no percent". */
71
+ /** The stored choice; a missing file reads as the default (on), a malformed or hand-edited one as "off, no percent". */
65
72
  export function readStoredAutoHandoff(repoRoot) {
66
73
  if (!isAbsolute(repoRoot))
67
74
  return { stored: DEFAULT_STORED, warning: null };
@@ -80,7 +87,7 @@ export function readStoredAutoHandoff(repoRoot) {
80
87
  }
81
88
  catch {
82
89
  return {
83
- stored: DEFAULT_STORED,
90
+ stored: UNREADABLE_STORED,
84
91
  warning: `${AUTO_HANDOFF_DIR}/${AUTO_HANDOFF_SETTINGS_FILE} could not be read, so automatic handoff stays off.`,
85
92
  };
86
93
  }
@@ -92,7 +99,7 @@ function shown(raw) {
92
99
  /**
93
100
  * Combine the environment with the stored choice. The environment wins when it is set: `=1` turns the
94
101
  * feature on and `=0` turns it off. The percent comes from its variable first, then from the stored
95
- * value. Nothing is active without a valid percent.
102
+ * value, then from the default. An invalid percent variable keeps the feature off.
96
103
  */
97
104
  export function resolveAutoHandoff(env, stored, storedWarning = null) {
98
105
  const warnings = [];
@@ -110,11 +117,13 @@ export function resolveAutoHandoff(env, stored, storedWarning = null) {
110
117
  if (envPercentInvalid) {
111
118
  warnings.push(`${AUTO_HANDOFF_PERCENT_ENV}=${shown(rawPercent)} is not a whole number from 1 to 99, so automatic handoff stays off.`);
112
119
  }
113
- const percent = envPercentInvalid ? null : (envPercent ?? stored.percent);
114
- const source = envDecision !== null || envPercent !== null ? "environment" : enabled ? "command" : "default";
115
- if (enabled && !envPercentInvalid && percent === null) {
116
- warnings.push(`Automatic handoff is on but has no percent. Run "lit-handoff auto on <percent>" or set ${AUTO_HANDOFF_PERCENT_ENV}.`);
117
- }
120
+ const fallback = enabled ? DEFAULT_AUTO_HANDOFF_PERCENT : null;
121
+ const percent = envPercentInvalid ? null : (envPercent ?? stored.percent ?? fallback);
122
+ let source = "command";
123
+ if (envDecision !== null || envPercent !== null)
124
+ source = "environment";
125
+ else if (enabled && stored.percent === null)
126
+ source = "default";
118
127
  return { active: enabled && percent !== null, percent, source, warnings };
119
128
  }
120
129
  export function loadAutoHandoffState(repoRoot, env) {
@@ -315,13 +324,17 @@ export function removeProjectCompaction(repoRoot) {
315
324
  }
316
325
  /**
317
326
  * Remove the managed block when the feature is effectively off, however it got there: `lit-handoff auto
318
- * off`, `LITCODEX_AUTO_HANDOFF=0`, a deleted settings file, or a percent that is not valid. Without this the
319
- * block outlives the switch and Codex keeps compacting at that percent with no handoff. Only the marked
327
+ * off`, `LITCODEX_AUTO_HANDOFF=0`, or a percent that is not valid. A deleted settings file puts the feature
328
+ * back on its default percent, which the block no longer matches, so it goes too. Without this the block
329
+ * outlives the switch and Codex keeps compacting at that percent with no handoff. Only the marked
320
330
  * block goes; a key the user wrote by hand is never touched. Never throws.
321
331
  */
322
332
  export function clearManagedCompactionWhenOff(repoRoot, env) {
323
333
  try {
324
- if (!isAbsolute(repoRoot) || loadAutoHandoffState(repoRoot, env).active)
334
+ if (!isAbsolute(repoRoot))
335
+ return "nothing-to-remove";
336
+ const state = loadAutoHandoffState(repoRoot, env);
337
+ if (state.active && state.source !== "default")
325
338
  return "nothing-to-remove";
326
339
  return removeProjectCompaction(repoRoot);
327
340
  }
@@ -354,8 +367,14 @@ function compactionSentence(repoRoot, percent, env) {
354
367
  export function describeAutoHandoff(repoRoot, state, env) {
355
368
  const lines = [];
356
369
  if (state.active && state.percent !== null) {
357
- const origin = state.source === "environment" ? "set by environment variables" : "set by command";
370
+ const origin = state.source === "environment"
371
+ ? "set by environment variables"
372
+ : state.source === "default"
373
+ ? "default"
374
+ : "set by command";
358
375
  lines.push(`Automatic handoff is ON at ${state.percent}% (${origin}).`);
376
+ if (state.source === "default")
377
+ lines.push('Run "lit-handoff auto off" to turn it off.');
359
378
  lines.push(compactionSentence(repoRoot, state.percent, env));
360
379
  }
361
380
  else {
@@ -388,10 +407,7 @@ export function applyAutoHandoffRoute(repoRoot, env, route) {
388
407
  const kept = stored.percent === null ? "" : ` Your last percent (${stored.percent}%) is kept for next time.`;
389
408
  return `Automatic handoff is OFF.${kept}${envNote}`;
390
409
  }
391
- const percent = route.argument === null ? stored.percent : parsePercent(route.argument);
392
- if (route.argument === null && percent === null) {
393
- return "Which percent should trigger the handoff? Run: lit-handoff auto on <percent from 1 to 99> (for example 60).";
394
- }
410
+ const percent = route.argument === null ? (stored.percent ?? DEFAULT_AUTO_HANDOFF_PERCENT) : parsePercent(route.argument);
395
411
  if (percent === null)
396
412
  return `"${shown(route.argument ?? "")}" is not a whole number from 1 to 99. Nothing changed.`;
397
413
  if (!writeStoredAutoHandoff(repoRoot, { enabled: true, percent })) {
@@ -3,9 +3,9 @@
3
3
  // The flow across Codex hooks, each step reading and writing one small per-session record under
4
4
  // `.litcodex/auto-handoff/<session>.json`:
5
5
  //
6
- // Stop reads the context percent from the session transcript. At or above the user's
7
- // percent, once per crossing, it blocks the stop with an instruction to write the
8
- // handoff now and to tell the user one plain line.
6
+ // Stop reads the context percent from the session transcript. At or above the percent in
7
+ // force (the user's, else the default), once per crossing, it blocks the stop with an
8
+ // instruction to write the handoff now and to tell the user one plain line.
9
9
  // PostCompact marks the session as compacted (Codex compacts after the handoff turn when the
10
10
  // project config asks for it, or the user runs /compact).
11
11
  // SessionStart source "compact" (compaction inside a turn) and the next UserPromptSubmit (compaction
@@ -145,7 +145,7 @@ function percentText(value) {
145
145
  export function buildHandoffInstruction(sessionId, percent, threshold, hostCompacts) {
146
146
  const line = hostCompacts ? SAVED_LINE_HOST_COMPACTS : SAVED_LINE_RUN_COMPACT;
147
147
  return [
148
- `Automatic handoff: this conversation has used ${percentText(percent)}% of the context window, past the ${threshold}% the user chose.`,
148
+ `Automatic handoff: this conversation has used ${percentText(percent)}% of the context window, past the ${threshold}% set for automatic handoff.`,
149
149
  "Save the handoff now, before anything else:",
150
150
  `1. Read ${resolveSkillPath("lit-handoff")} in full and follow it to create or refresh the handoff file. Its destination rules pick the file.`,
151
151
  `2. Put this exact line in the handoff file so the next context can find it: ${HANDOFF_MARKER_LABEL} ${sessionId}`,
@@ -176,8 +176,10 @@ export function evaluateAutoHandoffStop(input) {
176
176
  return PASS;
177
177
  if (reading.percent < state.percent) {
178
178
  if (session.phase === "idle" || session.phase === "compacted") {
179
- if (session.lastPercent !== seen.lastPercent)
179
+ // On the default alone nothing is written below the percent, so a project that never gets there stays untouched.
180
+ if (session.lastPercent !== seen.lastPercent && state.source !== "default") {
180
181
  writeSession(input.repoRoot, path, seen);
182
+ }
181
183
  return PASS;
182
184
  }
183
185
  writeSession(input.repoRoot, path, { ...seen, phase: "idle", firedAt: null, firedPercent: null });
@@ -18,6 +18,7 @@ import { detectWaitReason, endLiveStep, recordLiveStepEnd, recordLiveStepStart,
18
18
  import { evaluatePlanPersistence, formatStopBlockOutput, rearmLitPlanIfSatisfied, recordLitPlanActivation, } from "./plan-persistence.js";
19
19
  import { clearActiveRoute, isBareLit, isLitContinue, readActiveRoute, readResumeWork, recordActiveRoute, } from "./reentry.js";
20
20
  import { isBoundaryAnswer, isGoPrompt, takeGo } from "./rewind-go.js";
21
+ import { outcomeFor, recordRunEnd } from "./run-end.js";
21
22
  import { workflowCard } from "./screen-card.js";
22
23
  import { screenColor } from "./screen-status.js";
23
24
  import { recordLiveness } from "./session-liveness.js";
@@ -390,6 +391,12 @@ export async function runStopPlanPersistenceHookCli(stdin, stdout, stderr, repoR
390
391
  : null;
391
392
  const turn = line === null ? null : workflowTurn(scope.cwd, scope.sessionId);
392
393
  const card = turn === null ? null : workflowCard(scope.cwd, scope.sessionId, turn.mode, line, { color: screenColor(env) });
394
+ // The end of a LIT run: remember whether it reported, had nothing to report, or waits on the user.
395
+ const opened = workflowTurn(scope.cwd, scope.sessionId);
396
+ const outcome = opened === null ? null : outcomeFor(line, detectWaitReason(lastMsg));
397
+ if (opened !== null && outcome !== null) {
398
+ recordRunEnd(scope.cwd, scope.sessionId, { mode: opened.mode, outcome }, auto.now);
399
+ }
393
400
  // Codex puts a hook label before the first row, so the card starts on the next one.
394
401
  if (card !== null)
395
402
  stdout.write(`${JSON.stringify({ systemMessage: `\n${card}` })}\n`);
@@ -0,0 +1,22 @@
1
+ export type RunOutcome = "sent" | "nothing" | "waiting";
2
+ export interface RunEnd {
3
+ readonly version: 1;
4
+ readonly at: number;
5
+ readonly session: string;
6
+ readonly mode: string;
7
+ readonly outcome: RunOutcome;
8
+ }
9
+ export declare function runEndPath(repoRoot: string): string;
10
+ /**
11
+ * The outcome for a turn that just closed, or null when the run is not over. `line` is the Stop line
12
+ * `workflowStopLine` made for the recorded turn (null when it made none) and `waitReason` what
13
+ * `detectWaitReason` read from the last assistant message.
14
+ */
15
+ export declare function outcomeFor(line: string | null, waitReason: string | null): RunOutcome | null;
16
+ /** Append one run end. Never throws. */
17
+ export declare function recordRunEnd(repoRoot: string, sessionId: string, entry: {
18
+ readonly mode: string;
19
+ readonly outcome: RunOutcome;
20
+ }, now?: number): void;
21
+ /** Every well-formed run end, oldest first; a corrupt line is skipped and an unreadable file reads as empty. */
22
+ export declare function readRunEnds(repoRoot: string): RunEnd[];
@@ -0,0 +1,93 @@
1
+ // src/run-end.ts — how each LIT run ended: `sent`, `nothing` or `waiting`.
2
+ //
3
+ // The lit-loop Stop hook is the run-end point of a LIT thread: the turn that ignited a LIT skill closes there. It
4
+ // then leaves one line in `.litcodex/run-end/outcomes.jsonl`:
5
+ //
6
+ // sent the turn closed with its summary card, the report LitCodex itself prints
7
+ // waiting the last assistant message asks the user something or reports BLOCKED, so the run waits on a person
8
+ // nothing the Stop has no card to print for the recorded turn
9
+ //
10
+ // A Stop that start-work keeps running (the `⏳ … continuing` line) is not an end and writes nothing, and a
11
+ // session that never ignited LIT writes nothing, so other projects get no `.litcodex` folder. The record is
12
+ // append-only, capped, never written through a symlink, and every failure is silent: the Stop output is the same
13
+ // with or without it.
14
+ import { appendFileSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
15
+ import { join } from "node:path";
16
+ import { plainDirsOrMissing, writeFileAtomic } from "./live-step.js";
17
+ import { normalizeSessionId } from "./state-paths.js";
18
+ import { CONTINUING_MARK } from "./workflow-map.js";
19
+ const RUN_END_DIR = ".litcodex/run-end";
20
+ const RUN_END_FILE = "outcomes.jsonl";
21
+ /** Past this the oldest lines are dropped before the next one is appended. */
22
+ const MAX_BYTES = 32 * 1024;
23
+ const KEEP_LINES = 100;
24
+ const OUTCOMES = ["sent", "nothing", "waiting"];
25
+ export function runEndPath(repoRoot) {
26
+ return join(repoRoot, RUN_END_DIR, RUN_END_FILE);
27
+ }
28
+ /**
29
+ * The outcome for a turn that just closed, or null when the run is not over. `line` is the Stop line
30
+ * `workflowStopLine` made for the recorded turn (null when it made none) and `waitReason` what
31
+ * `detectWaitReason` read from the last assistant message.
32
+ */
33
+ export function outcomeFor(line, waitReason) {
34
+ if (line?.startsWith(CONTINUING_MARK) === true)
35
+ return null;
36
+ if (waitReason !== null)
37
+ return "waiting";
38
+ return line === null ? "nothing" : "sent";
39
+ }
40
+ /** Append one run end. Never throws. */
41
+ export function recordRunEnd(repoRoot, sessionId, entry, now = Date.now()) {
42
+ try {
43
+ const session = normalizeSessionId(sessionId);
44
+ if (session === null || !plainDirsOrMissing(repoRoot, RUN_END_DIR))
45
+ return;
46
+ const path = runEndPath(repoRoot);
47
+ const existing = lstatSync(path, { throwIfNoEntry: false });
48
+ if (existing !== undefined && !existing.isFile())
49
+ return;
50
+ mkdirSync(join(repoRoot, RUN_END_DIR), { recursive: true });
51
+ if (existing !== undefined && existing.size >= MAX_BYTES) {
52
+ const kept = readFileSync(path, "utf8").split("\n").filter(Boolean).slice(-KEEP_LINES);
53
+ writeFileAtomic(path, `${kept.join("\n")}\n`);
54
+ }
55
+ const line = { version: 1, at: now, session, mode: entry.mode, outcome: entry.outcome };
56
+ appendFileSync(path, `${JSON.stringify(line)}\n`);
57
+ }
58
+ catch {
59
+ // The Stop output does not depend on this record.
60
+ }
61
+ }
62
+ /** Every well-formed run end, oldest first; a corrupt line is skipped and an unreadable file reads as empty. */
63
+ export function readRunEnds(repoRoot) {
64
+ try {
65
+ const path = runEndPath(repoRoot);
66
+ const stat = lstatSync(path, { throwIfNoEntry: false });
67
+ if (stat === undefined || !stat.isFile() || stat.size > 4 * MAX_BYTES)
68
+ return [];
69
+ const ends = [];
70
+ for (const line of readFileSync(path, "utf8").split("\n")) {
71
+ try {
72
+ const entry = JSON.parse(line);
73
+ if (typeof entry === "object" &&
74
+ entry !== null &&
75
+ entry["version"] === 1 &&
76
+ typeof entry["at"] === "number" &&
77
+ typeof entry["session"] === "string" &&
78
+ typeof entry["mode"] === "string" &&
79
+ typeof entry["outcome"] === "string" &&
80
+ OUTCOMES.includes(entry["outcome"])) {
81
+ ends.push(entry);
82
+ }
83
+ }
84
+ catch {
85
+ // a corrupt line is skipped
86
+ }
87
+ }
88
+ return ends;
89
+ }
90
+ catch {
91
+ return [];
92
+ }
93
+ }
@@ -87,6 +87,8 @@ export declare function workflowTurn(repoRoot: string, sessionId: string): {
87
87
  mode: string;
88
88
  startedAt: number;
89
89
  } | null;
90
+ /** The Stop line of a turn that start-work keeps running starts with this mark; it is not the end of the run. */
91
+ export declare const CONTINUING_MARK = "\u23F3";
90
92
  /**
91
93
  * The Stop line for a LIT turn, or null when this turn was not a LIT activation. At a start-work
92
94
  * checkpoint the continuation hook keeps the turn going, so the line says so instead of "turn done".
@@ -592,6 +592,8 @@ function continuingWork(repoRoot, sessionId, turnId, stop) {
592
592
  return null;
593
593
  return { done, total: rows.length, next: rows.find((row) => !row.done)?.label ?? null };
594
594
  }
595
+ /** The Stop line of a turn that start-work keeps running starts with this mark; it is not the end of the run. */
596
+ export const CONTINUING_MARK = "⏳";
595
597
  function counted(n, unit) {
596
598
  return `${n} ${unit}${n === 1 ? "" : "s"} ✓`;
597
599
  }
@@ -610,7 +612,7 @@ export function workflowStopLine(repoRoot, sessionId, turnId, stop = NO_STOP_CON
610
612
  const continuing = continuingWork(repoRoot, sessionId, turnId, stop);
611
613
  if (continuing !== null) {
612
614
  const next = continuing.next === null ? null : safeTitle(continuing.next);
613
- const status = `⏳ ${continuing.done}/${continuing.total} tasks ✓ · continuing`;
615
+ const status = `${CONTINUING_MARK} ${continuing.done}/${continuing.total} tasks ✓ · continuing`;
614
616
  return next === null ? status : `${status} ▸ ${next}`;
615
617
  }
616
618
  const signals = readWorkflowSignals(repoRoot, sessionId);
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/lit-loop",
3
- "version": "1.0.40",
3
+ "version": "1.0.41",
4
4
  "description": "LitCodex Lit-Loop runtime: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
5
5
  "type": "module",
6
6
  "private": true,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litfamily/litcodex",
3
- "version": "1.0.40",
3
+ "version": "1.0.41",
4
4
  "description": "Codex CLI plugin that turns a request into a goal with checks, keeps the evidence in your project and hands unfinished work to the next session.",
5
5
  "keywords": [
6
6
  "codex",
@@ -53,7 +53,7 @@
53
53
  "readme-assets"
54
54
  ],
55
55
  "dependencies": {
56
- "@litcodex/lit-loop": "1.0.40"
56
+ "@litcodex/lit-loop": "1.0.41"
57
57
  },
58
58
  "bundledDependencies": [
59
59
  "@litcodex/lit-loop"
@@ -1 +1 @@
1
- <svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.40"><title>release: 1.0.40</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.40</text></g></svg>
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.41"><title>release: 1.0.41</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.41</text></g></svg>