@ngockhoale/ukit 2.3.2 → 2.3.4

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

@@ -75,7 +75,7 @@ function loadHardCap() {
     const value = JSON.parse(raw)?.compact?.hardCapTokens;
     if (Number.isFinite(value) && value > 0) return value;
   } catch { /* fall through to the default */ }
-  return 220_000;
+  return 500_000;
 }
 
 let text;
@@ -94,12 +94,14 @@ if (truncated) lines.shift(); // a tail read almost certainly split the first li
 // Everything before the last compact boundary is already summarised away and is NOT in
 // the live context. Counting it is what makes naive file-size estimates useless.
 let start = 0;
+let boundaryTs = null;
 for (let i = lines.length - 1; i >= 0; i -= 1) {
   if (!lines[i].includes('compact_boundary')) continue;
   try {
     const entry = JSON.parse(lines[i]);
     if (entry?.type === 'system' && entry?.subtype === 'compact_boundary') {
       start = i + 1;
+      boundaryTs = Date.parse(entry.timestamp) || null;
       break;
     }
   } catch { /* not a usable boundary line */ }
@@ -200,6 +202,31 @@ if (swapDetected && persistedState.lastSwapModel !== currentModel) {
   }
 }
 
+// ── Post-compact shrink check ──
+// Compaction only helps if the live context AFTER the boundary is actually small. When the
+// prompts right after a fresh compact already measure >= 60% of the cap, the summary did
+// not shrink the session enough — and re-compacting the same session recovers very little.
+// The honest recovery moves are: stop re-inflating it with rereads, delegate broad work to
+// subagents (separate windows), or finish in a FRESH session (UKit resume state carries
+// the goal across). Fires once per compact boundary.
+const POST_COMPACT_RATIO = 0.6;
+const POST_COMPACT_WINDOW_MS = 10 * 60 * 1000;
+const boundaryAgeMs = boundaryTs !== null ? Date.now() - boundaryTs : null;
+const justCompacted = boundaryAgeMs !== null && boundaryAgeMs >= 0 && boundaryAgeMs < POST_COMPACT_WINDOW_MS;
+if (justCompacted && ratio >= POST_COMPACT_RATIO && persistedState.lastPostCompactBoundary !== String(boundaryTs)) {
+  persistedState.lastPostCompactBoundary = String(boundaryTs);
+  writeGuardState(persistedState);
+  process.stdout.write(
+    [
+      `UKIT POST-COMPACT CHECK — compaction ~${Math.max(1, Math.round(boundaryAgeMs / 60000))} min ago, but live context is still ~${estimatedTokens.toLocaleString()} tokens (${Math.round(ratio * 100)}% of the ${hardCap.toLocaleString()} cap).`,
+      'The compact did not shrink this session enough. Recover context now, in this order:',
+      '1) STOP re-reading old files, logs and tool outputs — durable state is in the PROJECT CONTEXT block or on disk. Rereads are what re-inflate a just-compacted session.',
+      '2) DELEGATE remaining broad work (searches, big reads, multi-file edits) to subagents: their tool output lives in their own windows; keep this context for decisions and short summaries only.',
+      '3) If substantial work still remains: land the current step, persist docs/STATUS.md, then ask the user to start a FRESH session — UKit resume state carries the goal forward with a near-empty window. Another /compact here recovers far less.',
+    ].join('\n') + '\n',
+  );
+}
+
 if (ratio < 0.8) process.exit(0);
 
 const pct = Math.round(ratio * 100);
