@ngockhoale/ukit 2.3.2 → 2.3.4

package/CHANGELOG.md

@@ -2,6 +2,106 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.4 - 2026-09-10
+
+Silent-stall audit and compact-recovery release. Two themes: every block reports a
+user-visible reason, and compaction must actually buy back context.
+
+Security hooks can no longer be bypassed or silently disabled. `block-dangerous.sh` catches
+split recursive/force flags (`rm -r -f`, `rm --force -r`) and evaluates every delete target
+per shell segment, so one allowlisted word can no longer legitimise a sibling target
+(`rm -rf dist /`); a bare `/` stays classified unsafe, wrapped forms keep the whole-command
+fallback, and detections surface as structured `ask` decisions that never echo the raw
+command. `block-dangerous.sh`, `protect-files.sh`, and `auto-allow-bash.sh` fall back to
+Node when `jq` is absent (stock macOS), so a missing optional binary cannot disable a gate.
+`protect-files.sh` matches exact sensitive basenames and directory components instead of
+substrings — `.env.d.ts` and `app.envrc` are source files, not secrets — and emits a
+structured human-decision response on real blocks. `sensitive-data-guard.sh` only treats
+`-u/--user` as credentials on tools that authenticate with it, so `docker run --user
+1000:1000` no longer false-blocks while `curl -u user:pass` still does.
+
+Stops always carry a reason. `handoff-model-guard.sh` pairs its stderr refusal with a
+structured `systemMessage`; the completion gate reports a lost route state after real
+session activity instead of releasing silently; hard-cap grace and sensitive-data blocks
+already speak `systemMessage` from 2.3.3. `Phase: done …` with trailing status text now
+counts as finished (`^done\b`, not `^done$`) in `handoff-resume.sh`,
+`context-hardcap-gate.sh`, and `context-window-guard.sh`, so annotated done-phases stop
+being resumed forever. Multi-file resume intents survive compaction: identity is session +
+prompt key, because the router re-keys `requestKey` on every tool call and that churn is
+what made post-compact resume a silent no-op.
+
+The hard-cap grace budget is race-proof. Parallel subagents hitting the cap in one episode
+used to race a single read-modify-write counter and multiply the budget; each spent call
+now claims an exclusive-create sentinel file, so the sentinels present are the true count
+and one claim can never be counted twice (verified by an 8-process parallel test: exactly
+the configured grants, the next call blocked).
+
+omp payloads moved off argv. PostToolUse Bash payloads embed whole tool outputs and exceed
+macOS's ~256KB-per-argument limit, failing exec with E2BIG before any hook ran. The bridge
+now writes the payload to a temp file (`@path` marker, hourly sweep, inline fallback for
+read-only roots) and `hook-chain-runner.mjs` reads the marker; raw JSON never starts with
+`@`, so both forms stay unambiguous.
+
+Compact recovery, directed. Near-cap advisories now order the work: land the smallest
+finishable item end-to-end, defer the rest as one-line notes to disk, delegate broad
+reads/searches to subagents, then ask the user to compact. A new post-compact check fires
+once per compact boundary when the live context after the boundary is still ≥60% of the
+cap: stop re-reading old files (the fastest way to re-inflate a just-compacted session),
+delegate, or finish in a fresh session — UKit resume state carries the goal across with a
+near-empty window. The reinjected PROJECT CONTEXT block carries the same discipline.
+
+Also fixed: `ukit install|diff --with-codegraph` crashed before the flag was consumed;
+`route-task.mjs` helper commands use POSIX single-quote escaping instead of `JSON.stringify`
+(printed commands were open to `$(...)`/backtick expansion) and reject absolute outside-root
+targets instead of routing foreign-file context.
+
+## 2.3.3 - 2026-09-10
+
+False-stop and long-context release. Four fixes that share one theme: UKit must run a prompt
+to a finished result, and any stop must say why.
+
+Session-bound completion gate. Project-scoped route state could outlive the session-scoped
+execution ledger, so a new session could inherit an older session's completion contract and
+stop with a false `missing write-evidence` message. `skill-router.sh` now binds fresh, cached,
+and route-less state to `sessionId`; `execution-ledger.mjs` accepts route state only when its
+session matches the hook payload and ignores unbound legacy state for session-aware payloads.
+Same-session gating and prompt-scoped evidence carry remain intact. Regression coverage now
+covers mismatched sessions, unbound legacy state, and prior-session route isolation.
+
+Orchestration envelopes no longer corrupt the active route. `<task-notification>`,
+`<tool-result>`, `<system-reminder>`, and `<local-command-caveat>…</local-command-stdout>`
+payloads delivered through the prompt boundary were treated as explicit user prompts,
+rewriting route/cache/audit state mid-run. `skill-router.sh` now ignores complete envelopes
+before routing (fail-open, opening-tag attributes accepted); router exceptions surface on
+stderr instead of disappearing. Related ownership fixes: Stop evaluation loads route state
+with the current session payload, execution-ledger/route-task reject incompatible explicit
+session ownership without inventing identity, subagent tool calls cannot rewrite the main
+route, and cache entries are not touched before ownership is established.
+
+Ordinary long-context tasks preserve and resume. A natural-language routed task with no
+`docs/AI_HANDOFF/RUN.md` previously hit the hard-cap gate with no landing window and no
+resume cursor after compaction. Ordinary ledger state now gets the existing finite
+`hardCapGraceCalls` landing budget (only with explicit session ownership, matching
+session/prompt/request identity, unfinished evidence, and no blocker); the first grace call
+writes a 30-minute hash-only resume intent that `handoff-resume.sh` consumes once and
+emits as a continuation instruction with no raw prompt/command data. The
+`context-window-guard.sh` fallback moved from 220k to the shipped 500k default.
+
+New `vibecode` autonomy level. One typed prompt must run to a finished result: with
+`autonomy.level: vibecode`, the completion gate opts out of the continuation cap entirely and
+keeps blocking (including the reentrant `stop_hook_active` Stop) until completion evidence
+arrives or a genuine blocker is recorded — every block carries its reason. `deriveTaskRoute`
+now propagates `autonomyLevel` and a `continuousExecution` policy
+(`{ enabled, stopOn, maxContinuations }`) into `routeSummary` for every level, and
+`validateRuntimeConfig` accepts the fourth level.
+
+Dangerous commands are a human decision, not a silent block. `block-dangerous.sh` now emits a
+structured `permissionDecision: "ask"` (PreToolUse JSON) with the raw command scrubbed from
+all output — arguments and comments can carry secrets — while exit 2 still refuses the call
+for harnesses that ignore structured output. The omp bridge chain layer translates the same
+structured decision into an `ask` verdict; because omp has no native ask, its host boundary
+surfaces it as a block carrying the decision reason.
+
 ## 2.3.2 - 2026-09-09
 
 Docs-contract release. "Every stop says why — no silent idle" is now a shipping Execution

