@ishlabs/cli 0.17.3 → 0.17.5

package/dist/index.js

@@ -26,8 +26,21 @@ import { tagAlias, ALIAS_PREFIX } from "./lib/alias-store.js";
 import { output } from "./lib/output.js";
 import { ishDir } from "./lib/paths.js";
 import { findInstalledSkill } from "./lib/skill-content.js";
+import { exitWithFlush, initObservability } from "./lib/observability.js";
+import { setSurfaceBaggage } from "./lib/baggage.js";
 import pkg from "../package.json" with { type: "json" };
 const { version } = pkg;
+// Bootstrap observability before anything else so the very first
+// outbound API call (e.g. `ish login` polling) carries baggage +
+// traceparent. Failures are swallowed inside `initObservability`;
+// belt-and-suspenders try/catch here so a synchronous throw from the
+// dynamic import can't crash the CLI either.
+try {
+    await initObservability();
+}
+catch {
+    /* observability outage must never crash the CLI */
+}
 program
     .name("ish")
     .description("ish CLI — run studies and asks against AI tester audiences")
@@ -49,7 +62,8 @@ program.exitOverride((err) => {
     if (err.code === "commander.helpDisplayed"
         || err.code === "commander.version"
         || err.code === "commander.help") {
-        process.exit(0);
+        void exitWithFlush(0);
+        return;
     }
     // Detect --json without relying on parsed opts (parse may have failed).
     const useJson = process.argv.includes("--json") || !process.stdout.isTTY;
@@ -67,7 +81,7 @@ program.exitOverride((err) => {
         console.error(`Error: ${err.message}`);
         console.error("  → Run `ish <command> --help` for usage");
     }
-    process.exit(EXIT_USAGE);
+    void exitWithFlush(EXIT_USAGE);
 });
 // Global options
 program
@@ -328,4 +342,18 @@ function injectAgentTipsFooter(cmd) {
     }
 }
 injectAgentTipsFooter(program);
+// Single source of `client.surface` baggage: fires before EVERY
+// subcommand's action handler. `actionCommand.name()` is the leaf
+// command name (e.g. "list" inside `ish workspace list`). For groups,
+// Commander joins names via `.parent` — flatten to the dotted path so
+// the backend sees `client.surface=workspace.list` not just `list`.
+program.hook("preAction", (_thisCommand, actionCommand) => {
+    const parts = [];
+    let cmd = actionCommand;
+    while (cmd && cmd.parent) {
+        parts.unshift(cmd.name());
+        cmd = cmd.parent;
+    }
+    setSurfaceBaggage(parts.join(".") || actionCommand.name());
+});
 program.parse();

package/dist/lib/api-client.js

@@ -2,6 +2,7 @@
  * Shared HTTP API client for the Ish backend.
  */
 import { API_BASE } from "./auth.js";
