@ngockhoale/ukit 2.4.2 → 2.4.3

package/templates/.claude/hooks/stale-spec-guard.sh

@@ -5,16 +5,42 @@
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
+# TASK-019: arm advisory latency telemetry; the finish row is written by the
+# shared cleanup path before the staged payload is removed. A missing
+# runtime (pre-install tree) simply leaves telemetry off.
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): stage before anything reads it; the shell var is capped.
   ukit_stage_hook_input 2097152 truncate || exit 0
 else
-  # Runtime helper missing (pre-install tree): bounded inline staging keeps the
-  # wrapper's own fail-loud/advisory behavior below alive.
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline - `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
   UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
-  head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null
-  cat >/dev/null 2>&1
-  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -gt 2097152 ]; then
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 2097153 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
+  # already degrades on - the shared helper's truncate posture (R4.5).
+  if [ "$__ukit_size" -gt 2097152 ]; then
     truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT

package/templates/.claude/hooks/task-watchdog.sh

@@ -5,33 +5,35 @@
 #   The Quality Gate lets handoff runs go on for a while, but a wedged task
 #   that never reports a blocker still burns the rest of the pipeline. This
 #   hook measures wall-clock per in_progress task against approved budgets
-#   (S 8/15, M 15/30, L 25/45 minutes by default) and either:
-#     - soft overrun: emits a VISIBLE "checkpoint milestone now + split remainder"
-#                     advisory on Stop (systemMessage), never blocks.
-#     - hard overrun (split policy, default): emits Stop decision=block with a
-#                     visible split instruction naming the follow-up
-#                     TASK-<id>-b; keeps the cycle running instead of letting
-#                     the agent stop silently mid-budget.
-#     - hard overrun (pause policy, selectable in config): emits a pause
-#                     advisory on Stop, never blocks.
+#   (S 8/15, M 15/30, L 25/45 minutes by default).
 #
-#   PostToolUse NEVER emits decision — that would block the in-flight Edit.
-#   Stop is the only path that can hard-trip; PostToolUse stays advisory only.
+# TASK-025 (PLAN §2 H17): the watchdog no longer owns any Stop decision. A single
+# coordinator (.claude/ukit/runtime/stop-coordinator.mjs, registered once on Stop
+# through completion-gate.sh) evaluates BOTH the completion policy and this
+# watchdog's budget policy and emits at most one continuation decision — two
+# independent blockers used to double-block the same Stop.
+#
+# Dispatch on hook_event_name:
+#   Stop         → thin delegate: hand the staged payload to the stop coordinator
+#                  and pass its single decision through. Kept for legacy settings
+#                  that still register this script on Stop; the coordinator's
+#                  once-per-stop dedupe keeps a double-registered Stop inert.
+#   PostToolUse  → advisory only (systemMessage); NEVER emits decision. Re-evaluates
+#                  so the runtime state stays warm for the next Stop.
+#   anything else → exit 0 silently.
 #
 #   Everything fails open and stays inside the 4s hook-chain budget:
 #     - HOOK_DEADLINE_MS=3000 self-kill via setTimeout(...).unref()
 #     - all I/O is async (sync reads on a stalled mount would block the timer)
 #     - process.exit(0) on every path; never throws.
-#
-# Dispatch on hook_event_name:
-#   Stop         → evaluate and may emit decision=block; never emits decision
-#                  unless the trip crosses hardMin AND hardPolicy='split'.
-#   PostToolUse  → advisory only (systemMessage); NEVER emits decision.
-#   anything else → exit 0 silently.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
+# TASK-019: arm advisory latency telemetry; the finish row is written by the
+# shared cleanup path before the staged payload is removed. A missing
+# runtime (pre-install tree) simply leaves telemetry off.
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): the 64 KiB cap is preserved, but the payload now travels
   # as a staged file path — never through the exec environment, so an oversized
@@ -40,12 +42,35 @@ if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
   # degrade exit 0 (documented posture).
   ukit_stage_hook_input 65536 truncate || exit 0
 else
-  # Runtime helper missing (pre-install tree): bounded inline staging keeps the
   # 64 KiB cap and the advisory degrade path alive.
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline - `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
   UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
