@ngockhoale/ukit 2.1.0 → 2.1.3

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 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.
+
+### Fixed
+
+- **`context-hardcap-gate.sh` gets a grace window for unfinished runs.** 2.1.0 made the *advisory* `context-window-guard.sh` (UserPromptSubmit) run-cursor aware, but the halt users hit came from `context-hardcap-gate.sh` — a separate PreToolUse hook that hard-refuses Edit/Write/Bash with `exit 2` once `estimatedTotalTokens >= compact.hardCapTokens`. It knew nothing about `docs/AI_HANDOFF/RUN.md`, so it froze runs mid-edit exactly as before 2.1.0. It now reads the run cursor and, while a run is unfinished, allows a bounded `compact.hardCapGraceCalls` (default 10) further calls with an explicit "spend this on landing, not new work" directive — finish the edit, commit, write the cursor, push — then blocks hard as it always did.
+
+### Added
+
+- **`compact.hardCapGraceCalls`** (default `10`). Budget is per over-cap episode, not per wave: it resets only when the token estimate actually falls (a real compaction happened), so a long run cannot mint itself unlimited grace by advancing its cursor. With no unfinished run the gate's behavior is unchanged.
+- **`tests/hooks/contextHardcapGate.test.js`** — 12 cases covering under-cap pass-through, blocking with no run in flight, `Phase: done` treated as no run, grace grant/exhaustion, no top-up on cursor advance, budget restored after a real compaction, `hardCapBlock=false` escape hatch, non-gated tools, fail-open on malformed input, template/mirror parity, and manifest+settings wiring.
+
+### Notes
+
+- **No hook can call `/compact`** — it is a client-only command, so UKit cannot auto-compact on your behalf. The supported path is: land inside the grace window → user runs `/compact` (or Claude Code's own auto-compact fires) → the `handoff-resume.sh` SessionStart hook replays the cursor → the run continues. Enabling auto-compact in Claude Code's `/config` makes that middle step automatic.
+
 ## 2.1.0 - 2026-08-16
 
 Handoff autonomy wave: `/ukit:handoff-fullstack` runs a whole goal end-to-end without stopping to ask. Questions are collected once, up front, in the planning phase; everything that used to be a mid-run STOP now resolves automatically and keeps going.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.1.0",
+  "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/hooks/context-hardcap-gate.sh

@@ -16,6 +16,14 @@
 # just brick the session with no way out, since only the user (not the agent) can invoke
 # real compaction.
 #
+# Grace window (compact.hardCapGraceCalls, default 10): blocking the very first tool call
+# past the cap strands a handoff run mid-edit — files half-written, nothing committed, no
+# cursor — which is strictly worse than letting it land. When docs/AI_HANDOFF/RUN.md shows
+# an unfinished run, the gate therefore allows a BOUNDED number of further calls so the run
+# can commit, write its cursor and push; after that it blocks exactly as before. The budget
+# is per over-cap episode, not per wave: it only resets when the estimate actually drops
+# (i.e. a real compaction happened), so a run cannot mint itself fresh grace forever.
+#
 # Config toggle: compact.hardCapBlock (default true). Set to false only to debug this
 # gate itself; it must not become a normal escape hatch.
 
@@ -59,6 +67,22 @@ function readJsonSafe(filePath, fallback = null) {
   }
 }
 
