@ngockhoale/ukit 2.3.0 → 2.3.2

package/CHANGELOG.md

@@ -2,6 +2,78 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.2 - 2026-09-09
+
+Docs-contract release. "Every stop says why — no silent idle" is now a shipping Execution
+Contract rule, born from a real incident: a turn ended waiting for the user's `npm login`,
+the request sat at the bottom of a long report, the user did their part (created
+`~/.npmrc`), and the idle session looked exactly like a stall for 79 minutes.
+
+The new contract (identical in `CLAUDE.md` and `AGENTS.md`, parity-test enforced): when a
+turn ends only because the user must act (login, approval, protected-file edit), the reply
+opens with one line naming the exact action — `WAITING ON YOU: <command/action>` — and a
+one-shot wakeup (~20-30 min) is scheduled when the harness provides one, so the session
+re-checks and auto-continues once the user has acted. An ended turn cannot observe
+external/auth changes by itself; without that line the idle session is indistinguishable
+from a stall. Companion rule: any error (failed command, hook, test, publish) is reported
+verbatim in the same turn, never silently retried past the user.
+
+Decision recorded in `docs/MEMORY.md` with the incident as the reason. Verified: all
+doc-referencing suites 298/298 (incl. the CLAUDE↔AGENTS parity test, which caught the
+first one-sided edit before it could ship), consistency 194/194.
+
+## 2.3.1 - 2026-09-09
+
+"1 prompt mà đứng 10 lần" is fixed at the root. Four stall vectors in the completion
+gate and router are gone, no stop is silent anymore, and routine backend model swaps
+are now worked through instead of stalled on. All found by root-cause debugging with a
+failing regression test per fix.
+
+1) Stop-hook recursion: `execution-ledger.mjs --evaluate-stop` re-blocked the reentrant
+Stop event (Claude Code re-invokes Stop with `stop_hook_active: true` after a block), so
+one block became a self-sustaining block/continue chain ending in a cap-forced mid-task
+stop. The gate now honors `stop_hook_active` and, when evidence is still missing, emits
+a user-visible `systemMessage` instead of silently ending.
+
+2) requestKey churn wiped evidence: `skill-router.sh` rebuilds requestKey per tool call
+(commandText/targetFile are hashed in), so the first verification command re-keyed the
+route mid-request and `--record` took the freshLedger path, erasing the write/verification
+evidence the same request had produced — the gate then re-blocked until the cap forced a
+silent stop. The ledger now keys evidence identity by the user prompt text
+(`promptKey`); a re-key within one logical request carries evidence forward, a genuinely
+new prompt starts clean.
+
+3) Subagent stalls: subagent tool calls run the same hooks against the same session
+ledger and route state (docs-confirmed; sidechain payloads carry `agent_id`/
+`agent_type`). A subagent's Edit could re-route the request to a different
+executionMode, which both broke the old promptKey identity (wiping main evidence) and
+replaced the main route's completionEvidence. Fixes: promptKey is the prompt text alone
+(null prompt never carries), and `skill-router.sh` early-exits on sidechain payloads so
+subagent tool calls never touch the main route state. omp's bridge invokes the same
+script, so every harness is covered.
+
+4) No silent endings: the non-gated modes' `notify` and the post-cap `capped` paths now
+emit a `systemMessage` alongside their stderr line — previously these ended turns with
+the user seeing nothing.
+
+Gateway model swaps (limit hit → a different vendor model behind the same alias) are
+detected from the transcript's per-assistant `message.model` and surfaced in
+`context-window-guard.sh` as ONE routine line per hour: keep working, do not restart or
+re-plan; if a tool call errors after a swap, re-check the tool and call it again. The
+swap itself cold-reads the prompt cache once — that latency is transport-level and
+cannot be removed by hooks; everything after it now continues automatically.
+
+Integrated on top of 2.3.0 (rebased; not published as 2.2.17): 2.3.0's stricter gates
+made the re-key carry load-bearing for `targetedVerificationSucceeded`/`sourceFiles`
+too — without carrying them, a mid-request re-key re-demanded targeted evidence and
+re-introduced the stall this release fixes (regression-tested RED→GREEN). The 2.3.0
+notify test that expected a silent stdout was updated to the no-silent-stops contract.
+
+Verified: executionLedgerCli 29/29, skillRouterHook 33/33, contextWindowGuard 18/18;
+full suite 1280/1280 (74 files) and `release:verify` green on the integrated tree;
+template↔live mirrors byte-identical (live settings.json re-rendered through the install
+pipeline, not copied raw).
+
 ## 2.3.0 - 2026-09-08
 
 Model-agnostic hardening release. Every configured model name is treated as a gateway

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/templates/.claude/hooks/context-window-guard.sh