-  head -c 65537 > "$UKIT_INPUT_FILE" 2>/dev/null
-  cat >/dev/null 2>&1
-  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -gt 65536 ]; then
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 65537 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 65537 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
+  # already degrades on - the shared helper's truncate posture (R4.5).
+  if [ "$__ukit_size" -gt 65536 ]; then
     truncate -s 65536 "$UKIT_INPUT_FILE" 2>/dev/null
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
@@ -56,7 +81,13 @@ INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE' || true
 'use strict';
 
 const fsp = require('fs/promises');
+// TASK-024 fix (regression from TASK-014's H01 bounded-staging refactor): the staged
+// payload is read with fs.readFileSync, but the `fs` require was dropped — every
+// payload read then threw ReferenceError, was swallowed by the try/catch, and the
+// hook silently became a no-op (empty payload → irrelevant event → exit 0).
+const fs = require('fs');
 const path = require('path');
+const { spawn } = require('child_process');
 const { pathToFileURL } = require('url');
 
 // Wall-clock watchdog. Anything that stalls here must end in clean exit 0 —
@@ -79,7 +110,6 @@ try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch
   })();
 
   const hookEvent = typeof payload.hook_event_name === 'string' ? payload.hook_event_name : '';
-  const toolName = typeof payload.tool_name === 'string' ? payload.tool_name : '';
   const projectRoot = process.env.PROJECT_ROOT || process.cwd();
 
   // Silent degrade for non-relevant events — same posture as every other
@@ -88,6 +118,43 @@ try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch
     process.exit(0);
   }
 
+  // TASK-025: Stop is a thin delegate — the stop coordinator owns every Stop
+  // decision (completion policy + this watchdog's budget policy, merged into at
+  // most one continuation decision). Fail-open: a missing coordinator (pre-install
+  // tree) just means no watchdog Stop evaluation, as before the delegate existed.
+  if (hookEvent === 'Stop') {
+    const coordinatorPath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'stop-coordinator.mjs');
+    try {
+      await fsp.access(coordinatorPath);
+    } catch {
+      process.exit(0);
+    }
+    const delegateInput = rawInput;
+    const child = spawn(process.execPath, [coordinatorPath, '--evaluate-stop'], {
+      cwd: projectRoot,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: projectRoot },
+      stdio: ['pipe', 'pipe', 'inherit'],
+    });
+    let delegatedOutput = '';
+    const killTimer = setTimeout(() => {
+      try { child.kill('SIGKILL'); } catch {}
+    }, HOOK_DEADLINE_MS);
+    if (typeof killTimer.unref === 'function') killTimer.unref();
+    child.stdout.on('data', (chunk) => { delegatedOutput += chunk; });
+    child.stdin.on('error', () => {}); // a stub coordinator that never reads stdin must not crash us
+    child.on('error', () => {
+      try { process.exit(0); } catch {}
+    });
+    child.on('close', () => {
+      try {
+        if (delegatedOutput.trim()) process.stdout.write(delegatedOutput);
+      } catch {}
+      process.exit(0);
+    });
+    child.stdin.end(delegateInput);
+    return;
+  }
+
   const runtimePath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'task-watchdog.mjs');
   // Async existence check — sync fs here would violate the all-async invariant
   // (a stalled mount would block the loop and the 3s self-kill could not fire).
@@ -121,112 +188,30 @@ try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch
   // PostToolUse: advisory only. NEVER emit decision — that would block the
   // in-flight Edit and stall the run. We still re-evaluate so the runtime
   // state stays warm and the next Stop sees an up-to-date view.
-  if (hookEvent === 'PostToolUse') {
-    const now = Date.now();
-    const evals = runtime.evaluateBudgets({ tasks, state, now, config });
-    const advisories = evals
-      .filter((r) => r.phase !== 'ok')
-      .map((r) => {
-        const task = tasks.find((t) => t.id === r.id);
-        if (!task) return null;
-        if (r.phase === 'hard') {
-          const blocks = Number(state.hardBlocks[r.id] || 0);
-          if (blocks >= (runtime.HARD_BLOCK_CAP || 2)) {
-            return runtime.describeDegraded({ id: r.id, hardBlocks: blocks });
-          }
-          return runtime.describeHardAdvisory(r, r.id);
-        }
-        return runtime.describeSoft(r, r.id);
-      })
-      .filter(Boolean);
-
-    if (advisories.length > 0) {
-      const message = advisories.join('\n');
-      try {
-        process.stdout.write(`${JSON.stringify({ systemMessage: message })}\n`);
-      } catch {}
-    }
-    process.exit(0);
-  }
-
-  // Stop: full evaluation, may emit decision=block under split policy.
   const now = Date.now();
