@ngockhoale/ukit 3.0.12 → 3.1.0

package/src/core/observability/support/projector.js

@@ -29,8 +29,10 @@
  * Pipeline: stage gate → Documents resolution → collect → double-gate
  * (validateSemanticRecord + sanitizeForSupport — default-deny, unknown
  * fields rejected) → age cap → bundle-local pseudonymization → per-trace
- * summarize + digest (failure-promoted ordering) → byte cap → atomic
- * per-file temp-rename write (manifest.json last = commit point) →
+ * summarize + digest (failure-promoted ordering) → byte cap →
+ * detectAnomalies over the final digest set + readCrashReports (DF2-FR11:
+ * anomalies section + crash_count in SUMMARY.md and manifest coverage) →
+ * atomic per-file temp-rename write (manifest.json last = commit point) →
  * stale owned-file cleanup → support-view prune.
  *
  * Safety invariants:
@@ -60,6 +62,8 @@ import { validateSemanticRecord } from '../schema/validate.js';
 import { summarizeTrace, METRIC_VERSION } from '../analytics/summary.js';
 import { renderTraceDigest } from '../analytics/digest.js';
 import { resolveStage } from '../emit/config.js';
+import { detectAnomalies } from '../analytics/anomalies.js';
+import { readCrashReports } from '../emit/crash.js';
 import { resolveSupportDir } from './paths.js';
 import { pruneSupportView, isOwnedName } from './retention.js';
 
@@ -167,7 +171,7 @@ function renderReadme() {
   ].join('\n');
 }
 