+// An unfinished handoff run — same cursor file the resume hook and the advisory
+// context guard read. `Phase: done` (or no file) means there is nothing in flight.
+function readRunCursor() {
+  try {
+    const text = fs.readFileSync(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
+    const runPhase = (text.match(/^Phase:\s*(.+)$/m)?.[1] || '').trim();
+    if (!runPhase || /^done$/i.test(runPhase)) return null;
+    return {
+      phase: runPhase,
+      cursor: (text.match(/^Cursor:\s*(.+)$/m)?.[1] || '').trim(),
+    };
+  } catch {
+    return null;
+  }
+}
+
 (async () => {
   const config = readJsonSafe(path.join(projectRoot, '.ukit', 'storage', 'config.json'), {}) || {};
   if (config?.compact?.hardCapBlock === false) {
@@ -78,15 +102,58 @@ function readJsonSafe(filePath, fallback = null) {
   const state = mod.buildCompactPressureState(rawState, config);
   const thresholds = mod.buildCompactThresholds(config);
 
+  const gracePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'hardcap-grace.json');
+
   if (state.estimatedTotalTokens < thresholds.hardCapTokens) {
+    // Back under the cap — the episode is over, so the next one starts with a full budget.
+    fs.rmSync(gracePath, { force: true });
     process.exit(0);
     return;
   }
 
+  const run = readRunCursor();
+  if (run) {
+    const graceCalls = Number.isFinite(config?.compact?.hardCapGraceCalls)
+      ? config.compact.hardCapGraceCalls
+      : 10;
+    const prior = readJsonSafe(gracePath, null);
+    // Reset only when the estimate actually fell since grace started: that is the signal a
+    // real compaction/shed happened. Advancing the cursor alone must NOT top the budget up,
+    // otherwise a long run gets unlimited grace and the ceiling stops meaning anything.
+    const carried =
+      prior && Number.isFinite(prior.startedAtTokens) && state.estimatedTotalTokens >= prior.startedAtTokens
+        ? prior
+        : { startedAtTokens: state.estimatedTotalTokens, used: 0 };
+
+    if (carried.used < graceCalls) {
+      const used = carried.used + 1;
+      try {
+        fs.mkdirSync(path.dirname(gracePath), { recursive: true });
+        fs.writeFileSync(gracePath, JSON.stringify({ ...carried, used }));
+      } catch {
+        // Losing the counter must not block the run; worst case grace restarts.
+      }
+      process.stderr.write(
+        [
+          `CONTEXT OVER CAP — grace ${used}/${graceCalls} (~${state.estimatedTotalTokens} tokens >= ${thresholds.hardCapTokens}).`,
+          `An unfinished run is in flight (Phase: ${run.phase}${run.cursor ? `, Cursor: ${run.cursor}` : ''}), so this call is allowed instead of stranding it mid-edit.`,
+          'Spend the remaining grace on LANDING, not on new work: finish the current edit, commit, update docs/AI_HANDOFF/RUN.md, push.',
+          'Do NOT start a new task, open new files, or spawn agents. When grace runs out the gate blocks hard.',
+          'After the user runs /compact, the SessionStart resume hook replays the cursor and the run continues automatically.',
+        ].join('\n') + '\n',
+      );
+      process.exit(0);
+      return;
+    }
+  }
+
   const lines = [
     `BLOCKED (context hard cap): estimated context ~${state.estimatedTotalTokens} tokens >= hard cap ${thresholds.hardCapTokens}.`,
     'This is an absolute ceiling (compact.hardCapTokens), separate from the soft/hard advisory phases — those were apparently not followed.',
     `Edit/Write/Bash refused (tool_name=${toolName}) until real compaction happens.`,
+    run
+      ? 'The unfinished-run grace window (compact.hardCapGraceCalls) is already exhausted — progress should be committed and the cursor written by now.'
+      : 'No unfinished run in docs/AI_HANDOFF/RUN.md, so there is no grace window to spend.',
     'Remedy (any one): run /compact, or start a new session (SessionStart resets the counter), or delete .ukit/storage/cache/compact-pressure.json.',
     'Do not work around this by summarizing inline and continuing, and do not reach for a non-gated write tool.',
   ];

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

@@ -79,6 +79,9 @@ Next: <bước kế tiếp chính xác>
 - Subagent ghi **full log vào task file trên đĩa**, chỉ trả về orchestrator ≤10 dòng (executor) / ≤6 dòng (reviewer). Paste log ngược lại orchestrator là nguyên nhân số 1 làm run chết vì hết context.
 - 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. 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
 

package/templates/ukit/storage/config.json

@@ -11,6 +11,7 @@
     "tokenThreshold": 50000,
     "hardCapTokens": 160000,
     "hardCapBlock": true,
+    "hardCapGraceCalls": 10,
     "contextRotDetection": true,
     "askBeforeDrop": true,
     "codexContext": {
@@ -384,7 +385,8 @@
       "enabled": "Bật/tắt toàn bộ helper compact của UKit.",
       "tokenThreshold": "Ngưỡng token chung cho runtime compact dùng chung.",
       "hardCapTokens": "Ngưỡng cứng tuyệt đối (mặc định 160000 token ước lượng). Chạm/vượt ngưỡng này thì context coi như quá dài — không phải gợi ý nữa, là bắt buộc. PHẢI thấp hơn context window thật của model (200k), nếu không API sẽ báo lỗi vượt context trước khi gate kịp chặn.",
-      "hardCapBlock": "Nếu true, hook context-hardcap-gate chặn cứng Edit/Write/Bash (exit 2) khi vượt hardCapTokens, cho tới khi có compact thật (PreCompact) reset lại bộ đếm. Không có ngoại lệ.",
+      "hardCapBlock": "Nếu true, hook context-hardcap-gate chặn cứng Edit/Write/Bash (exit 2) khi vượt hardCapTokens, cho tới khi có compact thật (PreCompact) reset lại bộ đếm.",
+      "hardCapGraceCalls": "Số tool call được phép chạy tiếp sau khi vượt hardCapTokens KHI docs/AI_HANDOFF/RUN.md còn run dở (mặc định 10). Dùng để run kịp commit + ghi cursor + push rồi mới bị chặn, thay vì chết giữa lúc đang Edit. Hết grace là chặn cứng như cũ. Budget tính theo mỗi đợt vượt cap, chỉ reset khi ước lượng token thật sự giảm (có compact thật) — không reset theo wave.",
       "contextRotDetection": "Phát hiện context quá dài/dễ mục để giữ lại state quan trọng trước khi AI nhớ sai.",
       "askBeforeDrop": "Giữ thái độ thận trọng trước khi bỏ context quan trọng. Nếu rủi ro thì hand back cho main model.",
       "agentContext": {