@@ -131,24 +131,14 @@ const estimatedTokens = Math.round(contentChars / CHARS_PER_TOKEN);
 const hardCap = loadHardCap();
 const ratio = estimatedTokens / hardCap;
 
-if (ratio < 0.8) process.exit(0);
-
-const pct = Math.round(ratio * 100);
-const phase = ratio >= 1 ? 'hard' : 'soft';
-
-// Debounce the directive block so it does not re-print in full every single prompt
-// while the phase is unchanged — that would just be more tokens added to the same
-// oversized context it is warning about. Re-arms on phase change (soft -> hard) or
-// after the cooldown, and resets naturally once a real compaction/new session drops
-// the live transcript back under 0.8, since this whole branch exits early above.
+// Debounce/state file shared by the context warning and the gateway model-swap note.
 const GUARD_STATE_PATH = path.join(projectRoot, '.ukit', 'storage', 'cache', 'context-guard-state.json');
-const COOLDOWN_MS = phase === 'hard' ? 3 * 60 * 1000 : 8 * 60 * 1000;
 
 function readGuardState() {
   try {
     return JSON.parse(fs.readFileSync(GUARD_STATE_PATH, 'utf8'));
   } catch {
-    return { lastPhase: null, lastActionAt: 0 };
+    return { lastPhase: null, lastActionAt: 0, lastSwapModel: null, lastSwapNoteAt: 0 };
   }
 }
 
@@ -160,6 +150,68 @@ function writeGuardState(state) {
 }
 
 const guardState = readGuardState();
+let persistedState = { ...guardState };
+
+// ── Gateway model-swap note ──
+// Assistant entries carry the REAL model that served them, so a swapping gateway
+// (the backend alias resolves to a different vendor model, e.g. on limit) is directly
+// visible here. Swapping is ROUTINE on such gateways, not an incident: a swap can
+// look like a short stall (cold prompt cache re-reads the context once) and providers
+// expose slightly different tools. So this is ONE line, cooldown-bounded — never a
+// per-swap directive block — telling the session the only two things that matter:
+// keep working through swaps, and on a tool error after a swap, re-check the tool and
+// call it again instead of stopping. Runs before the ratio early-exit because a swap
+// can happen at any context level.
+const RECENT_MODEL_WINDOW = 40;
+const SWAP_NOTE_COOLDOWN_MS = 60 * 60 * 1000;
+const modelSequence = [];
+for (let i = start; i < lines.length; i += 1) {
+  let entry;
+  try {
+    entry = JSON.parse(lines[i]);
+  } catch {
+    continue;
+  }
+  if (entry?.isSidechain || entry?.type !== 'assistant') continue;
+  const model = entry?.message?.model;
+  if (typeof model === 'string' && model.trim()) modelSequence.push(model.trim());
+}
+const recentModels = modelSequence.slice(-RECENT_MODEL_WINDOW);
+const currentModel = recentModels[recentModels.length - 1] || null;
+let previousModel = null;
+for (let i = recentModels.length - 2; i >= 0; i -= 1) {
+  if (recentModels[i] !== currentModel) {
+    previousModel = recentModels[i];
+    break;
+  }
+}
+const swapDetected = Boolean(currentModel && previousModel);
+if (swapDetected && persistedState.lastSwapModel !== currentModel) {
+  persistedState.lastSwapModel = currentModel;
+  const withinSwapCooldown = (Date.now() - Number(persistedState.lastSwapNoteAt || 0)) < SWAP_NOTE_COOLDOWN_MS;
+  if (!withinSwapCooldown) {
+    persistedState.lastSwapNoteAt = Date.now();
+    writeGuardState(persistedState);
+    process.stdout.write(
+      `UKIT GATEWAY — routine backend model swap ("${currentModel}" after "${previousModel}"): keep working, do not restart or re-plan; if a tool call errors after a swap, re-check the tool (providers differ) and simply call it again — never stop over it.\n`,
+    );
+  } else {
+    writeGuardState(persistedState);
+  }
+}
+
+if (ratio < 0.8) process.exit(0);
+
+const pct = Math.round(ratio * 100);
+const phase = ratio >= 1 ? 'hard' : 'soft';
+
+// Debounce the directive block so it does not re-print in full every single prompt
+// while the phase is unchanged — that would just be more tokens added to the same
+// oversized context it is warning about. Re-arms on phase change (soft -> hard) or
+// after the cooldown, and resets naturally once a real compaction/new session drops
+// the live transcript back under 0.8, since this whole branch exits early above.
+const COOLDOWN_MS = phase === 'hard' ? 3 * 60 * 1000 : 8 * 60 * 1000;
+
 const now = Date.now();
 const withinCooldown = guardState.lastPhase === phase
   && (now - Number(guardState.lastActionAt || 0)) < COOLDOWN_MS;
