@ngockhoale/ukit 3.0.2 → 3.0.4

package/src/core/experiments/dynamicWorkflow.js

@@ -0,0 +1,492 @@
+/**
+ * dynamicWorkflow.js (TASK-012 / M06.2)
+ *
+ * Bounded dynamic-workflow experiment — compose a workflow only from a frozen
+ * known-block catalog, validate the graph before execution, and run a
+ * dependency-graph program with per-task route/completion and finite breakers
+ * (`maxAttemptsPerFailure`, global `noProgressCap`, genuine-blocker
+ * classification). Behind `experiments.dynamicWorkflow.enabled` (default
+ * false). Not wired into route-task; evaluated by fixtures (SPEC §5 FR-022;
+ * §10 "no-progress loop").
+ *
+ * Disabled posture: `composeWorkflow` returns `{status:'disabled'}` and
+ * `runProgram` returns `{status:'disabled'}` BEFORE any runner call — zero
+ * calls, zero prompt content.
+ *
+ * Program state reuses the C10 CompactResumable record *shape* (derived from
+ * CONTRACTS.md §C10 — schemaVersion/taskId/route/budget/workflow/decisions/
+ * escalationHistory/unresolvedFailures/nextAction, bounded arrays). No new
+ * state DB, no persistence, no auto-promotion: a mid-run failure degrades to
+ * the caller-supplied stable `fallback` workflow and the composition is never
+ * promoted (`promoted:false` always).
+ *
+ * Runner contract: `runner({task, attempt, strategy, state}) → result` where
+ * `result.status === 'ok'` (or the task's own `completion(result)` predicate)
+ * completes the task; any other result is a failure whose signature is
+ * `result.failure ?? result.status`. An identical repeated failure signature
+ * is not progress and is capped by `maxAttemptsPerFailure`; consecutive
+ * non-completing attempts are capped globally by `noProgressCap`. The runner
+ * is also the fault-injection hook — tests inject failures through it.
+ */
+
+const DEFAULT_MAX_ATTEMPTS_PER_FAILURE = 2;
+const DEFAULT_NO_PROGRESS_CAP = 3;
+
+// C10 bounds (CONTRACTS.md §C10): hypotheses ≤8, decisions ≤12,
+// evidenceRefs ≤24, escalationHistory ≤8.
+const MAX_DECISIONS = 12;
+const MAX_ESCALATIONS = 8;
+
+/**
+ * Frozen known-block catalog — the only blocks a composition may use.
+ * `permissions` are required grants; `owns` are exclusively-owned resources
+ * (two blocks owning the same resource is an ownership conflict); `cost` is
+ * charged against `constraints.budgetLimit`.
+ */
+export const KNOWN_BLOCKS = Object.freeze({
+  'scan-context': Object.freeze({ permissions: ['read'], owns: [], cost: 1 }),
+  plan: Object.freeze({ permissions: ['read'], owns: [], cost: 1 }),
+  edit: Object.freeze({ permissions: ['read', 'write'], owns: ['worktree'], cost: 2 }),
+  'apply-patch': Object.freeze({ permissions: ['read', 'write'], owns: ['worktree'], cost: 2 }),
+  verify: Object.freeze({ permissions: ['read', 'execute'], owns: [], cost: 1 }),
+  report: Object.freeze({ permissions: ['read'], owns: [], cost: 1 }),
+});
+
+function dynamicWorkflowEnabled(config) {
+  return config?.experiments?.dynamicWorkflow?.enabled === true;
+}
+
+function breakersOf(config) {
+  const cfg = config?.experiments?.dynamicWorkflow ?? {};
+  return {
+    maxAttemptsPerFailure:
+      typeof cfg.maxAttemptsPerFailure === 'number' && cfg.maxAttemptsPerFailure > 0
+        ? cfg.maxAttemptsPerFailure
+        : DEFAULT_MAX_ATTEMPTS_PER_FAILURE,
+    noProgressCap:
+      typeof cfg.noProgressCap === 'number' && cfg.noProgressCap > 0
+        ? cfg.noProgressCap
+        : DEFAULT_NO_PROGRESS_CAP,
+  };
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function boundedPush(list, item, cap) {
+  if (list.length < cap) {
+    list.push(item);
+  }
+}
+
+/**
+ * Compose a workflow graph from the frozen known-block catalog.
+ * Unknown block ids pass through unresolved so `validateComposition` can
+ * reject them with a named reason — a composed graph is only executable
+ * after `validateComposition` returns `{valid:true}`.
+ *
+ * @param {{blocks: Array<string|{id:string, needs?:string[]}>,
+ *   constraints?: {allowedPermissions?: string[], budgetLimit?: number},
+ *   config?: object}} input
+ * @returns {{version:1, nodes: Array, edges: Array, constraints: object} |
+ *   {status:'disabled', reasons:string[]}}
+ */
+export function composeWorkflow({ blocks = [], constraints = {}, config = null } = {}) {
+  if (!dynamicWorkflowEnabled(config)) {
+    return { status: 'disabled', reasons: ['experiment-disabled'] };
+  }
+  const list = Array.isArray(blocks) ? blocks : [];
+  const nodes = list.map((entry) => {
+    const id = typeof entry === 'string' ? entry : entry?.id;
+    const requestedNeeds = typeof entry === 'string' ? [] : entry?.needs;
+    const known = KNOWN_BLOCKS[id] ?? null;
+    return {
+      id,
+      needs: Array.isArray(requestedNeeds) ? [...requestedNeeds] : [],
+      known,
+      permissions: known ? [...known.permissions] : [],
+      owns: known ? [...known.owns] : [],
+      cost: known ? known.cost : 0,
+    };
+  });
+  const edges = [];
+  for (const node of nodes) {
+    for (const dep of node.needs) {
+      edges.push({ from: dep, to: node.id });
+    }
+  }
+  return {
+    version: 1,
+    nodes,
+    edges,
+    constraints: isPlainObject(constraints) ? { ...constraints } : {},
+  };
+}
+
+/**
+ * Validate a composed graph before execution. Rejects malformed graphs,
+ * duplicate/unknown blocks, missing dependency targets, cycles, permission
+ * violations (block requires a grant absent from
+ * `constraints.allowedPermissions`), ownership conflicts (two blocks owning
+ * the same resource), and budget overruns (Σ block cost >
+ * `constraints.budgetLimit`).
+ *
+ * @param {object} graph — output of `composeWorkflow`
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+export function validateComposition(graph) {
+  const errors = [];
+  if (!isPlainObject(graph) || !Array.isArray(graph.nodes)) {
+    return { valid: false, errors: ['malformed-graph'] };
+  }
+  const nodes = graph.nodes;
+  const constraints = isPlainObject(graph.constraints) ? graph.constraints : {};
+
+  const seen = new Set();
+  const ids = new Set();
+  for (const node of nodes) {
+    if (typeof node?.id !== 'string' || !node.id) {
+      errors.push('malformed-node');
+      continue;
+    }
+    if (seen.has(node.id)) {
+      errors.push(`duplicate-block:${node.id}`);
+      continue;
+    }
+    seen.add(node.id);
+    ids.add(node.id);
+    if (!KNOWN_BLOCKS[node.id]) {
+      errors.push(`unknown-block:${node.id}`);
+    }
+  }
+
+  const needs = new Map();
+  for (const node of nodes) {
+    if (typeof node?.id !== 'string' || !node.id) continue;
+    const list = Array.isArray(node.needs) ? node.needs : [];
+    needs.set(node.id, list);
+    for (const dep of list) {
+      if (!ids.has(dep)) {
+        errors.push(`missing-dependency:${dep}`);
+      }
+    }
+  }
+
+  // Cycle detection — iterative DFS, three-color.
+  const color = new Map(); // 0=unvisited implicit, 1=in-stack, 2=done
+  for (const start of ids) {
+    if (color.get(start) === 2) continue;
+    const stack = [[start, 0]];
+    color.set(start, 1);
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      const [id, idx] = frame;
+      const deps = (needs.get(id) ?? []).filter((d) => ids.has(d));
+      if (idx >= deps.length) {
+        color.set(id, 2);
+        stack.pop();
+        continue;
+      }
+      frame[1] = idx + 1;
+      const dep = deps[idx];
+      const depColor = color.get(dep) ?? 0;
+      if (depColor === 1) {
+        errors.push(`cycle:${dep}->${id}`);
+      } else if (depColor === 0) {
+        color.set(dep, 1);
+        stack.push([dep, 0]);
+      }
+    }
+  }
+
+  // Permission violations.
+  if (constraints.allowedPermissions !== undefined) {
+    const allowed = new Set(
+      Array.isArray(constraints.allowedPermissions) ? constraints.allowedPermissions : [],
+    );
+    for (const node of nodes) {
+      if (typeof node?.id !== 'string' || !KNOWN_BLOCKS[node.id]) continue;
+      const required = KNOWN_BLOCKS[node.id].permissions;
+      const missing = required.filter((p) => !allowed.has(p));
+      if (missing.length > 0) {
+        errors.push(`permission-denied:${node.id}:${missing.join(',')}`);
+      }
+    }
+  }
+
+  // Ownership conflicts — two blocks claiming the same exclusive resource.
+  const owners = new Map();
+  for (const node of nodes) {
+    if (typeof node?.id !== 'string' || !KNOWN_BLOCKS[node.id]) continue;
+    for (const resource of KNOWN_BLOCKS[node.id].owns) {
+      if (owners.has(resource)) {
+        errors.push(`ownership-conflict:${resource}`);
+      } else {
+        owners.set(resource, node.id);
+      }
+    }
+  }
+
+  // Budget overrun.
+  if (typeof constraints.budgetLimit === 'number') {
+    const total = nodes.reduce(
+      (sum, node) => sum + (KNOWN_BLOCKS[node?.id]?.cost ?? 0),
+      0,
+    );
+    if (total > constraints.budgetLimit) {
+      errors.push('budget-exceeded');
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+function defaultCompletion(result) {
+  return result?.status === 'ok' || result?.ok === true;
+}
+
+function failureSignature(result) {
+  if (typeof result?.failure === 'string' && result.failure) {
+    return result.failure;
+  }
+  return String(result?.status ?? 'unknown');
+}
+
+function newProgramState({ programId, tasks }) {
+  // C10 CompactResumableRun shape (CONTRACTS.md §C10) — in-memory only,
+  // bounded and redacted; no new state DB.
+  return {
+    schemaVersion: 1,
+    taskId: programId,
+    taskBoundary: 'experiment-program',
+    route: { routeVersion: 1, mode: 'dynamic-workflow', rigor: 'bounded', contractVersion: 1 },
+    budget: { policyVersion: 1, consumed: 0, remaining: tasks.length },
+    workflow: {
+      workflowId: programId,
+      workflowVersion: 1,
+      phase: 'execute',
+      completedBlocks: [],
+    },
+    invariants: [],
+    hypotheses: [],
+    decisions: [],
+    evidenceRefs: [],
+    escalationHistory: [],
+    unresolvedFailures: [],
+    nextAction: null,
+    sourceSnapshot: null,
+  };
+}
+
+/**
+ * Run a dependency-graph program of bounded tasks. Each task carries its own
+ * `route` and `completion(result)` predicate; tasks execute in dependency
+ * order and dependents of a blocked task are skipped. Finite breakers:
+ * `maxAttemptsPerFailure` caps retries of an identical failure signature
+ * (identical retry ≠ progress), `noProgressCap` caps consecutive
+ * non-completing attempts program-wide. A tripped breaker is a genuine
+ * blocker — the run degrades to the caller-supplied stable `fallback`
+ * workflow when present, else returns `status:'blocked'`. Never infinite,
+ * never auto-promoted.
+ *
+ * @param {{tasks: Array<{id:string, needs?:string[], route?:object,
+ *   completion?:Function, strategies?:string[]}>, runner: Function,
+ *   fallback?: Function, programId?: string, config?: object}} input
+ * @returns {object} `{status:'ok'|'blocked'|'degraded'|'disabled'|'invalid',
+ *   order, completed, skipped, blockers, attempts, state, promoted:false}`
+ */
+export function runProgram({
+  tasks = [],
+  runner = null,
+  fallback = null,
+  programId = 'dynamic-workflow-program',
+  config = null,
+} = {}) {
+  if (!dynamicWorkflowEnabled(config)) {
+    return { status: 'disabled', reasons: ['experiment-disabled'], promoted: false };
+  }
+  if (typeof runner !== 'function') {
+    throw new TypeError('runProgram runner must be a function.');
+  }
+  const list = Array.isArray(tasks) ? tasks : [];
+  const { maxAttemptsPerFailure, noProgressCap } = breakersOf(config);
+
+  // Structural validation — same named reasons as validateComposition.
+  const errors = [];
+  const ids = new Set();
+  const needs = new Map();
+  for (const task of list) {
+    if (typeof task?.id !== 'string' || !task.id) {
+      errors.push('malformed-task');
+      continue;
+    }
+    if (ids.has(task.id)) {
+      errors.push(`duplicate-task:${task.id}`);
+      continue;
+    }
+    ids.add(task.id);
+  }
+  for (const task of list) {
+    if (typeof task?.id !== 'string' || !task.id) continue;
+    const deps = Array.isArray(task.needs) ? task.needs : [];
+    needs.set(task.id, deps);
+    for (const dep of deps) {
+      if (!ids.has(dep)) {
+        errors.push(`missing-dependency:${dep}`);
+      }
+    }
+  }
+  // Topological order (Kahn) — deterministic input-order tie-break; leftover
+  // in-degree means a cycle.
+  const indegree = new Map([...ids].map((id) => [id, 0]));
+  for (const task of list) {
+    if (typeof task?.id !== 'string' || !task.id || !needs.has(task.id)) continue;
+    for (const dep of needs.get(task.id)) {
+      if (ids.has(dep)) {
+        indegree.set(task.id, indegree.get(task.id) + 1);
+      }
+    }
+  }
+  const order = [];
+  const ready = list
+    .filter((t) => typeof t?.id === 'string' && indegree.get(t.id) === 0)
+    .map((t) => t.id);
+  const dependents = new Map([...ids].map((id) => [id, []]));
+  for (const task of list) {
+    if (typeof task?.id !== 'string' || !task.id || !needs.has(task.id)) continue;
+    for (const dep of needs.get(task.id)) {
+      if (ids.has(dep)) {
+        dependents.get(dep).push(task.id);
+      }
+    }
+  }
+  while (ready.length > 0) {
+    const id = ready.shift();
+    order.push(id);
+    for (const next of dependents.get(id)) {
+      indegree.set(next, indegree.get(next) - 1);
+      if (indegree.get(next) === 0) {
+        ready.push(next);
+      }
+    }
+  }
+  if (order.length < ids.size) {
+    const stuck = [...ids].filter((id) => !order.includes(id));
+    errors.push(`cycle:${stuck.join(',')}`);
+  }
+  if (errors.length > 0) {
+    return { status: 'invalid', errors, promoted: false };
+  }
+
+  const state = newProgramState({ programId, tasks: list });
+  const taskById = new Map(list.map((t) => [t.id, t]));
+  const completed = [];
+  const completedSet = new Set();
+  const skipped = [];
+  const blockers = [];
+  const attempts = {};
+  let noProgress = 0;
+  let programBlocked = false;
+
+  for (const id of order) {
+    if (programBlocked) {
+      skipped.push(id);
+      continue;
+    }
+    const task = taskById.get(id);
+    const deps = needs.get(id) ?? [];
+    if (deps.some((dep) => !completedSet.has(dep))) {
+      skipped.push(id);
+      continue;
+    }
+
+    const strategies = Array.isArray(task.strategies) ? task.strategies : [];
+    const completion = typeof task.completion === 'function' ? task.completion : defaultCompletion;
+    const signatureCounts = new Map();
+    let done = false;
+    let blockedReason = null;
+    let blockedSignature = null;
+    let attempt = 0;
+
+    while (!done && blockedReason === null) {
+      attempt += 1;
+      const strategy = strategies.length > 0 ? strategies[attempt - 1] : undefined;
+      const result = runner({ task, attempt, strategy, state }) ?? {};
+      state.budget.consumed += 1;
+      if (completion(result)) {
+        done = true;
+        break;
+      }
+      noProgress += 1;
+      const signature = failureSignature(result);
+      const count = (signatureCounts.get(signature) ?? 0) + 1;
+      signatureCounts.set(signature, count);
+      if (count >= maxAttemptsPerFailure) {
+        blockedReason = 'repeated-identical-failure';
+        blockedSignature = signature;
+      } else if (noProgress >= noProgressCap) {
+        blockedReason = 'no-progress-cap';
+        blockedSignature = signature;
+      } else if (strategies.length > 0 && attempt >= strategies.length) {
+        blockedReason = 'strategies-exhausted';
+        blockedSignature = signature;
+      }
+    }
+
+    attempts[id] = attempt;
+    if (done) {
+      completed.push(id);
+      completedSet.add(id);
+      state.workflow.completedBlocks.push(id);
+      boundedPush(
+        state.decisions,
+        { taskId: id, route: task.route ?? null, attempts: attempt },
+        MAX_DECISIONS,
+      );
+      continue;
+    }
+
+    // Genuine blocker — finite, classified, recorded.
+    programBlocked = true;
+    const blocker = { taskId: id, reason: blockedReason, signature: blockedSignature, attempts: attempt };
+    blockers.push(blocker);
+    boundedPush(state.unresolvedFailures, blocker, MAX_ESCALATIONS);
+    boundedPush(
+      state.escalationHistory,
+      { taskId: id, reason: blockedReason, at: 'program' },
+      MAX_ESCALATIONS,
+    );
+    state.nextAction = `blocked:${id}:${blockedReason}`;
+  }
+
+  // `remaining` counts unfinished tasks (blocked/skipped stay unfinished) —
+  // decrementing per attempt would corrupt it on retries.
+  state.budget.remaining = Math.max(0, ids.size - completedSet.size);
+
+  const result = {
+    order,
+    completed,
+    skipped,
+    blockers,
+    attempts,
+    state,
+    promoted: false, // no auto-promotion — ever
+  };
+
+  if (blockers.length === 0) {
+    state.workflow.phase = 'complete';
+    state.nextAction = null;
+    return { status: 'ok', ...result };
+  }
+
+  state.workflow.phase = 'blocked';
+  if (typeof fallback === 'function') {
+    const fallbackResult = fallback({ state, blockers }) ?? {};
+    if (fallbackResult.status === 'ok') {
+      return { status: 'degraded', fallback: fallbackResult, ...result };
+    }
+    blockers.push({ taskId: null, reason: 'fallback-failed' });
+  }
+  return { status: 'blocked', ...result, blockers };
+}

package/src/core/fileOps.js

@@ -62,7 +62,14 @@ export async function cleanupEmptyParents(targetPath, projectRoot) {
       break;
     }
 
-    await fs.rmdir(currentDir);
+    try {
+      await fs.rmdir(currentDir);
+    } catch {
+      // Raced: the dir filled up or vanished between readdir and rmdir
+      // (concurrent install/uninstall). Either way the walk stops here —
+      // a non-empty or missing parent can never be pruned.
+      break;
+    }
     currentDir = path.dirname(currentDir);
   }
 }

