@ngockhoale/ukit 2.7.6 → 2.7.7

package/templates/.claude/ukit/runtime/hook-chain-runner.mjs

@@ -97,6 +97,20 @@ function chainFailureKind(processResult) {
   }
 }
 
+// B1 (TASK-001, SPEC §FR-001): a child that emits a `hookSpecificOutput`
+// permission decision owns the verdict. `hookSpecificOutput` alone is NOT
+// enough — a child killed mid-write can carry the marker in a truncated
+// capture, and calling that a decision would exempt a genuinely-skipped gate
+// from the fail-closed verdict. A real decision is a clean exit-0 verdict.
+function emitsPermissionDecision(entry) {
+  return Boolean(entry)
+    && !entry.killed
+    && entry.code === 0
+    && entry.failureKind === 'ok'
+    && typeof entry.stdout === 'string'
+    && entry.stdout.includes('"hookSpecificOutput"');
+}
+
 function recordTiming(projectRoot, payload, timing) {
   // Timing telemetry is advisory and must never delay or block a tool call;
   // appendTelemetryRow carries the same posture (and the per-session cap).
@@ -109,12 +123,37 @@ function recordTiming(projectRoot, payload, timing) {
 // A `:0` or negative suffix is rejected (falls back) — zero would mean "no
 // budget", which silently disables the deadline; that is never a valid hook
 // contract.
+// TASK-001 (C8 / SPEC §FR-006): "rejected silently" was the bug. A `:0`/`: -1`
+// typo used to leave the suffix on the path, so the child never spawned and the
+// hook silently vanished from the chain. It now warns (never hard-fails — a
+// config typo must not block every tool call in a fail-closed chain) and runs
+// the script under the DEFAULT child budget.
+const TIMEOUT_SUFFIX_RE = /^(.*):(-?\d+(?:\.\d+)?)$/;
+
+// The ONE suffix stripper. Identity checks that need a script's declared name
+// (fail-closed lookups, skipped-gate reporting) go through it too: a `:-1` arg
+// must not look like an advisory script there while `parseScriptArg` already
+// normalized it to a gate for execution.
+function stripTimeoutSuffix(arg) {
+  const match = TIMEOUT_SUFFIX_RE.exec(String(arg ?? ''));
+  return match ? match[1] : String(arg ?? '');
+}
+
+function failClosedName(arg) {
+  return path.basename(stripTimeoutSuffix(arg));
+}
+
 function parseScriptArg(arg) {
-  const match = /^(.*):(\d+(?:\.\d+)?)$/.exec(arg || '');
-  if (!match) return { scriptPath: arg, timeoutMs: null };
-  const seconds = Number(match[2]);
-  if (!Number.isFinite(seconds) || seconds <= 0) return { scriptPath: arg, timeoutMs: null };
-  return { scriptPath: match[1], timeoutMs: Math.round(seconds * 1000) };
+  const suffix = TIMEOUT_SUFFIX_RE.exec(String(arg ?? ''));
+  if (!suffix) return { scriptPath: arg, timeoutMs: null };
+  const seconds = Number(suffix[2]);
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    process.stderr.write(
+      `[ukit] ignoring invalid timeout suffix "${arg}" — using default child budget\n`,
+    );
+    return { scriptPath: suffix[1], timeoutMs: null };
+  }
+  return { scriptPath: suffix[1], timeoutMs: Math.round(seconds * 1000) };
 }
 
 // TASK-001 (SPEC §FR-001, §8): a chain arg ending in `.mjs` is an IN-PROC step —
@@ -178,7 +217,7 @@ async function runModuleStep({ scriptPath, payload, payloadText, projectRoot, en
   }
 }
 
-async function run(payloadText, scriptArgs, { chainMarker = true } = {}) {
+async function run(payloadText, scriptArgs, { chainMarker = true, decisionShortCircuit = false, stdinStageMs = null } = {}) {
   const parsedArgs = scriptArgs.map(parseScriptArg);
   const scriptPaths = parsedArgs.map((a) => a.scriptPath);
   const payload = JSON.parse(payloadText || '{}');
@@ -224,7 +263,7 @@ async function run(payloadText, scriptArgs, { chainMarker = true } = {}) {
   const deadline = startedAt + totalBudgetMs;
   const results = [];
   let budgetExhausted = false;
-
+  let decisionEmitted = false;
   for (let scriptIndex = 0; scriptIndex < scriptPaths.length; scriptIndex++) {
     const scriptPath = scriptPaths[scriptIndex];
     const scriptName = path.basename(scriptPath);
@@ -321,7 +360,20 @@ async function run(payloadText, scriptArgs, { chainMarker = true } = {}) {
       });
     }
 
-    if (code === 2 || killed || (code !== 0 && FAIL_CLOSED_SCRIPTS.has(scriptName))) {
+    // B1 (TASK-001, SPEC §FR-001): under `--emit-verdict` a child that emits a
+    // `hookSpecificOutput` permission decision owns the verdict even at exit 0
+    // (the direct Claude contract: deny + exit 0 still blocks). The chain stops
+    // HERE, before the next child spawns — filtering the decision at emit time
+    // instead would still let the next script's side effects run (e.g.
+    // pre-edit-backup.sh backing up a file whose edit was just denied) and its
+    // stdout would be concatenated in front of the decision JSON, which Claude
+    // Code rejects as invalid JSON. The predicate is shared with the emit-time
+    // lookup so a truncated capture can never count as a decision here.
+
+    if (decisionShortCircuit && emitsPermissionDecision(results[results.length - 1])) {
+      decisionEmitted = true;
+    }
+    if (decisionEmitted || code === 2 || killed || (code !== 0 && FAIL_CLOSED_SCRIPTS.has(scriptName))) {
       break;
     }
   }
@@ -331,9 +383,12 @@ async function run(payloadText, scriptArgs, { chainMarker = true } = {}) {
   // of those unrun scripts is fail-closed, the chain must fail CLOSED — the old
   // per-script path ran every hook independently, so a timed-out advisory never
   // skipped a gate. `skippedFailClosed` carries that signal to the verdict.
-  const skippedFailClosed = scriptPaths
+  // ... unless this break WAS the decision: a decision owns the verdict, so the
+  // unrun gates are not a fail-closed gap (SPEC §FR-001 — the verdict must stay
+  // exit 0 with the decision JSON).
+  const skippedFailClosed = !decisionEmitted && scriptPaths
     .slice(results.length)
-    .some((p) => FAIL_CLOSED_SCRIPTS.has(path.basename(p)));
+    .some((p) => FAIL_CLOSED_SCRIPTS.has(failClosedName(p)));
 
   const elapsedMs = Date.now() - startedAt;
   // TASK-019: versioned rows shared with direct hooks. `outcome` reuses this
@@ -350,6 +405,18 @@ async function run(payloadText, scriptArgs, { chainMarker = true } = {}) {
     toolName: payload?.tool_name || null,
     toolUseId: payload?.tool_use_id || null,
     elapsedMs,
+    // O3 (SPEC §FR-009): the row's wall time split into the stdin stage — the
+    // bounded read this process waits on while the producer writes — and the
+    // chain's own execution. A producer holding the pipe open is then
+    // attributable instead of looking like a slow hook (the reported artifact:
+    // project-important.sh p95 = 1539ms with no row doing real work ≥ 1s).
+    // Clamped to `elapsedMs` because the split describes the row it sits on
+    // (the two are measured from different origins). Absent — not 0 and not
+    // null — when this invocation never read stdin, so a v1 reader sees the
+    // row it always saw.
+    ...(stdinStageMs === null
+      ? {}
+      : { stdinStageMs: Math.min(Math.max(0, Math.round(stdinStageMs)), elapsedMs) }),
     budgetMs: totalBudgetMs,
     budgetExhausted,
     scripts: results.map(({ scriptName, code, killed, failureKind, elapsedMs: scriptElapsedMs }) => ({
@@ -358,6 +425,12 @@ async function run(payloadText, scriptArgs, { chainMarker = true } = {}) {
       killed,
       failureKind,
       elapsedMs: scriptElapsedMs,
+      // TASK-007 (SPEC §FR-012): which steps the runner treated as gates. The
+      // doctor reads this flag instead of importing FAIL_CLOSED_SCRIPTS — the
+      // runner is the only component that knows which paths it gated, and a
+      // second copy of a security-relevant list is a drift hazard. Additive and
+      // optional: v1 readers that read the five original keys keep working.
+      failClosed: FAIL_CLOSED_SCRIPTS.has(scriptName),
     })),
   });
 
@@ -384,8 +457,14 @@ try {
   // '-' reads the payload from stdin — the form Claude Code hook commands use.
   let payloadText = payloadArg;
   let stdinTruncated = false;
+  // O3: the stage window is measured HERE, around the bounded read, and not
+  // inside run() — run() starts after the payload is already in hand, and a
+  // truncated read exits before run() is ever called.
+  let stdinStageMs = null;
   if (payloadArg === '-') {
+    const stageStartedAt = Date.now();
     const staged = await readStdinBounded();
+    stdinStageMs = Date.now() - stageStartedAt;
     payloadText = staged.text;
     stdinTruncated = staged.truncated;
   } else if (payloadArg.startsWith('@')) {
@@ -402,8 +481,7 @@ try {
   // chain carries a fail-closed gate, emit deny now instead of letting gates
   // pass on a payload they never fully received.
   if (stdinTruncated) {
-    const hasFailClosed = scriptPaths.some((p) =>
-      FAIL_CLOSED_SCRIPTS.has(path.basename(String(p).replace(/:\d+(?:\.\d+)?$/, ''))));
+    const hasFailClosed = scriptPaths.some((p) => FAIL_CLOSED_SCRIPTS.has(failClosedName(p)));
     if (hasFailClosed) {
       const deny = JSON.stringify({
         hookSpecificOutput: {
@@ -427,7 +505,13 @@ try {
       process.exit(emitVerdict ? 0 : 2);
     }
   }
-  const chain = await run(payloadText, scriptPaths, { chainMarker: !emitVerdict });
+  const chain = await run(payloadText, scriptPaths, {
+    chainMarker: !emitVerdict,
+    // B1: only the --emit-verdict contract short-circuits on a decision; the
+    // omp bridge parses the JSON envelope and needs every step's context stdout.
+    decisionShortCircuit: emitVerdict,
+    stdinStageMs,
+  });
   if (!emitVerdict) {
     process.stdout.write(JSON.stringify(chain));
   } else {
@@ -435,10 +519,21 @@ try {
     // verdict even when it exits 0 (the direct Claude contract: deny + exit 0
     // still blocks). The first decision wins, matching per-script semantics
     // where each hook's output is its own verdict and a deny short-circuits.
+    // The loose lookup decides which entry is REPORTED as the verdict owner (a
+    // non-zero decision emitter stays routed through the code-2/fail-closed
+    // paths below, per SPEC §FR-001); the strict predicate decides whether that
+    // entry may claim stdout outright.
     const decisionResult = chain.results.find((r) =>
       typeof r.stdout === 'string' && r.stdout.includes('"hookSpecificOutput"'));
+    const decisionOwnsVerdict = emitsPermissionDecision(decisionResult);
     const last = decisionResult ?? chain.results[chain.results.length - 1];
 
+    // B1 (SPEC §FR-001): a clean decision owns the ENTIRE stdout — no context
+    // text before or after it. Claude Code parses stdout as one JSON document,
+    // so leading context turns a valid deny into "Hook JSON output validation
+    // failed"; the chain already stopped at the decision, so no later script's
+    // output can be concatenated in.
+
     // TASK-234 review fix (critical): context stdout must be REPLAYED, not
     // dropped. SessionStart/UserPromptSubmit hooks emit plain-text context
     // (PROJECT_IMPORTANT mandate, skill-router guidance) — replaying only the
@@ -449,15 +544,18 @@ try {
       .filter((r) => r !== decisionResult && r !== last && typeof r.stdout === 'string' && r.stdout.length > 0)
       .map((r) => r.stdout)
       .join('');
-
-    // TASK-234 review fix (critical): a mid-chain break that skipped a
-    // fail-closed gate must fail CLOSED — the old per-script path ran every
-    // hook independently, so a killed advisory never skipped a gate.
-    if (chain.skippedFailClosed) {
+    if (decisionOwnsVerdict) {
+      process.stdout.write(decisionResult.stdout);
+      if (decisionResult.stderr) process.stderr.write(decisionResult.stderr);
+      process.exitCode = 0;
+    } else if (chain.skippedFailClosed) {
+      // TASK-234 review fix (critical): a mid-chain break that skipped a
+      // fail-closed gate must fail CLOSED — the old per-script path ran every
+      // hook independently, so a killed advisory never skipped a gate.
       if (contextStdout) process.stdout.write(contextStdout);
       const skipped = scriptPaths
         .slice(chain.results.length)
-        .map((p) => path.basename(String(p).replace(/:\d+(?:\.\d+)?$/, '')))
+        .map((p) => failClosedName(p))
         .filter((name) => FAIL_CLOSED_SCRIPTS.has(name))
         .join(', ');
       process.stderr.write(`UKit hook chain broke before fail-closed gate(s) ran: ${skipped}\n`);
@@ -466,7 +564,7 @@ try {
       // No script ran at all (empty chain or budget spent before the first
       // child). With fail-closed scripts declared in the chain this must not
       // fail open.
-      const hasFailClosed = scriptPaths.some((p) => FAIL_CLOSED_SCRIPTS.has(path.basename(String(p).replace(/:\d+(?:\.\d+)?$/, ''))));
+      const hasFailClosed = scriptPaths.some((p) => FAIL_CLOSED_SCRIPTS.has(failClosedName(p)));
       if (hasFailClosed) {
         process.stderr.write('UKit hook chain produced no verdict — fail-closed gate did not run\n');
         process.exitCode = 2;

package/templates/.claude/ukit/runtime/hook-telemetry.mjs

@@ -69,7 +69,13 @@ function normalizeElapsedMs(value) {
 // Allowlist builder — the ONLY place row fields are chosen. `elapsedMs` may be
 // null when the caller genuinely could not measure it (e.g. the hook exited
 // before its stdin envelope was staged); unknown stays unknown, never zero.
+//
+// O3 (SPEC §FR-009): `stageMs` splits that elapsed window into the part the hook
+// spent waiting on stdin staging and the part it spent executing. It is OPTIONAL
+// — omitted entirely when unmeasurable — so a v1 reader's key set is unchanged
+// for a row that has no stage data, and `TELEMETRY_VERSION` stays 1.
 export function buildTimingRow(entry = {}) {
+  const stageMs = normalizeElapsedMs(entry.stageMs);
   return {
     v: TELEMETRY_VERSION,
     ts: Number.isFinite(entry.ts) ? entry.ts : Date.now(),
@@ -79,6 +85,7 @@ export function buildTimingRow(entry = {}) {
     hook: shortString(entry.hook, 128),
     elapsedMs: normalizeElapsedMs(entry.elapsedMs),
     outcome: shortString(entry.outcome, 32) || 'ok',
+    ...(stageMs === null ? {} : { stageMs }),
   };
 }
 
@@ -242,13 +249,14 @@ export function recordHookTiming({
   tool,
   hook,
   elapsedMs,
+  stageMs,
   outcome,
   toolUseId,
   ts,
   projectRoot,
   maxBytes,
 } = {}) {
-  const row = buildTimingRow({ ts, event, tool, toolUseId, hook, elapsedMs, outcome });
+  const row = buildTimingRow({ ts, event, tool, toolUseId, hook, elapsedMs, outcome, stageMs });
   const root = projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
   return appendTelemetryRow(root, sessionId, row, { maxBytes });
 }
@@ -256,6 +264,13 @@ export function recordHookTiming({
 // --- `--finish` CLI: one short-lived node process per direct hook exit ------
 // Invoked by ukit_hook_telemetry_finish (hook-telemetry.sh) from the shared
 // cleanup path in hook-input.sh, while the staged payload file still exists.
+//
+// O1 (TASK-008): the same CLI serves hooks that deliberately never stage stdin
+// (gate-first fast paths). Those have no payload mtime to measure from, so the
+// arm helper hands over an explicit start plus the envelope's identifying
+// fields: UKIT_TEL_START_MS (epoch ms), UKIT_TEL_SESSION_ID, UKIT_TEL_EVENT.
+// Every override is optional and falsy-safe, so the 18 staging hooks that set
+// none of them keep byte-for-byte today's behaviour.
 
 const FINISH_PARSE_LIMIT = 2 * 1024 * 1024; // all hooks except record-execution stage <= 2 MiB
 const FINISH_HEAD_BYTES = 256 * 1024; // bounded head scan for oversized payloads
@@ -318,32 +333,89 @@ function readEnvelope(inputFile) {
   }
 }
 
+// Explicit arm start. Non-finite, zero, or negative values are ignored: a
+// malformed marker must degrade to the staged-payload mtime (or to the honest
+// null), never to a bogus "0ms" measurement.
+function explicitStartMs(raw) {
+  const parsed = Number.parseInt(String(raw ?? ''), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return null;
+  return parsed;
+}
+
+// Start reference, most explicit first: the arm helper's epoch-ms reading, the
+// arm marker's mtime (the shell could not express sub-second precision on this
+// host), then the staged payload's mtime. None present stays null — an armed
+// hook that lost its marker must not be reported as a zero-millisecond hook.
+//
+// O3 (SPEC §FR-009) needs the two ends SEPARATELY, not just their difference:
+// when the payload's own mtime is the start, `elapsedMs` already begins where
+// staging ended, so `source` is what tells the stage split that no window is
+// left to measure.
+function resolveStartRef() {
+  const explicit = explicitStartMs(process.env.UKIT_TEL_START_MS);
+  if (explicit !== null) return { startMs: explicit, source: 'explicit' };
+  const marker = process.env.UKIT_TEL_START_FILE || '';
+  if (marker) {
+    try {
+      return { startMs: fs.statSync(marker).mtimeMs, source: 'marker' };
+    } catch {
+      // Marker already reaped — fall through to the staged payload.
+    }
+  }
+  const inputFile = process.env.UKIT_INPUT_FILE || '';
+  if (!inputFile) return { startMs: null, source: null };
+  try {
+    return { startMs: fs.statSync(inputFile).mtimeMs, source: 'payload' };
+  } catch {
+    return { startMs: null, source: null }; // never staged (refuse path) — unknown, not zero
+  }
+}
+
+// O3 (SPEC §FR-009): the stage window = the staged payload's mtime minus the arm
+// start, and only the two ARM sources qualify. A hook that deliberately skips
+// stdin staging (gate-first fast paths, SPEC §14) has no payload at all, and an
+// unarmed hook's start IS the payload mtime — reporting a stage from either
+// would invent a window that never existed, so unmeasurable stays ABSENT.
+// Clamped to the row's own elapsed window: the split attributes time inside that
+// whole, it never exceeds it.
+function resolveStageMs(startRef, elapsedMs) {
+  if (startRef.source !== 'explicit' && startRef.source !== 'marker') return null;
+  const inputFile = process.env.UKIT_INPUT_FILE || '';
+  if (!inputFile) return null;
+  let stagedAt;
+  try {
+    stagedAt = fs.statSync(inputFile).mtimeMs;
+  } catch {
+    return null;
+  }
+  const raw = stagedAt - startRef.startMs;
+  if (!Number.isFinite(raw) || raw < 0) return null;
+  return Math.min(raw, normalizeElapsedMs(elapsedMs) ?? raw);
+}
+
 function finishMain() {
   try {
     // process.uptime() covers this spawn itself so the row measures the hook,
     // not the telemetry process startup.
     const spawnOverheadMs = process.uptime() * 1000;
     const inputFile = process.env.UKIT_INPUT_FILE || '';
-    let startMs = null;
-    if (inputFile) {
-      try {
-        startMs = fs.statSync(inputFile).mtimeMs;
-      } catch {
-        startMs = null; // envelope never staged (refuse path) — unknown, not zero
-      }
-    }
+    const startRef = resolveStartRef();
+    const elapsedMs = startRef.startMs === null
+      ? null
+      : Date.now() - startRef.startMs - spawnOverheadMs;
     const envelope = inputFile ? readEnvelope(inputFile) : {};
     const rc = Number.parseInt(process.env.UKIT_TEL_RC ?? '', 10);
     // The wrapper resolves PROJECT_ROOT before arming; fall back to the hook
     // env's CLAUDE_PROJECT_DIR, then cwd (same resolution as the wrappers).
     recordHookTiming({
       projectRoot: process.env.PROJECT_ROOT || process.env.CLAUDE_PROJECT_DIR || undefined,
-      sessionId: envelope.session_id,
-      event: envelope.hook_event_name,
+      sessionId: process.env.UKIT_TEL_SESSION_ID || envelope.session_id,
+      event: process.env.UKIT_TEL_EVENT || envelope.hook_event_name,
       tool: envelope.tool_name,
       toolUseId: envelope.tool_use_id,
       hook: process.env.UKIT_TEL_HOOK,
-      elapsedMs: startMs === null ? null : Date.now() - startMs - spawnOverheadMs,
+      elapsedMs,
+      stageMs: resolveStageMs(startRef, elapsedMs),
       // Direct rows reuse the chain taxonomy (TASK-018): a non-zero exit is a
       // verdict ('exit-code'), not a guess. Timeout/overflow kills bypass the
       // EXIT trap, so those kinds stay chain-runner-reported.

package/templates/.claude/ukit/runtime/hook-telemetry.sh

@@ -11,12 +11,54 @@
 # payload. Finish spawns at most one bounded node process, discards all output,
 # and never changes the hook's exit status or verdict.
 #
+# O1 (TASK-008): hooks that never stage stdin (the gate-first fast paths wired
+# in TASK-009) have no payload mtime to measure from. They call
+# ukit_hook_telemetry_arm instead, which creates the same kind of start marker
+# without adding a node spawn to the hot path — and trap
+# ukit_hook_telemetry_finish on EXIT themselves.
+#
 # Missing runtime (pre-install tree) simply leaves telemetry off: wrappers
 # source this file with `|| true` and the armed flag stays unset.
 
 UKIT_TEL_ARMED=1
 UKIT_TEL_HOOK="$(basename "${BASH_SOURCE[1]:-$0}")"
 UKIT_TEL_RUNTIME_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+UKIT_TEL_START_FILE=""
+UKIT_TEL_START_MS=""
+
+# Epoch milliseconds from a file's mtime, or empty when this host's stat cannot
+# express sub-second precision. GNU coreutils is probed first: it rejects the
+# BSD format string outright, while BSD stat would read a GNU format string as
+# a list of directives and print something plausible-but-wrong.
+ukit_tel_file_ms() {
+  local raw seconds frac
+  raw="$(/usr/bin/stat -c '%.3Y' "$1" 2>/dev/null)" || raw=""
+  case "$raw" in
+    ''|*[!0-9.]*) raw="$(/usr/bin/stat -f '%Fm' "$1" 2>/dev/null)" || raw="" ;;
+  esac
+  case "$raw" in
+    *.*) seconds="${raw%%.*}"; frac="${raw#*.}" ;;
+    *) seconds="$raw"; frac="" ;;
+  esac
+  # Unknown stays unknown: an unparseable mtime yields empty, never a bogus 0.
+  case "$seconds" in
+    ''|*[!0-9]*) return 0 ;;
+  esac
+  frac="${frac}000"
+  printf '%s' "$(( seconds * 1000 + 10#${frac:0:3} ))"
+}
+
+# No-staging arm path. A marker file whose mtime is the start reference costs
+# one mktemp; a `node -e` clock read would cost ~30ms to measure milliseconds.
+# Always returns 0 — an unarmed hook must behave exactly like an unmeasured one.
+ukit_hook_telemetry_arm() {
+  UKIT_TEL_START_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-tel-start.XXXXXX" 2>/dev/null)" || {
+    UKIT_TEL_START_FILE=""
+    return 0
+  }
+  UKIT_TEL_START_MS="$(ukit_tel_file_ms "$UKIT_TEL_START_FILE")"
+  return 0
+}
 
 ukit_hook_telemetry_finish() {
   # The hook's exit status arrives via UKIT_TEL_RC (ukit_cleanup_hook_input
@@ -44,6 +86,8 @@ ukit_hook_telemetry_finish() {
 
   UKIT_TEL_RC="$rc" \
   UKIT_TEL_HOOK="$UKIT_TEL_HOOK" \
+  UKIT_TEL_START_MS="${UKIT_TEL_START_MS:-}" \
+  UKIT_TEL_START_FILE="${UKIT_TEL_START_FILE:-}" \
   UKIT_INPUT_FILE="${UKIT_INPUT_FILE:-}" \
   PROJECT_ROOT="${PROJECT_ROOT:-${CLAUDE_PROJECT_DIR:-}}" \
     node "$UKIT_TEL_RUNTIME_DIR/hook-telemetry.mjs" --finish </dev/null >/dev/null 2>&1 &
@@ -56,5 +100,11 @@ ukit_hook_telemetry_finish() {
   if wait "$child" 2>/dev/null; then :; fi
   kill "$watchdog" 2>/dev/null || true
   if wait "$watchdog" 2>/dev/null; then :; fi
+  # The marker existed only to be stat'd by the child above; dropping it here
+  # keeps a long session from accumulating one temp file per hooked event.
+  if [ -n "${UKIT_TEL_START_FILE:-}" ]; then
+    rm -f "$UKIT_TEL_START_FILE" 2>/dev/null || true
+    UKIT_TEL_START_FILE=""
+  fi
   return 0
 }