package/package.json

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

package/src/cli/commands/diff.js

@@ -15,7 +15,7 @@ export async function runDiff({ packageRoot, projectRoot, packageVersion, argv =
     return;
   }
 
-  const toolsArg = parseToolsArg(argv);
+  const toolsArg = parseToolsArg(argv.filter((arg) => arg !== '--with-codegraph'));
   const selectedOptionalTools = resolveOptionalToolKeys(toolsArg);
   const selectedAdapterItemIds = toSelectedAdapterItemIds(selectedOptionalTools);
   const withCodegraph = argv.includes('--with-codegraph');

package/src/cli/commands/install.js

@@ -197,7 +197,10 @@ export async function pruneDeselectedAdapters({
 }
 
 export async function runInstall({ packageRoot, projectRoot, packageVersion, argv = [] }) {
-  const toolsArg = parseToolsArg(argv);
+  // parseToolsArg owns only --tools and throws on anything else, so hand it the argv with
+  // the flags consumed here (--with-codegraph) already removed — order-dependent parsing
+  // used to make the documented `ukit install --with-codegraph` fail 100% of the time.
+  const toolsArg = parseToolsArg(argv.filter((arg) => arg !== '--with-codegraph'));
   const selectedOptionalTools = resolveOptionalToolKeys(toolsArg);
   const withCodegraph = argv.includes('--with-codegraph');
 

package/src/core/runtimeConfig.js

@@ -257,7 +257,7 @@ export function validateRuntimeConfig(config) {
     errors.push('version must be a non-empty string.');
   }
 
-  const VALID_AUTONOMY_LEVELS = new Set(['conservative', 'balanced', 'free-run']);
+  const VALID_AUTONOMY_LEVELS = new Set(['conservative', 'balanced', 'free-run', 'vibecode']);
   if (!isPlainObject(config.autonomy)) {
     errors.push('autonomy must be an object.');
   } else {

package/src/index/taskRouting.js

@@ -240,6 +240,7 @@ export function buildRouteSummary({
     executionCandidates,
   });
   const executionContract = buildExecutionContract(executionMode);
+  const continuousExecution = buildContinuousExecutionPolicy(autonomyLevel);
   const postEditReview = executionContract?.postEditReviewPolicy
     ? { policy: executionContract.postEditReviewPolicy, agent: 'code-reviewer', reviewTargetType: 'diff' }
     : null;
@@ -290,6 +291,8 @@ export function buildRouteSummary({
     completionState,
     postEditReview,
     continuationState,
+    autonomyLevel,
+    continuousExecution,
     intentMode: routingContext.intentMode ?? null,
     handoffFile,
     handoffBudget,
@@ -303,6 +306,19 @@ export function buildRouteSummary({
   };
 }
 
+// Execution-ledger.mjs mirrors this policy for its Stop gate; the two must stay aligned.
+// MAX_CONTINUATIONS (6) below is the same constant the ledger enforces for bounded modes.
+function buildContinuousExecutionPolicy(autonomyLevel) {
+  if (autonomyLevel === 'vibecode') {
+    return {
+      enabled: true,
+      stopOn: ['completion-evidence', 'genuine-blocker', 'dangerous-command-decision'],
+      maxContinuations: null,
+    };
+  }
+  return { enabled: false, maxContinuations: 6 };
+}
+
 function deriveContextMode(taskType) {
   if (taskType === 'trivial' || taskType === 'simple') return 'LITE';
   if (taskType === 'non-trivial' || taskType === 'shared-simple') return 'FULL';

package/templates/.claude/hooks/auto-allow-bash.sh

@@ -3,7 +3,22 @@
 # Optimized: fast-path grep to skip Node.js when rule already exists.
 
 INPUT=$(cat)
-COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+# jq is absent on stock macOS. Keep jq as the low-latency normal path, but fall back to
+# UKit's required Node runtime so safe commands still receive managed metadata.
+if command -v jq >/dev/null 2>&1 && jq --version >/dev/null 2>&1; then
+  COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty')
+else
+  COMMAND=$(printf '%s' "$INPUT" | node -e '
+const chunks = [];
+process.stdin.on("data", (chunk) => chunks.push(chunk));
+process.stdin.on("end", () => {
+  try {
+    const payload = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    process.stdout.write(typeof payload?.tool_input?.command === "string" ? payload.tool_input.command : "");
+  } catch {}
+});
+' 2>/dev/null)
+fi
 
 if [ -z "$COMMAND" ]; then
   exit 0

package/templates/.claude/hooks/block-dangerous.sh

@@ -3,7 +3,22 @@
 # Matched on: Bash
 
 INPUT=$(cat)
-COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+# jq is not installed on stock macOS. Keep jq as the low-latency normal path, but use
+# UKit's required Node runtime as a fallback so its absence cannot silently disable the gate.
+if command -v jq >/dev/null 2>&1 && jq --version >/dev/null 2>&1; then
+  COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty')
+else
+  COMMAND=$(printf '%s' "$INPUT" | node -e '
+const chunks = [];
+process.stdin.on("data", (chunk) => chunks.push(chunk));
+process.stdin.on("end", () => {
+  try {
+    const payload = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    process.stdout.write(typeof payload?.tool_input?.command === "string" ? payload.tool_input.command : "");
+  } catch {}
+});
+' 2>/dev/null)
+fi
 
 if [ -z "$COMMAND" ]; then
   exit 0
@@ -42,31 +57,97 @@ DANGEROUS_PATTERNS=(
   "dd if=/dev/"
 )
 
+# Dangerous detections surface as a structured `ask` decision (stdout JSON) so a human
+# decides; exit 2 still refuses the call for harnesses that ignore structured output.
+# The raw command and the matched pattern are NEVER echoed — arguments and comments can
+# carry secrets, and the pattern text itself restates the dangerous command.
+emit_dangerous_decision() {
+  REASON="$1"
+  printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"$REASON\"}}"
+  echo "BLOCKED: $REASON" >&2
+  exit 2
+}
+
 for pattern in "${DANGEROUS_PATTERNS[@]}"; do
   if echo "$SCAN_COMMAND" | grep -qE "$pattern"; then
-    echo "BLOCKED: Dangerous command detected matching pattern '$pattern'. This command could cause irreversible damage. Ask the user to run it manually if truly needed." >&2
-    exit 2
+    emit_dangerous_decision "Dangerous command pattern detected; it could cause irreversible damage. UKit defers this to a human decision."
   fi
 done
 
-# Handle rm commands: allow safe cleanup targets, block risky recursive force-deletes
-if echo "$SCAN_COMMAND" | grep -qE "(^|[;&|[:space:]])rm([[:space:]]|$)"; then
-  if echo "$SCAN_COMMAND" | grep -qE "rm\s+(-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r|--recursive\s+--force|--force\s+--recursive|--recursive\s+-f|-f\s+--recursive)"; then
-    SAFE_DELETE_REGEX='(^|[[:space:]])(\./)?(dist|build|coverage|\.next|\.nuxt|\.turbo|tmp|temp|\.cache|node_modules)(/|[[:space:]]|$)'
-    UNSAFE_TARGET_REGEX='(^|[[:space:]])(/|~|\.\.?($|/)|\.($|/))'
+# Handle rm commands: allow safe cleanup targets only, defer everything else to a human.
+# Direct rm invocations are parsed per shell segment (`;`, `&`, `|` split) with per-target
+# allowlist evaluation: split flags (`rm -r -f`, `rm --force -r`) register, and one
+# allowlisted word can never legitimise a sibling target (`rm -rf dist /`). A whole-command
+# fallback still catches rm inside wrapped/quoted contexts (`bash -c "rm -r -f /x"`) and
+# flags placed after targets (`rm src -rf`), where segment parsing cannot see rm as a head.
+SAFE_DELETE_REGEX='(^|[[:space:]])(\./)?(dist|build|coverage|\.next|\.nuxt|\.turbo|tmp|temp|\.cache|node_modules)(/|[[:space:]]|$)'
+UNSAFE_TARGET_REGEX='(^|[[:space:]])(/|~|\.\.?($|/)|\.($|/))'
+SAFE_ONE_TARGET_REGEX='^(\./)?(dist|build|coverage|\.next|\.nuxt|\.turbo|tmp|temp|\.cache|node_modules)(/.*)?$'
+UNSAFE_ONE_TARGET_REGEX='^(/.*|~|~/.*|\.\.|\.\./.*|\.)$'
+RM_WORD_REGEX=$'(^|[;&|[:space:]"\x27])rm([[:space:]"\x27]|$)'
 
-    # Check the allowlist first: `./dist` legitimately contains a leading "./" that would
-    # otherwise be mistaken for a bare current-directory target by UNSAFE_TARGET_REGEX below.
-    if echo "$SCAN_COMMAND" | grep -qE "$SAFE_DELETE_REGEX"; then
+RM_VERDICT_UNSAFE=0
+RM_VERDICT_GENERIC=0
+RM_DIRECT_SEEN=0
+set -f
+while IFS= read -r segment; do
+  [ -n "$segment" ] || continue
+  seg_head=$(printf '%s' "$segment" | sed -E 's/^[[:space:]]*//' | awk '{print $1}' | xargs -I{} basename {} 2>/dev/null)
+  [ "$seg_head" = "rm" ] || continue
+  seg_flags=$(printf '%s' "$segment" | awk '{for(i=2;i<=NF;i++){if($i=="--")break;if($i ~ /^-/)printf "%s\n",$i;else break}}')
+  seg_has_r=0
+  seg_has_f=0
+  for flag in $seg_flags; do
+    case "$flag" in
+      --recursive) seg_has_r=1 ;;
+      --force) seg_has_f=1 ;;
+      --*) ;;
+      -*) case "$flag" in *[rR]*) seg_has_r=1 ;; esac
+          case "$flag" in *f*) seg_has_f=1 ;; esac ;;
+    esac
+  done
+  [ "$seg_has_r" -eq 1 ] && [ "$seg_has_f" -eq 1 ] || continue
+  RM_DIRECT_SEEN=1
+  seg_targets=$(printf '%s' "$segment" | awk '{saw=0;for(i=2;i<=NF;i++){if(!saw){if($i=="--"){saw=1;continue}if($i ~ /^-/)continue;saw=1;printf "%s\n",$i}else if($i !~ /^-/)printf "%s\n",$i}}')
+  seg_all_safe=1
+  seg_any_unsafe=0
+  for target in $seg_targets; do
+    # Strip ONE trailing slash so `dist/` matches the allowlist — but never shrink a
+    # bare `/` (or `~`) to an empty string, which would silently dodge the unsafe check.
+    if [ "${#target}" -gt 1 ]; then target="${target%/}"; fi
+    if printf '%s' "$target" | grep -qE "$UNSAFE_ONE_TARGET_REGEX"; then
+      seg_any_unsafe=1
+      seg_all_safe=0
+    elif printf '%s' "$target" | grep -qE "$SAFE_ONE_TARGET_REGEX"; then
       :
-    elif echo "$SCAN_COMMAND" | grep -qE "$UNSAFE_TARGET_REGEX"; then
-      echo "BLOCKED: Unsafe delete target detected. Refusing recursive force-delete." >&2
-      exit 2
     else
-      echo "BLOCKED: 'rm -rf' is only auto-allowed for safe cleanup targets (dist/build/coverage/.next/.nuxt/.turbo/tmp/.cache/node_modules)." >&2
-      exit 2
+      seg_all_safe=0
     fi
+  done
+  if [ "$seg_any_unsafe" -eq 1 ]; then RM_VERDICT_UNSAFE=1
+  elif [ "$seg_all_safe" -eq 0 ]; then RM_VERDICT_GENERIC=1
+  fi
+done <<SEGMENTS
+$(printf '%s' "$SCAN_COMMAND" | tr ';&|' '\n\n\n')
+SEGMENTS
+set +f
+
+if [ "$RM_DIRECT_SEEN" -eq 0 ] && echo "$SCAN_COMMAND" | grep -qE "$RM_WORD_REGEX" \
+  && echo "$SCAN_COMMAND" | grep -qE "(^|[[:space:]])--recursive|(^|[[:space:]])-[a-zA-Z]*[rR]" \
+  && echo "$SCAN_COMMAND" | grep -qE "(^|[[:space:]])--force|(^|[[:space:]])-[a-zA-Z]*f"; then
+  # Unsafe wins over the allowlist here: a safe word elsewhere in the line must never
+  # legitimise an absolute/home/parent target we can also see.
+  if echo "$SCAN_COMMAND" | grep -qE "$UNSAFE_TARGET_REGEX"; then
+    RM_VERDICT_UNSAFE=1
+  elif ! echo "$SCAN_COMMAND" | grep -qE "$SAFE_DELETE_REGEX"; then
+    RM_VERDICT_GENERIC=1
   fi
 fi
 
+if [ "$RM_VERDICT_UNSAFE" -eq 1 ]; then
+  emit_dangerous_decision "Unsafe delete target detected; recursive force-delete could cause irreversible damage. UKit defers this to a human decision."
+elif [ "$RM_VERDICT_GENERIC" -eq 1 ]; then
+  emit_dangerous_decision "Recursive force-delete outside safe cleanup targets (dist/build/coverage/.next/.nuxt/.turbo/tmp/.cache/node_modules) is destructive. UKit defers this to a human decision."
+fi
+
 exit 0

package/templates/.claude/hooks/context-hardcap-gate.sh

@@ -1,9 +1,9 @@
 #!/bin/bash
 # PreToolUse hook: hard-enforce an absolute context token cap (compact.hardCapTokens,
-# default 220000, sized for a 256k window — must stay below the model's real context
-# window, so lower it on a 200k model), separate from the
+# default 500000, sized for a 1M window — must stay below the model's real context
+# window, so lower it on a 200k/256k model), separate from the
 # soft/hard advisory pressure phases in
-# compact-threshold.mjs (default soft=50000/hard=80000, which only print a suggestion).
+# compact-threshold.mjs (default soft=150000/hard=240000, which only print a suggestion).
 #
 # Those advisory phases are just injected text — nothing stops the agent from ignoring
 # them and letting a session run to hundreds of thousands of tokens with no compaction.
@@ -18,12 +18,13 @@
 # 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.
+# past the cap strands a handoff run or ordinary routed task mid-edit — files half-written,
+# no durable completion state — which is strictly worse than letting it land. When RUN.md
+# shows an unfinished handoff run, or the shared ledger proves an unfinished session-bound
+# ordinary task, the gate allows a BOUNDED number of further calls so it can land the current
+# edit/verification and persist resume state; 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 task 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.
@@ -74,7 +75,7 @@ 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;
+    if (!runPhase || /^done\b/i.test(runPhase)) return null;
     return {
       phase: runPhase,
       cursor: (text.match(/^Cursor:\s*(.+)$/m)?.[1] || '').trim(),
@@ -98,6 +99,10 @@ function readRunCursor() {
   }
 
   const mod = await import(pathToFileURL(thresholdModulePath).href);
+  const ledgerModulePath = path.join(hookDir, '..', 'ukit', 'runtime', 'execution-ledger.mjs');
+  const ledgerMod = fs.existsSync(ledgerModulePath)
+    ? await import(pathToFileURL(ledgerModulePath).href)
+    : null;
   const pressurePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'compact-pressure.json');
   const rawState = readJsonSafe(pressurePath, null);
 
@@ -117,49 +122,134 @@ function readRunCursor() {
   }
   const thresholds = mod.buildCompactThresholds(config);
 
+  // The grace budget must survive parallel subagents hitting the cap in the same episode.
+  // A read-modify-write of one JSON file under-counts (two processes both read used=3 and
+  // both write 4, silently multiplying the budget), so each spent call is claimed with an
+  // exclusive-create sentinel file (openSync 'wx'): the sentinels present ARE the number
+  // of grace calls spent, and one claim can never be counted twice.
   const gracePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'hardcap-grace.json');
+  const graceDir = path.dirname(gracePath);
+  const slotPath = (n) => path.join(graceDir, `hardcap-grace.json.${n}`);
+  const readSlots = () => {
+    try {
+      return fs.readdirSync(graceDir)
+        .map((name) => /^hardcap-grace\.json\.(\d+)$/.exec(name))
+        .filter(Boolean)
+        .map((m) => Number(m[1]))
+        .sort((a, b) => a - b);
+    } catch {
+      return [];
+    }
+  };
+  const clearGrace = () => {
+    try { fs.rmSync(gracePath, { force: true }); } catch { /* advisory only */ }
+    for (const n of readSlots()) {
+      try { fs.rmSync(slotPath(n), { force: true }); } catch { /* advisory only */ }
+    }
+  };
 
   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 });