-  for (const task of tasks) {
-    try {
-      await runtime.ensureFirstSeen(state, task.id, now);
-    } catch {}
-  }
-
   const evals = runtime.evaluateBudgets({ tasks, state, now, config });
-
-  // First save firstSeen updates so the next Stop sees the same anchored clock.
-  await runtime.writeState(statePath, state);
-
-  const hardResults = evals.filter((r) => r.phase === 'hard');
-  const softResults = evals.filter((r) => r.phase === 'soft');
-
-  if (hardResults.length === 0) {
-    // No hard trips. Emit a soft advisory if anything is in the soft zone,
-    // then exit 0 cleanly. We deliberately do not emit decision here — the
-    // completion gate owns Stop's continuation logic and we never want to
-    // double-block for the same reason.
-    if (softResults.length > 0) {
-      const advisory = softResults
-        .map((r) => runtime.describeSoft(r, r.id))
-        .join('\n');
-      try {
-        process.stdout.write(`${JSON.stringify({ systemMessage: advisory })}\n`);
-      } catch {}
-    }
-    process.exit(0);
-  }
-
-  // At least one hard-trip. Apply policy.
-  const hardPolicy = String(config.taskBudgets?.hardPolicy || 'split');
-  const firstHard = hardResults[0];
-  const blocks = Number(state.hardBlocks[firstHard.id] || 0);
-
-  if (hardPolicy !== 'split') {
-    // pause (or anything non-split) → advisory only, never block.
-    const advisory = hardResults
-      .map((r) => runtime.describePause({ id: r.id, result: r }))
-      .join('\n');
-    try {
-      process.stdout.write(`${JSON.stringify({ systemMessage: advisory })}\n`);
-    } catch {}
-    process.exit(0);
-  }
-
-  // split policy + hard-trip — but the per-task block cap has already been
-  // hit. Degrade to advisory so the orchestrator can hand back to the user.
-  if (blocks >= (runtime.HARD_BLOCK_CAP || 2)) {
-    await runtime.bumpHardBlocks(state, firstHard.id);
-    await runtime.writeState(statePath, state);
-    const advisory = runtime.describeDegraded({ id: firstHard.id, hardBlocks: blocks + 1 });
+  const advisories = evals
+    .filter((r) => r.phase !== 'ok')
+    .map((r) => {
+      const task = tasks.find((t) => t.id === r.id);
+      if (!task) return null;
+      if (r.phase === 'hard') {
+        const blocks = Number(state.hardBlocks[r.id] || 0);
+        if (blocks >= (runtime.HARD_BLOCK_CAP || 2)) {
+          return runtime.describeDegraded({ id: r.id, hardBlocks: blocks });
+        }
+        return runtime.describeHardAdvisory(r, r.id);
+      }
+      return runtime.describeSoft(r, r.id);
+    })
+    .filter(Boolean);
+
+  if (advisories.length > 0) {
+    const message = advisories.join('\n');
     try {
-      process.stdout.write(`${JSON.stringify({ systemMessage: advisory })}\n`);
+      process.stdout.write(`${JSON.stringify({ systemMessage: message })}\n`);
     } catch {}
-    process.exit(0);
   }
-
-  // Hard trip + split policy + under the cap → emit Stop decision=block
-  // with the visible split instruction. This is the "auto-split and continue"
-  // path: blocking the stop IS the continue mechanism — the executor / orchestrator
-  // performs the actual TASK-<id>-b cut on the next turn following the reason.
-  const newBlocks = await runtime.bumpHardBlocks(state, firstHard.id);
-  await runtime.writeState(statePath, state);
-
-  const task = tasks.find((t) => t.id === firstHard.id) || { id: firstHard.id };
-  const lastGreen = runtime.pickLastGreen(task);
-  const reason = runtime.describeSplitReason({
-    id: firstHard.id,
-    result: firstHard,
-    hardBlocks: newBlocks,
-    lastGreen,
-  });
-  try {
-    process.stdout.write(`${JSON.stringify({ decision: 'block', reason })}\n`);
-  } catch {}
   process.exit(0);
 })().catch(() => {
   // Fail-open: never let an exception kill the hook.

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

@@ -5,16 +5,42 @@
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
 if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
+# TASK-019: arm advisory latency telemetry; the finish row is written by the
+# shared cleanup path before the staged payload is removed. A missing
+# runtime (pre-install tree) simply leaves telemetry off.
+source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): stage before anything reads it; Node gets a path, never the payload.
   ukit_stage_hook_input 2097152 truncate || exit 0
 else
-  # Runtime helper missing (pre-install tree): bounded inline staging keeps the
-  # advisory/fail-open behavior below alive with a capped payload file.
+  # Runtime helper missing (pre-install tree): the SAME bounded staging,
+  # inline - `cat >/dev/null` used to block forever on a producer that never
+  # closes the pipe (R4.5). Read cap+1 in the background, bound the wait.
   UKIT_INPUT_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-hook-in.XXXXXX")"
-  head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null
-  cat >/dev/null 2>&1
-  if [ "$(wc -c < "$UKIT_INPUT_FILE" | tr -d '[:space:]')" -gt 2097152 ]; then
+  if [ -e /dev/fd/0 ]; then
+    exec 8<&0
+    head -c 2097153 <&8 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  else
+    head -c 2097153 > "$UKIT_INPUT_FILE" 2>/dev/null &
+  fi
+  __ukit_reader=$!
+  __ukit_stage_ms="${UKIT_HOOK_STAGE_MS:-2000}"
+  case "$__ukit_stage_ms" in
+    ''|*[!0-9]*) __ukit_stage_ms=2000 ;;
+  esac
+  [ "$__ukit_stage_ms" -gt 0 ] 2>/dev/null || __ukit_stage_ms=2000
+  printf -v __ukit_stage_s '%d.%03d' $((__ukit_stage_ms / 1000)) $((__ukit_stage_ms % 1000))
+  ( sleep "$__ukit_stage_s" 2>/dev/null; kill -9 "$__ukit_reader" 2>/dev/null ) <&- >/dev/null 2>&1 &
+  __ukit_waiter=$!
+  wait "$__ukit_reader" 2>/dev/null
+  __ukit_stage_rc=$?
+  kill "$__ukit_waiter" 2>/dev/null
+  wait "$__ukit_waiter" 2>/dev/null
+  exec 8<&-
+  __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
+  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
+  # already degrades on - the shared helper's truncate posture (R4.5).
+  if [ "$__ukit_size" -gt 2097152 ]; then
     truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