+import { withBaggage } from "./baggage.js";
 function mapErrorCode(status) {
     if (status === 401)
         return "auth_failed";
@@ -93,10 +94,27 @@ export class ApiClient {
         return this.baseUrl;
     }
     headers() {
-        return {
+        // `withBaggage` reads the active OTel baggage and adds a `baggage`
+        // header. In Node mode, OTel's undici auto-instrumentation also
+        // injects the same header; the manual + auto layers are idempotent
+        // (same values, last write wins). In Bun-compile mode auto-instrumentation
+        // is broken — this manual call is the only injection path.
+        const base = {
             Authorization: `Bearer ${this.token}`,
             "Content-Type": "application/json",
         };
+        const withBag = withBaggage(base);
+        // `withBaggage` returns HeadersInit; narrow back to the
+        // Record<string,string> shape the rest of this class expects.
+        if (withBag instanceof Headers) {
+            const out = {};
+            withBag.forEach((v, k) => { out[k] = v; });
+            return out;
+        }
+        if (Array.isArray(withBag)) {
+            return Object.fromEntries(withBag);
+        }
+        return withBag;
     }
     async get(path, params, opts) {
         let url = `${this.baseUrl}${path}`;

package/dist/lib/auth.js

@@ -5,6 +5,7 @@
 import * as fs from "node:fs";
 import { loadConfig, saveConfig } from "../config.js";
 import { refreshTokens, isTokenExpired } from "../auth.js";
+import { withBaggage } from "./baggage.js";
 export const DEFAULT_API_URL = "https://api.ishlabs.io";
 export const API_BASE = "/api/v1";
 export function resolveApiUrl(apiUrlArg, dev) {
@@ -17,7 +18,7 @@ export function resolveApiUrl(apiUrlArg, dev) {
 async function verifyToken(token, apiUrl) {
     try {
         const resp = await fetch(`${apiUrl}${API_BASE}/connect/active`, {
-            headers: { Authorization: `Bearer ${token}` },
+            headers: withBaggage({ Authorization: `Bearer ${token}` }),
             signal: AbortSignal.timeout(10_000),
         });
         // 404 = valid token, no connection (expected). 401/403 = bad token.

package/dist/lib/baggage.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Helpers for setting OTel Baggage entries and propagating them on
+ * outbound fetches.
+ *
+ * The CLI carries three baggage entries on every backend call so the
+ * backend can attribute spans + Sentry events to the right surface:
+ *
+ *     baggage: client.name=ish-cli,client.surface=<command>,client.version=<x.y.z>
+ *
+ * In Node mode, `@opentelemetry/instrumentation-undici` will inject the
+ * active baggage onto outbound `fetch` automatically once
+ * ``setSurfaceBaggage`` has run — no per-call wiring needed.
+ *
+ * In Bun-compile mode auto-instrumentation breaks, so ``withBaggage(headers)``
+ * is the manual fallback: it reads the active baggage and adds a
+ * ``baggage`` header to a ``HeadersInit`` value.
+ *
+ * All helpers are safe to call even when the OTel SDK isn't initialised
+ * — `@opentelemetry/api` provides no-op fallbacks so the import never
+ * throws and the calls degrade gracefully.
+ */
+export declare const BAGGAGE_KEY_CLIENT_NAME = "client.name";
+export declare const BAGGAGE_KEY_CLIENT_SURFACE = "client.surface";
+export declare const BAGGAGE_KEY_CLIENT_VERSION = "client.version";
+export declare const BAGGAGE_KEY_CONSENT_ANALYTICS = "consent.analytics";
+/** The fixed ``client.name`` we tag every CLI invocation with. The plan
+ * pins this string — backend dashboards filter on it. */
+export declare const CLIENT_NAME = "ish-cli";
+/**
+ * Stamp the active OTel baggage with ``client.name`` / ``client.surface``
+ * / ``client.version`` and stash a process-local copy for the
+ * manual-injection ``withBaggage`` helper.
+ *
+ * Idempotent — subsequent calls overwrite the previous surface, which is
+ * what we want when Commander invokes ``preAction`` once per resolved
+ * subcommand.
+ *
+ * Why process-local (`_activeBaggage`) instead of relying purely on OTel's
+ * context manager: OTel's API tracks active context via scope-bound
+ * `context.with(newCtx, fn)` semantics — there is no "set the global
+ * active context" primitive (by design). Commander's `preAction` hook
+ * runs BEFORE the action and can't wrap it in a context scope. The
+ * cleanest cross-runtime path is to keep the canonical baggage in a
+ * module-local variable and inject it manually via ``withBaggage()`` at
+ * each outbound fetch site. This works identically under Node and the
+ * Bun-compiled binary, and the auto-instrumentation Sentry provides
+ * still handles its own `sentry-trace` propagation in parallel.
+ *
+ * Safe to call even with no OTel SDK registered — `@opentelemetry/api`
+ * ships no-op fallbacks.
+ */
+export declare function setSurfaceBaggage(commandName: string): void;
+/**
+ * Manually inject the active baggage into a ``HeadersInit`` value.
+ *
+ * Use this for outbound HTTP requests in environments where the OTel
+ * undici instrumentation can't auto-propagate — primarily the
+ * ``bun build --compile`` standalone binary, where bundler hooks break
+ * diagnostics_channel patching. In Node mode this still runs but is
+ * harmless: the instrumentation also adds the header and our manual
+ * one is overwritten by the live OTel context value (same content).
+ *
+ * The return type matches `HeadersInit` so callers can drop this in
+ * wherever they were already passing headers.
+ */
+export declare function withBaggage(headers?: HeadersInit): HeadersInit;
+/** Test-only: clear process-local baggage between assertions. Not
+ * exported from the package root. */
+export declare function _resetForTests(): void;

package/dist/lib/baggage.js

@@ -0,0 +1,164 @@
+/**
+ * Helpers for setting OTel Baggage entries and propagating them on
+ * outbound fetches.
+ *
+ * The CLI carries three baggage entries on every backend call so the
+ * backend can attribute spans + Sentry events to the right surface:
+ *
+ *     baggage: client.name=ish-cli,client.surface=<command>,client.version=<x.y.z>
+ *
+ * In Node mode, `@opentelemetry/instrumentation-undici` will inject the
+ * active baggage onto outbound `fetch` automatically once
+ * ``setSurfaceBaggage`` has run — no per-call wiring needed.
+ *
+ * In Bun-compile mode auto-instrumentation breaks, so ``withBaggage(headers)``
+ * is the manual fallback: it reads the active baggage and adds a
+ * ``baggage`` header to a ``HeadersInit`` value.
+ *
+ * All helpers are safe to call even when the OTel SDK isn't initialised
+ * — `@opentelemetry/api` provides no-op fallbacks so the import never
+ * throws and the calls degrade gracefully.
+ */
+import { propagation, trace, context as otelContext } from "@opentelemetry/api";
+import pkg from "../../package.json" with { type: "json" };
+export const BAGGAGE_KEY_CLIENT_NAME = "client.name";
+export const BAGGAGE_KEY_CLIENT_SURFACE = "client.surface";
+export const BAGGAGE_KEY_CLIENT_VERSION = "client.version";
+export const BAGGAGE_KEY_CONSENT_ANALYTICS = "consent.analytics";
+/** The fixed ``client.name`` we tag every CLI invocation with. The plan
+ * pins this string — backend dashboards filter on it. */
+export const CLIENT_NAME = "ish-cli";
+/**
+ * Stamp the active OTel baggage with ``client.name`` / ``client.surface``
+ * / ``client.version`` and stash a process-local copy for the
+ * manual-injection ``withBaggage`` helper.
+ *
+ * Idempotent — subsequent calls overwrite the previous surface, which is
+ * what we want when Commander invokes ``preAction`` once per resolved
+ * subcommand.
+ *
+ * Why process-local (`_activeBaggage`) instead of relying purely on OTel's
+ * context manager: OTel's API tracks active context via scope-bound
+ * `context.with(newCtx, fn)` semantics — there is no "set the global
+ * active context" primitive (by design). Commander's `preAction` hook
+ * runs BEFORE the action and can't wrap it in a context scope. The
+ * cleanest cross-runtime path is to keep the canonical baggage in a
+ * module-local variable and inject it manually via ``withBaggage()`` at
+ * each outbound fetch site. This works identically under Node and the
+ * Bun-compiled binary, and the auto-instrumentation Sentry provides
+ * still handles its own `sentry-trace` propagation in parallel.
+ *
+ * Safe to call even with no OTel SDK registered — `@opentelemetry/api`
+ * ships no-op fallbacks.
+ */
+export function setSurfaceBaggage(commandName) {
+    const existing = propagation.getActiveBaggage() ?? propagation.createBaggage();
+    const next = existing
+        .setEntry(BAGGAGE_KEY_CLIENT_NAME, { value: CLIENT_NAME })
+        .setEntry(BAGGAGE_KEY_CLIENT_SURFACE, { value: commandName })
+        .setEntry(BAGGAGE_KEY_CLIENT_VERSION, { value: pkg.version })
+        // CLI runs on a developer's machine with no client-side consent UI.
+        // Emit "unknown" so the backend resolver falls through to the
+        // authenticated user's persisted consent rather than default-denying
+        // via baggage absence.
+        .setEntry(BAGGAGE_KEY_CONSENT_ANALYTICS, { value: "unknown" });
+    _activeBaggage = next;
+}
+/** Process-local copy of the active baggage for the manual-injection path.
+ * Populated by `setSurfaceBaggage`; read by `withBaggage`. The OTel API
+ * also tracks it but we keep this so the Bun-compile path doesn't need
+ * a working context manager. */
+let _activeBaggage;
+/**
+ * Manually inject the active baggage into a ``HeadersInit`` value.
+ *
+ * Use this for outbound HTTP requests in environments where the OTel
+ * undici instrumentation can't auto-propagate — primarily the
+ * ``bun build --compile`` standalone binary, where bundler hooks break
+ * diagnostics_channel patching. In Node mode this still runs but is
+ * harmless: the instrumentation also adds the header and our manual
+ * one is overwritten by the live OTel context value (same content).
+ *
+ * The return type matches `HeadersInit` so callers can drop this in
+ * wherever they were already passing headers.
+ */
+export function withBaggage(headers) {
+    const baggage = _activeBaggage ?? propagation.getActiveBaggage();
+    const traceparent = _activeTraceparent();
+    if (!baggage && !traceparent)
+        return headers ?? {};
+    // Build the W3C `baggage` header value. Format is
+    // `key1=value1,key2=value2`. We don't URL-encode here because all
+    // our values are plain ASCII (command names, version strings).
+    const entries = baggage ? baggage.getAllEntries() : [];
+    const baggageValue = entries.length > 0
+        ? entries.map(([k, v]) => `${k}=${v.value}`).join(",")
+        : null;
+    if (!baggageValue && !traceparent)
+        return headers ?? {};
+    // Merge with whatever the caller already had. Handle the three
+    // HeadersInit shapes (Headers, Record, array of tuples).
+    if (headers instanceof Headers) {
+        const merged = new Headers(headers);
+        if (baggageValue)
+            merged.set("baggage", baggageValue);
+        if (traceparent)
+            merged.set("traceparent", traceparent);
+        return merged;
+    }
+    if (Array.isArray(headers)) {
+        const filtered = headers.filter(([k]) => {
+            const lower = k.toLowerCase();
+            return lower !== "baggage" && lower !== "traceparent";
+        });
+        if (baggageValue)
+            filtered.push(["baggage", baggageValue]);
+        if (traceparent)
+            filtered.push(["traceparent", traceparent]);
+        return filtered;
+    }
+    const out = { ...(headers ?? {}) };
+    if (baggageValue)
+        out.baggage = baggageValue;
+    if (traceparent)
+        out.traceparent = traceparent;
+    return out;
+}
+/**
+ * Derive a W3C `traceparent` header value from the currently-active OTel
+ * span context.
+ *
+ * Why this lives here and not in `observability.ts`: `@sentry/node`'s OTel
+ * propagator handles `traceparent` injection for HTTP calls patched by its
+ * `nativeNodeFetchIntegration`, but the standalone-binary path (`bun build
+ * --compile`) and a handful of raw `fetch()` callers in the CLI bypass that
+ * patch. Emitting the header explicitly here keeps CLI → backend trace
+ * stitching working regardless of which runtime layer is active.
+ *
+ * Returns `undefined` when there is no active span (e.g. before
+ * `initObservability` has installed a tracer provider, or when called
+ * outside any tracer scope) so we don't emit an invalid all-zeros id.
+ *
+ * Format per W3C Trace Context: `00-<trace-id>-<span-id>-<flags>` where
+ * `<flags>` is two lowercase hex chars (`01` = sampled).
+ */
+function _activeTraceparent() {
+    const span = trace.getSpan(otelContext.active());
+    if (!span)
+        return undefined;
+    const ctx = span.spanContext();
+    // The OTel no-op SDK reports an all-zero context; treat that as "no span".
+    if (!ctx.traceId ||
+        ctx.traceId === "00000000000000000000000000000000" ||
+        !ctx.spanId ||
+        ctx.spanId === "0000000000000000") {
+        return undefined;
+    }
+    const flags = ctx.traceFlags.toString(16).padStart(2, "0");
+    return `00-${ctx.traceId}-${ctx.spanId}-${flags}`;
+}
+/** Test-only: clear process-local baggage between assertions. Not
+ * exported from the package root. */
+export function _resetForTests() {
+    _activeBaggage = undefined;
+}

package/dist/lib/command-helpers.js

@@ -10,6 +10,7 @@ import { outputError, setVerbose, setFields, setGetField } from "./output.js";
 import { setColorsEnabled, colorsEnabled } from "./colors.js";
 import { loadConfig } from "../config.js";
 import { resolveId } from "./alias-store.js";
+import { exitWithFlush } from "./observability.js";
 function isSimulatable(p) {
     return Boolean(p.simulation_config_id) || Boolean(p.simulation_config);
 }
@@ -277,6 +278,10 @@ export function getGlobals(cmd) {
             || process.argv.includes("--get")
             || !process.stdout.isTTY;
         outputError(err, useJson);
+        // Sync exit path: getGlobals is called from non-async Commander hooks,
+        // so we can't await exitWithFlush here. Usage errors are typed early-
+        // exits without rich Sentry signal; accept losing the flush on this
+        // one site rather than cascading async through every getGlobals caller.
         process.exit(exitCodeFromError(err));
     }
     // Apply side effects (verbose, fields, colors, get-field, active workspace)
@@ -409,7 +414,7 @@ export async function withClient(cmd, fn) {
     }
     catch (err) {
         outputError(err, globals.json);
-        process.exit(exitCodeFromError(err));
+        await exitWithFlush(exitCodeFromError(err));
     }
 }
 /**
@@ -424,7 +429,7 @@ export async function runInline(cmd, fn) {
     }
     catch (err) {
         outputError(err, globals.json);
-        process.exit(exitCodeFromError(err));
+        await exitWithFlush(exitCodeFromError(err));
     }
 }
 export function getWebUrl(globals, path) {

package/dist/lib/observability.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Observability bootstrap for the CLI.
+ *
+ * Initialises Sentry (runtime-detected: `@sentry/bun` under Bun, `@sentry/node`
+ * under Node) and — in Node mode only — the OpenTelemetry SDK with the W3C
+ * tracecontext + baggage propagators and undici fetch auto-instrumentation.
+ *
+ * Why runtime detection: ish-cli ships two ways. `npm i -g @ishlabs/cli`
+ * runs the compiled JS on the user's Node. `curl | sh` / `brew` install the
+ * `bun build --compile` standalone binary. The Sentry packages differ
+ * (`@sentry/bun` wraps Bun's runtime hooks; `@sentry/node` uses Node's).
+ * `@sentry/profiling-node` is incompatible with Bun (native addon) and is
+ * deliberately not added as a dep.
+ *
+ * Why OTel only in Node mode: under `bun build --compile`, the bundler
+ * inlines `@opentelemetry/instrumentation-undici`'s require-time hooks in a
+ * way that breaks the diagnostics_channel auto-patching. Manual baggage
+ * injection via ``withBaggage(headers)`` in ``src/lib/api-client.ts`` is the
+ * documented fallback for the Bun-compiled binary — see
+ * `.docs/observability/cli-bun-compile.md`.
+ *
+ * Init failures are swallowed: an observability outage must never crash
+ * the CLI for the end user.
+ */
+/** Bun-global probe. ``typeof Bun !== 'undefined'`` is the only reliable
+ * runtime-detect: ``process.versions.bun`` exists but is set up well after
+ * import time on some Bun-compile builds. */
+export declare function isBunRuntime(): boolean;
+export declare function initObservability(): Promise<void>;
+/**
+ * Drain the Sentry buffer before exiting the process.
+ *
+ * Why this exists: Sentry's transport buffers events asynchronously. `ish`
+ * is a short-lived process — most commands call `process.exit(code)` within
+ * milliseconds of init, so the buffered envelope is dropped before the HTTP
+ * batch fires. Net effect: zero telemetry from real CLI invocations.
+ *
+ * Wrap every `process.exit(code)` callsite with `exitWithFlush(code)` instead,
+ * OR await `flushObservability()` directly before exit.
+ *
+ * Always safe to call: no-op when Sentry wasn't initialised (no DSN, or
+ * init failed). Never throws — an observability outage must not crash the
+ * CLI.
+ */
+export declare function flushObservability(timeoutMs?: number): Promise<void>;
+/**
+ * Async-flush-then-exit helper. Use this in place of `process.exit(code)`
+ * anywhere we want telemetry to ship before teardown.
+ *
+ * The Node `beforeExit` event would fire automatically on natural process
+ * end, but it does NOT fire when `process.exit()` is called explicitly —
+ * which the CLI does from at least 5 sites. This helper closes that gap.
+ */
+export declare function exitWithFlush(code: number): Promise<never>;

package/dist/lib/observability.js

@@ -0,0 +1,165 @@
+/**
+ * Observability bootstrap for the CLI.
+ *
+ * Initialises Sentry (runtime-detected: `@sentry/bun` under Bun, `@sentry/node`
+ * under Node) and — in Node mode only — the OpenTelemetry SDK with the W3C
+ * tracecontext + baggage propagators and undici fetch auto-instrumentation.
+ *
+ * Why runtime detection: ish-cli ships two ways. `npm i -g @ishlabs/cli`
+ * runs the compiled JS on the user's Node. `curl | sh` / `brew` install the
+ * `bun build --compile` standalone binary. The Sentry packages differ
+ * (`@sentry/bun` wraps Bun's runtime hooks; `@sentry/node` uses Node's).
+ * `@sentry/profiling-node` is incompatible with Bun (native addon) and is
+ * deliberately not added as a dep.
+ *
+ * Why OTel only in Node mode: under `bun build --compile`, the bundler
+ * inlines `@opentelemetry/instrumentation-undici`'s require-time hooks in a
+ * way that breaks the diagnostics_channel auto-patching. Manual baggage
+ * injection via ``withBaggage(headers)`` in ``src/lib/api-client.ts`` is the
+ * documented fallback for the Bun-compiled binary — see
+ * `.docs/observability/cli-bun-compile.md`.
+ *
+ * Init failures are swallowed: an observability outage must never crash
+ * the CLI for the end user.
+ */
+import pkg from "../../package.json" with { type: "json" };
+import { beforeSend } from "./sentry-scrub.js";
+/** Module-local reference to the loaded Sentry module so `flushObservability`
+ * can call `flush()` without re-importing (which would lose runtime-pinned
+ * state and create a second Hub in some bundler configurations). */
+let _sentryModule = null;
+/** Bun-global probe. ``typeof Bun !== 'undefined'`` is the only reliable
+ * runtime-detect: ``process.versions.bun`` exists but is set up well after
+ * import time on some Bun-compile builds. */
+export function isBunRuntime() {
+    // @ts-expect-error — Bun is a runtime global, not a TS-known symbol
+    return typeof Bun !== "undefined";
+}
+let _initialized = false;
+export async function initObservability() {
+    if (_initialized)
+        return;
+    _initialized = true;
+    const dsn = process.env.ISH_CLI_SENTRY_DSN;
+    if (!dsn)
+        return; // unset → opt out; the CLI runs untraced.
+    const bun = isBunRuntime();
+    try {
+        const sentryModule = bun
+            ? await import("@sentry/bun")
+            : await import("@sentry/node");
+        _sentryModule = sentryModule;
+        const init = sentryModule.init;
+        init({
+            dsn,
+            release: `ish-cli@${pkg.version}`,
+            environment: process.env.NODE_ENV ?? "development",
+            // Keep traces sampled at 1.0 in dev — CLI invocation volume is low
+            // and we want full visibility for distributed-trace continuity with
+            // the backend. Backend (ish-backend) is the SLO source of truth.
+            tracesSampleRate: 1.0,
+            // ARGV (including `--token` flags), workspace ids in `~/.ish/`
+            // paths, and `@sentry/node`'s default RequestData integration
+            // (Authorization headers) would otherwise ship raw. ``beforeSend``
+            // is the single chokepoint; mirrors the backend's ``_scrub_event``.
+            beforeSend,
+            // Under Bun the default integration set assumes Node internals
+            // (diagnostics_channel + http.Agent hooks) that aren't reliably
+            // wired in the compiled binary. Strip integrations there.
+            ...(bun ? { integrations: [], defaultIntegrations: false } : {}),
+        });
+        // client.name / client.version must be Sentry tags (not just OTel
+        // baggage / span attributes) so the Sentry UI's `tags[client.name]:…`
+        // filter works for saved searches and dashboards.
+        const setTag = sentryModule.setTag;
+        if (setTag) {
+            setTag("client.name", "ish-cli");
+            setTag("client.version", pkg.version);
+        }
+    }
+    catch (err) {
+        // Don't crash the CLI on init failure. Print to stderr at verbose
+        // level only — most users will never see this.
+        if (process.env.ISH_DEBUG_OBS) {
+            console.error("ish-cli: Sentry init failed:", err);
+        }
+        return;
+    }
+    if (bun)
+        return; // OTel auto-instrumentation only in Node mode.
+    try {
+        await initOtelNode();
+    }
+    catch (err) {
+        if (process.env.ISH_DEBUG_OBS) {
+            console.error("ish-cli: OTel init failed:", err);
+        }
+    }
+}
+/** Node-only: register the undici fetch auto-instrumentation.
+ *
+ * `@sentry/node` v10 already wires its own OTel propagator composite that
+ * emits W3C `baggage`, `traceparent`, and Sentry's `sentry-trace` — we
+ * deliberately do NOT call `propagation.setGlobalPropagator(...)` here
+ * (that would clobber Sentry's propagator and break Sentry's distributed
+ * tracing).
+ *
+ * What we DO add is `UndiciInstrumentation`, which patches the global
+ * `fetch` / undici so outbound HTTP calls open child spans and let the
+ * propagator inject the active context's headers. This is best-effort:
+ * Sentry's own `nativeNodeFetchIntegration` also patches `fetch` and will
+ * win in many cases — but registering Undici explicitly ensures the
+ * `baggage` propagation path is active even in setups where Sentry's
+ * fetch integration is opted out.
+ *
+ * The load-bearing injection path remains `withBaggage(headers)` in
+ * `src/lib/api-client.ts:headers()` — it works in both Node and Bun
+ * runtimes and doesn't depend on bundler-fragile diagnostics_channel
+ * hooks. The undici instrumentation here is a redundant secondary layer.
+ */
+async function initOtelNode() {
+    const [{ registerInstrumentations }, { UndiciInstrumentation }] = await Promise.all([
+        import("@opentelemetry/instrumentation"),
+        import("@opentelemetry/instrumentation-undici"),
+    ]);
+    registerInstrumentations({
+        instrumentations: [new UndiciInstrumentation()],
+    });
+}
+/**
+ * Drain the Sentry buffer before exiting the process.
+ *
+ * Why this exists: Sentry's transport buffers events asynchronously. `ish`
+ * is a short-lived process — most commands call `process.exit(code)` within
+ * milliseconds of init, so the buffered envelope is dropped before the HTTP
+ * batch fires. Net effect: zero telemetry from real CLI invocations.
+ *
+ * Wrap every `process.exit(code)` callsite with `exitWithFlush(code)` instead,
+ * OR await `flushObservability()` directly before exit.
+ *
+ * Always safe to call: no-op when Sentry wasn't initialised (no DSN, or
+ * init failed). Never throws — an observability outage must not crash the
+ * CLI.
+ */
+export async function flushObservability(timeoutMs = 2000) {
+    if (!_initialized || _sentryModule?.flush === undefined)
+        return;
+    try {
+        await _sentryModule.flush(timeoutMs);
+    }
+    catch {
+        // Swallow — same rationale as init failure.
+    }
+}
+/**
+ * Async-flush-then-exit helper. Use this in place of `process.exit(code)`
+ * anywhere we want telemetry to ship before teardown.
+ *
+ * The Node `beforeExit` event would fire automatically on natural process
+ * end, but it does NOT fire when `process.exit()` is called explicitly —
+ * which the CLI does from at least 5 sites. This helper closes that gap.
+ */
+export async function exitWithFlush(code) {
+    await flushObservability();
+    process.exit(code);
+}

package/dist/lib/sentry-scrub.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Sentry `beforeSend` scrubber for the CLI.
+ *
+ * Mirrors the backend's ``_scrub_event`` policy (``app/core/sentry.py``) so
+ * secrets and PII shaped by the same regex are stripped on the way out of
+ * every client. Substring-match is conservative — better to over-redact a
+ * benign field name than ship a token. Applied recursively up to
+ * ``_MAX_DEPTH`` levels; past that, the subtree is left as-is rather than
+ * truncated, so a pathological event surface can't blow the stack.
+ *
+ * Specifically scrubbed:
+ *  - ``event.request.headers`` — ``@sentry/node``'s default ``RequestData``
+ *    integration attaches ``Authorization`` / ``Cookie`` verbatim; without
+ *    this walk, every captured 500 ships the user's session JWT to Sentry.
+ *  - ``event.extra`` and ``event.contexts.*`` — fan-out values surfaced
+ *    via ``Sentry.setExtra`` / ``Sentry.setContext``.
+ *  - ``event.breadcrumbs[].data`` — auto-instrumented HTTP crumbs land
+ *    request headers here too.
+ *  - ``event.request.url`` — the query string is stripped entirely;
+ *    ``?token=…`` shows up in CLI HTTP traces.
+ *
+ * Control-flow exceptions (user-cancelled, aborts) drop to ``null`` so
+ * Sentry doesn't see them as noise.
+ */
+import type { Event, EventHint } from "@sentry/node";
+/** Walk an arbitrary value and redact secret-shaped keys. */
+declare function scrubValue(value: unknown, depth: number): unknown;
+declare function stripQueryString(url: string): string;
+declare function isControlFlowException(hint: EventHint | undefined): boolean;
+/**
+ * Sentry ``beforeSend`` hook — returns ``null`` to drop the event, or the
+ * (mutated in place) event to send it.
+ */
+export declare function beforeSend(event: Event, hint?: EventHint): Event | null;
+export declare const _internals: {
+    scrubValue: typeof scrubValue;
+    stripQueryString: typeof stripQueryString;
+    isControlFlowException: typeof isControlFlowException;
+    SECRET_KEY_RE: RegExp;
+    REDACTED: string;
+    MAX_DEPTH: number;
+};
+export {};

package/dist/lib/sentry-scrub.js

@@ -0,0 +1,141 @@
+/**
+ * Sentry `beforeSend` scrubber for the CLI.
+ *
+ * Mirrors the backend's ``_scrub_event`` policy (``app/core/sentry.py``) so
+ * secrets and PII shaped by the same regex are stripped on the way out of
+ * every client. Substring-match is conservative — better to over-redact a
+ * benign field name than ship a token. Applied recursively up to
+ * ``_MAX_DEPTH`` levels; past that, the subtree is left as-is rather than
+ * truncated, so a pathological event surface can't blow the stack.
+ *
+ * Specifically scrubbed:
+ *  - ``event.request.headers`` — ``@sentry/node``'s default ``RequestData``
+ *    integration attaches ``Authorization`` / ``Cookie`` verbatim; without
+ *    this walk, every captured 500 ships the user's session JWT to Sentry.
+ *  - ``event.extra`` and ``event.contexts.*`` — fan-out values surfaced
+ *    via ``Sentry.setExtra`` / ``Sentry.setContext``.
+ *  - ``event.breadcrumbs[].data`` — auto-instrumented HTTP crumbs land
+ *    request headers here too.
+ *  - ``event.request.url`` — the query string is stripped entirely;
+ *    ``?token=…`` shows up in CLI HTTP traces.
+ *
+ * Control-flow exceptions (user-cancelled, aborts) drop to ``null`` so
+ * Sentry doesn't see them as noise.
+ */
+const _SECRET_KEY_RE = /api[_-]?key|token|password|secret|authorization|cookie|bearer|email|full[_-]?name|phone/i;
+const _REDACTED = "[REDACTED]";
+// Hard ceiling for nested-scrub recursion. Mirrors backend's _SCRUB_MAX_DEPTH.
+// Sentry breadcrumb data nests one or two levels deep
+// (``crumb.data.headers.Authorization``); 5 leaves headroom without letting a
+// pathological event blow the stack.
+const _MAX_DEPTH = 5;
+// Exception ``name`` values that represent expected control flow, not a
+// crash. Mirrors backend's ``_DROP_EXCEPTIONS`` set adapted to JS: Node's
+// ``AbortError`` (HTTP aborted by signal) and the SIGINT-driven cancel
+// path used by ``ish connect``. Match by name so we don't have to import
+// the constructor.
+const _DROP_EXCEPTION_NAMES = new Set([
+    "AbortError",
+    "CancelError",
+    "UserCancelledError",
+]);
+/** Walk an arbitrary value and redact secret-shaped keys. */
+function scrubValue(value, depth) {
+    if (depth >= _MAX_DEPTH || value === null || value === undefined) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => scrubValue(item, depth + 1));
+    }
+    if (typeof value !== "object") {
+        return value;
+    }
+    const obj = value;
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (_SECRET_KEY_RE.test(k)) {
+            out[k] = _REDACTED;
+        }
+        else if (v !== null && typeof v === "object") {
+            out[k] = scrubValue(v, depth + 1);
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+function scrubDict(dict) {
+    return scrubValue(dict, 0);
+}
+function stripQueryString(url) {
+    const q = url.indexOf("?");
+    return q === -1 ? url : url.slice(0, q);
+}
+function isControlFlowException(hint) {
+    const exc = hint?.originalException;
+    if (exc === null || exc === undefined)
+        return false;
+    if (typeof exc !== "object")
+        return false;
+    const name = exc.name;
+    return typeof name === "string" && _DROP_EXCEPTION_NAMES.has(name);
+}
+/**
+ * Sentry ``beforeSend`` hook — returns ``null`` to drop the event, or the
+ * (mutated in place) event to send it.
+ */
+export function beforeSend(event, hint) {
+    if (isControlFlowException(hint))
+        return null;
+    const request = event.request;
+    if (request !== undefined) {
+        if (request.headers !== undefined && request.headers !== null) {
+            request.headers = scrubDict(request.headers);
+        }
+        if (typeof request.url === "string") {
+            request.url = stripQueryString(request.url);
+        }
+        if (request.cookies !== undefined && request.cookies !== null) {
+            // Every cookie value is sensitive; cookie *names* don't match the
+            // secret regex on their own. Redact values, keep names so debug
+            // context still shows which cookies were attached.
+            const cookies = request.cookies;
+            const redacted = {};
+            for (const name of Object.keys(cookies))
+                redacted[name] = _REDACTED;
+            request.cookies = redacted;
+        }
+    }
+    if (event.extra !== undefined && event.extra !== null) {
+        event.extra = scrubDict(event.extra);
+    }
+    if (event.contexts !== undefined && event.contexts !== null) {
+        const contexts = event.contexts;
+        for (const [ctxName, ctxValue] of Object.entries(contexts)) {
+            if (ctxValue !== null && typeof ctxValue === "object") {
+                contexts[ctxName] = scrubDict(ctxValue);
+            }
+        }
+    }
+    if (Array.isArray(event.breadcrumbs)) {
+        for (const crumb of event.breadcrumbs) {
+            if (crumb !== null
+                && typeof crumb === "object"
+                && crumb.data !== null
+                && typeof crumb.data === "object") {
+                crumb.data = scrubDict(crumb.data);
+            }
+        }
+    }
+    return event;
+}
+// Re-exports for tests — these would otherwise be private.
+export const _internals = {
+    scrubValue,
+    stripQueryString,
+    isControlFlowException,
+    SECRET_KEY_RE: _SECRET_KEY_RE,
+    REDACTED: _REDACTED,
+    MAX_DEPTH: _MAX_DEPTH,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.17.3",
+  "version": "0.17.5",
   "description": "The command-line interface for ish",
   "type": "module",
   "bin": {
@@ -37,6 +37,13 @@
     "email": "support@ishlabs.io"
   },
   "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^1.30.0",
+    "@opentelemetry/instrumentation": "^0.57.0",
+    "@opentelemetry/instrumentation-undici": "^0.10.0",
+    "@opentelemetry/sdk-node": "^0.57.0",
+    "@sentry/bun": "^10.13.0",
+    "@sentry/node": "^10.13.0",
     "commander": "^13.0.0",
     "playwright-core": "^1.58.2"
   },