@@ -226,7 +253,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(),
@@ -261,9 +288,10 @@ if (withinCooldown) {
   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.');
-  lines_out.push('2) If the remaining work still has multiple steps or pipeline phases left, split what remains into bounded docs/AI_HANDOFF tasks instead of continuing in this one thread — smaller phases keep each turn under the cap.');
-  lines_out.push('3) Otherwise, make the user\'s next action the FIRST sentence of your reply so it cannot be missed: "Context sắp đầy — gõ /compact ngay (run /compact now)", or wrap up and start a fresh session — work already committed/persisted to disk is not lost. Do not keep working silently until tools start being refused.');
+  lines_out.push('1) LAND ONE THING: pick the smallest in-flight item you can finish end-to-end in ≤3 tool calls (edit + verify), complete exactly that one, and report it done. Do not open anything new.');
+  lines_out.push('2) DEFER THE REST: write each remaining step as one line into docs/STATUS.md (update-status skill), or split what remains into bounded docs/AI_HANDOFF tasks — a fresh context then continues from disk without re-reading this thread.');
+  lines_out.push('3) DELEGATE anything broad that must still run (searches, big reads, multi-file edits) to subagents instead of doing it inline — their tool output stays in their own windows, not this one.');
+  lines_out.push('4) Then make the user\'s next action the FIRST sentence of your reply: "Context sắp đầy — gõ /compact ngay (run /compact now)". After /compact UKit auto-resumes from disk; if the compacted session is still large, ask for a fresh session instead. Do not keep working silently until tools start being refused.');
   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.`);
   }

package/templates/.claude/hooks/handoff-model-guard.sh

@@ -39,6 +39,13 @@ const input = payload?.tool_input || {};
 
 function block(message) {
   process.stderr.write(`BLOCKED (handoff model-tier guard): ${message}\n`);
+  // stderr reaches the model, not reliably the user. Pair the refusal with a structured
+  // systemMessage (first line only — the full problem list stays in stderr) so a
+  // handoff-contract block never looks like a silent stall in the UI.
+  const firstLine = String(message).split('\n').find((l) => l.trim()) || 'model-tier contract violated';
+  process.stdout.write(`${JSON.stringify({
+    systemMessage: `UKit handoff model-tier guard refused this action: ${firstLine.trim()}`,
+  })}\n`);
   process.exit(2);
 }
 

package/templates/.claude/hooks/handoff-resume.sh

@@ -25,6 +25,7 @@ PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE' || true
 const fs = require('fs');
 const path = require('path');
+const { pathToFileURL } = require('url');
 
 const payload = (() => {
   try {
@@ -37,54 +38,84 @@ const payload = (() => {
 
 const projectRoot = process.env.PROJECT_ROOT;
 const runPath = path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md');
+const runtimePath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'execution-ledger.mjs');
+const source = typeof payload.source === 'string' ? payload.source : 'startup';
 
-let text;
-try {
-  text = fs.readFileSync(runPath, 'utf8');
-} catch {
-  // No cursor file: nothing was running, or the last cycle was cleared. Stay silent —
-  // a resume banner on every ordinary session start would be pure noise.
-  process.exit(0);
+async function emitOrdinaryResume() {
+  if (!fs.existsSync(runtimePath)) return false;
+  try {
+    const runtime = await import(pathToFileURL(runtimePath).href);
+    const intent = await runtime.readResumeIntent(projectRoot, payload, { consume: true });
+    if (!intent) return false;
+    const out = [
+      'UKIT ROUTED TASK RESUME — an unfinished ordinary routed task was preserved before context compaction.',
+      '',
+      'This is a CONTINUATION, not a new request. Do not re-plan or ask whether to continue.',
+      'Resume the current routed task from its existing route state and execution ledger.',
+      'Use one bounded source/context slice if needed, then execute the next missing edit or verification milestone.',
+    ];
+    if (source === 'compact') {
+      out.push('');
+      out.push('The session was just compacted, so the window is clean — resume immediately rather than reporting status and waiting.');
+    }
+    process.stdout.write(`${out.join('\n')}\n`);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
-const field = (name) => (text.match(new RegExp(`^${name}:\\s*(.+)$`, 'm'))?.[1] || '').trim();
+(async () => {
+  let text;
+  try {
+    text = fs.readFileSync(runPath, 'utf8');
+  } catch {
+    // No handoff cursor: an ordinary routed-task intent may still be resumable.
+    await emitOrdinaryResume();
+    process.exit(0);
+  }
 
-const phase = field('Phase');
-// `done` means the last cycle finished cleanly. Anything else means a step was in flight.
-if (!phase || /^done$/i.test(phase)) process.exit(0);
+  const field = (name) => (text.match(new RegExp(`^${name}:\\s*(.+)$`, 'm'))?.[1] || '').trim();
 
-const goal = field('Goal');
-const base = field('Base');
-const cursor = field('Cursor');
-const next = field('Next');
-const source = typeof payload.source === 'string' ? payload.source : 'startup';
+  const phase = field('Phase');
+  // `done` means the last cycle finished cleanly. Anything else means a step was in flight.
+  if (!phase || /^done\b/i.test(phase)) {
+    await emitOrdinaryResume();
+    process.exit(0);
+  }
 
-const out = [
-  'UKIT HANDOFF RESUME — an unfinished handoff-fullstack run was found on disk.',
-  `  Goal:   ${goal || '(not recorded)'}`,
-  `  Base:   ${base || '(not recorded)'}`,
-  `  Phase:  ${phase}`,
-  `  Cursor: ${cursor || '(not recorded)'}`,
-  `  Next:   ${next || '(not recorded)'}`,
-  '',
-  'This is a CONTINUATION, not a new cycle. Do not re-plan, do not overwrite PLAN.md or the',
-  'task files, and do not ask the user whether to continue — they already asked for a',
-  'one-shot run and the pipeline was interrupted, not cancelled.',
-  '',
-  'Read docs/AI_HANDOFF/RUN.md and docs/AI_HANDOFF/INDEX.md, then execute the `Next:` step',
-  'above using .claude/commands/ukit/handoff-fullstack.md as the procedure. Skip tasks',
-  'already `done` or `pending_review`; pick up `ready`, `in_progress`, `changes_requested`',
-  'and `blocked` ones. Keep writing the cursor after every step.',
-];
+  const goal = field('Goal');
+  const base = field('Base');
+  const cursor = field('Cursor');
+  const next = field('Next');
 
-if (source === 'compact') {
-  out.push('');
-  out.push('The session was just compacted, so the window is clean — this is the ideal moment');
-  out.push('to continue. Resume immediately rather than reporting status and waiting.');
-}
+  const out = [
+    'UKIT HANDOFF RESUME — an unfinished handoff-fullstack run was found on disk.',
+    `  Goal:   ${goal || '(not recorded)'}`,
+    `  Base:   ${base || '(not recorded)'}`,
+    `  Phase:  ${phase}`,
+    `  Cursor: ${cursor || '(not recorded)'}`,
+    `  Next:   ${next || '(not recorded)'}`,
+    '',
+    'This is a CONTINUATION, not a new cycle. Do not re-plan, do not overwrite PLAN.md or the',
+    'task files, and do not ask the user whether to continue — they already asked for a',
+    'one-shot run and the pipeline was interrupted, not cancelled.',
+    '',
+    'Read docs/AI_HANDOFF/RUN.md and docs/AI_HANDOFF/INDEX.md, then execute the `Next:` step',
+    'above using .claude/commands/ukit/handoff-fullstack.md as the procedure. Skip tasks',
+    'already `done` or `pending_review`; pick up `ready`, `in_progress`, `changes_requested`',
+    'and `blocked` ones. Keep writing the cursor after every step.',
+  ];
 
-process.stdout.write(`${out.join('\n')}\n`);
-process.exit(0);
+  if (source === 'compact') {
+    out.push('');
+    out.push('The session was just compacted, so the window is clean — this is the ideal moment');
+    out.push('to continue. Resume immediately rather than reporting status and waiting.');
+  }
+
+  process.stdout.write(`${out.join('\n')}\n`);
+  process.exit(0);
+})();
 NODE
 
 exit 0

package/templates/.claude/hooks/protect-files.sh

@@ -3,7 +3,22 @@
 # Matched on: Edit|Write
 
 INPUT=$(cat)
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+# jq is absent on stock macOS. Keep jq as the low-latency normal path, but fall back to
+# UKit's required Node runtime so a missing optional binary cannot disable this gate.
+if command -v jq >/dev/null 2>&1 && jq --version >/dev/null 2>&1; then
+  FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')
+else
+  FILE_PATH=$(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?.file_path === "string" ? payload.tool_input.file_path : "");
+  } catch {}
+});
+' 2>/dev/null)
+fi
 
 if [ -z "$FILE_PATH" ]; then
   exit 0
@@ -16,23 +31,32 @@ if [[ "$BASENAME" == ".env.example" ]]; then
   exit 0
 fi
 
-PROTECTED_PATTERNS=(
-  ".env"
-  ".env.local"
-  ".env.production"
-  "package-lock.json"
-  "yarn.lock"
-  ".git/"
-  "node_modules/"
-  ".claude/settings.local.json"
-  ".ukit/storage/security/"
-)
+# Match exact sensitive filenames and directory components, never arbitrary substrings:
+# `.env.d.ts` and `app.envrc` are source files, not secrets. The old `*".env"*`
+# check blocked both, which could appear as a mysterious stopped edit.
+PATH_SLASHED="/${FILE_PATH#/}"
+PROTECTED_MATCH=""
+case "$BASENAME" in
+  .env|.env.local|.env.production|package-lock.json|yarn.lock)
+    PROTECTED_MATCH="$BASENAME"
+    ;;
+esac
+if [ -z "$PROTECTED_MATCH" ]; then
+  case "$PATH_SLASHED" in
+    */.git/*) PROTECTED_MATCH=".git/" ;;
+    */node_modules/*) PROTECTED_MATCH="node_modules/" ;;
+    */.claude/settings.local.json) PROTECTED_MATCH=".claude/settings.local.json" ;;
+    */.ukit/storage/security/*) PROTECTED_MATCH=".ukit/storage/security/" ;;
+  esac
+fi
 
-for pattern in "${PROTECTED_PATTERNS[@]}"; do
-  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
-    echo "BLOCKED: Cannot modify '$FILE_PATH' — matches protected pattern '$pattern'. Ask the user to modify this file manually." >&2
-    exit 2
-  fi
-done
+if [ -n "$PROTECTED_MATCH" ]; then
+  # A stderr-only refusal can look like a silent stall when the host does not render
+  # hook stderr. Do not expose the path/pattern on stdout: the generic explanation is
+  # enough for the user and avoids leaking a potentially sensitive filename.
+  printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"UKit protected-file guard blocked this edit. Ask the user to modify the protected file manually."}}'
+  echo "BLOCKED: Cannot modify '$FILE_PATH' — matches protected pattern '$PROTECTED_MATCH'. Ask the user to modify this file manually." >&2
+  exit 2
+fi
 
 exit 0

package/templates/.claude/hooks/sensitive-data-guard.sh

@@ -163,8 +163,18 @@ function scanBashShapes(command) {
       }
     }
 
-    if (/(^|\s)(-u|--user)\s+["']?[^\s"':]+:[^\s"']+/.test(segment)) {
-      found.push({ label: 'curl/wget inline credentials (-u user:password)', value: segment });
+    // `-u/--user user:pass` is only credentials on tools that authenticate with it.
+    // The same flag shape on docker/runuser/chown (`--user 1000:1000`, a uid:gid pair)
+    // is NOT a secret — matching it anyway false-positives every containerised test run.
+    const headBase = head.replace(/^.*\//, '');
+    const CRED_USER_TOOLS = new Set(['curl', 'wget', 'ftp', 'lftp', 'aria2c', 'http', 'https']);
+    const inlineUser = /(^|\s)(-u|--user)\s+["']?([^\s"':]+):([^\s"']+)/.exec(segment);
+    if (inlineUser && CRED_USER_TOOLS.has(headBase)) {
+      // Even on credential tools, a purely numeric pair is a uid:gid, not a password.
+      const numericIds = /^\d+$/.test(inlineUser[3]) && /^\d+$/.test(inlineUser[4]);
+      if (!numericIds) {
+        found.push({ label: 'curl/wget inline credentials (-u user:password)', value: segment });
+      }
     }
     if (/https?:\/\/[^\s/@'"]+:[^\s/@'"]+@/.test(segment)) {
       found.push({ label: 'URL with embedded credentials (user:pass@host)', value: segment });
@@ -263,6 +273,12 @@ const lines = [
   'Never repeat or guess the detected value in your reply. Ask the user instead.',
 ];
 process.stderr.write(`${lines.join('\n')}\n`);
+// stderr reaches the model; the user needs a stop reason they can actually see. Emit a
+// structured systemMessage (redacted — labels only, never the matched value) so a
+// sensitive-data block never looks like a silent stall in the UI.
+process.stdout.write(`${JSON.stringify({
+  systemMessage: `UKit blocked this call: ${findings.length} potential secret(s) detected (${findings.map((f) => f.label).slice(0, 3).join('; ')}${findings.length > 3 ? '; …' : ''}). Redact the value, allowlist its sha256, or ask the user to decide.`,
+})}\n`);
 process.exit(2);
 NODE
 

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

@@ -5,6 +5,34 @@
 INPUT=$(cat)
 PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 
+# Internal orchestration envelopes are not user requests. Ignore them before routing or
+# compact-pressure bookkeeping so task results cannot replace the active completion contract.
+case "$INPUT" in
+  *"<task-notification"*|*"<tool-result"*|*"<system-reminder"*|*"<local-command-caveat"*)
+    INTERNAL_ORCHESTRATION=$(INPUT="$INPUT" node -e '
+try {
+  const payload = JSON.parse(process.env.INPUT || "{}");
+  const candidates = [payload?.prompt, payload?.user_prompt, payload?.text, payload?.message, payload?.input]
+    .filter((value) => typeof value === "string")
+    .map((value) => value.trim());
+  const block = (name) => new RegExp(`^<${name}(?:\\s[^>]*)?>[\\s\\S]*<\\/${name}>$`, "i");
+  const internal = candidates.some((value) => (
+    block("task-notification").test(value)
+    || block("tool-result").test(value)
+    || block("system-reminder").test(value)
+    || /^<local-command-caveat(?:\s[^>]*)?>[\s\S]*<\/local-command-stdout>$/i.test(value)
+  ));
+  process.stdout.write(internal ? "1" : "0");
+} catch {
+  process.stdout.write("0");
+}
+' 2>/dev/null)
+    if [ "$INTERNAL_ORCHESTRATION" = "1" ]; then
+      exit 0
+    fi
+    ;;
+esac
+
 # Worktree early-exit: when the tool call is scoped to a disposable .worktrees/task-*
 # tree, there is nothing to route — exit before spawning the router. Reads
 # tool_input.file_path / tool_input.path / tool_input.command (never tool_input.pattern).
@@ -2367,8 +2395,6 @@ const { pathToFileURL } = require('url');
   const routeCachePath = path.join(projectRoot, '.claude', 'ukit', 'route-cache.json');
   const routeAuditPath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'route-audit.json');
   const cacheUtilsPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'cache-utils.mjs');
-  const previous = readJson(statePath, {});
-  const runtimeConfig = loadRuntimeConfig(projectRoot);
 
   let payload = {};
   try {
@@ -2377,6 +2403,20 @@ const { pathToFileURL } = require('url');
     payload = {};
   }
 
+  const sessionCandidate = payload.session_id ?? payload.sessionId;
+  const sessionId = sessionCandidate === undefined || sessionCandidate === null
+    ? null
+    : String(sessionCandidate).trim() || null;
+  const storedPrevious = readJson(statePath, {});
+  // Route state is project-local, while hook ledgers are session-local. Do not let a
+  // differently-bound snapshot become the contract for a new session.
+  const previous = sessionId
+    ? (storedPrevious?.sessionId && String(storedPrevious.sessionId).trim() === sessionId
+      ? storedPrevious
+      : {})
+    : storedPrevious;
+  const runtimeConfig = loadRuntimeConfig(projectRoot);
+
   const promptText = extractPrompt(payload);
   const commandText = payload.tool_input?.command || payload.command || '';
   const filePath = normalizeRelativeFile(projectRoot, payload.tool_input?.file_path || payload.file_path || '');
@@ -2447,6 +2487,7 @@ const { pathToFileURL } = require('url');
     // whether a Stop is premature. Downgrading to a route-less state here silently disarms
     // the gate mid-task, so carry the previous route forward until a real route replaces it.
     fs.writeFileSync(statePath, JSON.stringify({
+      ...(sessionId ? { sessionId } : {}),
       fingerprint,
       ts: now,
       source: 'skill-router',
@@ -2539,6 +2580,34 @@ const { pathToFileURL } = require('url');
     routingContext,
     previousContextFingerprint: previousContext?.fingerprint || null,
   });
+  // Persist the completion contract BEFORE any cache import or indexed-context resolution.
+  // Those later steps can take longer than the host's PreToolUse hook timeout. Previously a
+  // timeout killed this process before its only state write, and completion-gate.sh then had
+  // no route to evaluate — so it released Stop with no message. This provisional state has
+  // the full execution/evidence contract; the final richer state below atomically replaces it.
+  const provisionalRouteSummary = buildRouteSummary({
+    activeSkills: selected,
+    routingContext,
+  });
+  provisionalRouteSummary.continuationState = advanceContinuationState(
+    provisionalRouteSummary.continuationState,
+    previous?.routeSummary?.continuationState || null,
+  );
+  applyRescueBiasToRouteSummary(provisionalRouteSummary);
+  const provisionalState = {
+    ...(sessionId ? { sessionId } : {}),
+    requestKey,
+    ts: now,
+    source: 'skill-router-provisional',
+    activeSkills: compactActiveSkills(selected),
+    routingContext: compactRoutingContext(routingContext),
+    ...(previousContext ? { previousContext: compactPreviousContext(previousContext) } : {}),
+    routeSummary: compactRouteSummary(provisionalRouteSummary),
+  };
+  provisionalState.fingerprint = buildRouteStateFingerprint(provisionalState);
+  ensureDir(statePath);
+  fs.writeFileSync(statePath, JSON.stringify(provisionalState));
+
   let cacheUtils = null;
   if (fs.existsSync(cacheUtilsPath)) {
     try {
@@ -2562,8 +2631,12 @@ const { pathToFileURL } = require('url');
         touch: true,
       })
     : null;
+  const sessionCompatibleCachedRoute = !sessionId
+    || Boolean(cachedRouteState?.sessionId)
+      && String(cachedRouteState.sessionId).trim() === sessionId;
   if (
-    cachedRouteState?.requestKey === requestKey
+    sessionCompatibleCachedRoute
+    && cachedRouteState?.requestKey === requestKey
     && cachedRouteState?.routeSummary
     && Array.isArray(cachedRouteState?.activeSkills)
   ) {
@@ -2581,6 +2654,7 @@ const { pathToFileURL } = require('url');
     }
     const reusedState = {
       ...cachedRouteState,
+      ...(sessionId ? { sessionId } : {}),
       source: 'skill-router',
       ts: now,
       requestKey,
@@ -2671,6 +2745,7 @@ const { pathToFileURL } = require('url');
     routeSummary,
   });
   const sharedState = {
+    ...(sessionId ? { sessionId } : {}),
     requestKey,
     fingerprint,
     ts: now,
@@ -2709,7 +2784,9 @@ const { pathToFileURL } = require('url');
     ) {
       process.stdout.write(`[ukit-skill-router] Helper: ${routeSummary.helperHint}\n`);
     }
-})().catch(() => {
+})().catch((error) => {
+  const detail = error?.message || String(error);
+  process.stderr.write(`[ukit-skill-router] ${detail}\n`);
   process.exit(0);
 });
 NODE