-function renderSummary({ generatedAt, lagMs, coverage, caps, traces }) {
+function renderSummary({ generatedAt, lagMs, coverage, caps, traces, anomalies }) {
   const lines = [
     '# UKit Support — projection summary',
     '',
@@ -185,6 +189,8 @@ function renderSummary({ generatedAt, lagMs, coverage, caps, traces }) {
     `traces: ${traces.length}`,
     `digests_written: ${coverage.digests_written}`,
     `digests_dropped_by_cap: ${coverage.digests_dropped_by_cap}`,
+    `anomalies_detected: ${coverage.anomalies_detected}`,
+    `crash_count: ${coverage.crash_count === null ? 'unknown' : coverage.crash_count}`,
   ];
   if (coverage.store) {
     lines.push(
@@ -195,6 +201,24 @@ function renderSummary({ generatedAt, lagMs, coverage, caps, traces }) {
     lines.push(`skipped_files: ${coverage.skipped_files.join(', ')}`);
   }
   lines.push('', '## caps', `max_bytes: ${caps.maxBytes}`, `max_age_ms: ${caps.maxAgeMs}`, `max_digests: ${caps.maxDigests}`, `max_records: ${caps.maxRecords}`, '');
+
+  // Anomalies: failed digests first (existing promotion), then detector
+  // hits (`- anomaly:<kind> <trace-ref>`). Deterministic — detectAnomalies
+  // returns sorted records; anomaly counts are declared in coverage above.
+  lines.push('## anomalies');
+  const anomalyLines = [];
+  for (const t of traces) {
+    if (t.failed) anomalyLines.push(`- failed:${t.digestName}`);
+  }
+  for (const a of anomalies) {
+    const owner = traces.find((t) => t.traceId === a.trace_id);
+    const traceRef = a.trace_id === null ? 'untraced' : a.trace_id;
+    anomalyLines.push(`- anomaly:${a.payload.kind} trace=${traceRef}${owner ? ` digest=${owner.digestName}` : ''}`);
+  }
+  if (anomalyLines.length === 0) anomalyLines.push('- none');
+  lines.push(...anomalyLines);
+  lines.push('');
+
   lines.push('## traces');
   for (const t of traces) {
     lines.push(`- ${t.digestName} failed=${t.failed} spans=${t.summary.coverage.spans} telemetry_complete=${t.summary.telemetry_complete}`);
@@ -254,8 +278,8 @@ function projectKeyFor(snapshot, options) {
   return { key: 'unknown', source: 'unknown' };
 }
 
-function projectDirName(key) {
-  return `proj-${sha256Hex(key).slice(0, 12)}`;
+export function projectDirName(key) {
+  return `proj-${sha256Hex(String(key)).slice(0, 12)}`;
 }
 
 /**
@@ -408,10 +432,20 @@ export async function projectSupport(snapshot = {}, options = {}) {
     truncated_records: 0,
     digests_written: 0,
     digests_dropped_by_cap: 0,
+    anomalies_detected: 0,
+    // null until readCrashReports resolves — unknown is declared, never 0.
+    crash_count: null,
     skipped_files: [],
     store: null,
   };
 
+  // Crash reports live beside the canonical segment root; when the
+  // snapshot is record-array-only the crash state is honestly unknown.
+  if (typeof snap.root === 'string' && snap.root.length > 0) {
+    const crashRead = readCrashReports(snap.root);
+    if (crashRead.ok) coverage.crash_count = crashRead.crashes.length;
+  }
+
   // --- collect + double-gate ---
   const raw = await collectRecords(snap, coverage);
   coverage.records_in = raw.length;
@@ -489,32 +523,66 @@ export async function projectSupport(snapshot = {}, options = {}) {
   const lagMs = latestRecordMs > 0 ? Math.max(0, now - latestRecordMs) : null;
 
   // --- assemble file set under the byte cap ---
+  // The fixed set is README + SUMMARY.md + manifest.json: all three are
+  // mandatory outputs, so their EXACT bytes are charged against maxBytes
+  // before any digest or record line claims budget. records.jsonl is
+  // trimmed into whatever remains, with a small wobble reserve covering
+  // the byte-count digits the final SUMMARY/manifest render gains.
   const files = {};
   files['README.md'] = renderReadme();
-  files['SUMMARY.md'] = renderSummary({ generatedAt, lagMs, coverage, caps, traces: shown });
+  // Pre-seed so the in-loop manifest already lists a records.jsonl
+  // file-table entry — otherwise fixedBytes() under-sizes the manifest by
+  // a whole entry (~80B) and the written bundle can exceed maxBytes.
+  files['records.jsonl'] = '';
   const recordLines = projected.map((r) => JSON.stringify(r));
-  files['records.jsonl'] = recordLines.length ? `${recordLines.join('\n')}\n` : '';
   for (const t of shown) {
     files[t.digestName] = renderTraceDigest(t.summary, { records: t.records, coverage: coverage.store });
   }
 
-  // Drop lowest-ranked digests until the fixed set fits under the cap.
-  const manifestReserve = 4096;
+  const digestBytes = () => shown.reduce((s, t) => s + Buffer.byteLength(files[t.digestName], 'utf8'), 0);
+  const manifestBytes = (manifest) => Buffer.byteLength(`${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
   const fixedBytes = () =>
     Buffer.byteLength(files['README.md'], 'utf8') +
     Buffer.byteLength(files['SUMMARY.md'], 'utf8') +
-    manifestReserve;
-  while (shown.length > 0 && fixedBytes() + shown.reduce((s, t) => s + Buffer.byteLength(files[t.digestName], 'utf8'), 0) > caps.maxBytes) {
+    manifestBytes(files['manifest.json']);
+
+  // Anomaly detection runs on the digest set it renders — every cited
+  // trace has a digest the reader can open (no dangling citation).
+  // Records are the projected/pseudonymized set, so evidence_refs stay
+  // bundle-local. Span-less event-only traces are valid TraceSummaries
+  // here — detectAnomalies still runs its event-level detectors on them.
+  const renderSummaryCurrent = () => {
+    const evidenceRecords = new Map(shown.map((t) => [t.traceId, t.records]));
+    const anomalies = detectAnomalies(shown.map((t) => t.summary), { evidenceRecords });
+    coverage.anomalies_detected = anomalies.length;
+    return renderSummary({ generatedAt, lagMs, coverage, caps, traces: shown, anomalies });
+  };
+
+  const renderFixed = () => {
+    coverage.digests_written = shown.length;
+    files['SUMMARY.md'] = renderSummaryCurrent();
+    files['manifest.json'] = buildManifest({ generatedAt, pseudonym: projectPseudonym, coverage, caps, files, projectIdSource });
+  };
+
+  // Drop lowest-ranked digests until the whole fixed set fits the cap.
+  // Each drop shrinks SUMMARY.md and the manifest, so they are re-rendered
+  // inside the loop rather than sized once against a reserve estimate.
+  renderFixed();
+  while (shown.length > 0 && fixedBytes() + digestBytes() > caps.maxBytes) {
     const dropped = shown.pop();
     delete files[dropped.digestName];
     coverage.digests_dropped_by_cap += 1;
+    renderFixed();
   }
-  coverage.digests_written = shown.length;
 
-  // records.jsonl takes the remaining budget; tail (lowest-ranked) lines
-  // drop first. Prefix accumulation — O(n), no repeated joins.
-  const digestBytes = shown.reduce((s, t) => s + Buffer.byteLength(files[t.digestName], 'utf8'), 0);
-  const recordsBudget = Math.max(0, caps.maxBytes - fixedBytes() - digestBytes);
+  // records.jsonl takes whatever budget the fixed set + digests leave;
+  // tail (lowest-ranked) lines drop first. The final SUMMARY/manifest
+  // re-render below can grow by a few bytes (records.jsonl byte count +
+  // truncated_records digit width inside their own contents) — the wobble
+  // is bounded by RECORDS_WOBBLE_RESERVE and charged up front, so the
+  // written bundle never exceeds maxBytes.
+  const RECORDS_WOBBLE_RESERVE = 64;
+  const recordsBudget = Math.max(0, caps.maxBytes - fixedBytes() - digestBytes() - RECORDS_WOBBLE_RESERVE);
   let used = 0;
   let keptLines = 0;
   for (const line of recordLines) {
@@ -526,8 +594,10 @@ export async function projectSupport(snapshot = {}, options = {}) {
   coverage.truncated_records += recordLines.length - keptLines;
   files['records.jsonl'] = keptLines > 0 ? `${recordLines.slice(0, keptLines).join('\n')}\n` : '';
 
-  const manifest = buildManifest({ generatedAt, pseudonym: projectPseudonym, coverage, caps, files, projectIdSource });
-  files['manifest.json'] = `${JSON.stringify(manifest, null, 2)}\n`;
+  // Final render at true coverage: SUMMARY declares the real truncated
+  // count, manifest carries checksums/sizes at written size.
+  files['SUMMARY.md'] = renderSummaryCurrent();
+  files['manifest.json'] = `${JSON.stringify(buildManifest({ generatedAt, pseudonym: projectPseudonym, coverage, caps, files, projectIdSource }), null, 2)}\n`;
 
   // --- write phase: per-file atomic temp-rename, manifest last ---
   await fs.promises.mkdir(dir, { recursive: true });

package/src/core/observability/support/provision.js

@@ -0,0 +1,160 @@
+/**
+ * provision.js (TASK-010, SPEC §5 DF2-FR10, §8) — install-time
+ * `Documents/UKit Support` provisioning.
+ *
+ *   provisionSupportDir({ homeDir?, env?, platform?, now? })
+ *     → { status: 'created'|'exists'|'degraded', dir?, reason? }
+ *
+ * Called once per `ukit install` (see src/cli/commands/install.js). It
+ * resolves the OS-native Documents folder via paths.js, creates the
+ * `UKit Support` directory when absent, and lays down the two skeleton
+ * files the support view needs before any projection has ever run:
+ *
+ *   README.md      — human stub: what the folder is, how to zip+send it.
+ *   manifest.json  — minimal skeleton `{format, provisioned: true,
+ *                    redaction_version, created_at, files:{}}` marking the
+ *                    dir as UKit-owned. Written last — the manifest is the
+ *                    commit point, same convention as the projector.
+ *
+ * Safety invariants (shared with projector.js):
+ *   - Never overwrites: existing regular files are left byte-for-byte
+ *     intact — foreign files AND earlier skeleton files alike. A second
+ *     provision therefore reports `exists` with zero writes.
+ *   - Never follows symlinks: `UKit Support` or a skeleton file being a
+ *     symlink degrades with a typed reason (`blocked_symlink` /
+ *     `required_file_blocked`); the link is not traversed or replaced.
+ *   - No raw fallback: an unresolvable Documents folder degrades with the
+ *     resolver's `documents_*` reason — nothing is written anywhere else.
+ *   - Never throws: every io failure maps to {status:'degraded',reason}.
+ *
+ * `ukit uninstall` is deliberately untouched: user-facing data stays.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { writeFileAtomic } from '../../fileOps.js';
+import { ioReason } from '../segments/internal.js';
+import { REDACTION_VERSION } from '../privacy/allowlist.js';
+import { SUPPORT_FORMAT } from './manifest.js';
+import { resolveSupportDir } from './paths.js';
+
+/** Skeleton names provision may fill in; manifest is the commit point. */
+const SKELETON_ORDER = ['README.md', 'manifest.json'];
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function renderReadmeStub() {
+  return `# UKit Support
+
+This folder is created by UKit (\`ukit install\`) for support diagnostics.
+It is safe to share: every bundle is sanitized (IDs are bundle-local
+pseudonyms) and each project keeps its own proj-* subdirectory.
+
+## What lives here
+- \`proj-*\` directories — one per project, holding README/SUMMARY,
+  records, and per-trace digests when telemetry support projection runs.
+
+## How to send it for support
+
+1. Zip this whole folder (or just the proj-* subdirectory for the
+   project in question).
+2. Send the zip to whoever is helping you debug.
+3. They can verify and inspect it with \`ukit telemetry import <path>\`.
+
+You may delete this folder at any time — nothing depends on it
+unconditionally. \`ukit uninstall\` deliberately leaves it in place.
+`;
+}
+
+function skeletonManifest(createdAt) {
+  return {
+    format: SUPPORT_FORMAT,
+    provisioned: true,
+    redaction_version: REDACTION_VERSION,
+    created_at: createdAt,
+    files: {},
+  };
+}
+
+/**
+ * @param {{ homeDir?: string|null, env?: object, platform?: string, now?: number }} [opts]
+ * @returns {Promise<{ status: 'created'|'exists'|'degraded', dir?: string, reason?: string }>}
+ */
+export async function provisionSupportDir(opts = {}) {
+  const resolved = await resolveSupportDir({
+    homeDir: opts.homeDir,
+    env: opts.env,
+    platform: opts.platform,
+  });
+  if (!resolved.ok) {
+    return { status: 'degraded', reason: resolved.reason };
+  }
+  const dir = resolved.dir;
+
+  // The support path itself must be a real directory — never a symlink
+  // (nothing is followed) and never a foreign file (nothing replaced).
+  let status = 'created';
+  let existed = false;
+  try {
+    const st = await fs.promises.lstat(dir);
+    if (st.isSymbolicLink()) {
+      return { status: 'degraded', dir, reason: 'blocked_symlink' };
+    }
+    if (!st.isDirectory()) {
+      return { status: 'degraded', dir, reason: 'support_path_not_directory' };
+    }
+    existed = true;
+  } catch (err) {
+    if (!err || err.code !== 'ENOENT') {
+      return { status: 'degraded', dir, reason: ioReason(err) };
+    }
+  }
+  if (existed) status = 'exists';
+  else {
+    try {
+      await fs.promises.mkdir(dir, { recursive: true });
+    } catch (err) {
+      return { status: 'degraded', dir, reason: ioReason(err) };
+    }
+  }
+
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const files = {
+    'README.md': renderReadmeStub(),
+    'manifest.json': `${JSON.stringify(skeletonManifest(new Date(now).toISOString()), null, 2)}\n`,
+  };
+
+  // Fill in only missing skeleton files — an existing regular file wins,
+  // whether it is foreign or one of ours from a previous install.
+  let requiredBlocked = false;
+  for (const name of SKELETON_ORDER) {
+    const target = path.join(dir, name);
+    let st;
+    try {
+      st = await fs.promises.lstat(target);
+    } catch (err) {
+      if (err && err.code === 'ENOENT') {
+        st = null;
+      } else {
+        return { status: 'degraded', dir, reason: ioReason(err) };
+      }
+    }
+    if (st) {
+      if (!st.isFile() || st.isSymbolicLink()) requiredBlocked = true;
+      continue; // foreign or owned: never overwritten either way
+    }
+    try {
+      await writeFileAtomic(target, files[name]);
+    } catch (err) {
+      return { status: 'degraded', dir, reason: ioReason(err) };
+    }
+  }
+
+  if (requiredBlocked) {
+    return { status: 'degraded', dir, reason: 'required_file_blocked' };
+  }
+  return { status, dir };
+}

package/src/core/observability/support/renderer.js

@@ -27,8 +27,8 @@ const README_ORDER = [
   '   before trusting anything else.',
   '2. `SUMMARY.md` — projection summary: counts, freshness lag, declared',
   '   coverage gaps. Start here.',
-  '3. Anomalies — traces flagged failed/blocked are promoted first in',
-  '   SUMMARY.md and in the digest ordering.',
+  '3. Anomalies — SUMMARY.md `## anomalies` lists failed digests plus',
+  '   deterministic detector hits (anomaly:<kind>) with their trace refs.',
   '4. `digest-*.md` — per-trace digests, failure-promoted. Read the',
   '   failing traces before the clean ones.',
   '5. `records.jsonl` — the raw sanitized evidence behind every claim',

package/src/core/observability/support/schedule.js

@@ -0,0 +1,174 @@
+/**
+ * schedule.js (TASK-012, SPEC §5 DF2-FR12, §10) — automatic support-projection
+ * scheduling behind the projector seam.
+ *
+ *   maybeRefreshSupport({ projectRoot, config, recorder?, homeDir?, env?,
+ *                         platform?, now? })
+ *     → { status: 'refreshed', projected_at, stamped, bytes }
+ *       | { status: 'skipped', reason }
+ *
+ *   MIN_PROJECTION_INTERVAL_MS = 15 * 60 * 1000
+ *   STAMP_FORMAT = 'ukit-last-projection/1'
+ *
+ * Gate order (each gate reports its own typed reason):
+ *   1. no projectRoot            → skipped / no_project_root
+ *   2. projector seam off        → skipped / stage_off — resolveSeamStages
+ *      clamps global 'off'/'shadow' (and restrictive-only seam overrides)
+ *      below the projector minimum ('canary'); the call then delegates the
+ *      kill-switch obligation to projectSupport's existing stage-off
+ *      invalidation path instead of returning early, so disabling the seam
+ *      still scrubs previously-owned material.
+ *   3. interval gate             → skipped / min_interval — the persisted
+ *      stamp `.ukit/storage/observability/last-projection.json` carries the
+ *      last SUCCESSFUL projection; `observability.projector.min_interval_ms`
+ *      can lengthen the gap but never shrink it below the 15min floor
+ *      (write-spam bound — SPEC §10 wants no write storm on repeat runs).
+ *      A missing/corrupt stamp is treated as absent: refresh once, never
+ *      crash-loop on a poisoned state file.
+ *   4. projectSupport({ root })  → a 'written' result re-stamps the file;
+ *      degraded/skipped results map to { status:'skipped', reason } — the
+ *      scheduled path reports the degrade, it does not promote it to an
+ *      error (collect still exits on its own lane's verdict).
+ *
+ * `recorder?` is the in-process collect path's recorder (DF2-FR12 interfaces):
+ * before projecting, queued records are flushed with a bounded deadline so
+ * the projection sees what collect just ingested; flush failures degrade to
+ * whatever was already durable, never to an exception.
+ *
+ * Freshness lag is derived by the doctor/status surface from this stamp and
+ * from manifest.generated_at — the stamp is the scheduler's own memory, not
+ * the projector's.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { writeFileAtomic } from '../../fileOps.js';
+import { resolveStage } from '../emit/config.js';
+import { resolveSeamConfig } from '../rollout.js';
+import { projectSupport } from './projector.js';
+
+export const MIN_PROJECTION_INTERVAL_MS = 15 * 60 * 1000;
+export const STAMP_FORMAT = 'ukit-last-projection/1';
+const STAMP_FILE_NAME = 'last-projection.json';
+const PRE_PROJECTION_FLUSH_DEADLINE_MS = 10_000;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** `<projectRoot>/.ukit/storage/observability/last-projection.json`. */
+export function lastProjectionStampPath(projectRoot) {
+  return path.join(projectRoot, '.ukit', 'storage', 'observability', STAMP_FILE_NAME);
+}
+
+/**
+ * Effective minimum gap between scheduled writes: the configured override
+ * lengthens the interval but never beats the 15min floor; malformed values
+ * degrade to the floor itself.
+ */
+export function projectionMinIntervalMs(config) {
+  const node = isPlainObject(config) ? config.observability : undefined;
+  const raw = isPlainObject(node) && isPlainObject(node.projector)
+    ? node.projector.min_interval_ms
+    : undefined;
+  const interval = Number.isFinite(raw) && raw > 0 ? raw : MIN_PROJECTION_INTERVAL_MS;
+  return Math.max(interval, MIN_PROJECTION_INTERVAL_MS);
+}
+
+async function readStamp(stampPath) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await fs.readFile(stampPath, 'utf8'));
+  } catch {
+    return null; // missing, corrupt, unreadable — all mean "no stamp"
+  }
+  const at = isPlainObject(parsed) ? parsed.projected_at : undefined;
+  return Number.isFinite(at) ? at : null;
+}
+
+async function writeStamp(stampPath, at) {
+  try {
+    await fs.mkdir(path.dirname(stampPath), { recursive: true });
+    await writeFileAtomic(
+      stampPath,
+      JSON.stringify({ format: STAMP_FORMAT, projected_at: at }) + '\n',
+    );
+    return true;
+  } catch {
+    return false; // the stamp is scheduler memory — a write failure skips, never throws
+  }
+}
+
+/**
+ * @param {{ projectRoot?: string, config?: object, recorder?: object,
+ *           homeDir?: string|null, env?: object, platform?: string,
+ *           now?: number }} opts
+ * @returns {Promise<{status:'refreshed'|'skipped', reason?:string}>}
+ */
+export async function maybeRefreshSupport(opts = {}) {
+  const { projectRoot, config } = isPlainObject(opts) ? opts : {};
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    return { status: 'skipped', reason: 'no_project_root' };
+  }
+  const root = path.resolve(projectRoot);
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+
+  // Seam config view: resolveStage(view) is the projector seam's effective
+  // stage — below the seam's 'canary' minimum it resolves 'off', which is
+  // the value projectSupport already treats as its kill switch.
+  const seamConfig = resolveSeamConfig(config, 'projector');
+  const seamStage = resolveStage(seamConfig);
+  if (seamStage === 'off') {
+    try {
+      await projectSupport(
+        { root: path.join(root, '.ukit', 'storage', 'observability', 'segments') },
+        { config: seamConfig, projectRoot: root, homeDir: opts.homeDir, env: opts.env, platform: opts.platform },
+      );
+    } catch {
+      // invalidation is best-effort even on a dead projector path
+    }
+    return { status: 'skipped', reason: 'stage_off' };
+  }
+
+  const stampPath = lastProjectionStampPath(root);
+  const lastAt = await readStamp(stampPath);
+  if (lastAt !== null && now - lastAt < projectionMinIntervalMs(config)) {
+    return { status: 'skipped', reason: 'min_interval' };
+  }
+
+  // In-process collect lane: drain queued records before the snapshot read
+  // so the projection reflects this collect. Bounded — a stuck writer eats
+  // only the deadline, never the caller's lifetime.
+  const recorder = opts.recorder;
+  if (recorder && typeof recorder.flush === 'function') {
+    try {
+      await recorder.flush({ deadlineMs: PRE_PROJECTION_FLUSH_DEADLINE_MS });
+    } catch {
+      // degrade: project whatever is already durable
+    }
+  }
+
+  let result;
+  try {
+    result = await projectSupport(
+      { root: path.join(root, '.ukit', 'storage', 'observability', 'segments') },
+      {
+        config: seamConfig,
+        projectRoot: root,
+        homeDir: opts.homeDir,
+        env: opts.env,
+        platform: opts.platform,
+        now,
+      },
+    );
+  } catch {
+    return { status: 'skipped', reason: 'projector_error' };
+  }
+
+  if (result && result.status === 'written') {
+    const stamped = await writeStamp(stampPath, now);
+    return { status: 'refreshed', projected_at: now, stamped, bytes: result.bytes ?? 0 };
+  }
+  return { status: 'skipped', reason: (result && result.reason) || 'projection_skipped' };
+}

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

@@ -149,7 +149,13 @@ UKIT_RUNTIME_DIR="$SCRIPT_DIR/../ukit/runtime" node -e '
 // is still legally waiting for the lock.
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 8000;
 const LOCK_STARTED_AT = Date.now();
-setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+setTimeout(() => {
+  // A wedged fs op (fifo/NFS as a state file) parks a libuv threadpool thread and
+  // the atexit teardown of process.exit()/reallyExit() waits for it forever — the
+  // deadline can only escape by killing itself. The bash call is `|| true`-masked,
+  // so the observable contract stays "exit 0".
+  try { process.kill(process.pid, "SIGKILL"); } catch {}
+}, HOOK_DEADLINE_MS).unref();
 const fsp = require("fs").promises;
 const path = require("path");
 const { pathToFileURL } = require("url");

package/template_project/.claude/hooks/auto-prune-bash.sh

@@ -54,18 +54,27 @@ const LOCK_STARTED_AT = Date.now();
 // SPEC §8: a failed prune abandons configured work — announce it (success stays silent).
 // Unpruned rules are harmless (stale entries simply never match again), so degrade is
 // advisory-only and still exits 0.
-function emitDegrade(reason) {
+function emitDegrade(reason, onDone) {
   try {
-    process.stdout.write(JSON.stringify({
-      systemMessage: `UKit auto-prune-bash: ${reason}`,
-    }) + "\n");
-  } catch {}
+    process.stdout.write(
+      JSON.stringify({ systemMessage: `UKit auto-prune-bash: ${reason}` }) + "\n",
+      () => { try { onDone?.(); } catch {} },
+    );
+  } catch {
+    try { onDone?.(); } catch {}
+  }
 }
 
 setTimeout(() => {
-  emitDegrade("prune exceeded its deadline; stale Bash auto-allow rules were not pruned this session — the next session retries.");
-  process.exit(0);
+  emitDegrade("prune exceeded its deadline; stale Bash auto-allow rules were not pruned this session — the next session retries.", () => {
+    // The degrade line must be flushed BEFORE the kill, and process.exit() cannot
+    // be used here: a wedged fs op parks a libuv threadpool thread and atexit
+    // teardown waits for it forever. SIGKILL is the only guaranteed escape; the
+    // bash call is `|| true`-masked, so the observable contract stays "exit 0".
+    try { process.kill(process.pid, "SIGKILL"); } catch {}
+  });
 }, HOOK_DEADLINE_MS).unref();
+
 const fsp = require("fs").promises;
 const path = require("path");
 const { pathToFileURL } = require("url");

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

@@ -71,9 +71,16 @@ setTimeout(() => {
   try {
     process.stdout.write(JSON.stringify({
       systemMessage: `UKit verification-guard: evaluation exceeded its ${HOOK_DEADLINE_MS}ms deadline; this command was allowed without verification tracking.`,
-    }) + '\n');
-  } catch {}
-  process.exit(0);
+    }) + '\n', () => {
+      // The degrade line must be flushed BEFORE the kill, and process.exit() cannot
+      // be used here: a wedged fs op parks a libuv threadpool thread and atexit
+      // teardown waits for it forever. SIGKILL is the only guaranteed escape; the
+      // wrapper exits 0 regardless of node status (advisory contract).
+      try { process.kill(process.pid, 'SIGKILL'); } catch {}
+    });
+  } catch {
+    try { process.kill(process.pid, 'SIGKILL'); } catch {}
+  }
 }, HOOK_DEADLINE_MS).unref();
 // 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
