@litfamily/litcodex 1.0.12 → 1.0.13

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 (32) hide show
  1. package/README-Ko-KR.md +9 -9
  2. package/README.md +9 -9
  3. package/dist/config-migration/gpt56-policy.js +3 -0
  4. package/dist/install/auto-handoff-doctor.js +22 -2
  5. package/marketplace/plugins/litcodex/.codex-plugin/plugin.json +1 -1
  6. package/marketplace/plugins/litcodex/components/auto-update/package.json +1 -1
  7. package/marketplace/plugins/litcodex/components/comment-checker/package.json +1 -1
  8. package/marketplace/plugins/litcodex/components/git-bash/package.json +1 -1
  9. package/marketplace/plugins/litcodex/components/lit-loop/dist/auto-handoff-settings.d.ts +9 -2
  10. package/marketplace/plugins/litcodex/components/lit-loop/dist/auto-handoff-settings.js +55 -9
  11. package/marketplace/plugins/litcodex/components/lit-loop/dist/auto-handoff.d.ts +10 -2
  12. package/marketplace/plugins/litcodex/components/lit-loop/dist/auto-handoff.js +23 -17
  13. package/marketplace/plugins/litcodex/components/lit-loop/dist/hook-cli.d.ts +1 -1
  14. package/marketplace/plugins/litcodex/components/lit-loop/dist/hook-cli.js +41 -21
  15. package/marketplace/plugins/litcodex/components/lit-loop/package.json +1 -1
  16. package/marketplace/plugins/litcodex/components/lsp/package.json +1 -1
  17. package/marketplace/plugins/litcodex/components/rules/dist/model-metadata.d.ts +1 -1
  18. package/marketplace/plugins/litcodex/components/rules/dist/model-metadata.js +1 -0
  19. package/marketplace/plugins/litcodex/components/rules/package.json +1 -1
  20. package/marketplace/plugins/litcodex/components/start-work-continuation/package.json +1 -1
  21. package/marketplace/plugins/litcodex/components/telemetry/package.json +1 -1
  22. package/marketplace/plugins/litcodex/components/wikify-knowledge/package.json +1 -1
  23. package/model-catalog.json +25 -5
  24. package/node_modules/@litcodex/lit-loop/dist/auto-handoff-settings.d.ts +9 -2
  25. package/node_modules/@litcodex/lit-loop/dist/auto-handoff-settings.js +55 -9
  26. package/node_modules/@litcodex/lit-loop/dist/auto-handoff.d.ts +10 -2
  27. package/node_modules/@litcodex/lit-loop/dist/auto-handoff.js +23 -17
  28. package/node_modules/@litcodex/lit-loop/dist/hook-cli.d.ts +1 -1
  29. package/node_modules/@litcodex/lit-loop/dist/hook-cli.js +41 -21
  30. package/node_modules/@litcodex/lit-loop/package.json +1 -1
  31. package/package.json +2 -2
  32. 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.12/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.12/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.13/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.13/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.12/readme-assets/badge-version.svg" alt="1.0.12" /></a>
5
- <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.12/readme-assets/badge-license.svg" alt="MIT license" /></a>
4
+ <a href="#설치"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.13/readme-assets/badge-version.svg" alt="1.0.13" /></a>
5
+ <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.13/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.12/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.12/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.12/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.13/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.13/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.13/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
10
10
  </p>
11
11
 
12
12
  # LitCodex
@@ -24,13 +24,13 @@ LitCodex는 Codex CLI 플러그인입니다. 계획, 검토, 조사와 오래
24
24
  Node.js 22 이상과 Codex CLI가 필요합니다.
25
25
 
26
26
  ```sh
27
- npm exec --yes --package @litfamily/litcodex@1.0.12 -- litcodex install
27
+ npm exec --yes --package @litfamily/litcodex@1.0.13 -- litcodex install
28
28
  ```
29
29
 
30
30
  설치기는 플러그인과 훅, 에이전트를 등록하고 `~/.codex/config.toml`에서는 자기가 관리하는 항목만 고칩니다.
31
31
  설치 중에 어떤 모델이 작업을 이끌지(리드), 어떤 모델이 거들지(헬퍼), 답변 스타일은 무엇으로 할지 묻습니다.
