@ngockhoale/ukit 2.1.2 → 2.1.3

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to UKit are documented here.
 
+## 2.1.3 - 2026-08-16
+
+The reason auto-compact never fired in the terminal was UKit itself. This makes it fire.
+
+### Fixed
+
+- **Auto-compact now triggers below the hard cap instead of never.** `context-hardcap-gate.sh` refuses Edit/Write/Bash at `compact.hardCapTokens` (160,000 — 80% of a 200k window), while Claude Code's own auto-compact fires near the real window limit. The gate froze the session first, so the transcript stopped growing, so the auto-compact threshold was never reached: a deadlock whose only exit was typing `/compact` by hand. Default settings now ship `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = 150000`, which lands 10,000 tokens *before* the gate — compaction happens on its own, the run keeps going, and the grace window added in 2.1.2 stays as the backstop rather than the normal path.
+- **`autoCompactEnabled: true` is pinned in default settings**, so a stale toggle in `/config` cannot silently reinstate the deadlock.
+
+### Added
+
+- **`tests/core/autoCompactWindow.test.js`** — locks the ordering invariant `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW < compact.hardCapTokens`, the 100,000–1,000,000 range Claude Code accepts, `autoCompactEnabled`, template/mirror parity, and the `overwrite_with_backup` merge strategy that lets existing installs pick the fix up. Change either number in isolation and the suite fails instead of the deadlock returning silently.
+
+### Notes
+
+- `env` in `settings.json` applies to **new sessions**. After `npm i -g @ngockhoale/ukit@latest && ukit install`, restart the session (or `/compact` once) before the change takes effect.
+- Still true, and unchanged: no hook can invoke `/compact` — it is client-only. 2.1.3 does not call it; it moves the client's own threshold below UKit's gate so the client compacts on its own.
+
 ## 2.1.2 - 2026-08-16
 
 Follow-up to 2.1.0, which fixed the wrong hook. Runs were still freezing mid-task because the gate that actually blocks tools was never touched.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",

package/templates/.claude/settings.json

@@ -9,6 +9,10 @@
   "showThinkingSummaries": false,
   "spinnerTipsEnabled": false,
   "defaultView": "chat",
+  "autoCompactEnabled": true,
+  "env": {
+    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "150000"
+  },
   "permissions": {
     "defaultMode": "bypassPermissions",
     "allow": [

package/templates/docs/AI_HANDOFF/RULES.md

@@ -80,7 +80,8 @@ Next: <bước kế tiếp chính xác>
 - Hết mỗi wave: commit, ghi cursor, **collapse** wave đó còn 1 dòng/task trong bộ nhớ làm việc, rồi chạy tiếp.
 - Yêu cầu `/compact` **chỉ** được đặt ở cuối command, giữa 2 cycle. Giữa cycle thì tuyệt đối không — state đã nằm hết ở git + `INDEX.md` + `RUN.md` nên compact ở ranh giới cycle không mất gì.
 - Vượt `compact.hardCapTokens` (mặc định 160k) mà `RUN.md` còn run dở: `context-hardcap-gate` cho thêm `compact.hardCapGraceCalls` (mặc định 10) tool call rồi mới chặn cứng. **Grace đó chỉ để hạ cánh** — hoàn tất edit đang dở, commit, ghi cursor, push. Không mở task mới, không đọc thêm file, không spawn agent. Hết grace là chặn thật; budget chỉ reset khi ước lượng token thực sự giảm (có compact thật), không reset theo wave.
-- Không hook nào gọi được `/compact` — đó là lệnh client-only. Nên đường thoát duy nhất khi context đầy là: hạ cánh trong grace → user `/compact` → `handoff-resume.sh` replay cursor → chạy tiếp. Bật auto-compact trong `/config` của Claude Code để bước `/compact` tự xảy ra.
+- Không hook nào gọi được `/compact` — đó là lệnh client-only. Nhưng từ 2.1.3, settings mặc định đặt `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = 150000` < `hardCapTokens` (160k), nên **client tự auto-compact trước khi gate chặn**. Đường thường: auto-compact chạy → `handoff-resume.sh` replay cursor → chạy tiếp, không cần người gõ gì. Grace window ở trên chỉ còn là lưới an toàn.
+- Sửa một trong hai số đó thì phải giữ `autoCompactWindow < hardCapTokens`. Đảo thứ tự là deadlock: gate chặn tool trước → transcript ngừng lớn → ngưỡng auto-compact không bao giờ tới. `tests/core/autoCompactWindow.test.js` khóa bất biến này.
 
 ### Git