@@ -570,4 +577,6 @@ process.exit(0);
 });
 NODE
 
-exit $?
+# Advisory hook: the deadline may SIGKILL node past a wedged fs op — the hook
+# contract is still always-exit-0 regardless of the child status.
+exit 0

package/template_project/.claude/ukit/runtime/async-lock.mjs

@@ -452,6 +452,15 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
   const releaseRetry = (op) => withTransientFsRetry(op, { deadlineMs: LOCK_RESERVE_MS });
 
   while (true) {
+    // Abort wins over every other condition, checked once per iteration: an abort
+    // landing mid-sweep/mid-op must still surface the typed aborted outcome — the
+    // ops below can throw the raw signal.reason (withTransientFsRetry rethrows
+    // AbortError when the signal fires during a transient retry), and a non-EEXIST
+    // throw would otherwise escape as an unhandled rejection instead of the
+    // contract's { ok: false, reason: 'aborted' } envelope.
+    if (signal?.aborted) {
+      return { ok: false, reason: 'aborted', waitedMs: Date.now() - startedAt };
+    }
     // Reap stale `*.reclaim-*` quarantine dirs stranded by dead reapers. Cheap:
     // one readdir per attempt, all failures swallowed (C79-21).
     await sweepStaleReclaims(lockPath, stale);
@@ -489,6 +498,11 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
       owned = true;
       break;
     } catch (error) {
+      // An abort surfacing as the raw AbortError out of a transient retry is the
+      // typed aborted outcome, never an untyped throw.
+      if (signal?.aborted) {
+        return { ok: false, reason: 'aborted', waitedMs: Date.now() - startedAt };
+      }
       if (error?.code !== 'EEXIST') throw error;
     }
 
@@ -533,6 +547,12 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
     }
     if (reclaimed) continue;
 
+    // Abort after the wait phase still returns the typed aborted outcome — the
+    // budget check must not claim 'busy' for a caller that was actually cancelled.
+    if (signal?.aborted) {
+      return { ok: false, reason: 'aborted', waitedMs: Date.now() - startedAt };
+    }
+
     const waitedMs = Date.now() - startedAt;
     if (waitedMs >= budget) {
       // Fail closed: the caller's policy decides what a busy lock means. The callback
@@ -548,6 +568,12 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
     }
   }
 
+  // Abort between acquire and the critical section releases the owned lock through
+  // the normal finally path and reports 'aborted' instead of running fn after the
+  // caller was cancelled.
+  if (signal?.aborted) {
+    return { ok: false, reason: 'aborted', waitedMs: Date.now() - startedAt };
+  }
   try {
     return { ok: true, value: await fn() };
   } finally {