@ngockhoale/ukit 3.0.12 → 3.1.1

package/src/cli/commands/doctor.js

@@ -32,6 +32,22 @@ import { buildUserPaths } from '../../core/userPaths.js';
 import { loadPlaybooks } from '../../core/userPlaybooks.js';
 import { userMemoryStats } from '../../core/memory/userMemory.js';
 
+import { resolveSeamStages } from '../../core/observability/rollout.js';
+import {
+  observabilityRoot,
+  segmentsRoot,
+} from '../../core/observability/emit/lifecycle.js';
+import { readCrashReports } from '../../core/observability/emit/crash.js';
+import {
+  listSegments,
+  totalSegmentBytes,
+  ioReason,
+} from '../../core/observability/segments/internal.js';
+import {
+  lastProjectionStampPath,
+  MIN_PROJECTION_INTERVAL_MS,
+} from '../../core/observability/support/schedule.js';
+
 export const DOCTOR_HELP_FLAGS = new Set(['--help', '-h']);
 const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills', '--gateway', '--docs', '--permissions', '--conformance', '--json']);
 const SUPPORTED_FLAGS_LIST = '--help, -h, --skills, --gateway, --docs, --permissions, --conformance, --json';
@@ -73,6 +89,193 @@ function printPermissionSection(permissionReport, { verbose }) {
   }
 }
 