+    clearGrace();
     process.exit(0);
     return;
   }
 
   const run = readRunCursor();
-  if (run) {
+  let ordinaryTask = null;
+  if (!run && ledgerMod) {
+    try {
+      ordinaryTask = await ledgerMod.readResumableExecution(projectRoot, payload);
+    } catch {
+      ordinaryTask = null;
+    }
+  }
+  const resumable = run || ordinaryTask;
+  if (resumable) {
     const graceCalls = Number.isFinite(config?.compact?.hardCapGraceCalls)
       ? config.compact.hardCapGraceCalls
       : 10;
-    const prior = readJsonSafe(gracePath, null);
+
+    let slots = readSlots();
+    let startedAtTokens = null;
+    for (const n of slots) {
+      const data = readJsonSafe(slotPath(n), null);
+      if (data && Number.isFinite(data.startedAtTokens)) {
+        startedAtTokens = Math.max(startedAtTokens ?? -Infinity, data.startedAtTokens);
+      }
+    }
     // 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 (startedAtTokens !== null && state.estimatedTotalTokens < startedAtTokens) {
+      clearGrace();
+      slots = [];
+      startedAtTokens = null;
+    }
+    const spent = slots.length > 0 ? slots[slots.length - 1] : 0;
+    if (startedAtTokens === null) startedAtTokens = state.estimatedTotalTokens;
 
-    if (carried.used < graceCalls) {
-      const used = carried.used + 1;
+    if (spent < graceCalls) {
+      // Claim the next slot atomically: EEXIST means a parallel worker already claimed it,
+      // step to the next. A filesystem error keeps the old fail-open behavior — losing the
+      // counter must never block a landing — at the cost of one extra granted call.
+      let used = 0;
+      let counterFailed = false;
       try {
-        fs.mkdirSync(path.dirname(gracePath), { recursive: true });
-        fs.writeFileSync(gracePath, JSON.stringify({ ...carried, used }));
+        fs.mkdirSync(graceDir, { recursive: true });
+        for (let n = spent + 1; n <= graceCalls; n += 1) {
+          try {
+            const fd = fs.openSync(slotPath(n), 'wx');
+            fs.writeSync(fd, JSON.stringify({ startedAtTokens, used: n, ts: Date.now() }));
+            fs.closeSync(fd);
+            used = n;
+            break;
+          } catch (err) {
+            if (err?.code === 'EEXIST') continue;
+            throw err;
+          }
+        }
       } catch {
-        // Losing the counter must not block the run; worst case grace restarts.
+        counterFailed = true;
+      }
+      if (used === 0 && counterFailed) used = spent + 1;
+      if (used > 0 && used <= graceCalls) {
+        try {
+          fs.writeFileSync(gracePath, JSON.stringify({ startedAtTokens, used }));
+          if (ordinaryTask && ledgerMod && used === 1) {
+            await ledgerMod.writeResumeIntent(projectRoot, payload);
+          }
+        } catch {
+          // Losing the counter or advisory resume intent must not block the run.
+        }
+        const landing = run
+          ? `An unfinished handoff run is in flight (Phase: ${run.phase}${run.cursor ? `, Cursor: ${run.cursor}` : ''}), so this call is allowed instead of stranding it mid-edit.`
+          : 'An unfinished ordinary routed task is in flight, so this call is allowed instead of stranding it before compaction.';
+        process.stderr.write(
+          [
+            `CONTEXT OVER CAP — grace ${used}/${graceCalls} (~${state.estimatedTotalTokens} tokens >= ${thresholds.hardCapTokens}).`,
+            landing,
+            run
+              ? 'Spend the remaining grace on LANDING, not on new work: finish the current edit, commit, update docs/AI_HANDOFF/RUN.md, push.'
+              : 'Spend the remaining grace on LANDING, not on new work: finish the current mutation or verification, then compact as soon as the host allows it.',
+            'Do NOT start a new task, open new files, or spawn agents. When grace runs out the gate blocks hard.',
+            'Tell the user in your reply that context is over the cap and they should run /compact as soon as this landing step is complete.',
+            'After compaction, the SessionStart resume hook replays the safe cursor and the task continues automatically.',
+          ].join('\n') + '\n',
+        );
+        // The stderr contract above only reaches the model — if the turn dies before the
+        // model relays it, the user sees nothing. Mirror the first grace call as a
+        // structured systemMessage so the /compact advice is user-visible regardless.
+        if (used === 1) {
+          process.stdout.write(`${JSON.stringify({
+            systemMessage: `UKit: context is over the hard cap (~${state.estimatedTotalTokens} tokens). A short landing window (${graceCalls} calls) is active — run /compact when it ends; the task resumes automatically after compaction.`,
+          })}\n`);
+        }
+        process.exit(0);
+        return;
       }
-      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.',
-          'Tell the user in your reply that context is over the cap and they should run /compact as soon as this run lands.',
-          'After the user runs /compact, the SessionStart resume hook replays the cursor and the run continues automatically.',
-        ].join('\n') + '\n',
-      );
-      process.exit(0);
-      return;
+      // Every slot was claimed while we raced — the budget is genuinely spent; fall
+      // through to the hard block below.
     }
   }
 
@@ -169,12 +259,17 @@ function readRunCursor() {
     'Typing "continue" alone will hit this same block; only /compact (or a new session) resets the counter. After compacting, resume the interrupted task.',
     '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
+    resumable
       ? '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.',
+      : 'No resumable unfinished routed task was found, so there is no grace window to spend.',
     'Do not work around this by summarizing inline and continuing, and do not reach for a non-gated write tool.',
   ];
   process.stderr.write(`${lines.join('\n')}\n`);
+  // stderr reaches the model, not reliably the user. Pair the hard block with a
+  // structured systemMessage so "why did it stop" always has a user-visible answer.
+  process.stdout.write(`${JSON.stringify({
+    systemMessage: `UKit blocked ${toolName}: context is over the hard cap (~${state.estimatedTotalTokens} tokens >= ${thresholds.hardCapTokens}) and the landing window is spent. Run /compact now; after compaction the task continues automatically.`,
+  })}\n`);
   process.exit(2);
 })().catch((err) => {
   // A logic error here fails OPEN: this is a backstop on top of advisory nudges,