@ngockhoale/ukit 3.0.11 → 3.1.0

package/src/cli/commands/telemetry.js

@@ -0,0 +1,460 @@
+// `ukit telemetry` (TASK-009, SPEC §5 DF2-FR09, §8, §9) — the maintainer
+// surface over the local flight recorder.
+//
+//   collect          ingestStoredTelemetry → flush → maybeRefreshSupport (canary+)
+//   status [--json]  stage, segments, counters, support lag, crashes
+//   digest [--json]  rebuildIndex → anomalies + digest markdown
+//   export-support   projectSupport now (explicit user act — works below canary)
+//   import <path>    validateSupportBundle on a received bundle
+//   evaluate [--json] run the AI evaluator lane (provider-configured only)
+//
+// Exit codes: 0 success, 2 typed failure, 1 usage error. Read-only surfaces
+// degrade to `unknown`, never to a fabricated zero; written output carries
+// pseudonymous refs only (project dir is proj-<sha256>), no raw paths/secrets.
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { inspectRuntimeConfig } from '../../core/runtimeConfig.js';
+import { resolveStage } from '../../core/observability/emit/config.js';
+import {
+  getRecorder,
+  recorderHealth,
+  observabilityRoot,
+  segmentsRoot,
+} from '../../core/observability/emit/lifecycle.js';
+import { readCrashReports } from '../../core/observability/emit/crash.js';
+import { ingestStoredTelemetry } from '../../core/observability/adapters/ingest.js';
+import { listSegments, totalSegmentBytes } from '../../core/observability/segments/internal.js';
+import { readSegments } from '../../core/observability/segments/readSegments.js';
+import { rebuildIndex } from '../../core/observability/analytics/rebuild.js';
+import { renderStoreDigest } from '../../core/observability/analytics/storeDigest.js';
+import { renderTraceDigest } from '../../core/observability/analytics/digest.js';
+import {
+  projectSupport,
+  projectDirName,
+  SUPPORT_FORMAT,
+} from '../../core/observability/support/projector.js';
+import { maybeRefreshSupport } from '../../core/observability/support/schedule.js';
+import { resolveSupportDir, SUPPORT_DIR_NAME } from '../../core/observability/support/paths.js';
+import { validateSupportBundle } from '../../core/observability/support/import.js';
+import { runEvaluation } from '../../core/observability/evaluation/runner.js';
+
+const HELP_FLAGS = new Set(['--help', '-h', 'help']);
+const SUBCOMMANDS = new Set(['collect', 'status', 'digest', 'export-support', 'import', 'evaluate']);
+const JSON_SUBCOMMANDS = new Set(['status', 'digest', 'evaluate']);
+
+// The automatic support refresh's canary gate lives in schedule.js via
+// resolveSeamStages (projector seam minimum) — the CLI does not pre-gate.
+
+const COLLECT_DEADLINE_MS = 60_000;
+const FLUSH_DEADLINE_MS = 15_000;
+const MAX_TRACE_DIGESTS = 8;
+const MAX_ANOMALY_LINES = 20;
+
+function printUsage() {
+  console.log('Usage: ukit telemetry <command> [options]');
+  console.log('');
+  console.log('Commands:');
+  console.log('  collect          Ingest stored telemetry into the flight recorder,');
+  console.log('                   flush it, and refresh the support view (stage canary+)');
+  console.log('  status           Show stage, segments, counters, support lag, crashes');
+  console.log('  digest           Rebuild the trace index; print anomalies + digest markdown');
+  console.log('  export-support   Write the sanitized UKit Support bundle now');
+  console.log('  import <path>    Validate a received support bundle (zip or directory)');
+  console.log('  evaluate         Run the AI evaluator lane (needs observability.evaluator config)');
+  console.log('');
+  console.log('Options:');
+  console.log('  --json           JSON output (status, digest, evaluate)');
+  console.log('  -h, --help       Show this help');
+}
+
+// Invalid/missing config must not break the read path — stage resolves 'off'
+// on an empty object, which is the fail-safe posture everywhere else.
+async function loadConfig(projectRoot) {
+  try {
+    const inspection = await inspectRuntimeConfig(projectRoot, { homeDir: os.homedir() });
+    return inspection && inspection.config && typeof inspection.config === 'object'
+      ? inspection.config
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+// Bundle-local pseudonym convention shared with the projector: the support
+// view is addressed by hashed key, never by the project path — the
+// projectDirName helper lives in support/projector.js.
+
+
+function fmt(value) {
+  return value === null || value === undefined ? 'unknown' : String(value);
+}
+
+// --- status ------------------------------------------------------------------
+
+async function supportLagMs(projectRoot) {
+  const resolved = await resolveSupportDir({});
+  if (!resolved.ok) return null;
+  const manifestPath = path.join(resolved.dir, projectDirName(projectRoot), 'manifest.json');
+  try {
+    const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+    if (!manifest || manifest.format !== SUPPORT_FORMAT) return null;
+    const generated = Date.parse(manifest.generated_at);
+    return Number.isFinite(generated) ? Math.max(0, Date.now() - generated) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function statusCommand({ projectRoot, config, json }) {
+  const stage = resolveStage(config);
+  // getRecorder memoizes per root; in a one-shot CLI its counters read zero —
+  // that is honest per-process state, not a store claim.
+  getRecorder({ projectRoot, config });
+  const health = recorderHealth({ projectRoot });
+
+  const root = segmentsRoot(projectRoot);
+  const listing = await listSegments(root);
+  let active = null;
+  let sealed = null;
+  let bytes = null;
+  let records = null;
+  let readGaps = null;
+  if (listing.ok) {
+    active = listing.active ? 1 : 0;
+    sealed = listing.sealed.length;
+    bytes = totalSegmentBytes(listing);
+    const stream = readSegments(root);
+    let n = 0;
+    for await (const _record of stream) n += 1;
+    records = n;
+    const cov = stream.coverage;
+    readGaps =
+      (cov.corrupt_lines || 0) +
+      (cov.quarantined_segments || 0) +
+      (cov.expired_segments || 0) +
+      (Array.isArray(cov.degraded) ? cov.degraded.length : 0);
+  }
+
+  const lag = await supportLagMs(projectRoot);
+  const crashes = readCrashReports(observabilityRoot(projectRoot));
+  const crashCount = crashes.ok ? crashes.crashes.length : null;
+  const crashDetail = crashes.ok
+    ? { parsed: crashes.coverage.parsed, corrupt: crashes.coverage.corrupt, expired: crashes.coverage.expired }
+    : { error: crashes.reason };
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          stage,
+          segments: { active, sealed, bytes, records, read_gaps: readGaps },
+          counters: {
+            emitted: health.emitted ?? 0,
+            dropped: health.dropped ?? 0,
+            flushed: health.flushed ?? 0,
+            queue_depth: health.queue_depth ?? 0,
+            queue_bound: health.queue_bound ?? 0,
+            flushes: health.flushes ?? 0,
+            write_failures: health.write_failures ?? 0,
+          },
+          last_flush: health.last_flush ?? null,
+          support_lag_ms: lag,
+          crashes: { count: crashCount, ...crashDetail },
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  console.log('telemetry status');
+  console.log(`  stage: ${stage}`);
+  console.log(`  segments: active=${fmt(active)} sealed=${fmt(sealed)} bytes=${fmt(bytes)}`);
+  console.log(
+    records === 0 && active === 0 && sealed === 0
+      ? '  records: 0 (no records retained)'
+      : `  records: ${fmt(records)}`,
+  );
+  console.log(
+    `  counters: emitted=${health.emitted ?? 0} dropped=${health.dropped ?? 0} ` +
+      `flushed=${health.flushed ?? 0} queue=${health.queue_depth ?? 0}/${health.queue_bound ?? 0}`,
+  );
+  const lastFlush = health.last_flush;
+  console.log(
+    lastFlush
+      ? `  last_flush: ${lastFlush.status} written=${lastFlush.written} dropped=${lastFlush.dropped}`
+      : '  last_flush: none',
+  );
+  console.log(`  support_lag: ${fmt(lag === null ? null : `${lag}ms`)}`);
+  console.log(
+    crashCount === null
+      ? `  crashes: unknown (${crashDetail.error})`
+      : `  crashes: ${crashCount}`,
+  );
+}
+
+// --- collect -----------------------------------------------------------------
+async function collectCommand({ projectRoot, config }) {
+  const stage = resolveStage(config);
+  const recorder = getRecorder({ projectRoot, config });
+  console.log(`telemetry collect: stage=${stage}`);
+
+  // Provision the recorder root: appendRecord's resolveRoot requires the
+  // parent to already exist, so a project whose .ukit was created by an
+  // older install has no observability dir yet. UKit-owned path, mkdir -p.
+  try {
+    await fs.mkdir(segmentsRoot(projectRoot), { recursive: true });
+  } catch {
+    // Unwritable roots surface as typed degrade on the flush/ingest lanes.
+  }
+
+  const ingest = await ingestStoredTelemetry({
+    projectRoot,
+    recorder,
+    deadlineMs: COLLECT_DEADLINE_MS,
+  });
+  if (!ingest || ingest.ok !== true) {
+    console.log(`collect: failed reason=${ingest && ingest.reason ? ingest.reason : 'unknown'}`);
+    process.exitCode = 2;
+    return;
+  }
+  for (const [name, cov] of Object.entries(ingest.coverage ?? {})) {
+    const reason = cov.reason ? ` reason=${cov.reason}` : '';
+    console.log(
+      `  ${name}: read=${cov.read ?? 0} emitted=${cov.emitted ?? 0} ` +
+        `rejected=${cov.rejected ?? 0} skipped=${cov.skipped ?? 0}${reason}`,
+    );
+  }
+
+  const flushRes = await recorder.flush({ deadlineMs: FLUSH_DEADLINE_MS });
+  const flushReason = flushRes.reason ? ` reason=${flushRes.reason}` : '';
+  console.log(
+    `  flush: ${flushRes.status} written=${flushRes.written ?? 0} ` +
+      `dropped=${flushRes.dropped ?? 0} remaining=${flushRes.remaining ?? 0}${flushReason}`,
+  );
+
+  // DF2-FR12: automatic support refresh goes through the schedule seam —
+  // projector stage gate + ≥15min interval gate + stamp. A manual
+  // `export-support` is an explicit user act and bypasses both gates.
+  const support = await maybeRefreshSupport({ projectRoot, config, recorder });
+  console.log(
+    `  support: ${support.status}` +
+      (support.status === 'refreshed' ? ` bytes=${support.bytes ?? 0}` : '') +
+      (support.reason ? ` reason=${support.reason}` : ''),
+  );
+
+  // Typed failure is about the collect lane itself: a degraded ingest or a
+  // failed flush lost/queued records. Support refresh is the optional
+  // add-on (DF2-FR12) — its degrade is reported, not promoted to exit 2;
+  // `export-support` is the command whose own mission is the projection.
+  const failed =
+    ingest.status === 'degraded' ||
+    ingest.status === 'partial' ||
+    flushRes.status === 'error' ||
+    flushRes.status === 'partial';
+  const cursorNote = ingest.cursor_error ? ` cursor_error=${ingest.cursor_error}` : '';
+  console.log(`status: ${failed ? 'degraded' : ingest.status}${cursorNote}`);
+  if (failed) process.exitCode = 2;
+}
+
+// --- digest ------------------------------------------------------------------
+
+// Coarse per-trace anomaly roll-up mirroring digest.js anomalyLines: the
+// detector set is the summary fields, not re-scanned records.
+function traceAnomalies(summary) {
+  const s = summary && typeof summary === 'object' ? summary : {};
+  const kinds = [];
+  if (s.telemetry_complete === false) kinds.push('telemetry_incomplete');
+  const drops = s.drops && typeof s.drops === 'object' ? s.drops : {};
+  if ((drops.dropped_count ?? 0) > 0) kinds.push(`drops=${drops.dropped_count}`);
+  const retries = s.retries && typeof s.retries === 'object' ? s.retries : {};
+  if ((retries.failed_spans ?? 0) > 0) kinds.push(`failed_spans=${retries.failed_spans}`);
+  if ((retries.retries ?? 0) > 0) kinds.push(`retries=${retries.retries}`);
+  const cov = s.coverage && typeof s.coverage === 'object' ? s.coverage : {};
+  if ((cov.open_spans ?? 0) > 0) kinds.push(`open_spans=${cov.open_spans}`);
+  if ((cov.orphan_spans ?? 0) > 0) kinds.push(`orphan_spans=${cov.orphan_spans}`);
+  if ((cov.duplicate_ends ?? 0) > 0) kinds.push(`duplicate_ends=${cov.duplicate_ends}`);
+  const spans = Array.isArray(s.spans) ? s.spans : [];
+  const failed = spans.filter(
+    (sp) => sp && (sp.status === 'failed' || sp.status === 'blocked'),
+  ).length;
+  if (failed > 0) kinds.push(`span_status_failed=${failed}`);
+  return kinds;
+}
+async function digestCommand({ projectRoot, json }) {
+  const result = await rebuildIndex(segmentsRoot(projectRoot));
+  const summaries = Array.isArray(result.summaries) ? result.summaries : [];
+  const anomalies = summaries
+    .map((s) => ({ trace_id: s && s.trace_id ? s.trace_id : 'unknown', kinds: traceAnomalies(s) }))
+    .filter((a) => a.kinds.length > 0);
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: result.ok === true,
+          coverage: result.coverage ?? {},
+          anomalies,
+          traces_total: summaries.length,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  const out = ['# telemetry digest', '', '## anomalies'];
+  const shown = anomalies.slice(0, MAX_ANOMALY_LINES);
+  if (shown.length === 0) {
+    out.push('- none');
+  } else {
+    for (const a of shown) out.push(`- ${a.trace_id} · ${a.kinds.join(', ')}`);
+    if (anomalies.length > shown.length) {
+      out.push(`- … truncated: ${anomalies.length - shown.length} anomalous trace(s) omitted`);
+    }
+  }
+  out.push('', renderStoreDigest(result));
+
+  // Per-trace digests for anomalous traces only — the store digest already
+  // carries every summary line; full per-trace dumps belong in the bundle.
+  const anomalousSummaries = anomalies.slice(0, MAX_TRACE_DIGESTS).map(
+    (a) => summaries.find((s) => (s && s.trace_id ? s.trace_id : 'unknown') === a.trace_id),
+  );
+  for (const s of anomalousSummaries) {
+    if (!s) continue;
+    out.push('', renderTraceDigest(s, { coverage: result.coverage }));
+  }
+  if (anomalies.length > MAX_TRACE_DIGESTS) {
+    out.push('', `_${anomalies.length - MAX_TRACE_DIGESTS} more anomalous trace digest(s) omitted_`);
+  }
+  console.log(out.join('\n'));
+}
+
+// --- export-support / import --------------------------------------------------
+
+async function exportSupportCommand({ projectRoot, config }) {
+  // Manual export is an explicit user act: the stage gate governs automatic
+  // projection, so a stage-off config is lifted to 'default' for this call.
+  // Everything else (sanitizer, pseudonyms, caps) runs unchanged.
+  const effective =
+    resolveStage(config) === 'off'
+      ? { ...config, observability: { ...(config?.observability ?? {}), stage: 'default' } }
+      : config;
+  let res;
+  try {
+    res = await projectSupport(
+      { root: segmentsRoot(projectRoot) },
+      { config: effective, projectRoot },
+    );
+  } catch {
+    res = { status: 'degraded', reason: 'projector_error', bytes: 0 };
+  }
+  if (res.status === 'written') {
+    // Pseudonymous location only — the absolute path is user-private.
+    console.log(
+      `export-support: written bytes=${res.bytes ?? 0} ` +
+        `dir=${SUPPORT_DIR_NAME}/${projectDirName(projectRoot)}`,
+    );
+    return;
+  }
+  console.log(
+    `export-support: ${res.status}` +
+      (res.reason ? ` reason=${res.reason}` : '') +
+      ` bytes=${res.bytes ?? 0}`,
+  );
+  process.exitCode = 2;
+}
+
+async function importCommand({ bundlePath }) {
+  const res = await validateSupportBundle({ path: bundlePath });
+  if (!res.ok) {
+    // Typed reason verbatim — the maintainer keys remediation off it.
+    console.log(`import: ${res.reason}`);
+    process.exitCode = 2;
+    return;
+  }
+  const report = res.bundle.report;
+  console.log(
+    `import: ok files=${report.files} records=${report.records} ` +
+      `untrusted_prose=${report.untrusted_prose_present} ` +
+      `injection_signals=${report.injection_signals.length}`,
+  );
+}
+
+// --- evaluate -----------------------------------------------------------------
+
+// DF2-FR14: the evaluator lane runs only when the operator configured
+// observability.evaluator — skipped/no-provider is the honest default,
+// never a failure. Degraded is a typed failure (exit 2), matching collect.
+async function evaluateCommand({ projectRoot, config, json }) {
+  const result = await runEvaluation({ root: observabilityRoot(projectRoot), config });
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    const reason = result.reason ? ` reason=${result.reason}` : '';
+    console.log(
+      `telemetry evaluate: ${result.status}${reason} ` +
+        `packet_bytes=${result.packet_bytes ?? 0} ` +
+        `findings_accepted=${result.findings_accepted ?? 0} ` +
+        `findings_rejected=${result.findings_rejected ?? 0} ` +
+        `kb_records=${(result.kb_ids ?? []).length}`,
+    );
+  }
+  if (result.status === 'degraded') process.exitCode = 2;
+}
+
+// --- dispatch ----------------------------------------------------------------
+
+export async function runTelemetry({ projectRoot, packageRoot, argv = [] }) {
+  const args = Array.isArray(argv) ? argv : [];
+  const sub = (args[0] ?? '').toLowerCase();
+
+  if (args.length === 0 || HELP_FLAGS.has(sub)) {
+    printUsage();
+    return;
+  }
+  if (!SUBCOMMANDS.has(sub)) {
+    console.error(`[UKit] Unknown telemetry subcommand: ${sub}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  const rest = args.slice(1);
+  if (rest.some((a) => HELP_FLAGS.has(a))) {
+    printUsage();
+    return;
+  }
+  const positional = rest.filter((a) => !a.startsWith('-'));
+  const flags = rest.filter((a) => a.startsWith('-'));
+  const allowed = JSON_SUBCOMMANDS.has(sub) ? new Set(['--json']) : new Set();
+  const unknownFlags = flags.filter((f) => !allowed.has(f));
+  const maxPositional = sub === 'import' ? 1 : 0;
+
+  if (unknownFlags.length > 0) {
+    console.error(`[UKit] Unknown telemetry flag(s): ${unknownFlags.join(', ')}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+  if (positional.length > maxPositional || (sub === 'import' && positional.length === 0)) {
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  const config = await loadConfig(projectRoot);
+  const json = flags.includes('--json');
+
+  if (sub === 'collect') return collectCommand({ projectRoot, config });
+  if (sub === 'status') return statusCommand({ projectRoot, config, json });
+  if (sub === 'digest') return digestCommand({ projectRoot, json });
+  if (sub === 'export-support') return exportSupportCommand({ projectRoot, config });
+  if (sub === 'evaluate') return evaluateCommand({ projectRoot, config, json });
+  return importCommand({ bundlePath: positional[0] });
+}

package/src/cli/index.js

@@ -8,6 +8,7 @@ import { runMemory } from './commands/memory.js';
 import { runUpdate } from './commands/update.js';
 import { runCode } from './commands/code.js';
 import { runMetrics } from './commands/metrics.js';
+import { runTelemetry } from './commands/telemetry.js';
 import { runFeedback } from './commands/feedback.js';
 import { runPlaybook } from './commands/playbook.js';
 
@@ -78,6 +79,11 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     return;
   }
 
+  if (command === 'telemetry') {
+    await runTelemetry({ projectRoot, packageRoot, argv: commandArgv });
+    return;
+  }
+
   if (command === 'feedback') {
     await runFeedback({ projectRoot, argv: commandArgv });
     return;
@@ -118,6 +124,7 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     console.log('  memory             Inspect shared UKit memory');
     console.log('  playbook           List/show playbooks (project > user > builtin)');
     console.log('  metrics            Telemetry roll-up (route outcomes, failure patterns, memory)');
+    console.log('  telemetry          Flight recorder (collect/status/digest/export-support/import/evaluate)');
     console.log('  feedback           Record or list wrong-route feedback labels');
     console.log('  update             Upgrade the global UKit CLI to the latest version');
     console.log('  version            Show UKit version');

package/src/core/agentRuntime/adapters.js

@@ -22,8 +22,10 @@
  * `PASSWORD=...`, `AUTHORIZATION: ...`) are redacted before any payload
  * or digest is built.
  *
- * Pure module: no imports of context/completionGate/qualityComparison.
- * `now` and `artifactStore` are injectable for tests.
+ * Pure module for summarization; the DF2-FR07 tool-span emit helpers
+ * (beginToolSpan/endToolSpan) own `tool.*` records and emit through the
+ * recorder via telemetry.js — synchronous, never-throw, stage-gated
+ * inside emit(). `now` and `artifactStore` are injectable for tests.
  *
  * `artifactStore` protocol (injected): `put(buffer)` →
  * `Promise<string | { path: string }>`; the returned ref is recorded on
@@ -37,6 +39,12 @@ import {
   CONTRACT_VERSION,
   MAX_SAFE_PAYLOAD_BYTES,
 } from './contract.js';
+import {
+  makeSpanContext,
+  emitSpanRecord,
+  durationMs,
+  registryCode,
+} from './telemetry.js';
 
 export const TOOL_PROFILES = Object.freeze(['generic', 'vitest']);
 
@@ -176,6 +184,59 @@ async function storeArtifact(artifactStore, buf) {
   }
 }
 
+// --- DF2-FR07: tool.* span records (TASK-008) ------------------------------
+// A tool span is a CHILD of the run's execution span — beginToolSpan is
+// only ever called with a parent ctx emitted in the same trace, so
+// parent_span_id always resolves (validator causality rule). Tool name is
+// an opaque code string (`spec.toolName`, profile, or operationId) — raw
+// command/argv/output are DENIED_PAYLOAD_FIELDS and never enter payloads.
+
+/**
+ * Open a `tool.started` span under a run ctx. Returns the child span ctx
+ * (with start_ns) or null when telemetry is off — callers branch once on
+ * null, the emit path itself is never reached.
+ * @param {object|null} telemetry resolved lane (telemetry.js)
+ * @param {object} parent run span ctx {trace_id, span_id, execution_id, agent_id?}
+ * @param {object} [opts] {toolName?, operationId?, attempt?}
+ */
+export function beginToolSpan(telemetry, parent, { toolName, operationId, attempt } = {}) {
+  if (telemetry == null || parent == null) return null;
+  const ctx = makeSpanContext(parent);
+  const name = typeof toolName === 'string' && toolName.length > 0
+    ? toolName
+    : String(operationId ?? 'tool');
+  const payload = { operation: name, tool_name: name };
+  if (Number.isInteger(attempt)) payload.attempt = attempt;
+  emitSpanRecord(telemetry, ctx, 'tool.started', payload);
+  return ctx;
+}
+
+/**
+ * Close a tool span. `status` is 'completed' | 'failed' | 'blocked'; a
+ * failure carries a registry error_code (UPPER_SNAKE only). Duration is
+ * measured from the begin() ctx's start_ns on the same injected clock.
+ * @param {object|null} telemetry
+ * @param {object} ctx span ctx returned by beginToolSpan
+ * @param {object} [opts] {status?, errorCode?, toolName?, operationId?, exitCode?}
+ */
+export function endToolSpan(telemetry, ctx, { status = 'completed', errorCode, toolName, operationId, exitCode } = {}) {
+  if (telemetry == null || ctx == null) return;
+  const semantic = `tool.${status === 'completed' ? 'completed' : status === 'blocked' ? 'blocked' : 'failed'}`;
+  const name = typeof toolName === 'string' && toolName.length > 0
+    ? toolName
+    : String(operationId ?? 'tool');
+  const payload = {
+    operation: name,
+    tool_name: name,
+    duration_ms: durationMs(ctx.start_ns, ctx.nowNs ? ctx.nowNs() : null),
+  };
+  if (semantic === 'tool.failed') {
+    payload.error_code = registryCode(errorCode);
+  }
+  if (Number.isInteger(exitCode)) payload.exit_code = exitCode;
+  emitSpanRecord(telemetry, ctx, semantic, payload);
+}
+
 /**
  * @param {object} args
  * @param {AsyncIterable<Buffer|string>} [args.stream] async-iterable output.
@@ -185,6 +246,11 @@ async function storeArtifact(artifactStore, buf) {
  * @param {number} [args.exitCode] child exit code when known.
  * @param {() => string} [args.now] injectable clock (ISO string).
  * @param {{put: (buf: Buffer) => Promise<string|{path:string}>}} [args.artifactStore]
+ * @param {object} [args.telemetry] resolved telemetry lane (DF2-FR07).
+ * @param {object} [args.toolSpan] open span ctx from beginToolSpan — when
+ *   supplied, adaptOutput closes it as tool.completed/tool.failed using
+ *   the summarized status (the adapter boundary IS the tool's outcome:
+ *   'failed' status or a throw inside adaptation → tool.failed).
  * @returns {Promise<{events: object[], artifactRefs: string[],
  *   parseStatus: 'parsed'|'generic'|'parse_fallback'}>}
  */
@@ -196,6 +262,8 @@ export async function adaptOutput({
   exitCode,
   now = () => new Date().toISOString(),
   artifactStore,
+  telemetry,
+  toolSpan,
 } = {}) {
   const raw = await collectInput({ stream, chunks });
   const redacted = redactSecrets(raw.toString('utf8'));
@@ -250,5 +318,18 @@ export async function adaptOutput({
     };
   }
 
+  // DF2-FR07: the summarizer owns the tool invocation's terminal record.
+  // status 'failed' (or an unparseable/indeterminate verdict never fakes
+  // a completion — indeterminate still closes 'completed' because the
+  // invocation itself finished; the payload carries the real status).
+  if (toolSpan) {
+    endToolSpan(telemetry, toolSpan, {
+      status: safePayload.status === 'failed' ? 'failed' : 'completed',
+      errorCode: safePayload.status === 'failed' ? 'HOST_BLIND' : undefined,
+      toolName: safePayload.profile,
+      operationId,
+      exitCode,
+    });
+  }
   return { events: [event], artifactRefs, parseStatus };
 }