+// TASK-016 / SPEC §5 DF2-FR16 — flight-recorder health, read COLD from disk.
+// Doctor must never spawn a live recorder (no getRecorder/recorderHealth here —
+// lifecycle.js is imported for its path helpers only), never write, rotate, or
+// queue. Every disk-derived value is `unknown` when unavailable — never a
+// fabricated zero. Queue/drop counters live only in the live recorder, so a
+// cold read honestly reports them as unknown. Severity: FAIL-class faults are
+// reserved for hard faults (segment root unwritable while the recorder seam is
+// active); staleness/degraded reads are WARN-class advisories.
+
+const FLIGHT_FAIL_REMEDY =
+  'Fix permissions on .ukit/storage/observability/segments (or an ancestor) so the recorder can write, or set observability.stage to "off".';
+
+// Writability probe that never creates anything: when the segment root itself
+// is absent the recorder would create it lazily, so walk up to the nearest
+// existing ancestor and probe that for W_OK instead.
+async function probeWritableSegmentsRoot(segRoot) {
+  let probe = segRoot;
+  for (;;) {
+    try {
+      await fs.access(probe, fs.constants.W_OK);
+      return { writable: true };
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        const parent = path.dirname(probe);
+        if (parent === probe) return { writable: false, reason: 'io_enoent' };
+        probe = parent;
+        continue;
+      }
+      return { writable: false, reason: ioReason(error) };
+    }
+  }
+}
+
+// Scheduler stamp (`ukit-last-projection/1`) read defensively — a missing or
+// corrupt stamp degrades to null, matching schedule.js's own readStamp.
+async function readProjectionStampAt(stampPath) {
+  try {
+    const parsed = JSON.parse(await fs.readFile(stampPath, 'utf8'));
+    const at = parsed && typeof parsed === 'object' ? parsed.projected_at : undefined;
+    return Number.isFinite(at) ? at : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read-only snapshot of the flight recorder's durable state.
+ * @returns {{stage:string, seams:object, segments:object, queue:object,
+ *   lastProjection:{lagMs:number|null}, crashes:object, faults:object[]}}
+ */
+async function inspectFlightRecorderDisk({ projectRoot, config }) {
+  const seams = resolveSeamStages(config);
+  const fr = {
+    stage: seams?.recorder ?? 'off',
+    seams,
+    segments: { active: null, sealed: null, bytes: null },
+    queue: { depth: null, dropped: null },
+    lastProjection: { lagMs: null },
+    crashes: { count: null },
+    faults: [],
+  };
+
+  const obsRoot = observabilityRoot(projectRoot);
+  if (!(await pathExists(obsRoot))) {
+    return fr; // never recorded — all disk fields stay unknown
+  }
+
+  const segRoot = segmentsRoot(projectRoot);
+  const listing = await listSegments(segRoot);
+  if (listing.ok) {
+    fr.segments = {
+      active: listing.active ? 1 : 0,
+      sealed: listing.sealed.length,
+      bytes: totalSegmentBytes(listing),
+    };
+    if (listing.skipped.length > 0) {
+      const skippedNames = listing.skipped.map((entry) => entry.name).join(', ');
+      fr.faults.push({
+        severity: 'warn',
+        reason: 'segments_degraded',
+        detail: `${listing.skipped.length} segment file(s) skipped: ${skippedNames}`,
+      });
+    }
+  } else {
+    fr.faults.push({
+      severity: 'warn',
+      reason: 'segments_unreadable',
+      detail: listing.reason,
+    });
+  }
+
+  if (fr.stage !== 'off') {
+    const probe = await probeWritableSegmentsRoot(segRoot);
+    if (!probe.writable) {
+      fr.faults.push({
+        severity: 'fail',
+        reason: 'segments_root_unwritable',
+        detail: `${segRoot} not writable (${probe.reason})`,
+      });
+    }
+  }
+
+  const stampAt = await readProjectionStampAt(lastProjectionStampPath(projectRoot));
+  if (stampAt !== null) {
+    const lagMs = Math.max(0, Date.now() - stampAt);
+    fr.lastProjection = { projectedAt: stampAt, lagMs };
+    if ((seams?.projector ?? 'off') !== 'off' && lagMs > MIN_PROJECTION_INTERVAL_MS) {
+      fr.faults.push({
+        severity: 'warn',
+        reason: 'projection_stale',
+        detail: `last projection ${lagMs}ms ago exceeds ${MIN_PROJECTION_INTERVAL_MS}ms refresh interval`,
+      });
+    }
+  }
+
+  const crashes = readCrashReports(obsRoot);
+  if (crashes.ok) {
+    fr.crashes = {
+      count: crashes.coverage.files,
+      parsed: crashes.coverage.parsed,
+      corrupt: crashes.coverage.corrupt,
+      expired: crashes.coverage.expired,
+    };
+  } else {
+    fr.crashes = { count: null, error: crashes.reason };
+  }
+
+  return fr;
+}
+
+const fmtUnknown = (value) => (value === null || value === undefined ? 'unknown' : String(value));
+
+function printFlightRecorderSection(flightRecorder) {
+  const { segments, queue, lastProjection, crashes } = flightRecorder;
+  const seamText = ['recorder', 'analytics', 'projector', 'evaluation']
+    .map((name) => `${name}=${flightRecorder.seams?.[name] ?? 'unknown'}`)
+    .join(' ');
+  const segmentText = segments.sealed === null
+    ? 'unknown'
+    : `active=${fmtUnknown(segments.active)} sealed=${fmtUnknown(segments.sealed)} bytes=${fmtUnknown(segments.bytes)}`;
+  const lagText = lastProjection.lagMs === null || lastProjection.lagMs === undefined
+    ? 'unknown'
+    : `lag=${lastProjection.lagMs}ms`;
+  const crashText = crashes.count === null || crashes.count === undefined
+    ? `unknown${crashes.error ? ` (${crashes.error})` : ''}`
+    : String(crashes.count);
+  console.log(`[UKit] Flight recorder: stage: ${flightRecorder.stage} | seams: ${seamText}`);
+  console.log(`[UKit]   segments: ${segmentText}`);
+  console.log(`[UKit]   queue: depth=${fmtUnknown(queue.depth)} dropped=${fmtUnknown(queue.dropped)}`);
+  console.log(`[UKit]   last_projection: ${lagText}`);
+  console.log(`[UKit]   crashes: ${crashText}`);
+  for (const fault of flightRecorder.faults) {
+    console.log(`[UKit]   ${fault.severity === 'fail' ? 'FAIL' : 'WARN'}  ${fault.reason}${fault.detail ? ` — ${fault.detail}` : ''}`);
+    if (fault.severity === 'fail') {
+      console.log(`[UKit]      remedy: ${FLIGHT_FAIL_REMEDY}`);
+    }
+  }
+}
+
+// --json machine shape: null = unknown (mirrors `ukit telemetry status`).
+function flightRecorderJson(flightRecorder) {
+  const { segments, queue, lastProjection, crashes } = flightRecorder;
+  return {
+    stage: flightRecorder.stage,
+    seams: { ...flightRecorder.seams },
+    segments: {
+      active: segments.active,
+      sealed: segments.sealed,
+      bytes: segments.bytes,
+    },
+    queue: { depth: queue.depth, dropped: queue.dropped },
+    last_projection: {
+      projected_at: lastProjection.projectedAt ?? null,
+      lag_ms: lastProjection.lagMs,
+    },
+    crashes: {
+      count: crashes.count ?? null,
+      ...(crashes.error ? { error: crashes.error } : {}),
+    },
+    faults: flightRecorder.faults.map((fault) => ({
+      severity: fault.severity,
+      reason: fault.reason,
+      ...(fault.detail ? { detail: fault.detail } : {}),
+    })),
+  };
+}
+
 export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir = os.homedir(), ompPath = 'omp' }) {
   const unknownFlags = argv.filter((flag) => !KNOWN_FLAGS.has(flag));
   if (unknownFlags.length > 0) {
@@ -85,11 +288,18 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
   }
 
   // TASK-006 / FR-006 — `--json` is a machine surface: emit ONLY the permission
-  // report object, exit 1 when any FAIL class fires.
+  // report object (plus TASK-016's flight-recorder snapshot), exit 1 when any
+  // FAIL class fires.
   if (argv.includes('--json')) {
     const permissionReport = await inspectPermissions({ projectRoot, ompPath });
-    console.log(JSON.stringify({ permissions: permissionReport }, null, 2));
-    if (permissionReport.failures.length > 0) process.exitCode = 1;
+    const { config: jsonRuntimeConfig } = await inspectRuntimeConfig(projectRoot, { homeDir });
+    const flightRecorder = await inspectFlightRecorderDisk({ projectRoot, config: jsonRuntimeConfig });
+    console.log(JSON.stringify({
+      permissions: permissionReport,
+      flight_recorder: flightRecorderJson(flightRecorder),
+    }, null, 2));
+    const flightFailed = flightRecorder.faults.some((fault) => fault.severity === 'fail');
+    if (permissionReport.failures.length > 0 || flightFailed) process.exitCode = 1;
     return;
   }
 
@@ -345,6 +555,25 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
     );
   }
 