@@ -24,30 +50,34 @@ STATE_FILE="$PROJECT_ROOT/.claude/ukit/skill-router-state.json"
 ROUTE_CACHE_FILE="$PROJECT_ROOT/.claude/ukit/route-cache.json"
 PROGRESS_FILE="$PROJECT_ROOT/.claude/ukit/verification-progress.json"
 
-INPUT_FILE="$UKIT_INPUT_FILE" STATE_FILE="$STATE_FILE" ROUTE_CACHE_FILE="$ROUTE_CACHE_FILE" PROGRESS_FILE="$PROGRESS_FILE" node <<'NODE'
+INPUT_FILE="$UKIT_INPUT_FILE" STATE_FILE="$STATE_FILE" ROUTE_CACHE_FILE="$ROUTE_CACHE_FILE" PROGRESS_FILE="$PROGRESS_FILE" UKIT_RUNTIME_DIR="$SCRIPT_DIR/../ukit/runtime" node <<'NODE'
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
+const LOCK_STARTED_AT = Date.now();
 setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
-const crypto = require('crypto');
-const fs = require('fs');
+// TASK-015 fix round 1: the awaitable fs surface. Every state/progress read and
+// the atomic progress mutation is awaited so the unref'd self-deadline above can
+// always preempt it; synchronous fs calls park the event loop instead.
+const fs = require('fs').promises;
 const path = require('path');
+const { pathToFileURL } = require('url');
 
-function readJson(filePath, fallback = null) {
+async function readJson(filePath, fallback = null) {
   try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
   } catch {
     return fallback;
   }
 }
 