32
32
  새로 설치하면 리드는 `gpt-6-astra`/`xhigh`, 헬퍼는 `gpt-6-luna`/`max`로 시작합니다. 바뀔 내용을 먼저 보려면
33
- `npm exec --yes --package @litfamily/litcodex@1.0.12 -- litcodex --dry-run install`을 실행하고, 묻는 단계 없이
33
+ `npm exec --yes --package @litfamily/litcodex@1.0.13 -- litcodex --dry-run install`을 실행하고, 묻는 단계 없이
34
34
  설치하려면 `install` 뒤에 `--yes`를 붙이세요.
35
35
 
36
36
  전역 명령으로 쓰려면 다음을 실행합니다.
@@ -50,7 +50,7 @@ litcodex install
50
50
  다만 이렇게 빼도 내려받기가 뒤로 미뤄질 뿐입니다. `litcodex install`이 설치에 성공한 뒤 같은 도구를 준비하고,
51
51
  이 단계는 끌 수 없습니다.
52
52
 
53
- > 전역 설치가 없다면 `npm exec --yes --package @litfamily/litcodex@1.0.12 -- litcodex <command>` 형식을 사용하세요.
53
+ > 전역 설치가 없다면 `npm exec --yes --package @litfamily/litcodex@1.0.13 -- litcodex <command>` 형식을 사용하세요.
54
54
 
55
55
  기존 설정과 떼어 놓고 써 보려면