@@ -206,7 +258,7 @@ if (withinCooldown) {
   if (sidechainEntries > 0) {
     lines_out.push(`Note: ${sidechainEntries} subagent entries in this stretch. Keep concurrency at or below handoff.maxParallelAgents and keep returns short; do not widen the batch while this warning stands.`);
   }
-  writeGuardState({ lastPhase: phase, lastActionAt: now });
+  writeGuardState({ ...persistedState, lastPhase: phase, lastActionAt: now });
 } else {
   lines_out.push('ACTION THIS TURN, before starting new investigation/subagents/pipeline phases:');
   lines_out.push('1) Persist current progress now (update docs/STATUS.md, e.g. via the update-status skill) so nothing is lost.');
@@ -215,7 +267,7 @@ if (withinCooldown) {
   if (sidechainEntries > 0) {
     lines_out.push(`Note: ${sidechainEntries} subagent entries in this stretch — each teammate carries its own context window, and every finished report is injected back here, so running many at once is the fastest way to overflow this session. Avoid spawning more until context drops back under the cap.`);
   }
-  writeGuardState({ lastPhase: phase, lastActionAt: now });
+  writeGuardState({ ...persistedState, lastPhase: phase, lastActionAt: now });
 }
 
 process.stdout.write(`${lines_out.join('\n')}\n`);

package/templates/.claude/hooks/skill-router.sh

@@ -41,6 +41,33 @@ STATE_FILE="$PROJECT_ROOT/.claude/ukit/skill-router-state.json"
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
 THRESHOLD_SCRIPT="$HOOK_DIR/../ukit/runtime/compact-threshold.mjs"
 
+# Sidechain early-exit: PreToolUse/PostToolUse payloads carry agent_id/agent_type only
+# when the tool call runs INSIDE a subagent (documented marker). A subagent's Edit/Bash
+# must not re-key or re-classify the MAIN request's route — that churn swapped
+# completionEvidence mid-request and made the main Stop gate demand the wrong evidence.
+# Fails OPEN: any parse problem, missing field, or node error falls through to normal
+# routing. Pure-bash pre-check first: the node guard can only match when the literal
+# "agent_id" key appears, so ordinary calls never pay the node spawn.
+case "$INPUT" in
+  *'"agent_id"'*|*'"agent_type"'*)
+    if printf '%s' "$INPUT" | node -e '
+const chunks = [];
+process.stdin.on("data", (c) => chunks.push(c));
+process.stdin.on("end", () => {
+  try {
+    const payload = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    process.exit(payload && typeof payload === "object"
+      && (payload.agent_id || payload.agent_type) ? 0 : 1);
+  } catch {
+    process.exit(1);
+  }
+});
+' >/dev/null 2>&1; then
+      exit 0
+    fi
+    ;;
+esac
+
 INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" STATE_FILE="$STATE_FILE" HOOK_DIR="$HOOK_DIR" node <<'NODE'
 const fs = require('fs');
 const path = require('path');