-function writeJsonAtomic(filePath, value) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+async function writeJsonAtomic(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
   const tempPath = `${filePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
   try {
-    fs.writeFileSync(tempPath, JSON.stringify(value, null, 2) + '\n');
-    fs.renameSync(tempPath, filePath);
+    await fs.writeFile(tempPath, JSON.stringify(value, null, 2) + '\n');
+    await fs.rename(tempPath, filePath);
   } catch (error) {
     try {
-      fs.rmSync(tempPath, { force: true });
+      await fs.rm(tempPath, { force: true });
     } catch {}
     throw error;
   }
@@ -56,86 +86,26 @@ function writeJsonAtomic(filePath, value) {
 // TASK-015: lock waits poll asynchronously. The old blocking shared-memory
 // sleep froze the event loop, so the unref'd deadline timer above could never
 // fire while waiting — a contended lock held the hook past its own 3s
-// self-deadline. setTimeout-based sleeps keep the loop live.
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function isPidAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return error?.code === 'EPERM';
-  }
-}
-
-function readLockOwner(lockPath) {
-  const owner = readJson(path.join(lockPath, 'owner'), null);
-  return owner && Number.isInteger(owner.pid) && typeof owner.token === 'string'
-    ? owner
-    : null;
-}
-
-// mkdir-based lock, protocol-compatible with runtime token-utils withFileLock.
-// Async now (see sleep above): the single-syscall mkdir/stat/write critical
-// section stays synchronous, only the contention backoff awaits. Fail-open
-// after 5s: this hook must never hang a PreToolUse chain, and a lost progress
-// entry only costs one repeated advisory.
-async function withLock(lockPath, fn) {
-  const staleMs = 10000;
-  const maxWaitMs = 5000;
-  const startedAt = Date.now();
-  const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
-  let held = false;
-  while (!held) {
-    try {
-      fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-      fs.mkdirSync(lockPath);
+// self-deadline. TASK-028: the lock itself is the shared runtime async-lock
+// utility (same mkdir/owner protocol as token-utils withFileLock, jittered
+// async backoff, no blocking shared-memory wait), so this hook carries no
+// inline lock copy.
+let lockModulePromise = null;
+function loadLockModule() {
+  if (!lockModulePromise) {
+    lockModulePromise = (async () => {
+      const runtimeDir = process.env.UKIT_RUNTIME_DIR || '';
+      const modulePath = runtimeDir ? path.join(runtimeDir, 'async-lock.mjs') : '';
+      if (!modulePath) return null;
       try {
-        fs.writeFileSync(path.join(lockPath, 'owner'), JSON.stringify({
-          pid: process.pid,
-          token: ownerToken,
-          ts: Date.now(),
-        }));
-      } catch (error) {
-        try {
-          fs.rmSync(lockPath, { recursive: true, force: true });
-        } catch {}
-        throw error;
+        await fs.access(modulePath);
+        return await import(pathToFileURL(modulePath).href);
+      } catch {
+        return null;
       }
-      held = true;
-    } catch (error) {
-      if (!error || error.code !== 'EEXIST') return fn();
-      try {
-        const stat = fs.statSync(lockPath);
-        if (Date.now() - stat.mtimeMs > staleMs) {
-          const owner = readLockOwner(lockPath);
-          if (!owner || !isPidAlive(owner.pid)) {
-            try {
-              fs.rmSync(lockPath, { recursive: true, force: true });
-              continue;
-            } catch {}
-          }
-        }
-      } catch {}
-      if (Date.now() - startedAt > maxWaitMs) break;
-      await sleep(3 + Math.floor(Math.random() * 9));
-    }
-  }
-  try {
-    return await fn();
-  } finally {
-    if (held) {
-      const owner = readLockOwner(lockPath);
-      if (owner?.token === ownerToken) {
-        try {
-          fs.rmSync(lockPath, { recursive: true, force: true });
-        } catch {}
-      }
-    }
+    })();
   }
+  return lockModulePromise;
 }
 
 function normalizeCommand(value) {
@@ -351,23 +321,30 @@ function advise(message) {
   // ledger, context hard-cap, protected-file, and destructive-command guards; turning
   // a verification-order recommendation into an exit-2 refusal gave a stale opt-in env
   // variable a way to freeze a run before it could diagnose or land its current change.
-  fs.writeSync(1, `${message.replace(/^BLOCKED:/, 'ADVISORY:')}\n`);
+  process.stdout.write(`${message.replace(/^BLOCKED:/, 'ADVISORY:')}\n`);
   process.exit(0);
 }
 
-// TASK-015: the whole flow runs in an async IIFE so the lock acquire can be
-// awaited (async polling) before the policy checks; every path still ends in
-// exit 0 — this hook is advisory by design.
+// TASK-015 fix round 1: the whole flow runs in an async IIFE and every
+// deadline-scoped filesystem operation yields to the event loop. Synchronous
+// reads/writes park the loop and make the self-deadline un-fireable.
 (async () => {
-let rawInput = '';
-try { rawInput = fs.readFileSync(process.env.INPUT_FILE || '', 'utf8'); } catch {}
-const payload = (() => {
-  try {
-    return JSON.parse(rawInput || '{}');
-  } catch {
-    return {};
+  const rawInput = await readTextSafe(process.env.INPUT_FILE || '');
+  const payload = (() => {
+    try {
+      return JSON.parse(rawInput || '{}');
+    } catch {
+      return {};
+    }
+  })();
+
+  async function readTextSafe(filePath) {
+    try {
+      return await fs.readFile(filePath, 'utf8');
+    } catch {
+      return '';
+    }
   }
-})();
 const command = normalizeCommand(payload?.tool_input?.command || payload?.command || '');
 if (!command) {
   process.exit(0);
@@ -375,8 +352,8 @@ if (!command) {
 
 const statePath = process.env.STATE_FILE;
 const progressPath = process.env.PROGRESS_FILE;
-const state = readJson(statePath, null);
-const routeCache = readJson(process.env.ROUTE_CACHE_FILE, null);
+const state = await readJson(statePath, null);
+const routeCache = await readJson(process.env.ROUTE_CACHE_FILE, null);
 const recommendation = state?.verificationRecommendation ?? null;
 const routeSummary = state?.routeSummary ?? null;
 const helpers = state?.helpers ?? null;
@@ -423,7 +400,7 @@ if (!policyMode && primaryCommands.length === 0 && fallbackCommands.length === 0
   process.exit(0);
 }
 
-const progress = readJson(progressPath, {});
+const progress = await readJson(progressPath, {});
 const attemptedCommands = collectAttemptedCommands(progress, {
   currentFingerprint: state?.fingerprint || null,
   maxAgeMs: STATE_FRESH_MS,
@@ -436,8 +413,8 @@ async function persistAttempt(commandText) {
   // Locked re-read + merge: parallel subagents record attempts concurrently, and a
   // stale-snapshot rewrite would silently drop their entries — the guard would then keep
   // advising instead of allowing, re-litigating verification order forever.
-  await withLock(`${progressPath}.lock`, async () => {
-    const current = readJson(progressPath, {});
+  const mutation = async () => {
+    const current = await readJson(progressPath, {});
     const mergedAttempts = new Set(collectAttemptedCommands(current, {
       currentFingerprint: state?.fingerprint || null,
       maxAgeMs: STATE_FRESH_MS,
@@ -457,13 +434,31 @@ async function persistAttempt(commandText) {
       .filter((entry, index, list) => (
         list.findLastIndex((candidate) => candidate.command === entry.command) === index
       ));
-    writeJsonAtomic(progressPath, {
+    await writeJsonAtomic(progressPath, {
       fingerprint: state?.fingerprint || null,
       updatedAt: now,
       attemptedCommands: [...mergedAttempts],
       recentAttempts,
     });
-  });
+  };
+  const lockModule = await loadLockModule();
+  if (lockModule && typeof lockModule.withAsyncLock === 'function') {
+    // TASK-028: the acquisition budget derives from the remaining hook deadline minus
+    // a cleanup reserve, capped at a short slice — a contended lock can never hold
+    // this hook near its own 3s deadline. On busy/abort the persist is SKIPPED, not
+    // written unlocked: the progress file is advisory and the next uncontended run
+    // re-records the attempt.
+    const deadlineMs = lockModule.lockBudgetMs({
+      hookDeadlineMs: HOOK_DEADLINE_MS,
+      startedAt: LOCK_STARTED_AT,
+    });
+    const outcome = await lockModule.withAsyncLock(progressPath, { deadlineMs }, mutation);
+    if (!outcome.ok) return;
+    return;
+  }
+  // Degraded install (runtime module missing): advisory progress file — keep the
+  // pre-utility unlocked persist so the advisory lane stays lively.
+  await mutation();
 }
 
 const isPrimaryCommand = primaryCommands.includes(command);
@@ -538,7 +533,7 @@ process.exit(0);
   // Advisory hook: an unexpected error (including a rejected lock) must never
   // turn into a non-zero exit — degrade to a bounded diagnostic and exit 0.
   try {
-    fs.writeSync(2, `verification-guard: unexpected error (${err?.message ?? err})\n`);
+    process.stderr.write(`verification-guard: unexpected error (${err?.message ?? err})\n`);
   } catch {}
   process.exit(0);
 });