@ngockhoale/ukit 3.4.0 → 3.4.2

package/template_project/.claude/hooks/sensitive-data-guard.mjs

@@ -220,20 +220,319 @@ async function evaluate({ rawInput, projectRoot, env }) {
     'base64', 'od', 'hexdump', 'bat', 'grep', 'egrep', 'fgrep', 'rg', 'awk', 'sed',
   ]);
 
-  const scanBashShapes = (command) => {
+  // W2-D03: token normalisation must mirror what the shell does to a word
+  // before the dump verb sees it. Quote modes are tracked so a QUOTED
+  // backslash stays literal — bash keeps `\` inside quotes, so `'C:\x\.env'`
+  // (Windows/git-bash path) must still classify to `.env` — while an unquoted
+  // `.e\nv` still folds to `.env`. Backticks survive dequoting: they delimit
+  // substitutions, which removeSubstSpans below cuts out of the class view.
+  const DQ_ESCAPABLE = '"$`\\\n';
+  const stripQuotes = (token) => {
+    const src = String(token ?? '');
+    let out = '';
+    let i = 0;
+    while (i < src.length) {
+      const ch = src[i];
+      if (ch === "'") {
+        // Single quotes: fully literal to the next '. Unterminated consumes
+        // the rest (bash would reject; classify the pessimistic view).
+        const end = src.indexOf("'", i + 1);
+        out += src.slice(i + 1, end === -1 ? src.length : end);
+        i = end === -1 ? src.length : end + 1;
+        continue;
+      }
+      if (ch === '"') {
+        // Double quotes: `\` escapes only before " $ ` \ newline; it is
+        // literal otherwise — `"C:\x"` must keep its backslash.
+        i += 1;
+        while (i < src.length && src[i] !== '"') {
+          if (src[i] === '\\' && i + 1 < src.length && DQ_ESCAPABLE.includes(src[i + 1])) {
+            out += src[i + 1];
+            i += 2;
+            continue;
+          }
+          out += src[i];
+          i += 1;
+        }
+        i += 1;
+        continue;
+      }
+      if (ch === '\\') {
+        // Unquoted escape: drops the backslash, keeps the next char.
+        i += 1;
+        if (i < src.length) {
+          out += src[i];
+          i += 1;
+        }
+        continue;
+      }
+      out += ch;
+      i += 1;
+    }
+    return out;
+  };
+  // Substitution spans contribute their EXPANSION, which the scanner cannot
+  // know — classify the word with the span removed (fail-closed: `.env$(:)`,
+  // `.env$()` and `.env`:` splice onto a protected name exactly like the
+  // shell's empty expansion). `$(`/`${` spans are balanced so an inner `)`/`}`
+  // cannot truncate early; an unterminated span consumes the rest. The span's
+  // own body was already scanned by extractSubstBodies, so nothing hides in
+  // the removed text. Unbraced `$name`/`$1`/`$$` refs drop the same way —
+  // `$f.env` is `${f}.env` to the shell.
+  const removeSubstSpans = (token) => {
+    const src = String(token ?? '');
+    let out = '';
+    let i = 0;
+    while (i < src.length) {
+      const ch = src[i];
+      if (ch === '$' && (src[i + 1] === '(' || src[i + 1] === '{')) {
+        const open = src[i + 1];
+        const close = open === '(' ? ')' : '}';
+        let depth = 1;
+        let j = i + 2;
+        while (j < src.length && depth > 0) {
+          const b = src[j];
+          if (b === '\\') { j += 2; continue; }
+          if (b === open) depth += 1;
+          if (b === close) depth -= 1;
+          j += 1;
+        }
+        i = j; // unterminated: j === src.length consumes the rest
+        continue;
+      }
+      if (ch === '`') {
+        const end = src.indexOf('`', i + 1);
+        i = end === -1 ? src.length : end + 1;
+        continue;
+      }
+      if (ch === '$') {
+        const name = /^\$[A-Za-z_][A-Za-z0-9_]*|^\$[?@$*#!0-9-]/.exec(src.slice(i));
+        if (name) {
+          i += name[0].length;
+          continue;
+        }
+      }
+      out += ch;
+      i += 1;
+    }
+    return out;
+  };
+  // Classification view of a token: real shell dequote, substitution spans
+  // gone, plus the edge punctuation a protected name can hide behind —
+  // redirects are already split out, list separators trimmed at the edges.
+  const cleanPathToken = (token) =>
+    removeSubstSpans(stripQuotes(token)).replace(/^[(${]+/, '').replace(/[)},:;]+$/, '');
+  // Unquoted ${IFS}/$IFS expansions word-split exactly like whitespace —
+  // `cat${IFS}.env` IS `cat .env` to the shell. Quoted ${IFS} stays inside the
+  // word (a quoted expansion does not split).
+  const IFS_PREFIX = /^\$\{IFS[^}]*\}|^\$IFS(?![A-Za-z0-9_])/;
+  // Quote/IFS/substitution-aware word split. Tokens come back RAW (quotes and
+  // backslashes kept): `X="a b" cat .env` must not hand `"b"` the head slot,
+  // and keeping the quote chars lets stripQuotes re-parse modes correctly.
+  // Substitution spans are appended verbatim so interior spaces cannot split
+  // a word mid-span — extractSubstBodies already scanned their content.
+  const splitShellWords = (segment) => {
+    const src = String(segment ?? '');
+    const tokens = [];
+    let cur = '';
+    let has = false;
+    const flush = () => {
+      if (has) tokens.push(cur);
+      cur = '';
+      has = false;
+    };
+    let i = 0;
+    while (i < src.length) {
+      const ch = src[i];
+      if (ch === "'") {
+        const end = src.indexOf("'", i + 1);
+        cur += src.slice(i, end === -1 ? src.length : end + 1);
+        i = end === -1 ? src.length : end + 1;
+        has = true;
+        continue;
+      }
+      if (ch === '"') {
+        const start = i;
+        i += 1;
+        while (i < src.length && src[i] !== '"') {
+          if (src[i] === '\\' && i + 1 < src.length && DQ_ESCAPABLE.includes(src[i + 1])) {
+            i += 2;
+            continue;
+          }
+          i += 1;
+        }
+        i += 1;
+        cur += src.slice(start, i);
+        has = true;
+        continue;
+      }
+      if (ch === '\\') {
+        cur += src.slice(i, Math.min(i + 2, src.length));
+        i = Math.min(i + 2, src.length);
+        has = true;
+        continue;
+      }
+      if (ch === '<' || ch === '>' || /\s/.test(ch)) {
+        flush();
+        i += 1;
+        continue;
+      }
+      if (ch === '$') {
+        const ifs = IFS_PREFIX.exec(src.slice(i));
+        if (ifs) {
+          // ${IFS}/$IFS is a separator itself — flush, skip the expansion,
+          // keep scanning (it never contributes literal text to a word).
+          flush();
+          i += ifs[0].length;
+          continue;
+        }
+        if (src[i + 1] === '(' || src[i + 1] === '{') {
+          const open = src[i + 1];
+          const close = open === '(' ? ')' : '}';
+          const start = i;
+          let depth = 1;
+          let j = i + 2;
+          while (j < src.length && depth > 0) {
+            const b = src[j];
+            if (b === '\\') { j += 2; continue; }
+            if (b === open) depth += 1;
+            if (b === close) depth -= 1;
+            j += 1;
+          }
+          cur += src.slice(start, j);
+          i = j;
+          has = true;
+          continue;
+        }
+      }
+      if (ch === '`') {
+        const end = src.indexOf('`', i + 1);
+        cur += src.slice(i, end === -1 ? src.length : end + 1);
+        i = end === -1 ? src.length : end + 1;
+        has = true;
+        continue;
+      }
+      cur += ch;
+      i += 1;
+      has = true;
+    }
+    flush();
+    return tokens;
+  };
+
+  // W2-D03: `$(…)` and backtick bodies are scanned recursively (bounded by
+  // MAX_SUBST_DEPTH so a hostile nest cannot eat the hook deadline). The
+  // extractor is quote-mode aware: '$(…)' is literal text in bash and must
+  // NOT expand here, while "$(…)" still expands like the real shell.
+  const MAX_SUBST_DEPTH = 8;
+  const extractSubstBodies = (text) => {
+    const bodies = [];
+    // Scan src[pos..] under a quote mode: null = unquoted, '"' = inside
+    // double quotes (substitutions still expand). Single quotes freeze
+    // everything to the next '. Returns the index after the terminator
+    // (or src.length). An unterminated quote consumes the rest — the shell
+    // would reject the command anyway.
+    const scan = (src, pos, mode) => {
+      let i = pos;
+      while (i < src.length) {
+        const ch = src[i];
+        if (ch === '\\') { i += 2; continue; }
+        if (mode === '"') {
+          if (ch === '"') return i + 1;
+        } else if (ch === "'") {
+          const end = src.indexOf("'", i + 1);
+          i = end === -1 ? src.length : end + 1;
+          continue;
+        } else if (ch === '"') {
+          i = scan(src, i + 1, '"');
+          continue;
+        }
+        if (ch === '`') {
+          const end = src.indexOf('`', i + 1);
+          if (end === -1) return src.length;
+          bodies.push(src.slice(i + 1, end));
+          i = end + 1;
+          continue;
+        }
+        if (ch === '$' && src[i + 1] === '(') {
+          let d = 1;
+          let j = i + 2;
+          while (j < src.length && d > 0) {
+            const b = src[j];
+            if (b === '\\') { j += 2; continue; }
+            if (b === "'") {
+              const e = src.indexOf("'", j + 1);
+              j = e === -1 ? src.length : e + 1;
+              continue;
+            }
+            if (b === '"') { j = scan(src, j + 1, '"'); continue; }
+            if (b === '`') {
+              const e = src.indexOf('`', j + 1);
+              if (e === -1) { j = src.length; break; }
+              bodies.push(src.slice(j + 1, e));
+              j = e + 1;
+              continue;
+            }
+            if (b === '$' && src[j + 1] === '(') { d += 1; j += 2; continue; }
+            if (b === '(') { d += 1; j += 1; continue; }
+            if (b === ')') { d -= 1; j += 1; continue; }
+            j += 1;
+          }
+          bodies.push(src.slice(i + 2, d === 0 ? j - 1 : src.length));
+          i = j;
+          continue;
+        }
+        i += 1;
+      }
+      return i;
+    };
+    scan(text, 0, null);
+    return bodies;
+  };
+
+  const scanBashShapes = (command, depth = 0) => {
     const found = [];
+    // Substitution bodies are extracted BEFORE segment splitting — a `;`
+    // inside `$(…)` belongs to the substitution, not the top level. Each body
+    // is scanned recursively AND its words are classified directly: `cat
+    // $(echo .env)` produces the file via substitution, a route no segment
+    // split can see.
+    if (depth < MAX_SUBST_DEPTH) {
+      for (const body of extractSubstBodies(command)) {
+        for (const inner of scanBashShapes(body, depth + 1)) found.push(inner);
+        for (const rawTok of splitShellWords(body)) {
+          const cleaned = cleanPathToken(rawTok);
+          const kind = classifySecretFile(cleaned);
+          if (kind && !pathAllowed(cleaned)) {
+            found.push({ label: `${kind} referenced in command substitution`, value: cleaned, isPath: true });
+          }
+        }
+      }
+    }
     const segments = command.split(/\|\||&&|;|\||\n/);
     for (const rawSegment of segments) {
       const segment = rawSegment.trim();
       if (!segment) continue;
-      const tokens = segment.split(/\s+/);
-      const head = tokens[0].replace(/^["']+|["']+$/g, '');
+      // Shell word semantics: whitespace AND `<`/`>` split words, quoted runs
+      // (`"a b"`), escapes and `${IFS}` separators behave like the shell —
+      // `cat<.env` splits on the redirect and `X="a b" cat .env` keeps the
+      // quoted space inside the assignment word. Tokens stay RAW here —
+      // cleanPathToken/unquote dequote once downstream; dequoting twice would
+      // eat a legit quoted backslash (`'C:\x\.env'` -> `C:x.env` -> miss).
+      // Words that dequote to nothing (`''`) drop so they never land in a
+      // head/arg slot, matching the pre-split filter(Boolean) behavior.
+      const tokens = splitShellWords(segment).filter((t) => stripQuotes(t) !== '');
+      if (!tokens.length) continue;
+      const head = cleanPathToken(tokens[0]);
+      // Tokens are RAW — quote chars are still on them so downstream helpers
+      // dequote once. Every literal comparison goes through unquote.
+      const unquote = stripQuotes;
 
       if ((head === 'env' || head === 'printenv' || head === 'history') && tokens.length === 1) {
         found.push({ label: `bare \`${head}\` dumps environment/history (may contain tokens)`, value: segment });
         continue;
       }
-      if (head === 'export' && (tokens[1] === '-p' || tokens[1] === '--print')) {
+      if (head === 'export' && (unquote(tokens[1]) === '-p' || unquote(tokens[1]) === '--print')) {
         found.push({ label: 'bare `export -p` dumps all environment variables', value: segment });
         continue;
       }
@@ -258,18 +557,58 @@ async function evaluate({ rawInput, projectRoot, env }) {
         ['flock', 1],
         ['docker', 2], ['podman', 2], ['nerdctl', 2], ['ctr', 2],
         ['kubectl', 2], ['machinectl', 2],
+        // W2-D03: shell keywords are transparent to the verb check — `do cat
+        // .env` or `then cat .env` runs cat exactly like a wrapper does. The
+        // loop heads (for/select/read/done) are NOT here: they own their word
+        // list and get the dedicated LOOP_HEADS check below.
+        ['do', 0], ['then', 0], ['else', 0], ['elif', 0],
+        ['if', 0], ['while', 0], ['until', 0], ['!', 0],
+      ]);
+      // Shells whose `-c` flag (also inside a cluster like `-lc`) introduces
+      // a command STRING: `bash -c 'cat .env'` hands the whole inner command
+      // to a child shell, so the operand's dequoted text is scanned as a
+      // nested command rather than classified as a path. `eval` (and remote
+      // wrappers such as `ssh`) carry the command string in the operand
+      // slot instead — that lane is handled at head resolution below.
+      const COMMAND_STRING_SHELLS = new Set([
+        'bash', 'sh', 'zsh', 'dash', 'ksh', 'su', 'sg', 'runuser',
       ]);
-      const unquote = (t) => String(t || '').replace(/^["']+|["']+$/g, '');
+      // Predicates dequote once: tokens are raw, and bash resolves `-n`/`X=v`
+      // the same whether or not the word carried quotes.
       const isVerbToken = (t) => DUMP_VERBS.has(unquote(t).replace(/^.*\//, ''));
       const wrapperPositionals = (t) => WRAPPER_POSITIONALS.get(unquote(t).replace(/^.*\//, ''));
-      const isAssignToken = (t) => /^[A-Za-z_][A-Za-z0-9_]*=/.test(t);
-      const isFlagToken = (t) => /^-[^-]?|--/.test(t);
+      const isAssignToken = (t) => /^[A-Za-z_][A-Za-z0-9_]*=/.test(unquote(t));
+      const isFlagToken = (t) => /^-[^-]?|--/.test(unquote(t));
       let headIdx = 0;
       let wrapperPositionalPending = 0;
+      // The wrapper most recently entered in this chain — `bash -c` / `su -c`
+      // tell their flag operand apart from e.g. `grep -c` (a count, not a
+      // command string).
+      let lastWrapperBase = null;
+      // A shell `-c` flag operand and an `eval` operand ARE inner command
+      // text no matter how compact: `bash -c 'cat<.env'` and `eval
+      // 'cat${IFS}.env'` need no literal whitespace or quote marks, so the
+      // operand's dequoted text is scanned as a nested command whenever it is
+      // non-empty. Escaped whitespace is normalised to a plain separator
+      // first — `cat\ .env` dequotes to the word `cat .env`, which can never
+      // run as a command name anyway, so splitting it only denies a
+      // construct bash itself rejects while catching the real bypass where
+      // the OUTER shell consumed the escape (`bash -c cat\ .env`).
+      // A head-position word outside a command-string slot keeps the old
+      // gate: it only hides a nested command when its text carries
+      // whitespace or the word was quoted — otherwise it is a plain
+      // head/path token for the checks below.
+      const scanCommandString = (rawToken, viaCommandStringSlot) => {
+        if (rawToken === undefined || depth >= MAX_SUBST_DEPTH) return;
+        const inner = unquote(rawToken).replace(/\\(?=\s)/g, '');
+        if (!inner) return;
+        if (!viaCommandStringSlot && !/\s/.test(inner) && !/["'`]/.test(rawToken)) return;
+        for (const innerFinding of scanBashShapes(inner, depth + 1)) found.push(innerFinding);
+      };
       for (;;) {
         const t = tokens[headIdx];
         if (t === undefined) break;
-        if (t === '--') { headIdx += 1; break; }
+        if (unquote(t) === '--') { headIdx += 1; break; }
         if (isAssignToken(t)) { headIdx += 1; continue; }
         if (wrapperPositionalPending > 0 && !isVerbToken(t) && !isFlagToken(t)) {
           // The wrapper's own operand (user/host/duration/image/service), then
@@ -284,6 +623,7 @@ async function evaluate({ rawInput, projectRoot, env }) {
         const positionalCount = wrapperPositionals(t);
         if (positionalCount !== undefined) {
           wrapperPositionalPending = positionalCount;
+          lastWrapperBase = unquote(t).replace(/^.*\//, '');
           // `docker compose <sub> <svc> <cmd>` carries one extra operand (the
           // service) beyond the flat two — `compose` is a sub-CLI, not a
           // subcommand like `exec`.
@@ -303,18 +643,32 @@ async function evaluate({ rawInput, projectRoot, env }) {
             && !isAssignToken(next)
             && !isVerbToken(next)
             && wrapperPositionals(next) === undefined) {
+            // A shell `-c` operand IS a command string — classify its inner
+            // text as a nested command so `bash -c 'cat .env'` cannot hide
+            // the dump behind quoting. viaCommandStringSlot=true: compact
+            // strings (`cat<.env`, `cat${IFS}.env`) bypassed the
+            // whitespace/quote gate.
+            if (COMMAND_STRING_SHELLS.has(lastWrapperBase) && /^-[^-]*c/.test(unquote(t))) {
+              scanCommandString(next, true);
+            }
             headIdx += 1;
           }
           continue;
         }
+        // Head reached. When it is a quoted command string (`eval 'cat
+        // .env'`, `ssh host 'cat .env'`) the real verb lives INSIDE the
+        // token — classify the inner text instead of the literal words.
+        // `eval` gets the unconditional lane: its operand is re-parsed as a
+        // command string regardless of quoting or whitespace.
+        scanCommandString(t, lastWrapperBase === 'eval');
         break;
       }
-      const effectiveHead = unquote(tokens[headIdx] ?? '');
+      const effectiveHead = cleanPathToken(tokens[headIdx] ?? '');
       const headBase = effectiveHead.replace(/^.*\//, '');
 
       if (DUMP_VERBS.has(headBase)) {
         for (const token of tokens.slice(headIdx + 1)) {
-          const cleaned = token.replace(/^["']+|["',:]+$/g, '');
+          const cleaned = cleanPathToken(token);
           const kind = classifySecretFile(cleaned);
           if (kind && !pathAllowed(cleaned)) {
             found.push({ label: `${effectiveHead} reads ${kind}`, value: cleaned, isPath: true });
@@ -322,6 +676,26 @@ async function evaluate({ rawInput, projectRoot, env }) {
         }
       }
 
+      // W2-D03: loop/read indirection — `for f in .env; do cat "$f"; done`
+      // reads the file even though no protected token sits in a dump-verb
+      // arg slot. Flag a protected literal in the `in` list (or the words
+      // after the loop head) instead of tracking variables; `read`/`done`
+      // carry the redirect target `while read x < .env` / `done < .env`.
+      const LOOP_HEADS = new Set(['for', 'select', 'read', 'done']);
+      if (LOOP_HEADS.has(headBase)) {
+        const inIdx = headBase === 'for' || headBase === 'select'
+          ? tokens.findIndex((t, idx) => idx > headIdx && unquote(t) === 'in')
+          : -1;
+        const listStart = inIdx === -1 ? headIdx + 1 : inIdx + 1;
+        for (const token of tokens.slice(listStart)) {
+          const cleaned = cleanPathToken(token);
+          const kind = classifySecretFile(cleaned);
+          if (kind && !pathAllowed(cleaned)) {
+            found.push({ label: `${headBase} list references ${kind}`, value: cleaned, isPath: true });
+          }
+        }
+      }
+
       const CRED_USER_TOOLS = new Set(['curl', 'wget', 'ftp', 'lftp', 'aria2c', 'http', 'https']);
       // `-uuser:pass`, `-u user:pass`, `--user=user:pass`, `--user user:pass` —
       // the old `\s+` separator missed the joined and `=` forms entirely.
@@ -336,7 +710,16 @@ async function evaluate({ rawInput, projectRoot, env }) {
         found.push({ label: 'URL with embedded credentials (user:pass@host)', value: segment });
       }
     }
-    return found;
+    // A protected file reachable through two routes (substitution body token
+    // AND a dump-verb slot in the same command) reports once — same verdict,
+    // less noise.
+    const seenPathValues = new Set();
+    return found.filter((finding) => {
+      if (!finding.isPath) return true;
+      if (seenPathValues.has(finding.value)) return false;
+      seenPathValues.add(finding.value);
+      return true;
+    });
   };
 
   // --- channel wiring ---

package/template_project/.claude/hooks/session-episode.sh

@@ -24,13 +24,17 @@ CONFIG_FILE="$PROJECT_ROOT/.ukit/storage/config.json"
 __ukit_ep_gate="$(node -e '
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 2000;
 setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
-const fs = require("fs");
-try {
-  const config = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
-  process.stdout.write(config?.learning?.episodes?.autoWrite === true ? "1" : "0");
-} catch {
-  process.stdout.write("0");
-}
+// W2-D06: async read so a wedged filesystem cannot park the deadline above.
+require("fs").promises.readFile(process.argv[1], "utf8")
+  .then((raw) => {
+    try {
+      const config = JSON.parse(raw);
+      process.stdout.write(config?.learning?.episodes?.autoWrite === true ? "1" : "0");
+    } catch {
+      process.stdout.write("0");
+    }
+  })
+  .catch(() => process.stdout.write("0"));
 ' "$CONFIG_FILE" 2>/dev/null)" || __ukit_ep_gate="0"
 if [ "$__ukit_ep_gate" != "1" ]; then
   exit 0
@@ -89,34 +93,66 @@ const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || ""
 setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 
 const fs = require("fs");
-const { spawnSync } = require("child_process");
+const fsp = fs.promises;
+const { spawn } = require("child_process");
 
 const inputFile = process.argv[1];
 const configPath = process.argv[2];
 const projectRoot = process.argv[3];
 
-function readJson(filePath) {
+// W2-D06: every filesystem and child-process wait inside the armed block is
+// async — a wedged sync read/spawnSync used to park the event loop so the
+// deadline above could never fire.
+async function readJson(filePath) {
   try {
-    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    return JSON.parse(await fsp.readFile(filePath, "utf8"));
   } catch {
     return null;
   }
 }
 
-let payload = {};
-try {
-  const raw = fs.readFileSync(inputFile, "utf8");
-  payload = JSON.parse(raw || "{}") || {};
-} catch {}
+// Bounded child: resolves on close; the timeout hard-kills so a hung `ukit`
+// can never hold the hook — and even that timeout is only a backstop for the
+// armed deadline, which is now free to preempt any residual wait.
+function runBounded(cmd, args, { timeout, cwd, env, shell } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, args, {
+        stdio: "ignore",
+        timeout,
+        killSignal: "SIGKILL",
+        ...(shell ? { shell: true } : {}),
+        ...(cwd ? { cwd } : {}),
+        ...(env ? { env } : {}),
+      });
+    } catch {
+      resolve({ ok: false });
+      return;
+    }
+    let timedOut = false;
+    child.on("error", () => resolve({ ok: false }));
+    child.on("close", (code, signal) => {
+      resolve({ ok: !timedOut && code === 0 && !signal });
+    });
+    child.on("timeout", () => { timedOut = true; });
+  });
+}
+
+(async () => {
+  let payload = {};
+  try {
+    const raw = await fsp.readFile(inputFile, "utf8");
+    payload = JSON.parse(raw || "{}") || {};
+  } catch {}
 
-const config = readJson(configPath) || {};
-if (config?.learning?.episodes?.autoWrite !== true) process.exit(0);
+  const config = (await readJson(configPath)) || {};
+  if (config?.learning?.episodes?.autoWrite !== true) process.exit(0);
 
-const sessionId = typeof payload.session_id === "string" && payload.session_id.trim()
-  ? payload.session_id.trim()
-  : null;
+  const sessionId = typeof payload.session_id === "string" && payload.session_id.trim()
+    ? payload.session_id.trim()
+    : null;
 
-(async () => {
   // 3.3.0: prefer the absolute node + CLI recorded by `ukit install`
   // (.ukit/storage/cli.json, validated by resolveCliLocator) — GUI-launched
   // hosts often lack nvm/volta on PATH, which made the bare `ukit` spawn fail
@@ -130,14 +166,10 @@ const sessionId = typeof payload.session_id === "string" && payload.session_id.t
     ? { cmd: located.node, pre: [located.bin], shell: false }
     : { cmd: "ukit", pre: [], shell: true };
 
-  const probe = spawnSync(cli.cmd, [...cli.pre, "--version"], {
-    shell: cli.shell, stdio: "ignore", timeout: 2000,
-  });
-  if (probe.error || probe.status === null || probe.status === undefined) return;
+  const probe = await runBounded(cli.cmd, [...cli.pre, "--version"], { timeout: 2000 });
+  if (!probe.ok) return;
 
-  spawnSync(cli.cmd, [...cli.pre, "memory", "episode"], {
-    shell: cli.shell,
-    stdio: "ignore",
+  await runBounded(cli.cmd, [...cli.pre, "memory", "episode"], {
     timeout: 4000,
     cwd: projectRoot,
     env: sessionId

package/template_project/.claude/hooks/verification-guard.sh

@@ -88,7 +88,7 @@ setTimeout(() => {
 const fs = require('fs').promises;
 const path = require('path');
 const { pathToFileURL } = require('url');
-const { execFileSync } = require('child_process');
+const { execFile } = require('child_process');
 
 async function readJson(filePath, fallback = null) {
   try {
@@ -432,18 +432,29 @@ const NEW_SOURCE_FILE_RE = /\.(jsx?|tsx?|mjs|cjs|vue|svelte|css|scss|sass|less|h
 
 // `git status --porcelain` positions: untracked entries start '??', index-staged
 // adds start 'A'. Both are "component-create" candidates for the wiring check.
-function readGitChangedPaths(projectRoot) {
-  try {
-    const out = execFileSync('git', ['status', '--porcelain', '--untracked-files=all'], {
-      cwd: projectRoot,
-      encoding: 'utf8',
-      timeout: 1500,
-      stdio: ['ignore', 'pipe', 'ignore'],
-    });
-    return out.split('\n').map((line) => line.trim()).filter(Boolean);
-  } catch {
-    return null;
-  }
+// W2-D06: async execFile — a wedged git (slow index lock, network fs) must not
+// park the event loop inside the armed deadline block the way execFileSync did.
+// SIGKILL keeps the child bound hard even for a TERM-ignoring process.
+async function readGitChangedPaths(projectRoot) {
+  return new Promise((resolve) => {
+    try {
+      execFile('git', ['status', '--porcelain', '--untracked-files=all'], {
+        cwd: projectRoot,
+        encoding: 'utf8',
+        timeout: 1500,
+        killSignal: 'SIGKILL',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }, (error, stdout) => {
+        if (error) {
+          resolve(null);
+          return;
+        }
+        resolve(String(stdout).split('\n').map((line) => line.trim()).filter(Boolean));
+      });
+    } catch {
+      resolve(null);
+    }
+  });
 }
 
 async function readSessionLedger(projectRoot, payload, ledgerModule) {
@@ -470,7 +481,7 @@ async function observeSmallFeatureDoneCriteria({ projectRoot, payload, state })
   }
   const ledgerModule = await loadLedgerModule();
   const ledger = await readSessionLedger(projectRoot, payload, ledgerModule);
-  const gitLines = readGitChangedPaths(projectRoot);
+  const gitLines = await readGitChangedPaths(projectRoot);
   const newSourceFiles = gitLines === null ? [] : gitLines
     .filter((line) => (line.startsWith('??') || line.startsWith('A')) && NEW_SOURCE_FILE_RE.test(line))
     .map((line) => line.replace(/^(..)\s+/, ''))
@@ -578,7 +589,7 @@ async function observeVerificationRecipe({ projectRoot, payload, state }) {
   const mapModule = await loadVerificationMapModule();
   if (!mapModule) return;
 
-  const gitLines = readGitChangedPaths(projectRoot);
+  const gitLines = await readGitChangedPaths(projectRoot);
   if (gitLines === null) return; // no git answer → no classification, no recipe
   const changedPaths = gitLines.map((line) => line.replace(/^(..)\s+/, ''));
   const artifactClass = mapModule.classifyArtifactClass(changedPaths);