@ngockhoale/ukit 3.5.13 → 3.5.14

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.
@@ -112,7 +112,22 @@ function writeDecisionLine(payload) {
112
112
  * Emit the fixed fail-closed block for the deadline path, exactly once, synchronously.
113
113
  * Exported so the deadline behaviour is directly testable.
114
114
  */
115
+ // Field telemetry #2 (2026-11-20): a reentrant Stop (`stop_hook_active: true` — the host already continued
116
+ // the turn once for a Stop block) whose fail-closed evaluator fails or overruns AGAIN cannot be helped by a
117
+ // second block: the infrastructure, not the task, is failing. Claude Code's own default for a failed or
118
+ // timed-out hook is non-blocking. The FIRST failure still blocks fail-closed; the repeat releases with a
119
+ // visible "not verified" advisory (outcome blocked, never complete). Set from main() before evaluation.
120
+ let reentrantStop = false;
121
+ export function setReentrantStop(value) { reentrantStop = value === true; }
122
+ export function infrastructureReleaseReason() {
123
+ return 'UKit stop coordinator: the completion evaluator failed or ran out of time again on a re-entered stop, so this stop is released WITHOUT verification (not complete — completion is unproven). This is usually a busy machine or slow disk; tell the user the task state is unverified. Only if this repeats across turns, run: ukit install.';
124
+ }
125
+ function emitReentrantInfrastructureRelease() {
126
+ return writeDecisionLine({ systemMessage: infrastructureReleaseReason(), policyOwner: 'fail-closed', outcome: 'blocked', complete: false });
127
+ }
128
+
115
129
  export function emitDeadlineBlock() {
130
+ if (reentrantStop) return emitReentrantInfrastructureRelease();
116
131
  return writeDecisionLine({
117
132
  decision: 'block',
118
133
  reason: redactDeadlineReason(),
@@ -3254,6 +3269,21 @@ export async function runStopCoordinator({
3254
3269
  } catch {
3255
3270
  ownership = { status: 'UNKNOWN', reason: 'handoff provenance runtime unavailable' };
3256
3271
  }
3272
+ // Field-telemetry #5 (2026-11-20): an UNKNOWN ownership beside a terminal
3273
+ // cursor (`Phase: done`, not paused) has no run to protect. Emitting "report
3274
+ // BLOCKED and reconcile provenance" on every stop there produced ~2,500
3275
+ // advisories (BAGuide 1,680, CKit 283) and marked healthy stops BLOCKED.
3276
+ // OWNED cursors still go through evaluateHandoffCursor (ExitPredicate); only
3277
+ // the UNKNOWN advisory/blockedOutcome lane is quieted.
3278
+ if (ownership.status === 'UNKNOWN' && ownership.reason !== 'run cursor absent') {
3279
+ try {
3280
+ const cursorText = await fs.readFile(path.join(runRoot, 'docs/AI_HANDOFF/RUN.md'), 'utf8');
3281
+ const phase = /^Phase:\s*(\S+)/im.exec(cursorText)?.[1]?.toLowerCase();
3282
+ if (phase === 'done' && !/^Paused:\s*yes\b/im.test(cursorText)) {
3283
+ ownership = { status: 'NOT_OWNED', reason: 'terminal run cursor (Phase: done)' };
3284
+ }
3285
+ } catch { /* unreadable cursor keeps the strict UNKNOWN lane */ }
3286
+ }
3257
3287
  if (ownership.reason === 'run cursor absent') {
3258
3288
  try {
3259
3289
  const watchdogRuntime = await import('./task-watchdog.mjs');
@@ -3453,9 +3483,14 @@ async function main() {
3453
3483
  } catch {
3454
3484
  payload = {}; // malformed payload: forward the raw text to the ledger, which owns crash counting
3455
3485
  }
3486
+ setReentrantStop(payload?.stop_hook_active === true);
3456
3487
  const projectRoot = process.env.CLAUDE_PROJECT_DIR || payload?.cwd || process.cwd();
3457
3488
  const { skip, merged } = await runStopCoordinator({ projectRoot, payload, rawInput, now: Date.now() });
3458
3489
  if (skip || !merged) return;
3490
+ if (merged.decision === 'block' && merged.policyOwner === 'fail-closed' && reentrantStop) {
3491
+ emitReentrantInfrastructureRelease();
3492
+ return;
3493
+ }
3459
3494
 
3460
3495
  // Synchronous writes through the shared emission gate: the deadline timer can fire
3461
3496
  // between any two turns of the event loop, and an already-written decision must never
@@ -3540,6 +3575,7 @@ if (isDirectRun()) {
3540
3575
  main().catch((error) => {
3541
3576
  // Last-resort failure INSIDE the coordinator: still fail-closed, still redacted.
3542
3577
  process.stderr.write(`[ukit-stop-coordinator] ${error?.message || error}\n`);
3578
+ if (reentrantStop) { emitReentrantInfrastructureRelease(); return; }
3543
3579
  writeDecisionLine({ decision: 'block', reason: redactInfrastructureReason(), policyOwner: 'fail-closed' });
3544
3580
  });
3545
3581
  }
@@ -134,7 +134,7 @@ memory:
134
134
  # edit any value here and `ukit update` keeps it. The legacy shipped 350000 is migrated
135
135
  # only when UKit's install ledger proves UKit wrote it; `ukit uninstall` reverts just
136
136
  # UKit's own additions and keeps your edits. Auto-compact must still trigger BEFORE
137
- # context-hardcap-gate blocks tool calls.
137
+ # context-hardcap-gate emits its (non-blocking) advisory.
138
138
  compaction:
139
139
  enabled: true
140
140
  thresholdTokens: {{omp.compactionThresholdTokens}}
@@ -35,7 +35,7 @@
35
35
 
36
36
  ## Long-Run Continuity
37
37
  <!-- RULES: LONG-01 LONG-02 -->
38
- - Near token-cap: **LAND one thing** end-to-end (edit + verify, ≤3 tool calls), **DEFER** the rest to `docs/STATUS.md` or bounded `docs/AI_HANDOFF/` tasks, **DELEGATE** broad work to subagents. Then compact.
38
+ - Near token-cap: **LAND one thing** end-to-end (edit + verify, ≤3 tool calls), **DEFER** the rest to `docs/STATUS.md` or bounded `docs/AI_HANDOFF/` tasks, **DELEGATE** broad work to subagents, then **keep working** — never end the turn just to ask the user for `/compact`; the host auto-compacts and work resumes from disk.
39
39
  - After compact/handoff: continue from persisted disk state — never reread pre-compact context; delegate broadly, keep replies short.
40
40
  - A run ends only on completion evidence, a genuine blocker, or a user-only action — every stop names its reason.
41
41
 
@@ -35,7 +35,7 @@
35
35
 
36
36
  ## Long-Run Continuity
37
37
  <!-- RULES: LONG-01 LONG-02 -->
38
- - Near token-cap: **LAND one thing** end-to-end (edit + verify, ≤3 tool calls), **DEFER** the rest to `docs/STATUS.md` or bounded `docs/AI_HANDOFF/` tasks, **DELEGATE** broad work to subagents. Then compact.
38
+ - Near token-cap: **LAND one thing** end-to-end (edit + verify, ≤3 tool calls), **DEFER** the rest to `docs/STATUS.md` or bounded `docs/AI_HANDOFF/` tasks, **DELEGATE** broad work to subagents, then **keep working** — never end the turn just to ask the user for `/compact`; the host auto-compacts and work resumes from disk.
39
39
  - After compact/handoff: continue from persisted disk state — never reread pre-compact context; delegate broadly, keep replies short.
40
40
  - A run ends only on completion evidence, a genuine blocker, or a user-only action — every stop names its reason.
41
41
 
@@ -82,7 +82,7 @@ Next: <bước kế tiếp chính xác>
82
82
  - 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.
83
83
  - 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.
84
84
  - 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ì.
85
- - Vượt `compact.hardCapTokens` (mặc định 235k, trong `compact.contextWindowTokens` 250k) mà `RUN.md` còn run dở **hoặc ordinary routed task có session execution ledger còn thiếu completion evidence**: `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/verification đang dở và ghi state resume; 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.
85
+ - Vượt `compact.hardCapTokens` (mặc định 235k, trong `compact.contextWindowTokens` 250k) : `context-hardcap-gate` KHÔNG BAO GIỜ chặn tool, chỉ phát một advisory mỗi cooldown. Compaction chỉ là lời nhắc: hạ cánh bước hiện tại, ghi các bước còn lại vào `docs/STATUS.md`, giao việc đọc rộng cho subagent, rồi tiếp tục làm; host tự auto-compact và việc resume từ disk (`RUN.md`/`docs/STATUS.md`).
86
86
  - 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` = `autoCompactWindowRatio` × `hardCapTokens` (mặc định 0.8 × 235k = 188000) và `env.CLAUDE_CODE_MAX_CONTEXT_TOKENS` = `contextWindowTokens` (250000), render lúc install, nên **client tự auto-compact trước khi gate chặn**. Đường thường: auto-compact chạy → `handoff-resume.sh` replay cursor cho handoff run hoặc tiêu thụ resume intent cho ordinary task → 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.
87
87
  - 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.
88
88
 
@@ -32,7 +32,7 @@
32
32
 
33
33
  ## Long-Run Continuity
34
34
  <!-- RULES: LONG-01 LONG-02 -->
35
- - Near token-cap: **LAND one thing** end-to-end (edit + verify, ≤3 tool calls), **DEFER** the rest to `docs/STATUS.md` or bounded `docs/AI_HANDOFF/` tasks, **DELEGATE** broad work to subagents. Then compact.
35
+ - Near token-cap: **LAND one thing** end-to-end (edit + verify, ≤3 tool calls), **DEFER** the rest to `docs/STATUS.md` or bounded `docs/AI_HANDOFF/` tasks, **DELEGATE** broad work to subagents, then **keep working** — never end the turn just to ask the user for `/compact`; the host auto-compacts and work resumes from disk.
36
36
  - After compact/handoff: continue from persisted disk state — never reread pre-compact context; delegate broadly, keep replies short.
37
37
  - A run ends only on completion evidence, a genuine blocker, or a user-only action — every stop names its reason.
38
38
 
@@ -683,9 +683,9 @@
683
683
  "enabled": "B\u1eadt/t\u1eaft to\u00e0n b\u1ed9 helper compact c\u1ee7a UKit.",
684
684
  "tokenThreshold": "Ng\u01b0\u1ee1ng token chung cho runtime compact d\u00f9ng chung.",
685
685
  "contextWindowTokens": "Context window t\u1ed1i \u0111a UKit cho client d\u00f9ng (m\u1eb7c \u0111\u1ecbnh 250000, k\u1ec3 c\u1ea3 khi provider h\u1ed7 tr\u1ee3 1M). Render th\u00e0nh env.CLAUDE_CODE_MAX_CONTEXT_TOKENS \u2014 model alias gateway nh\u01b0 unic-opus kh\u00f4ng c\u00f3 trong b\u1ea3ng c\u1ee7a Claude Code n\u00ean n\u1ebfu thi\u1ebfu s\u1ed1 n\u00e0y client t\u1ef1 \u0111o\u00e1n 200k/1M v\u00e0 b\u1ecf qua budget UKit. Kh\u00f4ng khuy\u1ebfn kh\u00edch t\u0103ng.",
686
- "hardCapTokens": "Ng\u01b0\u1ee1ng c\u1ee9ng tuy\u1ec7t \u0111\u1ed1i (m\u1eb7c \u0111\u1ecbnh 235000 token \u01b0\u1edbc l\u01b0\u1ee3ng, n\u1eb1m trong contextWindowTokens 250000). Ch\u1ea1m/v\u01b0\u1ee3t ng\u01b0\u1ee1ng n\u00e0y th\u00ec context-hardcap-gate ch\u1eb7n Edit/Write/Bash \u2014 kh\u00f4ng ph\u1ea3i g\u1ee3i \u00fd n\u1eefa, l\u00e0 b\u1eaft bu\u1ed9c. Ph\u1ea3i \u2264 contextWindowTokens. env.CLAUDE_CODE_AUTO_COMPACT_WINDOW (.claude/settings.json) v\u00e0 compaction.thresholdTokens (.omp/config.yml) \u0111\u1ec1u \u0111\u01b0\u1ee3c SUY RA t\u1eeb s\u1ed1 n\u00e0y khi ch\u1ea1y ukit install.",
687
- "autoCompactWindowRatio": "Auto-compact ch\u1ea1y \u1edf bao nhi\u00eau ph\u1ea7n c\u1ee7a hardCapTokens (m\u1eb7c \u0111\u1ecbnh 0.8 \u2192 188000). Ph\u1ea3i < 1 \u0111\u1ec3 client t\u1ef1 compact TR\u01af\u1edaC khi context-hardcap-gate ch\u1eb7n tool; s\u1ed1 c\u00e0ng nh\u1ecf th\u00ec compact c\u00e0ng s\u1edbm.",
688
- "hardCapBlock": "N\u1ebfu true, hook context-hardcap-gate ch\u1eb7n c\u1ee9ng Edit/Write/Bash (exit 2) khi v\u01b0\u1ee3t hardCapTokens, cho t\u1edbi khi c\u00f3 compact th\u1eadt (PreCompact) reset l\u1ea1i b\u1ed9 \u0111\u1ebfm.",
686
+ "hardCapTokens": "Ng\u01b0\u1ee1ng c\u1ee9ng tuy\u1ec7t \u0111\u1ed1i (m\u1eb7c \u0111\u1ecbnh 235000 token \u01b0\u1edbc l\u01b0\u1ee3ng, n\u1eb1m trong contextWindowTokens 250000). Ch\u1ea1m/v\u01b0\u1ee3t ng\u01b0\u1ee1ng n\u00e0y th\u00ec context-hardcap-gate ch\u1ec9 nh\u1eafc (advisory, kh\u00f4ng bao gi\u1edd ch\u1eb7n tool); host t\u1ef1 auto-compact. Ph\u1ea3i \u2264 contextWindowTokens. env.CLAUDE_CODE_AUTO_COMPACT_WINDOW (.claude/settings.json) v\u00e0 compaction.thresholdTokens (.omp/config.yml) \u0111\u1ec1u \u0111\u01b0\u1ee3c SUY RA t\u1eeb s\u1ed1 n\u00e0y khi ch\u1ea1y ukit install.",
687
+ "autoCompactWindowRatio": "Auto-compact ch\u1ea1y \u1edf bao nhi\u00eau ph\u1ea7n c\u1ee7a hardCapTokens (m\u1eb7c \u0111\u1ecbnh 0.8 \u2192 188000). Ph\u1ea3i < 1 \u0111\u1ec3 client t\u1ef1 compact TR\u01af\u1edaC khi context-hardcap-gate nh\u1eafc; s\u1ed1 c\u00e0ng nh\u1ecf th\u00ec compact c\u00e0ng s\u1edbm.",
688
+ "hardCapBlock": "N\u1ebfu true, hook context-hardcap-gate nh\u1eafc (advisory systemMessage, kh\u00f4ng bao gi\u1edd ch\u1eb7n/exit 2) m\u1ed9t l\u1ea7n m\u1ed7i cooldown khi v\u01b0\u1ee3t hardCapTokens; false = t\u1eaft nh\u1eafc.",
689
689
  "hardCapGraceCalls": "S\u1ed1 tool call \u0111\u01b0\u1ee3c ph\u00e9p ch\u1ea1y ti\u1ebfp sau khi v\u01b0\u1ee3t hardCapTokens khi handoff run trong docs/AI_HANDOFF/RUN.md ho\u1eb7c ordinary routed task c\u00f3 session execution ledger c\u00f2n dang d\u1edf (m\u1eb7c \u0111\u1ecbnh 10). \u0110\u00e2y ch\u1ec9 l\u00e0 landing window: ho\u00e0n t\u1ea5t edit/verification \u0111ang d\u1edf v\u00e0 ghi state resume, kh\u00f4ng m\u1edf task m\u1edbi. H\u1ebft grace l\u00e0 ch\u1eb7n c\u1ee9ng nh\u01b0 c\u0169. Budget t\u00ednh theo m\u1ed7i \u0111\u1ee3t v\u01b0\u1ee3t cap, ch\u1ec9 reset khi \u01b0\u1edbc l\u01b0\u1ee3ng token th\u1eadt s\u1ef1 gi\u1ea3m (c\u00f3 compact th\u1eadt) \u2014 kh\u00f4ng reset theo wave.",
690
690
  "contextRotDetection": "Ph\u00e1t hi\u1ec7n context qu\u00e1 d\u00e0i/d\u1ec5 m\u1ee5c \u0111\u1ec3 gi\u1eef l\u1ea1i state quan tr\u1ecdng tr\u01b0\u1edbc khi AI nh\u1edb sai.",
691
691
  "askBeforeDrop": "Gi\u1eef th\u00e1i \u0111\u1ed9 th\u1eadn tr\u1ecdng tr\u01b0\u1edbc khi b\u1ecf context quan tr\u1ecdng. N\u1ebfu r\u1ee7i ro th\u00ec hand back cho main model.",