package/src/core/gatewayProbe.js

@@ -131,7 +131,9 @@ export function resolveGatewayApiKey({
   }
   const settingsPaths = [
     ...(projectRoot ? [path.join(projectRoot, SETTINGS_RELATIVE_PROBE_PATH)] : []),
-    path.join(homeDir, SETTINGS_RELATIVE_PROBE_PATH),
+    // homeDir may be explicitly null — never let path.join throw (contract:
+    // this resolver never throws).
+    ...(homeDir ? [path.join(homeDir, SETTINGS_RELATIVE_PROBE_PATH)] : []),
   ];
   for (const settingsPath of settingsPaths) {
     const envBlock = readSettingsEnvBlock(settingsPath);
@@ -513,6 +515,32 @@ export async function probeGateway({
     ? (apiKeySource ?? 'api-key')
     : (envKey?.source ?? null);
   const effectiveModel = pickString(model, pickModel(env)) ?? 'claude-sonnet-4-5';
+
+  // Contract: never propagates exceptions — a missing/non-string baseUrl is a
+  // structured failure, not a TypeError on `.replace`.
+  if (typeof baseUrl !== 'string' || baseUrl.trim().length === 0) {
+    const failure = (error) => ({
+      ok: false,
+      eventsReceived: 0,
+      firstEventMs: null,
+      chunks: 0,
+      buffered: false,
+      httpOk: false,
+      isAnthropicMessage: false,
+      requestIdPresent: false,
+      bodyBytes: null,
+      error,
+    });
+    const reason = 'invalid baseUrl (non-empty string required)';
+    return {
+      streaming: failure(reason),
+      nonStreaming: failure(reason),
+      verdict: 'fail',
+      hints: [`Gateway probe could not run: ${reason} — see ${GATEWAY_DOC}.`],
+      model: effectiveModel,
+    };
+  }
+
   const url = `${baseUrl.replace(/\/+$/, '')}/v1/messages`;
   const headers = {
     'content-type': 'application/json',

package/src/core/gatewayResilienceEnv.js

@@ -118,13 +118,54 @@ export function detectCustomGateway({ rootDir, homeDir, env } = {}) {
   return { customGateway: false, baseUrl: null, source: null };
 }
 
+// Async twin of readBaseUrlFromSettingsFileSync — same swallow-everything
+// contract, but through fs.promises so the probe never blocks the event loop.
+async function readBaseUrlFromSettingsFileAsync(settingsPath) {
+  let raw;
+  try {
+    raw = await fs.readFile(settingsPath, 'utf8');
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  return readBaseUrlFromEnvBlock(parsed?.env);
+}
+
 /**
  * Async variant used by `applyGatewayResilienceEnv` so the settings-file probes can run
  * without blocking the event loop. Mirrors `detectCustomGateway` exactly; the only
  * difference is the Promise wrapper for callers that already sit in an async pipeline.
  */
-export function detectCustomGatewayAsync({ rootDir, homeDir, env } = {}) {
-  return Promise.resolve(detectCustomGateway({ rootDir, homeDir, env }));
+export async function detectCustomGatewayAsync({ rootDir, homeDir, env } = {}) {
+  const envValue = env ? readBaseUrlFromEnvValue(env[BASE_URL_ENV_VAR]) : null;
+  if (envValue) {
+    return { customGateway: true, baseUrl: envValue, source: 'env' };
+  }
+
+  if (rootDir) {
+    const projectValue = await readBaseUrlFromSettingsFileAsync(
+      path.join(rootDir, SETTINGS_RELATIVE_PATH),
+    );
+    if (projectValue) {
+      return { customGateway: true, baseUrl: projectValue, source: 'claude-settings' };
+    }
+  }
+
+  if (homeDir) {
+    const homeValue = await readBaseUrlFromSettingsFileAsync(
+      path.join(homeDir, SETTINGS_RELATIVE_PATH),
+    );
+    if (homeValue) {
+      return { customGateway: true, baseUrl: homeValue, source: 'claude-settings' };
+    }
+  }
+
+  return { customGateway: false, baseUrl: null, source: null };
 }
 
 function backupPathFor(settingsPath) {
@@ -154,7 +195,7 @@ export async function applyGatewayResilienceEnv({
   homeDir = os.homedir(),
   env = process.env,
 } = {}) {
-  const detection = detectCustomGateway({ rootDir: projectRoot, homeDir, env });
+  const detection = await detectCustomGatewayAsync({ rootDir: projectRoot, homeDir, env });
 
   if (!detection.customGateway) {
     return {

package/src/core/handoffDocValidator.js

@@ -64,7 +64,9 @@ function planSectionPositions(sections) {
   const positions = new Map();
   for (const s of sections) {
     for (const token of PLAN_SECTIONS) {
-      if (!positions.has(token) && s.name.startsWith(token)) positions.set(token, s.pos);
+      // `## §10`/`## §12` must not satisfy `§1` — the token only matches when it
+      // is the whole heading or is followed by a non-digit boundary (space, colon…).
+      if (!positions.has(token) && new RegExp(`^${token}(?!\\d)`).test(s.name)) positions.set(token, s.pos);
     }
   }
   return positions;

package/src/core/hookChainDoctor.js

@@ -79,6 +79,22 @@ async function tailLines(filePath, size) {
 }
 
 export async function inspectHookChainHealth({ projectRoot, now = Date.now() } = {}) {
+  const label = 'hook-chain health';
+
+  // Never-fatal posture extends to malformed input: a missing projectRoot is
+  // "unknown", not a TypeError (same contract as inspectProjectImportant).
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    return {
+      label,
+      passed: true,
+      failed: false,
+      severity: 'info',
+      remediationClass: 'advisory',
+      detail: 'no telemetry — invalid projectRoot (unknown, not failure)',
+      counts: { rowsScanned: 0, filesScanned: 0, ok: 0 },
+    };
+  }
+
   const dir = telemetryDirFor(projectRoot);
   const files = await recentTelemetryFiles(dir, now);
 
@@ -144,7 +160,6 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
     }
   }
 
-  const label = 'hook-chain health';
 
   if (counts.rowsScanned === 0) {
     return {