@meetless/mla 0.1.4

package/dist/lib/observability.js

@@ -0,0 +1,805 @@
+"use strict";
+// mla observability spine: trace_id + Sentry helpers + build-info loader.
+//
+// See notes/20260530-mla-observability-diagnostic-spine.md for the full design.
+// One trace_id per mla run; same string used as Sentry tag, X-Trace-ID header,
+// and Langfuse trace id once intel propagates it.
+//
+// Canonical format is 32 hex chars (16 random bytes hex-encoded). This is OTel-
+// native and matches intel's existing RequestContext.langfuse_trace_id format.
+// Spec (§4) names UUIDv4, but every Langfuse SDK and intel itself wants 32-hex
+// without dashes; zero translation across planes is the prize.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRACE_FLUSH_CEILING_MS = exports.HTTP_FLUSH_TIMEOUT_MS = exports.TraceRoundTripError = exports.telemetryDisabled = void 0;
+exports.loadBuildInfo = loadBuildInfo;
+exports.mintTraceId = mintTraceId;
+exports.isCanonicalTraceId = isCanonicalTraceId;
+exports.canonicalizeSessionId = canonicalizeSessionId;
+exports.redactSentryEvent = redactSentryEvent;
+exports.initSentry = initSentry;
+exports.isSentryAvailable = isSentryAvailable;
+exports.setWorkspaceConfig = setWorkspaceConfig;
+exports.getWorkspaceConfig = getWorkspaceConfig;
+exports.workspaceSentryAllowed = workspaceSentryAllowed;
+exports.pickSafeObservabilityFields = pickSafeObservabilityFields;
+exports.setSafeObservabilityContext = setSafeObservabilityContext;
+exports.captureCliError = captureCliError;
+exports.captureCliNonZeroExit = captureCliNonZeroExit;
+exports.captureBootstrapError = captureBootstrapError;
+exports.boundedSentryFlush = boundedSentryFlush;
+exports.setRunTraceId = setRunTraceId;
+exports.getRunTraceId = getRunTraceId;
+exports.setRunSessionId = setRunSessionId;
+exports.getRunSessionId = getRunSessionId;
+exports.resetRunSessionIdForTesting = resetRunSessionIdForTesting;
+exports.mintRunId = mintRunId;
+exports.setRunId = setRunId;
+exports.getRunId = getRunId;
+exports.resetRunIdForTesting = resetRunIdForTesting;
+exports.setRepoFingerprint = setRepoFingerprint;
+exports.getRepoFingerprint = getRepoFingerprint;
+exports.resetRepoFingerprintForTesting = resetRepoFingerprintForTesting;
+exports.noteIntelEchoedTraceId = noteIntelEchoedTraceId;
+exports.didIntelEchoTraceId = didIntelEchoTraceId;
+exports.resetIntelEchoForTesting = resetIntelEchoForTesting;
+exports.didTraceFlushSucceed = didTraceFlushSucceed;
+exports.resetTraceFlushOutcomeForTesting = resetTraceFlushOutcomeForTesting;
+exports.makeHttpFlush = makeHttpFlush;
+exports.setRunTracer = setRunTracer;
+exports.getRunTracer = getRunTracer;
+exports.resetRunTracerForTesting = resetRunTracerForTesting;
+exports.routeNameFromPath = routeNameFromPath;
+exports.redactArgvForSpan = redactArgvForSpan;
+exports.langfuseTraceUrl = langfuseTraceUrl;
+exports.langfuseDeepLink = langfuseDeepLink;
+exports.shouldPrintDeepLink = shouldPrintDeepLink;
+exports.maybePrintDeepLink = maybePrintDeepLink;
+exports.createRunTracer = createRunTracer;
+exports.boundedTraceFlush = boundedTraceFlush;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const Sentry = __importStar(require("@sentry/node"));
+const redactor_1 = require("./redactor");
+const config_1 = require("./config");
+Object.defineProperty(exports, "telemetryDisabled", { enumerable: true, get: function () { return config_1.telemetryDisabled; } });
+const failure_telemetry_1 = require("./failure-telemetry");
+function loadTraceCore() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        return require(path.resolve(__dirname, "..", "bundles", "trace-core.js"));
+    }
+    catch (e) {
+        const code = e?.code;
+        if (code !== "MODULE_NOT_FOUND" && code !== "ERR_MODULE_NOT_FOUND")
+            throw e;
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        return require("@meetless/trace-core");
+    }
+}
+const { makeNoopTracer, makeTracer } = loadTraceCore();
+let cachedBuildInfo = null;
+function loadBuildInfo() {
+    if (cachedBuildInfo)
+        return cachedBuildInfo;
+    try {
+        const raw = fs.readFileSync(path.join(__dirname, "..", "build-info.json"), "utf8");
+        cachedBuildInfo = JSON.parse(raw);
+    }
+    catch {
+        cachedBuildInfo = {
+            version: "0.0.0",
+            sha: "dev",
+            branch: "dev",
+            dirty: true,
+            builtAt: new Date().toISOString(),
+        };
+    }
+    return cachedBuildInfo;
+}
+function mintTraceId() {
+    return crypto.randomBytes(16).toString("hex");
+}
+// OBS-1 shape: a canonical trace_id is exactly 32 lowercase hex chars (OTel
+// native, the shape mintTraceId produces and the shape intel adopts verbatim as
+// a Langfuse trace id). The single source of truth for the shape guard, reused
+// by the debug-bundle command's `--trace-id` validation (Phase 5 / gap 6.7) so a
+// malformed id is rejected up front rather than seeding a bad bundle path.
+const CANONICAL_TRACE_ID_RE = /^[0-9a-f]{32}$/;
+function isCanonicalTraceId(value) {
+    return typeof value === "string" && CANONICAL_TRACE_ID_RE.test(value);
+}
+// The single canonical Claude agent-session UUID grammar, byte-identical to the
+// Python twin (intel app/observability/langfuse_session.py:_AGENT_SESSION_RE) and
+// the Bash hook twin. NEVER a language UUID parser: Python's uuid.UUID accepts
+// braces, urn:uuid:, and un-dashed 32-hex, and JS has no native UUID parser at
+// all; agreeing on this one explicit regex is what stops the same Claude id
+// canonicalizing to two different strings and splitting the Langfuse Session.
+const AGENT_SESSION_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+// TS twin of canonicalize_agent_session_id. Pure: no metric, no logging. Trim,
+// match the regex (case-insensitive), lowercase; no match -> null. The regex is
+// anchored, so any leftover whitespace or header-injection byte after trim fails
+// the match and yields null, which is what keeps the composed value safe to pass
+// to a `-H` curl header downstream.
+function canonicalizeSessionId(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    const s = raw.trim();
+    return AGENT_SESSION_RE.test(s) ? s.toLowerCase() : null;
+}
+let sentryAvailable = false;
+// Keys whose VALUE is always a credential regardless of entropy, redacted by
+// name in every Sentry event (breadcrumb data, contexts, extra, tags, request
+// headers, exception/stack vars). This is the §9 Sentry-redaction invariant
+// (Finding K / Patch P7): the observability layer must never ship an
+// Authorization header, access/refresh token, PKCE codeVerifier, control token,
+// or INTERNAL_API_KEY off the machine, even with telemetry enabled.
+//
+// Bare `code` is deliberately ABSENT: it collides with error/status/language
+// codes. The one-time login-grant `code` is 64-hex high-entropy, so it is
+// caught by the value-based redactor (entropy heuristic in redact()) instead.
+const SENTRY_SENSITIVE_KEY = /(authorization|access[_-]?token|refresh[_-]?token|code[_-]?verifier|control[_-]?token|internal[_-]?api[_-]?key|\bapi[_-]?key\b|x-api-key|secret|passw(?:or)?d|\bbearer\b|cookie|\btoken\b)/i;
+// Keys carrying NON-secret high-entropy identifiers (trace/span/event/run ids,
+// git sha, build version, environment). These are exactly the strings the value
+// redactor's entropy heuristic would otherwise nuke, and they are the whole
+// point of the observability spine (the cross-plane trace-id join + release
+// correlation). Exempt them from value redaction; everything else high-entropy
+// stays conservatively redacted (over-redaction is the safe failure mode).
+const SENTRY_SAFE_IDENTIFIER_KEY = /^(x-)?(trace|span|event|run)[_-]?id$|^trace_source$|^release$|^dist$|^sha$|^environment$|^mla_version$|^platform$/i;
+// One recursive scrub of a Sentry event. Per field: a credential KEY collapses
+// to [REDACTED]; a safe-identifier key passes its value verbatim; every other
+// string runs through the shared value redactor (Bearer/provider tokens, PEM,
+// cookies, and the high-entropy heuristic that catches the grant code +
+// codeVerifier even when they hide in a free-text body).
+function scrubEventNode(value, keyHint) {
+    if (keyHint !== undefined && SENTRY_SENSITIVE_KEY.test(keyHint))
+        return redactor_1.REDACTED;
+    if (typeof value === "string") {
+        if (keyHint !== undefined && SENTRY_SAFE_IDENTIFIER_KEY.test(keyHint))
+            return value;
+        return (0, redactor_1.redact)(value);
+    }
+    if (Array.isArray(value))
+        return value.map((v) => scrubEventNode(v, keyHint));
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = scrubEventNode(v, k);
+        }
+        return out;
+    }
+    return value;
+}
+// beforeSend hook: scrub every event before it leaves the process. On any
+// redaction error we DROP the event (return null) rather than risk shipping an
+// unscrubbed payload.
+function redactSentryEvent(event) {
+    if (event === null || event === undefined)
+        return event;
+    try {
+        return scrubEventNode(event, undefined);
+    }
+    catch {
+        return null;
+    }
+}
+function initSentry(buildInfo) {
+    // 4.4 kill switch wins over everything, including a baked production DSN.
+    if ((0, config_1.telemetryDisabled)()) {
+        sentryAvailable = false;
+        return false;
+    }
+    // Dev-only override: only honored when build-info reports a dev build
+    // (no baked DSN). Production binaries ignore the env override entirely.
+    // OSS-facing MEETLESS_SENTRY_DSN wins; legacy MLA_SENTRY_DSN still accepted.
+    const bakedDsn = buildInfo.sentryDsn;
+    const isDev = !bakedDsn;
+    const dsn = isDev
+        ? process.env.MEETLESS_SENTRY_DSN || process.env.MLA_SENTRY_DSN
+        : bakedDsn;
+    if (!dsn) {
+        sentryAvailable = false;
+        return false;
+    }
+    Sentry.init({
+        dsn,
+        release: buildInfo.sha,
+        environment: buildInfo.dirty ? "dev" : "prod",
+        // Pure CLI: no transaction sampling, no tracing integrations.
+        // Errors and explicit captureMessage only.
+        tracesSampleRate: 0,
+        // §9 redaction invariant (Finding K / P7): scrub credentials out of every
+        // event before transport. Must exist before any token-capturing path (login
+        // / refresh) can land a token in a breadcrumb or stack var.
+        beforeSend: (event) => redactSentryEvent(event),
+    });
+    Sentry.setTags({
+        mla_version: `${buildInfo.version} (${buildInfo.sha}${buildInfo.dirty ? "-dirty" : ""})`,
+        platform: process.platform,
+        trace_source: "mla-cli",
+    });
+    sentryAvailable = true;
+    return true;
+}
+function isSentryAvailable() {
+    return sentryAvailable;
+}
+// Run-local workspace config snapshot. Read by capture helpers to decide
+// whether non-bootstrap captures are allowed (cycle 4 fix 4). null until
+// workspace-me has loaded; bootstrap captures fire under null without
+// consulting this gate.
+let currentWorkspaceConfig = null;
+function setWorkspaceConfig(cfg) {
+    currentWorkspaceConfig = cfg;
+}
+function getWorkspaceConfig() {
+    return currentWorkspaceConfig;
+}
+// Tenant guardrail (§9): even if workspace.tracing.sentryEnabled were flipped
+// true on a non-dogfood workspace by a config drift, the CLI still refuses to
+// send full-context captures. Only ws_an_local or workspaces explicitly flagged
+// tracing_dogfood: true clear the gate.
+function workspaceSentryAllowed(cfg) {
+    if (!cfg)
+        return false;
+    if (cfg.tracing?.sentryEnabled !== true)
+        return false;
+    if (cfg.workspaceId === "ws_an_local")
+        return true;
+    return cfg.tracingDogfood === true;
+}
+const SAFE_OBSERVABILITY_KEYS = [
+    "traceId",
+    "langfuseUrl",
+    "release",
+    "command",
+    "exitCode",
+    "traceSource",
+    "workspaceIdOrHash",
+];
+// Pick only the allowlisted keys from arbitrary input, dropping anything else
+// plus null/undefined and non-scalar values (so an object smuggled into an
+// allowlisted key still cannot leak). Exported so the OBS-9 guarantee is
+// unit-testable without a live Sentry scope.
+function pickSafeObservabilityFields(input) {
+    const out = {};
+    for (const key of SAFE_OBSERVABILITY_KEYS) {
+        const value = input[key];
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value === "string" || typeof value === "number") {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+// Attach the allowlisted observability fields as a single Sentry "observability"
+// context block; returns the safe object actually attached (for tests). Pass the
+// full candidate object: non-allowlisted keys never reach Sentry. When nothing
+// safe survives, the context is set to null so no empty frame is advertised.
+function setSafeObservabilityContext(scope, fields) {
+    const safe = pickSafeObservabilityFields(fields);
+    scope.setContext("observability", Object.keys(safe).length > 0 ? safe : null);
+    return safe;
+}
+// Build the OBS-9-safe observability fields for a Sentry capture from run-local
+// state. langfuseUrl is included only when the workspace config carries a project
+// id; otherwise it is omitted (the allowlist drops the undefined). release is the
+// build sha so a Sentry event pins the exact binary.
+function captureObservabilityFields(ctx) {
+    const cfg = currentWorkspaceConfig;
+    const projectId = cfg?.tracing?.langfuseProjectId ?? null;
+    return {
+        traceId: ctx.traceId,
+        langfuseUrl: projectId ? langfuseTraceUrl(projectId, ctx.traceId) : undefined,
+        release: cachedBuildInfo?.sha,
+        command: ctx.sub ? `${ctx.command} ${ctx.sub}` : ctx.command,
+        exitCode: ctx.exitCode,
+        traceSource: "mla-cli",
+        workspaceIdOrHash: cfg?.workspaceId,
+    };
+}
+function captureCliError(err, ctx) {
+    if (!sentryAvailable)
+        return;
+    if (!workspaceSentryAllowed(currentWorkspaceConfig))
+        return;
+    Sentry.withScope((scope) => {
+        scope.setTag("trace_id", ctx.traceId);
+        scope.setTag("command", ctx.command);
+        scope.setTag("sub", ctx.sub ?? "none");
+        setSafeObservabilityContext(scope, captureObservabilityFields(ctx));
+        scope.setLevel("error");
+        Sentry.captureException(err);
+    });
+}
+function captureCliNonZeroExit(ctx) {
+    if (!sentryAvailable)
+        return;
+    if (!workspaceSentryAllowed(currentWorkspaceConfig))
+        return;
+    Sentry.withScope((scope) => {
+        scope.setTag("trace_id", ctx.traceId);
+        scope.setTag("command", ctx.command);
+        scope.setTag("sub", ctx.sub ?? "none");
+        scope.setTag("exit_code", String(ctx.exitCode));
+        setSafeObservabilityContext(scope, captureObservabilityFields(ctx));
+        scope.setLevel("warning");
+        Sentry.captureMessage(`mla ${ctx.command} exited ${ctx.exitCode}`);
+    });
+}
+// Bootstrap captures bypass the workspace gate by design: workspace config has
+// not loaded yet, but we still need visibility on bad token / control
+// unreachable. Tags are minimal so PII risk is zero.
+function captureBootstrapError(err, ctx) {
+    if (!sentryAvailable)
+        return;
+    Sentry.withScope((scope) => {
+        scope.setTag("trace_id", ctx.traceId);
+        scope.setTag("phase", "bootstrap");
+        scope.setLevel("error");
+        Sentry.captureException(err);
+    });
+}
+const sleep = (ms) => new Promise((res) => setTimeout(res, ms));
+async function boundedSentryFlush() {
+    if (!sentryAvailable)
+        return;
+    try {
+        await Promise.race([Sentry.flush(500), sleep(500)]);
+    }
+    catch {
+        // Never block exit on Sentry flush failure.
+    }
+}
+// Per-run trace_id storage. Read by mlaFetch to stamp X-Trace-ID on every
+// outbound HTTP request. Set exactly once at the top of the run.
+let currentTraceId = null;
+function setRunTraceId(traceId) {
+    currentTraceId = traceId;
+}
+function getRunTraceId() {
+    return currentTraceId;
+}
+// Per-run agent session id storage (the raw canonical Claude UUID, NOT the
+// composed namespaced value). Read by buildIntelHeaders to stamp
+// X-Agent-Session-ID on intel calls so the workspace-authoritative sink composes
+// the session exactly once (INV-COMPOSE-ONCE: the raw UUID rides the wire; intel
+// composes). Set exactly once at the top of the run from CLAUDE_CODE_SESSION_ID,
+// already canonicalized; null when the CLI is not running inside a Claude session
+// or the env value is malformed (the header is then simply not stamped).
+let currentSessionId = null;
+function setRunSessionId(sessionId) {
+    currentSessionId = sessionId;
+}
+function getRunSessionId() {
+    return currentSessionId;
+}
+// Test-only: clear the run-local session id so suites don't bleed state.
+function resetRunSessionIdForTesting() {
+    currentSessionId = null;
+}
+// Per-run analytics run_id (INV-RUN-1). Distinct identity from trace_id: minted
+// independently, never derived from it. trace_id is the cross-system
+// observability key; run_id is the analytics invocation key. They are 1:1 at the
+// CLI in v1, but kept separate so hooks/MCP/child-traces can mint their own
+// run_id under a shared trace later. uuid (not the 32-hex trace shape) so the two
+// can never be confused.
+let currentRunId = null;
+function mintRunId() {
+    return crypto.randomUUID();
+}
+function setRunId(runId) {
+    currentRunId = runId;
+}
+function getRunId() {
+    return currentRunId;
+}
+// Test-only: clear the run-local id so suites don't bleed state across cases.
+function resetRunIdForTesting() {
+    currentRunId = null;
+}
+// Per-run repo fingerprint (analytics attribution, spec section 3.7 / T1.10). A
+// NON-identifying one-way hash of the git remote/repo the run executed in,
+// computed ONCE at bootstrap (the git I/O lives in computeRepoFingerprint) and
+// read back by the analytics recorder. Stored as a run-local singleton, exactly
+// like run_id/trace_id, so buildEvent stays a pure read and never shells out to
+// git per event. null when the run is not in a git repo (or git is unavailable);
+// attribution then carries a null repoFingerprint rather than a fabricated one.
+let currentRepoFingerprint = null;
+function setRepoFingerprint(fingerprint) {
+    currentRepoFingerprint = fingerprint;
+}
+function getRepoFingerprint() {
+    return currentRepoFingerprint;
+}
+// Test-only: clear the run-local fingerprint so suites don't bleed state.
+function resetRepoFingerprintForTesting() {
+    currentRepoFingerprint = null;
+}
+// Intel-echo observation (P2.4 deep-link gate). Set true when ANY intel
+// response in this run carried our X-Trace-ID back in its response headers.
+// Observation only: the CLI never adopts the response id (immutability is
+// preserved by mlaFetch / intelGet / intelPost; they never read it back into
+// currentTraceId). The deep link is printed only when tracer.flush() succeeded
+// OR this flag is true (server-side intel route already produced a Langfuse
+// trace under the inbound id).
+let intelEchoedRunTraceId = false;
+// Thrown only in strict/debug mode (see traceStrictMode) when intel positively
+// echoes a trace id that is NOT ours. Typed so a caller can distinguish a
+// propagation-integrity failure from an ordinary HTTP error.
+class TraceRoundTripError extends Error {
+    sent;
+    echoed;
+    constructor(sent, echoed) {
+        super(`trace-id round-trip mismatch: sent ${sent}, intel echoed ${echoed}`);
+        this.sent = sent;
+        this.echoed = echoed;
+        this.name = "TraceRoundTripError";
+    }
+}
+exports.TraceRoundTripError = TraceRoundTripError;
+// Strict trace mode (the "strict/debug flag" of spec gap 6.5 / Phase 4). When
+// MEETLESS_TRACE_STRICT or MLA_TRACE_STRICT is truthy, a round-trip MISMATCH is
+// fatal (throws) instead of a one-line warning. Off by default: a mismatch is a
+// confidence-check failure, not a reason to fail a user's command. CI and local
+// debugging flip it on to make a silent propagation break loud.
+function traceStrictMode() {
+    const v = process.env.MEETLESS_TRACE_STRICT || process.env.MLA_TRACE_STRICT;
+    if (!v)
+        return false;
+    const norm = v.trim().toLowerCase();
+    return norm === "1" || norm === "true" || norm === "yes" || norm === "on";
+}
+// P4-T2: assert the trace_id round-trip against intel's echoed X-Trace-ID.
+//  - absent header  -> graceful no-op (older intel, or a proxy stripped it): the
+//    deep-link gate already falls back to didTraceFlushSucceed(), so a missing
+//    echo only weakens a confidence check; it never breaks a join.
+//  - match          -> record the positive confirmation.
+//  - mismatch       -> a real propagation break (a proxy rewrote the header, or
+//    intel minted a fresh id because ours never arrived). Warn by default; throw
+//    a TraceRoundTripError under strict/debug. Both ids are observability join
+//    keys, not payloads, so naming them is OBS-9-safe and is exactly what you
+//    need to debug the split.
+function noteIntelEchoedTraceId(echoedId) {
+    if (!echoedId)
+        return;
+    if (!currentTraceId)
+        return;
+    const normalized = echoedId.toLowerCase();
+    if (normalized === currentTraceId) {
+        intelEchoedRunTraceId = true;
+        return;
+    }
+    if (traceStrictMode()) {
+        throw new TraceRoundTripError(currentTraceId, normalized);
+    }
+    process.stderr.write(`warn: trace-id round-trip mismatch (sent ${currentTraceId}, ` +
+        `intel echoed ${normalized}); traces for this run may be split\n`);
+}
+function didIntelEchoTraceId() {
+    return intelEchoedRunTraceId;
+}
+function resetIntelEchoForTesting() {
+    intelEchoedRunTraceId = false;
+}
+// Trace-flush outcome (P2.4 deep-link gate). True when boundedTraceFlush
+// observed tracer.flush() resolve without throwing. The deep link is printed
+// only when this is true OR intel echoed the run trace id; otherwise we'd be
+// advertising URLs that resolve to nothing.
+let traceFlushSucceeded = false;
+function didTraceFlushSucceed() {
+    return traceFlushSucceeded;
+}
+function resetTraceFlushOutcomeForTesting() {
+    traceFlushSucceeded = false;
+}
+// HTTP-backed flush function the tracer calls inside flush(). POSTs the span
+// batch to control's /internal/v1/agent-traces/ingest. Auth uses the same
+// bearer the CLI uses for every other control hop (controlToken). workspaceId
+// is injected from the CLI's run-local workspace config so control can apply
+// the §9 tenant guardrail (only ws_an_local or tracing_dogfood workspaces are
+// allowed to relay). On non-2xx, throw so boundedTraceFlush prints its single
+// stderr line.
+// The HTTP flush's per-request deadline: the AbortController aborts the fetch at
+// this point. This is the AUTHORITATIVE trace-upload timeout.
+exports.HTTP_FLUSH_TIMEOUT_MS = 1500;
+// The outer ceiling boundedTraceFlush races tracer.flush() against. It MUST stay
+// >= HTTP_FLUSH_TIMEOUT_MS so the HTTP deadline is the real timeout and this is
+// only a backstop for a flush that hangs WITHOUT honoring its own deadline (e.g.
+// a non-HTTP flushFn). When this was 500ms and the HTTP timeout was 1500ms, a
+// slow-but-successful upload (500-1500ms) was killed by this race, dropped, and
+// reported as a false "timeout" (Finding #2). The +500ms headroom lets the inner
+// AbortController fire first on a genuinely slow network so the user sees the
+// precise HTTP error, not this generic ceiling.
+exports.TRACE_FLUSH_CEILING_MS = exports.HTTP_FLUSH_TIMEOUT_MS + 500;
+function makeHttpFlush(opts) {
+    const timeout = opts.timeoutMs ?? exports.HTTP_FLUSH_TIMEOUT_MS;
+    return async (payload) => {
+        const url = `${opts.controlUrl}/internal/v1/agent-traces/ingest`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeout);
+        try {
+            // agent-traces ingest is a workspace-bound write behind control's
+            // AgentReviewWorkspaceGuard (INV-AUTH-1): it 403s "Actor identity
+            // required for this write" unless the caller presents an actor. lib/http.ts
+            // stamps X-Meetless-Actor on every other control hop; this hand-rolled
+            // flush must mirror that, or every self-trace upload 403s. A blank/
+            // whitespace-only actor is treated as absent (same as buildRequestHeaders).
+            const headers = {
+                Authorization: `Bearer ${opts.controlToken}`,
+                "Content-Type": "application/json",
+                "X-Trace-ID": payload.traceId,
+            };
+            if (opts.actorUserId && opts.actorUserId.trim().length > 0) {
+                headers["X-Meetless-Actor"] = opts.actorUserId;
+            }
+            const res = await fetch(url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ ...payload, workspaceId: opts.workspaceId }),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => "");
+                const e = new Error(`POST ${url} -> HTTP ${res.status}: ${body.slice(0, 200)}`);
+                e.status = res.status;
+                // §9 tenant guardrail: a 403 TRACING_NOT_ENABLED_FOR_WORKSPACE is a
+                // deliberate policy refusal (this workspace simply does not relay CLI
+                // self-traces), not a failure. Tag it so boundedTraceFlush skips the
+                // user-facing warning. Any other non-2xx (auth 403, 5xx, etc.) stays
+                // a real, warnable failure.
+                if (res.status === 403 && body.includes(TRACING_DISABLED_CODE)) {
+                    e.tracingDisabledByPolicy = true;
+                }
+                throw e;
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}
+// Control's §9 error code for "this workspace is not authorized to relay
+// traces" (apps/control api-exception.ts TRACING_NOT_ENABLED_FOR_WORKSPACE).
+// Shared by the tag site (makeHttpFlush) and the classifier so the two cannot
+// drift on the literal.
+const TRACING_DISABLED_CODE = "TRACING_NOT_ENABLED_FOR_WORKSPACE";
+// True when a flush error is the §9 tracing-policy refusal: either tagged by
+// makeHttpFlush, or (defense in depth, if the tag is ever lost in transit) a
+// 403 whose message carries the policy code. Such a refusal is expected and
+// must NOT surface a "trace upload failed" warning.
+function isTracingPolicyDisabled(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const e = err;
+    if (e.tracingDisabledByPolicy === true)
+        return true;
+    return (e.status === 403 &&
+        typeof e.message === "string" &&
+        e.message.includes(TRACING_DISABLED_CODE));
+}
+function describeFlushErr(err) {
+    if (err && typeof err === "object") {
+        const e = err;
+        if (e.status)
+            return `HTTP ${e.status}`;
+        if (e.name === "AbortError")
+            return "timeout";
+        if (e.message)
+            return e.message.slice(0, 120);
+    }
+    return String(err).slice(0, 120);
+}
+// Per-run tracer storage. Read by mlaFetch / intelGet / intelPost to start
+// child spans around each outbound HTTP call. Set exactly once at the top of
+// the run (cli.ts runCliBootstrap). Null when the CLI is invoked without a
+// reachable config (e.g. mla init) so HTTP layers can no-op cheaply.
+let currentTracer = null;
+function setRunTracer(tracer) {
+    currentTracer = tracer;
+}
+function getRunTracer() {
+    return currentTracer;
+}
+function resetRunTracerForTesting() {
+    currentTracer = null;
+}
+// Convert an outbound URL path into the right side of an `intel.<route>` or
+// `control.<route>` span name. Drops `/internal/v1/` / `/v1/` prefixes, strips
+// query strings, and collapses obvious id-shaped path segments to `:id` so a
+// fleet of `coordination-cases.cse_xxxx` spans roll up cleanly in Langfuse.
+const ID_LIKE = /^([a-z]+_[A-Za-z0-9]{4,}|[0-9a-f]{20,}|[0-9a-fA-F-]{36})$/;
+function routeNameFromPath(rawPath) {
+    const qIdx = rawPath.indexOf("?");
+    const noQuery = qIdx >= 0 ? rawPath.slice(0, qIdx) : rawPath;
+    let p = noQuery;
+    if (p.startsWith("/internal/v1/"))
+        p = p.slice("/internal/v1/".length);
+    else if (p.startsWith("/v1/"))
+        p = p.slice("/v1/".length);
+    else if (p.startsWith("/"))
+        p = p.slice(1);
+    const parts = p.split("/").filter((s) => s.length > 0);
+    const sanitized = parts.map((s) => {
+        let token;
+        try {
+            token = decodeURIComponent(s);
+        }
+        catch {
+            token = s;
+        }
+        return ID_LIKE.test(token) ? ":id" : token;
+    });
+    return sanitized.join(".") || "root";
+}
+// Argv redaction for the root span attribute (P2.2 + spec §10.P2 must-test 6).
+// Reuses the shared secret redactor so a token leaked on the command line is
+// stripped before the trace reaches Langfuse. The redactor returns the input
+// unchanged for empty strings, otherwise a transformed string; the cast is
+// safe because every input here is already a string.
+function redactArgvForSpan(argv) {
+    return argv.map((arg) => (0, redactor_1.redact)(arg));
+}
+// Canonical Langfuse trace URL. ONE algorithm, mirrored byte-for-byte by the
+// Python twin (intel app/core/observability_context.py: langfuse_trace_url). A
+// Python-built URL that drifts from this shape produces a Sentry deep-link that
+// 404s, so the two are locked together by a cross-language fixture test
+// (test/fixtures/langfuse-url-fixtures.json; spec gap 6.3). The CLI has no
+// self-host config, so the host is always the Langfuse Cloud default.
+function langfuseTraceUrl(projectId, traceId) {
+    return `https://cloud.langfuse.com/project/${projectId}/traces/${traceId}`;
+}
+// P2.3 / spec §8 deep-link printer. Gate is the explicit boolean conjunction:
+// workspace config loaded, tracing.enabled true, langfuseProjectId set, AND
+// (flush succeeded OR intel echoed the inbound X-Trace-ID). Any single
+// condition failing returns false and prints nothing; printing when no trace
+// landed advertises dead URLs.
+function langfuseDeepLink(projectId, traceId) {
+    return `trace: ${langfuseTraceUrl(projectId, traceId)}`;
+}
+function shouldPrintDeepLink(opts) {
+    if (!opts.config)
+        return false;
+    if (opts.config.tracing?.enabled !== true)
+        return false;
+    if (!opts.config.tracing.langfuseProjectId)
+        return false;
+    return opts.flushSucceeded || opts.intelEchoed;
+}
+function maybePrintDeepLink(opts) {
+    if (!shouldPrintDeepLink(opts))
+        return false;
+    const projectId = opts.config.tracing.langfuseProjectId;
+    process.stdout.write(`${langfuseDeepLink(projectId, opts.traceId)}\n`);
+    return true;
+}
+// Build the run's tracer. Returns a no-op tracer when no HTTP flush function
+// is available (mla init / no config / fully-offline command). Otherwise
+// returns a real tracer whose flush POSTs to control's relay. flush() is
+// always called once (via boundedTraceFlush in cli.ts); the no-op tracer
+// resolves immediately so the lifecycle is unconditional.
+function createRunTracer(opts) {
+    if (!opts.flushFn) {
+        return makeNoopTracer({ traceId: opts.traceId });
+    }
+    return makeTracer({
+        traceId: opts.traceId,
+        rootName: opts.rootName,
+        client: {
+            mlaVersion: opts.buildInfo.version,
+            platform: process.platform,
+        },
+        flushFn: opts.flushFn,
+    });
+}
+// Visible-failure stderr line on flush error (spec §6.2). Exactly one line, no
+// retry, no persistence. Caller's command exit code is preserved; this never
+// throws so it cannot promote a successful command into a failed one.
+//
+// The ceiling uses a cleared setTimeout (not sleep().then(throw)) so the timer
+// is released when flush wins; otherwise it would hold the event loop open until
+// the full ceiling elapses after success (functionally masked by CLI's
+// process.exit, but leaks open handles in jest and would block any programmatic
+// caller). The ceiling defaults to TRACE_FLUSH_CEILING_MS, kept wider than the
+// HTTP flush's own deadline so a slow-but-successful upload is not killed here
+// (Finding #2); callers/tests may pass a tighter ceiling.
+async function boundedTraceFlush(tracer, ceilingMs = exports.TRACE_FLUSH_CEILING_MS) {
+    let timer = null;
+    let flushErr = null;
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            const err = new Error(`timeout: trace flush exceeded ${ceilingMs}ms`);
+            flushErr = err;
+            reject(err);
+        }, ceilingMs);
+    });
+    try {
+        let flushPromise;
+        try {
+            flushPromise = Promise.resolve(tracer.flush());
+        }
+        catch (err) {
+            // A synchronous throw inside tracer.flush() before it returns a promise.
+            flushPromise = Promise.reject(err);
+        }
+        await Promise.race([
+            flushPromise.catch((e) => {
+                flushErr = e;
+                throw e;
+            }),
+            timeoutPromise,
+        ]);
+        traceFlushSucceeded = true;
+    }
+    catch {
+        // Not relayed either way, so no trace URL to advertise (cli.ts gates on
+        // didTraceFlushSucceed()).
+        traceFlushSucceeded = false;
+        // A §9 tracing-policy refusal is expected, not a failure: stay silent.
+        // Every real failure (auth, 5xx, connection refused, timeout) still warns.
+        if (!isTracingPolicyDisabled(flushErr)) {
+            process.stderr.write(`warn: trace upload failed (${describeFlushErr(flushErr)}); ` +
+                `Sentry event still carries trace_id\n`);
+            // F8 (telemetry-upload-failed): the trace upload itself failed on a real,
+            // non-policy error. Record it to the local deadletter so the failure is
+            // never silently lost (a telemetry system that fails silently gives false
+            // "no alerts = no problems"). Per INV-SENTRY-NOISE-BUDGET this is
+            // local-deadletter + the local warning above, NOT a Sentry event from the
+            // CLI. recordTelemetryUploadFailure respects the kill switch and never
+            // throws; the extra guard keeps a future change from breaking the flush
+            // path (this must never promote a successful command into a failed one).
+            try {
+                const wsCfg = getWorkspaceConfig();
+                const status = flushErr?.status;
+                (0, failure_telemetry_1.recordTelemetryUploadFailure)({
+                    traceId: tracer.traceId,
+                    workspaceId: wsCfg?.workspaceId ?? null,
+                    surface: "mla-cli",
+                    reasonCode: "trace_upload_failed",
+                    status: typeof status === "number" ? status : undefined,
+                });
+            }
+            catch {
+                // F8 recording is best-effort; swallow so flush stays non-throwing.
+            }
+        }
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}