package/templates/.claude/ukit/runtime/execution-ledger.mjs

@@ -175,6 +175,45 @@ function appendReceipt(receipts, receipt) {
   return [...(receipts || []), compactReceipt(receipt)].slice(-MAX_RECEIPTS);
 }
 
+// A re-key within the same logical request must not drop the evidence the request
+// already produced — that turned one finished task into a cap-exhausted forced stop.
+// A genuinely different prompt keeps a clean slate so old work never satisfies a new
+// request's completion gate.
+function carriedEvidenceLedger(fresh, current) {
+  if (!current || !fresh.promptKey || !current.promptKey || current.promptKey !== fresh.promptKey) {
+    return fresh;
+  }
+  return {
+    ...fresh,
+    sourceSucceeded: fresh.sourceSucceeded || current.sourceSucceeded === true,
+    // targeted-verification evidence (2.3.0) must survive the same re-key carry as the
+    // coarse flags, or the stricter gates re-demand evidence mid-request — the exact
+    // stall this carry exists to prevent.
+    targetedVerificationSucceeded: fresh.targetedVerificationSucceeded
+      || current.targetedVerificationSucceeded === true,
+    sourceFiles: [...new Set([...(current.sourceFiles || []), ...(fresh.sourceFiles || [])])]
+      .slice(-MAX_SOURCE_FILES),
+    writeAttempted: fresh.writeAttempted || current.writeAttempted === true,
+    writeSucceeded: fresh.writeSucceeded || current.writeSucceeded === true,
+    verificationAttempted: fresh.verificationAttempted || current.verificationAttempted === true,
+    verificationSucceeded: fresh.verificationSucceeded || current.verificationSucceeded === true,
+    verificationFailed: fresh.verificationFailed || current.verificationFailed === true,
+    receipts: [...(current.receipts || [])].slice(-MAX_RECEIPTS),
+  };
+}
+
+// The router rebuilds requestKey per tool call (commandText/targetFile are part of the
+// key), so requestKey changes mid-request on every verification command — and a subagent's
+// Edit can additionally re-classify executionMode/taskType for the same user prompt. The
+// logical request identity is therefore the prompt text alone: hash it so completion
+// evidence survives any re-key/re-route within one request without leaking across requests.
+// States with no recorded prompt text get no identity and never carry evidence.
+function evidencePromptKey(routeState) {
+  const promptText = String(routeState?.routingContext?.lastExplicitUserPromptText || '').trim();
+  if (!promptText) return null;
+  return `prompt-${crypto.createHash('sha256').update(promptText).digest('hex').slice(0, 20)}`;
+}
+
 function freshLedger(payload, routeState, harness) {
   return {
     version: LEDGER_VERSION,
@@ -183,6 +222,7 @@ function freshLedger(payload, routeState, harness) {
     transcriptPath: payload.transcript_path || payload.transcriptPath || null,
     harness,
     requestKey: routeState?.requestKey || null,
+    promptKey: evidencePromptKey(routeState),
     routeFingerprint: routeState?.fingerprint || null,
     sourceSucceeded: false,
     sourceFiles: [],
@@ -209,7 +249,7 @@ export async function recordExecutionReceipt({
   const routeState = await readRouteState(projectRoot);
   const current = await readExecutionLedger(projectRoot, payload);
   const ledger = !current || current.requestKey !== (routeState?.requestKey || null)
-    ? freshLedger(payload, routeState, harness)
+    ? carriedEvidenceLedger(freshLedger(payload, routeState, harness), current)
     : { ...current, harness: current.harness || harness };
 
   const failed = explicitError(payload);
@@ -453,12 +493,31 @@ async function main() {
     const state = await readRouteState(projectRoot);
     const ledger = await readExecutionLedger(projectRoot, payload) || {};
     const result = evaluateCompletion({ state, ledger });
+
+    // Claude Code invokes Stop again after a Stop hook blocks the first stop. Re-blocking
+    // that recovery turn creates a self-sustaining loop, so let it end normally instead.
+    // If work still lacks evidence, surface the recovery reason to the user rather than
+    // silently ending after the automatic continuation.
+    if (payload.stop_hook_active === true) {
+      if (result.continue || result.capped || result.notify) {
+        const recoveryReason = result.reason
+          || 'UKit completion gate reached its continuation limit; unfinished work was not retried again.';
+        process.stdout.write(`${JSON.stringify({
+          systemMessage: `UKit stopped automatic recovery after one continuation: ${recoveryReason}`,
+        })}\n`);
+      }
+      return;
+    }
+
     if (result.continue) {
       if (result.finalNotice) await markNotified(projectRoot, payload, ledger);
       else await incrementContinuation(projectRoot, payload, ledger, state?.requestKey || null);
       process.stdout.write(`${JSON.stringify({ decision: 'block', reason: result.reason })}\n`);
     } else if (result.capped || result.notify) {
+      // Non-blocking endings (non-gated modes, or cap reached after the final notice) must
+      // still tell the user what is unfinished — a silent end is indistinguishable from a stall.
       process.stderr.write(`[ukit-completion] ${result.reason}\n`);
+      process.stdout.write(`${JSON.stringify({ systemMessage: result.reason })}\n`);
     }
   }
 }

package/templates/AGENTS.md

@@ -24,6 +24,7 @@
 - If routed state says `pull-indexed-context`, treat it as internal continuation — after the bounded read, **continue to edit/verify in the same turn** when safe.
 - If routed state shows `continuation required` or a stuck-lane rescue mode, finish the named milestone before widening reads or repeating analysis.
 - **Do NOT say "done", "applied", or "fixed" after Read/Grep/analysis alone.** Completion wording requires concrete Edit/Write evidence in the current turn, and verification when the scope is risky.
+- **Every stop says why — no silent idle.** When a turn ends because only the user can act (login, approval, protected-file edit), open the reply with one line naming the exact action: `WAITING ON YOU: <command/action>`, and schedule a one-shot wakeup (~20-30 min) when the harness provides one so the session re-checks and auto-continues once the user has acted. An ended turn cannot observe external/auth changes by itself, so without that line (and the wakeup) the idle session looks identical to a stall. Any error — failed command, hook, test, publish — is reported verbatim in the same turn, never silently retried past the user.
 
 ## Index-First Loop
 

package/templates/CLAUDE.md

@@ -24,6 +24,7 @@
 - If routed state says `pull-indexed-context`, treat it as internal continuation — after the bounded read, **continue to edit/verify in the same turn** when safe.
 - If routed state shows `continuation required` or a stuck-lane rescue mode, finish the named milestone before widening reads or repeating analysis.
 - **Do NOT say "done", "applied", or "fixed" after Read/Grep/analysis alone.** Completion wording requires concrete Edit/Write evidence in the current turn, and verification when the scope is risky.
+- **Every stop says why — no silent idle.** When a turn ends because only the user can act (login, approval, protected-file edit), open the reply with one line naming the exact action: `WAITING ON YOU: <command/action>`, and schedule a one-shot wakeup (~20-30 min) when the harness provides one so the session re-checks and auto-continues once the user has acted. An ended turn cannot observe external/auth changes by itself, so without that line (and the wakeup) the idle session looks identical to a stall. Any error — failed command, hook, test, publish — is reported verbatim in the same turn, never silently retried past the user.
 
 ## Index-First Loop