+  // TASK-016 / SPEC §5 DF2-FR16 — flight-recorder health read cold from disk.
+  // Read-only: no recorder spawn, no writes. FAIL-class faults join
+  // projectChecks so they print remedies and block the exit code; WARNs stay
+  // advisory and never do.
+  const flightRecorder = await inspectFlightRecorderDisk({
+    projectRoot,
+    config: runtimeConfigInspection.config,
+  });
+  printFlightRecorderSection(flightRecorder);
+  for (const fault of flightRecorder.faults) {
+    if (fault.severity !== 'fail') continue;
+    projectChecks.push({
+      label: `Flight recorder: ${fault.reason}`,
+      passed: false,
+      remediationClass: 'owner-action',
+      remedy: FLIGHT_FAIL_REMEDY,
+    });
+  }
+
   console.log('[UKit] Project rules checks:');
   for (const check of projectChecks) {
     if (check.applicable === false) continue;

package/src/cli/commands/feedback.js

@@ -6,10 +6,21 @@
 // `sessionId` = UKIT_SESSION_ID env only (SessionEnd hook exports it) — omitted
 // when unset. `--list` prints a byKind roll-up via collectFeedbackEvents and
 // never writes. Missing/empty text or unknown flag → usage on stderr, exit 1.
+//
+// DF2-FR13 (TASK-013): a successful write also emits one `outcome.observed`
+// record (kind 'user-correction', verdict 'rejected') through the recorder —
+// the write-time emit seam: the ingest lane does NOT read the manual file
+// (SPEC §14). Best-effort only: observability stage off → silent skip, and
+// any emit failure is swallowed — telemetry never changes the feedback UX.
 
 import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import { collectFeedbackEvents } from '../../diagnostics/feedbackEvents.js';
+import { inspectRuntimeConfig } from '../../core/runtimeConfig.js';
+import { resolveStage } from '../../core/observability/emit/config.js';
+import { getRecorder, segmentsRoot } from '../../core/observability/emit/lifecycle.js';
+import { recordOutcome } from '../../core/observability/evaluation/outcomes.js';
 
 const HELP_FLAGS = new Set(['--help', '-h', 'help']);
 
@@ -27,7 +38,55 @@ async function appendManualLine(projectRoot, record) {
   await fs.appendFile(filePath, JSON.stringify(record) + '\n');
 }
 
-export async function runFeedback({ projectRoot, argv = [] }) {
+// Outcome-emit latency bound: a one-shot CLI has no lifecycle loop, so the
+// record must be flushed inline to reach the segment file — bounded so the
+// telemetry path can never stall the command.
+const OUTCOME_FLUSH_DEADLINE_MS = 1_000;
+
+async function loadOutcomeConfig(projectRoot) {
+  try {
+    const inspection = await inspectRuntimeConfig(projectRoot, { homeDir: os.homedir() });
+    return inspection && inspection.config && typeof inspection.config === 'object'
+      ? inspection.config
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+// One logical event → one record: emit at write-time only. `manualRecord` is
+// the line just appended; only its sessionId leaves the process as an
+// envelope join key + opaque evidence ref — the feedback text stays in the
+// manual file, never in a payload.
+async function emitFeedbackOutcome(projectRoot, config, manualRecord) {
+  try {
+    const resolved = config ?? (await loadOutcomeConfig(projectRoot));
+    if (resolveStage(resolved) === 'off') return;
+    const recorder = getRecorder({ projectRoot, config: resolved });
+    const sessionId = typeof manualRecord?.sessionId === 'string' && manualRecord.sessionId
+      ? manualRecord.sessionId
+      : undefined;
+    recordOutcome({
+      recorder,
+      verdict: 'rejected', // a manual wrong-route label rejects the routed pick
+      kind: 'user-correction',
+      source: 'ukit-feedback',
+      sessionId,
+      evidenceRefs: sessionId ? [`session:${sessionId}`] : [],
+    });
+    // The segment store's appendRecord resolves the parent dir by realpath,
+    // which ENOENTs when no lifecycle has provisioned it yet (fresh project,
+    // one-shot CLI). Provision the recorder root inline — production does the
+    // same via startLifecycle's crash capture.
+    await fs.mkdir(segmentsRoot(projectRoot), { recursive: true });
+    await recorder.flush({ deadlineMs: OUTCOME_FLUSH_DEADLINE_MS });
+  } catch (err) {
+    if (process.env.UKIT_DEBUG_OUTCOME) console.error('outcome emit failed:', err);
+    // best-effort by contract — outcome telemetry never breaks feedback
+  }
+}
+
+export async function runFeedback({ projectRoot, argv = [], config } = {}) {
   const args = argv ?? [];
 
   if (args.some((a) => HELP_FLAGS.has(a))) {
@@ -94,4 +153,8 @@ export async function runFeedback({ projectRoot, argv = [] }) {
     return;
   }
   console.log('feedback recorded');
+
+  // DF2-FR13: land the outcome signal after the UX line is printed so the
+  // emit path can never stand between the user and the confirmation.
+  await emitFeedbackOutcome(projectRoot, config, record);
 }

package/src/cli/commands/install.js

@@ -7,6 +7,7 @@ import { installIndexRefreshHooks } from '../../index/gitHooks.js';
 import fs from 'node:fs/promises';
 import { pathExists, readJsonIfExists, removeFileOrLinkOnly } from '../../core/fileOps.js';
 import { removeTrackedPathsFromMetadata } from '../../core/metadata.js';
+import { provisionSupportDir } from '../../core/observability/support/provision.js';
 import {
   ADAPTER_BY_KEY,
   DEFAULT_OPTIONAL_TOOL_KEYS,
@@ -282,6 +283,18 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
     withCodegraph,
   });
 
+  // TASK-010 (DF2-FR10): provision Documents/UKit Support after mirror
+  // sync + config write succeed, before the summary block. The result joins
+  // the summary below; any degrade is a WARNING — never an install failure.
+  let supportProvision = null;
+  try {
+    supportProvision = await provisionSupportDir({});
+  } catch (error) {
+    supportProvision = {
+      status: 'degraded',
+      reason: error?.message ?? 'provision_failed',
+    };
+  }
   const { create, update, unchanged, skip } = result.summary;
 
   console.log(`[UKit] Project: ${result.projectContext.project.name}`);
@@ -313,6 +326,11 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
     .join(', ');
   console.log(`[UKit] Providers: ${providerStatus}, all=${result.providerContext.allSupported}`);
 
+  if (supportProvision && supportProvision.status !== 'degraded') {
+    console.log(`[UKit] Support folder: ${supportProvision.dir}`);
+  } else {
+    console.warn(`[UKit] Support folder: deferred (${supportProvision?.reason ?? 'unknown'})`);
+  }
   for (const line of formatRepairReport(result.hookRepair ?? { removals: [], files: [] })) {
     console.log(`[UKit] ${line}`);
   }