56
56
  [격리된 체험 안내](https://github.com/wjgoarxiv/litcodex/blob/main/docs/npm-migration.md#isolated-local-trial)를
@@ -185,7 +185,7 @@ Codex가 압축하도록 설정되어 있지 않으면 `/compact`를 실행하
185
185
  ## 확인, 문제 해결, 제거
186
186
 
187
187
  ```sh
188
- npm exec --yes --package @litfamily/litcodex@1.0.12 -- litcodex doctor
188
+ npm exec --yes --package @litfamily/litcodex@1.0.13 -- litcodex doctor
189
189
  ```
190
190
 
191
191
  `litcodex doctor`는 등록·훅·설정·호스트 기능을, `litcodex loop doctor`는 현재 프로젝트의 루프 상태를 확인합니다.
@@ -200,7 +200,7 @@ npm exec --yes --package @litfamily/litcodex@1.0.12 -- litcodex doctor
200
200
  [문제 해결](https://github.com/wjgoarxiv/litcodex/blob/main/README-Ko-KR.md#문제-해결)을 참고하세요.
201
201
 
202
202
  ```sh
203
- npm exec --yes --package @litfamily/litcodex@1.0.12 -- litcodex uninstall
203
+ npm exec --yes --package @litfamily/litcodex@1.0.13 -- litcodex uninstall
204
204
  ```
205
205
 
206
206
  플러그인과 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.12/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.12/readme-assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: five armored robots power on one by one, the LitCodex robot wakes with glowing eyes 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.13/readme-assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.13/readme-assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: five armored robots power on one by one, the LitCodex robot wakes with glowing eyes 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.12/readme-assets/badge-version.svg" alt="1.0.12" /></a>
5
- <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.12/readme-assets/badge-license.svg" alt="MIT license" /></a>
4
+ <a href="#install"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.13/readme-assets/badge-version.svg" alt="1.0.13" /></a>
5
+ <a href="https://github.com/wjgoarxiv/litcodex/blob/main/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litcodex@1.0.13/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.12/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.12/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.12/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.13/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.13/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.13/readme-assets/lucide-shield-check.svg" width="16" alt="" /> MIT</a>
10
10
  </p>
11
11
 
12
12
  # LitCodex
@@ -24,14 +24,14 @@ the results stay in your project, where a later session can pick them up.
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.12 -- litcodex install
27
+ npm exec --yes --package @litfamily/litcodex@1.0.13 -- litcodex install
28
28
  ```
29
29
 
30
30
  The installer registers the plugin, its hooks and its agents, and changes only the keys it manages in
31
31
  `~/.codex/config.toml`. It asks which model leads, which model helps, and which output style you like. A
32
32
  fresh install starts with `gpt-6-astra` at `xhigh` for the lead and `gpt-6-luna` at `max` for helpers. To
33
33
  see the changes before they happen, run
34
- `npm exec --yes --package @litfamily/litcodex@1.0.12 -- litcodex --dry-run install`. To install without
34
+ `npm exec --yes --package @litfamily/litcodex@1.0.13 -- litcodex --dry-run install`. To install without
35
35
  any questions, add `--yes` after `install`.
36
36
 
37
37
  For a global command:
@@ -52,7 +52,7 @@ To keep the script out of the global install, add `--ignore-scripts` or set `CI=
52
52
  That only postpones the downloads: `litcodex install` prepares
53
53
  the same tools after a successful install, with no switch to turn it off.
54
54
 
55
- > Without a global install, use `npm exec --yes --package @litfamily/litcodex@1.0.12 -- litcodex <command>`.
55
+ > Without a global install, use `npm exec --yes --package @litfamily/litcodex@1.0.13 -- litcodex <command>`.
56
56
 
57
57
  To try LitCodex apart from your existing settings, follow the
58
58
  [isolated trial guide](https://github.com/wjgoarxiv/litcodex/blob/main/docs/npm-migration.md#isolated-local-trial).
@@ -194,7 +194,7 @@ line asking you to run `/compact`. The handoff then comes back on its own. Read
194
194
  ## Check, fix, remove
195
195
 
196
196
  ```sh
197
- npm exec --yes --package @litfamily/litcodex@1.0.12 -- litcodex doctor
197
+ npm exec --yes --package @litfamily/litcodex@1.0.13 -- litcodex doctor
198
198
  ```
199
199
 
200
200
  `litcodex doctor` checks registration, hooks, config and host capabilities; `litcodex loop doctor` checks the
@@ -208,7 +208,7 @@ current project's loop state. Both look at the setup; a small real task shows wh
208
208
  time in an open terminal, note each exit status, and see [troubleshooting](https://github.com/wjgoarxiv/litcodex#troubleshooting).
209
209
 
210
210
  ```sh
211
- npm exec --yes --package @litfamily/litcodex@1.0.12 -- litcodex uninstall
211
+ npm exec --yes --package @litfamily/litcodex@1.0.13 -- litcodex uninstall
212
212
  ```
213
213
 
214
214
  This removes the plugin and the config LitCodex manages, and leaves your other settings alone.
@@ -35,6 +35,8 @@ export const GPT56_MODELS = {
35
35
  luna: requiredLegacyProfileModel("luna"),
36
36
  };
37
37
  export const ASTRA_MODEL = GPT6_MODELS.astra;
38
+ /** The previous-generation GPT-6 Sol id stays a known managed route for users who already chose it. */
39
+ const PREVIOUS_GPT6_SOL_MODEL = requiredModelForAlias("gpt-6-sol");
38
40
  export const EXPLICIT_GPT56_SOL_MODEL = requiredModelForAlias("sol");
39
41
  export const GPT56_CONTEXT_WINDOW_LIMIT = 372_000;
40
42
  export const GPT56_AUTO_COMPACT_TOKEN_LIMIT = 334_800;
@@ -157,6 +159,7 @@ export function classifyCatalogInput(args) {
157
159
  originalDispatchId === GPT56_MODELS.luna ||
158
160
  originalDispatchId === ASTRA_MODEL ||
159
161
  originalDispatchId === GPT6_MODELS.sol ||
162
+ originalDispatchId === PREVIOUS_GPT6_SOL_MODEL ||
160
163
  originalDispatchId === GPT6_MODELS.luna) {
161
164
  return { class: "existing_managed", originalDispatchId };
162
165
  }
@@ -7,6 +7,8 @@ const FLAG_ENV = "LITCODEX_AUTO_HANDOFF";
7
7
  const PERCENT_ENV = "LITCODEX_AUTO_HANDOFF_PERCENT";
8
8
  const HOST_KEY = "model_post_turn_compact_threshold_percent";
9
9
  const KEY_LINE = new RegExp(`^\\s*${HOST_KEY}\\s*=\\s*(\\d+)\\s*(?:#.*)?$`, "mu");
10
+ /** The marker line `lit-handoff auto on` writes directly above the key; only a key under it is managed. */
11
+ const MANAGED_BEGIN = "# litcodex automatic handoff (managed by `lit-handoff auto`; `lit-handoff auto off` removes it)";
10
12
  function percentOf(raw) {
11
13
  if (!/^\d{1,2}$/u.test(raw))
12
14
  return null;
@@ -36,6 +38,19 @@ function projectTrusted(fs, projectRoot, codexHome) {
36
38
  }
37
39
  return false;
38
40
  }
41
+ /** The percent of a managed compaction block in the project config, else null. */
42
+ function managedCompactionPercent(projectConfig) {
43
+ if (projectConfig === null)
44
+ return null;
45
+ const lines = projectConfig.split("\n");
46
+ for (let index = 1; index < lines.length; index += 1) {
47
+ const match = KEY_LINE.exec((lines[index] ?? "").replace(/\r$/u, ""));
48
+ if (match?.[1] !== undefined && (lines[index - 1] ?? "").replace(/\r$/u, "") === MANAGED_BEGIN) {
49
+ return Number(match[1]);
50
+ }
51
+ }
52
+ return null;
53
+ }
39
54
  function readIfPresent(fs, path) {
40
55
  try {
41
56
  return fs.existsSync(path) ? fs.readFileSync(path, "utf8") : null;
@@ -81,9 +96,14 @@ export function inspectAutoHandoff(fs, env, projectRoot, codexHome) {
81
96
  warnings.push(`Automatic handoff is on but has no percent. Run "lit-handoff auto on <percent>" or set ${PERCENT_ENV}.`);
82
97
  }
83
98
  const active = enabled && percent !== null;
84
- if (!active || percent === null)
85
- return { state: "off", percent, source, compaction: null, warnings };
86
99
  const projectConfig = readIfPresent(fs, join(projectRoot, ".codex", "config.toml"));
100
+ if (!active || percent === null) {
101
+ const left = managedCompactionPercent(projectConfig);
102
+ if (left !== null) {
103
+ warnings.push(`Automatic handoff is off, but the managed block in your project .codex/config.toml keeps compacting at ${left}% with no handoff. The next hook run removes it, or run "lit-handoff auto off".`);
104
+ }
105
+ return { state: "off", percent, source, compaction: null, warnings };
106
+ }
87
107
  const projectKey = projectConfig === null ? undefined : KEY_LINE.exec(projectConfig)?.[1];
88
108
  const projectPercent = projectKey === undefined ? null : Number(projectKey);
89
109
  const trusted = projectPercent !== null && projectTrusted(fs, projectRoot, codexHome);
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "litcodex",
3
- "version": "1.0.12",
3
+ "version": "1.0.13",
4
4
  "description": "LitCodex Codex plugin: the lit-loop activation, durable loop runtime, and local review-gated knowledge.",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/auto-update",
3
- "version": "1.0.12",
3
+ "version": "1.0.13",
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.12",
3
+ "version": "1.0.13",
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.12",
3
+ "version": "1.0.13",
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,
@@ -36,8 +36,8 @@ export declare function readStoredAutoHandoff(repoRoot: string): {
36
36
  */
37
37
  export declare function resolveAutoHandoff(env: NodeJS.ProcessEnv, stored: StoredAutoHandoff, storedWarning?: string | null): AutoHandoffState;
38
38
  export declare function loadAutoHandoffState(repoRoot: string, env: NodeJS.ProcessEnv): AutoHandoffState;
39
- /** Atomic write that refuses to go through a symlink or replace anything but a regular file. */
40
- export declare function writeSmallFile(path: string, text: string): boolean;
39
+ /** Atomic write that refuses to go through a symlink (in any component below `root`) or replace anything but a regular file. */
40
+ export declare function writeSmallFile(path: string, text: string, root: string): boolean;
41
41
  export declare function writeStoredAutoHandoff(repoRoot: string, stored: StoredAutoHandoff): boolean;
42
42
  export declare function projectConfigPath(repoRoot: string): string;
43
43
  export type ProjectCompaction = {
@@ -63,6 +63,13 @@ export type ProjectConfigResult = "written" | "unchanged-user-key" | "failed" |
63
63
  export declare function writeProjectCompaction(repoRoot: string, percent: number): ProjectConfigResult;
64
64
  /** Remove only the marked block; delete the file (and an empty `.codex`) when nothing else is left. */
65
65
  export declare function removeProjectCompaction(repoRoot: string): ProjectConfigResult;
66
+ /**
67
+ * 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
+ * block goes; a key the user wrote by hand is never touched. Never throws.
71
+ */
72
+ export declare function clearManagedCompactionWhenOff(repoRoot: string, env: NodeJS.ProcessEnv): ProjectConfigResult;
66
73
  export type AutoHandoffRoute = {
67
74
  readonly action: "on";
68
75
  readonly argument: string | null;
@@ -15,7 +15,7 @@
15
15
  import { randomBytes } from "node:crypto";
16
16
  import { closeSync, constants, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeSync, } from "node:fs";
17
17
  import { homedir } from "node:os";
18
- import { dirname, isAbsolute, join } from "node:path";
18
+ import { dirname, isAbsolute, join, relative, sep } from "node:path";
19
19
  export const AUTO_HANDOFF_FLAG_ENV = "LITCODEX_AUTO_HANDOFF";
20
20
  export const AUTO_HANDOFF_PERCENT_ENV = "LITCODEX_AUTO_HANDOFF_PERCENT";
21
21
  export const AUTO_HANDOFF_DIR = ".litcodex/auto-handoff";
@@ -122,6 +122,30 @@ export function loadAutoHandoffState(repoRoot, env) {
122
122
  return resolveAutoHandoff(env, stored, warning);
123
123
  }
124
124
  // ── Safe small-file writes ───────────────────────────────────────────────────
125
+ /**
126
+ * True when no existing component of `target` below `root` is a symlink, so a write or delete cannot be
127
+ * redirected out of the project. Components that do not exist yet are fine; `root` itself is trusted.
128
+ */
129
+ function clearOfSymlinks(root, target) {
130
+ const below = relative(root, target);
131
+ if (below === "" || below === ".." || below.startsWith(`..${sep}`) || isAbsolute(below))
132
+ return false;
133
+ let current = root;
134
+ try {
135
+ for (const part of below.split(sep)) {
136
+ current = join(current, part);
137
+ const stat = lstatSync(current, { throwIfNoEntry: false });
138
+ if (stat === undefined)
139
+ return true;
140
+ if (stat.isSymbolicLink())
141
+ return false;
142
+ }
143
+ return true;
144
+ }
145
+ catch {
146
+ return false;
147
+ }
148
+ }
125
149
  function ensureDir(dir) {
126
150
  try {
127
151
  const stat = lstatSync(dir, { throwIfNoEntry: false });
@@ -135,9 +159,9 @@ function ensureDir(dir) {
135
159
  return false;
136
160
  }
137
161
  }
138
- /** Atomic write that refuses to go through a symlink or replace anything but a regular file. */
139
- export function writeSmallFile(path, text) {
140
- if (!ensureDir(dirname(path)))
162
+ /** Atomic write that refuses to go through a symlink (in any component below `root`) or replace anything but a regular file. */
163
+ export function writeSmallFile(path, text, root) {
164
+ if (!clearOfSymlinks(root, path) || !ensureDir(dirname(path)))
141
165
  return false;
142
166
  const tmp = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
143
167
  try {
@@ -165,7 +189,7 @@ export function writeSmallFile(path, text) {
165
189
  }
166
190
  }
167
191
  export function writeStoredAutoHandoff(repoRoot, stored) {
168
- return writeSmallFile(settingsPath(repoRoot), `${JSON.stringify({ version: 1, ...stored })}\n`);
192
+ return writeSmallFile(settingsPath(repoRoot), `${JSON.stringify({ version: 1, ...stored })}\n`, repoRoot);
169
193
  }
170
194
  // ── Project config: Codex compacts after the handoff turn ────────────────────
171
195
  const KEY_LINE = new RegExp(`^\\s*${HOST_COMPACT_KEY}\\s*=\\s*(\\d+)\\s*(?:#.*)?$`, "u");
@@ -234,6 +258,8 @@ export function hostCompactsAt(repoRoot, percent, env) {
234
258
  /** Write (or update) the marked block. A key the user wrote by hand stays as it is. */
235
259
  export function writeProjectCompaction(repoRoot, percent) {
236
260
  const path = projectConfigPath(repoRoot);
261
+ if (!clearOfSymlinks(repoRoot, path))
262
+ return "failed";
237
263
  const stat = lstatSync(path, { throwIfNoEntry: false });
238
264
  if (stat !== undefined && !stat.isFile())
239
265
  return "failed";
@@ -248,15 +274,17 @@ export function writeProjectCompaction(repoRoot, percent) {
248
274
  const lines = raw.split("\n");
249
275
  const at = lines.findIndex((line) => KEY_LINE.test(line.replace(/\r$/u, "")));
250
276
  lines[at] = `${HOST_COMPACT_KEY} = ${percent}`;
251
- return writeSmallFile(path, lines.join("\n")) ? "written" : "failed";
277
+ return writeSmallFile(path, lines.join("\n"), repoRoot) ? "written" : "failed";
252
278
  }
253
- return writeSmallFile(path, raw === "" ? block : `${block}\n${raw}`) ? "written" : "failed";
279
+ return writeSmallFile(path, raw === "" ? block : `${block}\n${raw}`, repoRoot) ? "written" : "failed";
254
280
  }
255
281
  /** Remove only the marked block; delete the file (and an empty `.codex`) when nothing else is left. */
256
282
  export function removeProjectCompaction(repoRoot) {
257
283
  const path = projectConfigPath(repoRoot);
258
284
  if (readProjectCompaction(repoRoot).kind !== "managed")
259
285
  return "nothing-to-remove";
286
+ if (!clearOfSymlinks(repoRoot, path))
287
+ return "failed";
260
288
  const raw = readSmallFile(path);
261
289
  if (raw === null)
262
290
  return "failed";
@@ -283,7 +311,23 @@ export function removeProjectCompaction(repoRoot) {
283
311
  return "failed";
284
312
  }
285
313
  }
286
- return writeSmallFile(path, rest) ? "removed" : "failed";
314
+ return writeSmallFile(path, rest, repoRoot) ? "removed" : "failed";
315
+ }
316
+ /**
317
+ * 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
320
+ * block goes; a key the user wrote by hand is never touched. Never throws.
321
+ */
322
+ export function clearManagedCompactionWhenOff(repoRoot, env) {
323
+ try {
324
+ if (!isAbsolute(repoRoot) || loadAutoHandoffState(repoRoot, env).active)
325
+ return "nothing-to-remove";
326
+ return removeProjectCompaction(repoRoot);
327
+ }
328
+ catch {
329
+ return "failed";
330
+ }
287
331
  }
288
332
  /** Only the complete prompt `lit-handoff auto ...` (case-insensitive, edge whitespace allowed) is a route. */
289
333
  export function parseAutoHandoffRoute(prompt) {
@@ -329,8 +373,10 @@ export function applyAutoHandoffRoute(repoRoot, env, route) {
329
373
  if (route.action === "usage")
330
374
  return USAGE;
331
375
  const { stored } = readStoredAutoHandoff(repoRoot);
332
- if (route.action === "status")
376
+ if (route.action === "status") {
377
+ clearManagedCompactionWhenOff(repoRoot, env);
333
378
  return describeAutoHandoff(repoRoot, loadAutoHandoffState(repoRoot, env), env);
379
+ }
334
380
  const envNote = (env[AUTO_HANDOFF_FLAG_ENV]?.trim() ?? "") === ""
335
381
  ? ""
336
382
  : ` ${AUTO_HANDOFF_FLAG_ENV} is set in the environment and takes priority over this command.`;
@@ -53,11 +53,19 @@ interface FreshHandoff {
53
53
  }
54
54
  /** The newest HANDOFF file written after `since` that names `sessionId`; everything else is ignored. */
55
55
  export declare function findFreshHandoff(repoRoot: string, sessionId: string, since: number): FreshHandoff | null;
56
+ /** A reload the record has already been moved past; `release` puts the record back if the text never reached the model. */
57
+ export interface ReloadClaim {
58
+ readonly text: string;
59
+ readonly release: () => void;
60
+ }
56
61
  /**
57
- * The reload text for a session that fired and then compacted, or null when there is nothing to bring
62
+ * Claim the reload text for a session that fired and then compacted, or null when there is nothing to bring
58
63
  * back. `allowFired` lets SessionStart (source "compact") reload even when PostCompact has not run yet.
59
- * The record moves to "reloaded" first, so the excerpt is injected once.
64
+ * The record moves to "reloaded" first, so the excerpt is injected once; a caller that then fails to put
65
+ * the text into its hook output calls `release` so the next prompt can try again.
60
66
  */
67
+ export declare function claimReloadContext(repoRoot: string, sessionId: string, env: NodeJS.ProcessEnv, allowFired: boolean): ReloadClaim | null;
68
+ /** The reload text, claimed for good. Use `claimReloadContext` when the text might not reach the output. */
61
69
  export declare function takeReloadContext(repoRoot: string, sessionId: string, env: NodeJS.ProcessEnv, allowFired: boolean): string | null;
62
70
  /** Mirror of the rendered state for the doctor: what this session's record says. */
63
71
  export declare function readSessionPhase(repoRoot: string, sessionId: string): AutoHandoffPhase | null;
@@ -65,9 +65,10 @@ function readSession(path, sessionId) {
65
65
  return freshSession(sessionId);
66
66
  }
67
67
  }
68
- function writeSession(path, session) {
69
- return writeSmallFile(path, `${JSON.stringify(session)}\n`);
68
+ function writeSession(repoRoot, path, session) {
69
+ return writeSmallFile(path, `${JSON.stringify(session)}\n`, repoRoot);
70
70
  }
71
+ /** The last `bytes` bytes of a file. Byte counts are compared with byte counts, never with decoded text length. */
71
72
  function readTail(path, bytes) {
72
73
  let fd;
73
74
  try {
@@ -83,8 +84,8 @@ function readTail(path, bytes) {
83
84
  const size = fstatSync(fd).size;
84
85
  const length = Math.min(size, bytes);
85
86
  const buffer = Buffer.alloc(length);
86
- readSync(fd, buffer, 0, length, size - length);
87
- return buffer.toString("utf8");
87
+ const read = readSync(fd, buffer, 0, length, size - length);
88
+ return { text: buffer.subarray(0, read).toString("utf8"), whole: size <= bytes };
88
89
  }
89
90
  catch {
90
91
  return null;
@@ -126,13 +127,13 @@ export function readContextPercent(transcriptPath) {
126
127
  if (typeof transcriptPath !== "string" || transcriptPath === "" || !isAbsolute(transcriptPath))
127
128
  return null;
128
129
  for (const bytes of TAIL_STEPS) {
129
- const text = readTail(transcriptPath, bytes);
130
- if (text === null)
130
+ const tail = readTail(transcriptPath, bytes);
131
+ if (tail === null)
131
132
  return null;
132
- const reading = lastTokenCount(text);
133
+ const reading = lastTokenCount(tail.text);
133
134
  if (reading !== null)
134
135
  return reading;
135
- if (text.length < bytes)
136
+ if (tail.whole)
136
137
  return null;
137
138
  }
138
139
  return null;
@@ -176,10 +177,10 @@ export function evaluateAutoHandoffStop(input) {
176
177
  if (reading.percent < state.percent) {
177
178
  if (session.phase === "idle" || session.phase === "compacted") {
178
179
  if (session.lastPercent !== seen.lastPercent)
179
- writeSession(path, seen);
180
+ writeSession(input.repoRoot, path, seen);
180
181
  return PASS;
181
182
  }
182
- writeSession(path, { ...seen, phase: "idle", firedAt: null, firedPercent: null });
183
+ writeSession(input.repoRoot, path, { ...seen, phase: "idle", firedAt: null, firedPercent: null });
183
184
  return PASS;
184
185
  }
185
186
  if (session.phase !== "idle")
@@ -190,7 +191,7 @@ export function evaluateAutoHandoffStop(input) {
190
191
  firedAt: input.now ?? Date.now(),
191
192
  firedPercent: state.percent,
192
193
  };
193
- if (!writeSession(path, fired))
194
+ if (!writeSession(input.repoRoot, path, fired))
194
195
  return PASS;
195
196
  return {
196
197
  decision: "block",
@@ -210,7 +211,7 @@ export function recordCompaction(repoRoot, sessionId) {
210
211
  return;
211
212
  const session = readSession(path, sessionId);
212
213
  if (session.phase === "fired")
213
- writeSession(path, { ...session, phase: "compacted" });
214
+ writeSession(repoRoot, path, { ...session, phase: "compacted" });
214
215
  }
215
216
  catch {
216
217
  // fail-open
@@ -279,11 +280,12 @@ function buildReloadContext(repoRoot, session) {
279
280
  ].join("\n");
280
281
  }
281
282
  /**
282
- * The reload text for a session that fired and then compacted, or null when there is nothing to bring
283
+ * Claim the reload text for a session that fired and then compacted, or null when there is nothing to bring
283
284
  * back. `allowFired` lets SessionStart (source "compact") reload even when PostCompact has not run yet.
284
- * The record moves to "reloaded" first, so the excerpt is injected once.
285
+ * The record moves to "reloaded" first, so the excerpt is injected once; a caller that then fails to put
286
+ * the text into its hook output calls `release` so the next prompt can try again.
285
287
  */
286
- export function takeReloadContext(repoRoot, sessionId, env, allowFired) {
288
+ export function claimReloadContext(repoRoot, sessionId, env, allowFired) {
287
289
  try {
288
290
  const state = loadAutoHandoffState(repoRoot, env);
289
291
  if (!state.active)
@@ -294,14 +296,18 @@ export function takeReloadContext(repoRoot, sessionId, env, allowFired) {
294
296
  const session = readSession(path, sessionId);
295
297
  if (session.phase !== "compacted" && !(allowFired && session.phase === "fired"))
296
298
  return null;
297
- if (!writeSession(path, { ...session, phase: "reloaded" }))
299
+ if (!writeSession(repoRoot, path, { ...session, phase: "reloaded" }))
298
300
  return null;
299
- return buildReloadContext(repoRoot, session);
301
+ return { text: buildReloadContext(repoRoot, session), release: () => void writeSession(repoRoot, path, session) };
300
302
  }
301
303
  catch {
302
304
  return null;
303
305
  }
304
306
  }
307
+ /** The reload text, claimed for good. Use `claimReloadContext` when the text might not reach the output. */
308
+ export function takeReloadContext(repoRoot, sessionId, env, allowFired) {
309
+ return claimReloadContext(repoRoot, sessionId, env, allowFired)?.text ?? null;
310
+ }
305
311
  /** Mirror of the rendered state for the doctor: what this session's record says. */
306
312
  export function readSessionPhase(repoRoot, sessionId) {
307
313
  const path = sessionPath(repoRoot, sessionId);
@@ -32,5 +32,5 @@ export declare function runStopPlanPersistenceHookCli(stdin: NodeJS.ReadableStre
32
32
  /** SessionStart: after a compaction inside a turn, bring this session's fresh handoff back once. */
33
33
  export declare function runSessionStartHookCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream, stderr: NodeJS.WritableStream, repoRoot?: string, auto?: AutoHandoffHookOptions): Promise<number>;
34
34
  /** PostCompact: remember that a session that saved a handoff has now been compacted. Writes nothing to stdout. */
35
- export declare function runPostCompactHookCli(stdin: NodeJS.ReadableStream, _stdout: NodeJS.WritableStream, stderr: NodeJS.WritableStream, repoRoot?: string): Promise<number>;
35
+ export declare function runPostCompactHookCli(stdin: NodeJS.ReadableStream, _stdout: NodeJS.WritableStream, stderr: NodeJS.WritableStream, repoRoot?: string, auto?: AutoHandoffHookOptions): Promise<number>;
36
36
  export declare function runPreToolUseCreateGoalGuardCli(stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream, stderr: NodeJS.WritableStream): Promise<number>;