@kaelio/ktx 0.10.0 → 0.11.0

package/dist/cli-program.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { Command, InvalidArgumentError } from '@commander-js/extra-typings';
+import { SLACK_HELP_FOOTER, writeErrorCommunityHint } from './community-cta.js';
 import { registerCompletionCommands } from './commands/completion-commands.js';
 import { registerConnectionCommands } from './commands/connection-commands.js';
 import { registerIngestCommands } from './commands/ingest-commands.js';
@@ -168,6 +169,7 @@ function createBaseProgram(info, io) {
         .helpOption('-h, --help', 'Show this help text')
         .configureHelp({ showGlobalOptions: true })
         .showHelpAfterError()
+        .addHelpText('after', `\n${SLACK_HELP_FOOTER}`)
         .exitOverride()
         .configureOutput({
         writeOut: (chunk) => io.stdout.write(chunk),
@@ -433,6 +435,7 @@ export async function runCommanderKtxCli(argv, io, deps, info, options) {
                     io,
                 });
                 io.stderr.write(`${formatCliError(error)}\n`);
+                writeErrorCommunityHint(io, 'error');
                 return 1;
             }
         }
@@ -458,6 +461,7 @@ export async function runCommanderKtxCli(argv, io, deps, info, options) {
         }
         else {
             io.stderr.write(`${formatCliError(error)}\n`);
+            writeErrorCommunityHint(io, 'error');
             exitCode = 1;
         }
     }

package/dist/cli-runtime.d.ts

@@ -49,5 +49,7 @@ export declare function runInitForCommander(args: {
 }, io: KtxCliIo): Promise<number>;
 /** @internal */
 export declare function createGlobalExceptionReporter(io: KtxCliIo, info: KtxCliPackageInfo): (source: "uncaughtException" | "unhandledRejection", error: unknown) => Promise<void>;
+/** @internal */
+export declare function writeGlobalExceptionToStderr(io: KtxCliIo, error: unknown): void;
 export declare function installGlobalExceptionHandlers(io: KtxCliIo, info: KtxCliPackageInfo): () => void;
 export declare function runKtxCli(argv?: string[], io?: KtxCliIo, deps?: KtxCliDeps): Promise<number>;

package/dist/cli-runtime.js

@@ -1,6 +1,7 @@
 import { createRequire } from 'node:module';
 import { profileMark, profileSpan } from './startup-profile.js';
 import { assertCliVersion } from './release-version.js';
+import { writeErrorCommunityHint } from './community-cta.js';
 profileMark('module:cli-runtime');
 const requirePackageJson = createRequire(import.meta.url);
 export function getKtxCliPackageInfo() {
@@ -88,6 +89,16 @@ export function createGlobalExceptionReporter(io, info) {
         await shutdownTelemetryEmitter();
     };
 }
+/** @internal */
+export function writeGlobalExceptionToStderr(io, error) {
+    if (error instanceof Error && error.stack) {
+        io.stderr.write(`${error.stack}\n`);
+    }
+    else {
+        io.stderr.write(`${String(error)}\n`);
+    }
+    writeErrorCommunityHint(io, 'crash');
+}
 export function installGlobalExceptionHandlers(io, info) {
     const report = createGlobalExceptionReporter(io, info);
     const handle = (source, error) => {
@@ -98,12 +109,7 @@ export function installGlobalExceptionHandlers(io, info) {
             catch {
                 // Best-effort: preserve Node's process termination behavior.
             }
-            if (error instanceof Error && error.stack) {
-                io.stderr.write(`${error.stack}\n`);
-            }
-            else {
-                io.stderr.write(`${String(error)}\n`);
-            }
+            writeGlobalExceptionToStderr(io, error);
             process.exit(1);
         })();
     };

package/dist/community-cta.d.ts

@@ -0,0 +1,11 @@
+import type { KtxCliIo } from './cli-runtime.js';
+type ErrorCtaVariant = 'error' | 'crash';
+/** @internal */
+export declare const SLACK_HELP_FOOTER = "Community & support: https://ktx.sh/slack";
+/** @internal */
+export declare const SLACK_SETUP_NOTE: {
+    readonly title: "Community";
+    readonly body: "Questions or feedback? Join the ktx Slack: https://ktx.sh/slack";
+};
+export declare function writeErrorCommunityHint(io: KtxCliIo, variant: ErrorCtaVariant): void;
+export {};

package/dist/community-cta.js

@@ -0,0 +1,19 @@
+import { isWritableTtyOutput } from './io/tty.js';
+import { dim } from './io/symbols.js';
+import { SLACK_URL } from './links.js';
+/** @internal */
+export const SLACK_HELP_FOOTER = `Community & support: ${SLACK_URL}`;
+/** @internal */
+export const SLACK_SETUP_NOTE = {
+    title: 'Community',
+    body: `Questions or feedback? Join the ktx Slack: ${SLACK_URL}`,
+};
+export function writeErrorCommunityHint(io, variant) {
+    if (!isWritableTtyOutput(io.stderr)) {
+        return;
+    }
+    const line = variant === 'crash'
+        ? `This may be a bug - report it or ask in the ktx community: ${SLACK_URL}`
+        : `Stuck? The ktx community can help: ${SLACK_URL}`;
+    io.stderr.write(`${dim(line)}\n`);
+}

package/dist/context/core/git-env.d.ts

@@ -1,2 +1,13 @@
 import { type SimpleGit } from 'simple-git';
-export declare function createSimpleGit(baseDir: string): SimpleGit;
+/**
+ * Create a simple-git client scoped to `baseDir`. When an identity is provided, ktx's own
+ * commits carry it through the GIT_AUTHOR and GIT_COMMITTER environment variables instead of
+ * relying on repo-local or global git config. This keeps commits working when the project
+ * directory is an existing repo ktx did not create and the machine has no configured git
+ * identity (e.g. a fresh Mac with no ~/.gitconfig), without mutating the user's repo config.
+ * Explicit `--author` flags on individual commits still take precedence over GIT_AUTHOR_NAME.
+ */
+export declare function createSimpleGit(baseDir: string, identity?: {
+    name: string;
+    email: string;
+}): SimpleGit;

package/dist/context/core/git-env.js

@@ -21,6 +21,21 @@ function sanitizedGitEnv(env = process.env) {
     }
     return sanitized;
 }
-export function createSimpleGit(baseDir) {
-    return simpleGit({ baseDir, unsafe: { allowUnsafeAskPass: true } }).env(sanitizedGitEnv());
+/**
+ * Create a simple-git client scoped to `baseDir`. When an identity is provided, ktx's own
+ * commits carry it through the GIT_AUTHOR and GIT_COMMITTER environment variables instead of
+ * relying on repo-local or global git config. This keeps commits working when the project
+ * directory is an existing repo ktx did not create and the machine has no configured git
+ * identity (e.g. a fresh Mac with no ~/.gitconfig), without mutating the user's repo config.
+ * Explicit `--author` flags on individual commits still take precedence over GIT_AUTHOR_NAME.
+ */
+export function createSimpleGit(baseDir, identity) {
+    const env = sanitizedGitEnv();
+    if (identity?.name && identity.email) {
+        env.GIT_AUTHOR_NAME = identity.name;
+        env.GIT_AUTHOR_EMAIL = identity.email;
+        env.GIT_COMMITTER_NAME = identity.name;
+        env.GIT_COMMITTER_EMAIL = identity.email;
+    }
+    return simpleGit({ baseDir, unsafe: { allowUnsafeAskPass: true } }).env(env);
 }

package/dist/context/core/git.service.js

@@ -47,8 +47,12 @@ export class GitService {
         // Ensure config directory exists
         await fs.mkdir(this.configDir, { recursive: true });
         this.logger.log(`Config directory ensured at: ${this.configDir}`);
-        // Initialize simple-git
-        this.git = createSimpleGit(this.configDir);
+        // Initialize simple-git. Carry ktx's identity in the environment so commits succeed even
+        // when this repo already exists and the machine has no configured git identity.
+        this.git = createSimpleGit(this.configDir, {
+            name: this.config.git.userName,
+            email: this.config.git.userEmail,
+        });
         // Initialize git repository
         await this.initialize();
     }
@@ -58,9 +62,6 @@ export class GitService {
             const isRepo = await this.git.checkIsRepo();
             if (!isRepo) {
                 await this.git.init();
-                const gitConfig = this.config.git;
-                await this.git.addConfig('user.name', gitConfig.userName);
-                await this.git.addConfig('user.email', gitConfig.userEmail);
                 this.logger.log('Initialized git repository');
             }
             // Keep any auto-maintenance triggered by writes in-process. Detached maintenance can
@@ -81,7 +82,11 @@ export class GitService {
         }
         catch (error) {
             this.logger.error('Failed to initialize git repository', error);
-            throw new Error('Failed to initialize git repository');
+            // Preserve the underlying git error: the generic message alone is undiagnosable in
+            // telemetry and unactionable for the user. The exception reporter walks `cause` and
+            // redacts secrets before send.
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to initialize git repository: ${detail}`, { cause: error });
         }
     }
     async commitFile(filePath, commitMessage, author, authorEmail) {
@@ -740,7 +745,10 @@ export class GitService {
      */
     forWorktree(workdir) {
         const scoped = new GitService(this.config, this.logger);
-        scoped.git = createSimpleGit(workdir);
+        scoped.git = createSimpleGit(workdir, {
+            name: this.config.git.userName,
+            email: this.config.git.userEmail,
+        });
         scoped.configDir = workdir;
         return scoped;
     }

package/dist/io/tty.d.ts

@@ -0,0 +1,9 @@
+import type { Writable } from 'node:stream';
+import type { KtxCliIo } from '../cli-runtime.js';
+type KtxCliOutput = (KtxCliIo['stdout'] | KtxCliIo['stderr']) & {
+    isTTY?: boolean;
+    columns?: number;
+    on?: unknown;
+};
+export declare function isWritableTtyOutput(output: KtxCliOutput): output is KtxCliOutput & Writable;
+export {};

package/dist/io/tty.js

@@ -0,0 +1,5 @@
+export function isWritableTtyOutput(output) {
+    return (output.isTTY === true &&
+        typeof output.on === 'function' &&
+        typeof output.columns !== 'undefined');
+}

package/dist/links.d.ts

@@ -0,0 +1 @@
+export declare const SLACK_URL = "https://ktx.sh/slack";

package/dist/links.js

@@ -0,0 +1 @@
+export const SLACK_URL = 'https://ktx.sh/slack';

package/dist/setup-agents.js

@@ -9,14 +9,10 @@ import { markKtxSetupStateStepComplete } from './context/project/setup-config.js
 import { serializeKtxProjectConfig } from './context/project/config.js';
 import { strToU8, zipSync } from 'fflate';
 import { errorMessage, writePrefixedLines } from './clack.js';
+import { isWritableTtyOutput } from './io/tty.js';
 import { createKtxSetupPromptAdapter, createKtxSetupUiAdapter, } from './setup-prompts.js';
 import { readKtxMcpDaemonStatus } from './managed-mcp-daemon.js';
 const MCP_DAEMON_REQUIRED_NOTICE = 'mcp-daemon-required';
-function isWritableTtyOutput(output) {
-    return (output.isTTY === true &&
-        typeof output.on === 'function' &&
-        typeof output.columns !== 'undefined');
-}
 function writeSetupInfo(io, message) {
     if (isWritableTtyOutput(io.stdout)) {
         log.info(message, { output: io.stdout });

package/dist/setup-prompts.js

@@ -1,4 +1,5 @@
 import { autocomplete, autocompleteMultiselect, cancel, confirm, intro, isCancel, log, multiselect, note, select, text, } from '@clack/prompts';
+import { isWritableTtyOutput } from './io/tty.js';
 import { withMenuOptionsSpacing, withTextInputNavigation } from './prompt-navigation.js';
 import { revealPassword } from './reveal-password-prompt.js';
 import { withSetupInterruptConfirmation } from './setup-interrupt.js';
@@ -101,11 +102,6 @@ export function createKtxSetupPromptAdapter(options) {
         },
     };
 }
-function isWritableTtyOutput(output) {
-    return (output.isTTY === true &&
-        typeof output.on === 'function' &&
-        typeof output.columns !== 'undefined');
-}
 export function createKtxSetupUiAdapter() {
     return {
         intro(title, io) {

package/dist/setup.d.ts

@@ -1,5 +1,6 @@
 import { type KtxCliIo } from './cli-runtime.js';
 import { readManagedPythonRuntimeStatus } from './managed-python-runtime.js';
+import type { CommandOutcome } from './telemetry/index.js';
 import { type KtxAgentScope, type KtxAgentTarget, type KtxSetupAgentsDeps, runKtxSetupAgentsStep } from './setup-agents.js';
 import { type KtxSetupDatabaseDriver, type KtxSetupDatabasesDeps, runKtxSetupDatabasesStep } from './setup-databases.js';
 import { type KtxSetupEmbeddingsDeps, runKtxSetupEmbeddingsStep } from './setup-embeddings.js';
@@ -125,6 +126,7 @@ export interface KtxSetupDeps {
     entryMenuDeps?: KtxSetupEntryMenuDeps;
     setupUi?: KtxSetupUiAdapter;
 }
+type TelemetrySetupStep = 'project' | 'runtime' | 'models' | 'embeddings' | 'databases' | 'sources' | 'context' | 'agents' | 'demo-tour';
 export interface KtxSetupEntryMenuPromptAdapter {
     select(options: {
         message: string;
@@ -135,6 +137,28 @@ export interface KtxSetupEntryMenuPromptAdapter {
 export interface KtxSetupEntryMenuDeps {
     prompts?: KtxSetupEntryMenuPromptAdapter;
 }
+interface SetupCommandAnnotation {
+    outcome: CommandOutcome;
+    errorClass?: string;
+    errorDetail?: string;
+}
+/**
+ * Single source of truth for how a non-ready setup step ends: the process exit
+ * code and the telemetry annotation are both derived from one classification,
+ * so they can never disagree. A genuine failure (`error`) exits non-zero; an
+ * abort — the user leaving an interactive wizard — exits 0, matching the entry
+ * menu's "Exit", a project cancellation, and a confirmed Ctrl+C.
+ */
+/** @internal */
+export declare function setupTerminalOutcome(input: {
+    status: 'failed' | 'missing-input' | 'cancelled';
+    step: TelemetrySetupStep;
+    interactive: boolean;
+    errorDetail?: string;
+}): {
+    exitCode: number;
+    annotation: SetupCommandAnnotation;
+};
 export interface ReadKtxSetupStatusOptions {
     cliVersion?: string;
     env?: NodeJS.ProcessEnv;
@@ -146,3 +170,4 @@ export declare function formatKtxSetupCompletionSummary(status: KtxSetupStatus,
     agentNextActions?: string;
 }): string;
 export declare function runKtxSetup(args: KtxSetupArgs, io: KtxCliIo, deps?: KtxSetupDeps): Promise<number>;
+export {};

package/dist/setup.js

@@ -6,6 +6,7 @@ import { ktxLocalStateDbPath } from './context/project/local-state-db.js';
 import { loadKtxProject } from './context/project/project.js';
 import { readKtxSetupState } from './context/project/setup-config.js';
 import { getKtxCliPackageInfo } from './cli-runtime.js';
+import { SLACK_SETUP_NOTE } from './community-cta.js';
 import { formatNextStepLines, formatSetupNextStepLines } from './next-steps.js';
 import { runtimeInstallPolicyFromFlags } from './managed-python-command.js';
 import { readManagedPythonRuntimeStatus } from './managed-python-runtime.js';
@@ -36,6 +37,61 @@ function setupTelemetryOutcome(status) {
         return 'skipped';
     return 'abandoned';
 }
+/**
+ * Classify a terminal non-ready setup status into the `command` telemetry
+ * outcome. The setup flow is the decision-maker and knows the difference:
+ * - `failed` is a genuine error; attach a step-scoped reason so the dashboard
+ *   shows an actionable signature instead of a blank.
+ * - `missing-input` from a *non-interactive* run is an automation error
+ *   (required flags absent and no prompt was possible); attach a reason too.
+ * - `missing-input` from an interactive prompt, or a project `cancelled`, is the
+ *   user backing out of the wizard — an abort, not a failure. Keep it out of
+ *   error telemetry so it stops inflating the error count.
+ *
+ * `interactive` must reflect whether a prompt could actually be shown — input
+ * is enabled AND a TTY is attached. `inputMode: 'auto'` alone is not enough: a
+ * piped/CI run without `--no-input` is still non-interactive, and steps such as
+ * the project step return `missing-input` ("pass --yes …") there without ever
+ * prompting. Treating that as an abort would make a broken automation run exit
+ * 0, so it must classify as an error.
+ *
+ * Reasons are synthetic, step-scoped strings (no user input), so they satisfy
+ * the telemetry privacy rules. The step's own `errorDetail`, when present, has
+ * already been vetted for the `setup_step` event and is safe to reuse.
+ */
+function setupCommandOutcomeAnnotation(input) {
+    if (input.status === 'failed') {
+        return {
+            outcome: 'error',
+            errorClass: 'KtxSetupStepFailed',
+            errorDetail: input.errorDetail ?? `${input.step} setup step failed`,
+        };
+    }
+    if (input.status === 'missing-input' && !input.interactive) {
+        return {
+            outcome: 'error',
+            errorClass: 'KtxSetupMissingInput',
+            errorDetail: `${input.step} setup step requires input not provided in a non-interactive run`,
+        };
+    }
+    return { outcome: 'aborted' };
+}
+/**
+ * Single source of truth for how a non-ready setup step ends: the process exit
+ * code and the telemetry annotation are both derived from one classification,
+ * so they can never disagree. A genuine failure (`error`) exits non-zero; an
+ * abort — the user leaving an interactive wizard — exits 0, matching the entry
+ * menu's "Exit", a project cancellation, and a confirmed Ctrl+C.
+ */
+/** @internal */
+export function setupTerminalOutcome(input) {
+    const annotation = setupCommandOutcomeAnnotation(input);
+    return { exitCode: annotation.outcome === 'error' ? 1 : 0, annotation };
+}
+async function annotateSetupCommandOutcome(annotation) {
+    const { annotateCommandOutcome } = await import('./telemetry/index.js');
+    annotateCommandOutcome(annotation);
+}
 async function recordSetupStep(input) {
     const { emitTelemetryEvent } = await import('./telemetry/index.js');
     await emitTelemetryEvent({
@@ -325,6 +381,10 @@ async function runKtxSetupInner(args, io, deps = {}) {
         args.inputMode !== 'disabled' &&
         !args.agents &&
         (io.stdout.isTTY === true || deps.entryMenuDeps?.prompts !== undefined);
+    // A prompt is only possible when input is enabled AND a TTY is attached. A
+    // piped/CI `ktx setup` without `--no-input` is still `inputMode: 'auto'` but
+    // cannot prompt, so its `missing-input` is an automation error, not an abort.
+    const interactive = args.inputMode !== 'disabled' && io.stdout.isTTY === true;
     setupLoop: while (true) {
         entryAction = undefined;
         if (canShowEntryMenu) {
@@ -363,7 +423,13 @@ async function runKtxSetupInner(args, io, deps = {}) {
             continue;
         }
         if (projectResult.status !== 'ready') {
-            return projectResult.status === 'cancelled' ? 0 : 1;
+            const terminal = setupTerminalOutcome({
+                status: projectResult.status,
+                step: 'project',
+                interactive,
+            });
+            await annotateSetupCommandOutcome(terminal.annotation);
+            return terminal.exitCode;
         }
         const agentsRequested = args.agents || entryAction === 'agents';
         const currentStatus = await readKtxSetupStatus(projectResult.projectDir, { cliVersion: args.cliVersion });
@@ -576,11 +642,15 @@ async function runKtxSetupInner(args, io, deps = {}) {
                 cliVersion: args.cliVersion,
                 ...(stepResult.errorDetail ? { errorDetail: stepResult.errorDetail } : {}),
             });
-            if (stepResult.status === 'failed') {
-                return 1;
-            }
-            if (stepResult.status === 'missing-input') {
-                return 1;
+            if (stepResult.status === 'failed' || stepResult.status === 'missing-input') {
+                const terminal = setupTerminalOutcome({
+                    status: stepResult.status,
+                    step,
+                    interactive,
+                    ...(stepResult.errorDetail ? { errorDetail: stepResult.errorDetail } : {}),
+                });
+                await annotateSetupCommandOutcome(terminal.annotation);
+                return terminal.exitCode;
             }
             if (stepResult.status === 'back') {
                 const previousIndex = previousNavigableStepIndex(stepIndex);
@@ -630,5 +700,6 @@ async function runKtxSetupInner(args, io, deps = {}) {
             }).join('\n'), 'What you can do next', io);
         }
     }
+    setupUi.note(SLACK_SETUP_NOTE.body, SLACK_SETUP_NOTE.title, io);
     return 0;
 }

package/dist/telemetry/command-hook.d.ts

@@ -6,6 +6,9 @@ interface CommandSpan {
     hasProject: boolean;
     attachProjectGroup: boolean;
     startedAt: number;
+    annotatedOutcome?: CommandOutcome;
+    annotatedErrorClass?: string;
+    annotatedErrorDetail?: string;
 }
 export interface CompletedCommandSpan {
     commandPath: string[];
@@ -19,6 +22,27 @@ export interface CompletedCommandSpan {
     projectGroupAttached: boolean;
 }
 export declare function beginCommandSpan(input: CommandSpan): void;
+/**
+ * Let a command action record the true outcome and reason on the active span.
+ *
+ * The Commander wrapper can only derive an outcome from a thrown error or the
+ * process exit code, so a command that exits non-zero *without throwing* (e.g.
+ * `ktx setup` when the user abandons the wizard) lands as `outcome: 'error'`
+ * with no `errorClass`/`errorDetail` — an unactionable blank in the dashboard.
+ * The action is the decision-maker: it can mark the run `aborted`, or attach a
+ * scrubbed reason so the next occurrence is self-diagnosing. A later thrown
+ * error still wins (see {@link completeCommandSpan}), since that is the most
+ * authoritative signal and also feeds the `$exception` stream. No-ops when no
+ * span is active so call sites stay safe in tests and bare-help paths.
+ *
+ * Values are emitted verbatim and must already satisfy the telemetry privacy
+ * rules — pass synthetic or already-scrubbed strings, never raw user input.
+ */
+export declare function annotateCommandOutcome(input: {
+    outcome?: CommandOutcome;
+    errorClass?: string;
+    errorDetail?: string;
+}): void;
 export declare function completeCommandSpan(input: {
     completedAt: number;
     outcome: CommandOutcome;

package/dist/telemetry/command-hook.js

@@ -3,18 +3,52 @@ let activeCommandSpan;
 export function beginCommandSpan(input) {
     activeCommandSpan = input;
 }
+/**
+ * Let a command action record the true outcome and reason on the active span.
+ *
+ * The Commander wrapper can only derive an outcome from a thrown error or the
+ * process exit code, so a command that exits non-zero *without throwing* (e.g.
+ * `ktx setup` when the user abandons the wizard) lands as `outcome: 'error'`
+ * with no `errorClass`/`errorDetail` — an unactionable blank in the dashboard.
+ * The action is the decision-maker: it can mark the run `aborted`, or attach a
+ * scrubbed reason so the next occurrence is self-diagnosing. A later thrown
+ * error still wins (see {@link completeCommandSpan}), since that is the most
+ * authoritative signal and also feeds the `$exception` stream. No-ops when no
+ * span is active so call sites stay safe in tests and bare-help paths.
+ *
+ * Values are emitted verbatim and must already satisfy the telemetry privacy
+ * rules — pass synthetic or already-scrubbed strings, never raw user input.
+ */
+export function annotateCommandOutcome(input) {
+    if (!activeCommandSpan) {
+        return;
+    }
+    if (input.outcome !== undefined) {
+        activeCommandSpan.annotatedOutcome = input.outcome;
+    }
+    if (input.errorClass !== undefined) {
+        activeCommandSpan.annotatedErrorClass = input.errorClass;
+    }
+    if (input.errorDetail !== undefined) {
+        activeCommandSpan.annotatedErrorDetail = input.errorDetail;
+    }
+}
 export function completeCommandSpan(input) {
     const span = activeCommandSpan;
     activeCommandSpan = undefined;
     if (!span) {
         return undefined;
     }
-    const errorClass = input.error ? scrubErrorClass(input.error) : undefined;
-    const errorDetail = input.error ? formatErrorDetail(input.error) : undefined;
+    // Precedence: a thrown error is authoritative; otherwise an action's own
+    // annotation; otherwise the wrapper's exit-code-derived outcome.
+    const thrown = Boolean(input.error);
+    const outcome = thrown ? input.outcome : (span.annotatedOutcome ?? input.outcome);
+    const errorClass = thrown ? scrubErrorClass(input.error) : span.annotatedErrorClass;
+    const errorDetail = thrown ? formatErrorDetail(input.error) : span.annotatedErrorDetail;
     return {
         commandPath: span.commandPath,
         durationMs: Math.max(0, input.completedAt - span.startedAt),
-        outcome: input.outcome,
+        outcome,
         ...(errorClass ? { errorClass } : {}),
         ...(errorDetail ? { errorDetail } : {}),
         flagsPresent: span.flagsPresent,

package/dist/telemetry/index.d.ts

@@ -1,9 +1,9 @@
 import { type KtxCliIo, type KtxCliPackageInfo } from '../cli-runtime.js';
-import { beginCommandSpan, completeCommandSpan, type CommandOutcome, type CompletedCommandSpan } from './command-hook.js';
+import { annotateCommandOutcome, beginCommandSpan, completeCommandSpan, type CommandOutcome, type CompletedCommandSpan } from './command-hook.js';
 import { shutdownTelemetryEmitter } from './emitter.js';
 import { reportException, type ExceptionContext } from './exception.js';
 import { type TelemetryCommonEnvelope, type TelemetryEventName, type TelemetryEventProperties } from './events.js';
-export { beginCommandSpan, completeCommandSpan, reportException, shutdownTelemetryEmitter };
+export { annotateCommandOutcome, beginCommandSpan, completeCommandSpan, reportException, shutdownTelemetryEmitter };
 export type { CommandOutcome, CompletedCommandSpan, ExceptionContext };
 export declare function showTelemetryNoticeIfNeeded(io: KtxCliIo, packageInfo: KtxCliPackageInfo): Promise<void>;
 type TelemetryEventFields<Name extends TelemetryEventName> = Omit<TelemetryEventProperties<Name>, keyof TelemetryCommonEnvelope>;

package/dist/telemetry/index.js

@@ -1,12 +1,12 @@
 import { getKtxCliPackageInfo } from '../cli-runtime.js';
 import { loadKtxProject } from '../context/project/project.js';
-import { beginCommandSpan, completeCommandSpan, } from './command-hook.js';
+import { annotateCommandOutcome, beginCommandSpan, completeCommandSpan, } from './command-hook.js';
 import { shutdownTelemetryEmitter, trackTelemetryEvent } from './emitter.js';
 import { reportException } from './exception.js';
 import { buildCommonEnvelope, buildTelemetryEvent, } from './events.js';
 import { computeTelemetryProjectId, loadTelemetryIdentity } from './identity.js';
 import { buildProjectStackSnapshotFields } from './project-snapshot.js';
-export { beginCommandSpan, completeCommandSpan, reportException, shutdownTelemetryEmitter };
+export { annotateCommandOutcome, beginCommandSpan, completeCommandSpan, reportException, shutdownTelemetryEmitter };
 export async function showTelemetryNoticeIfNeeded(io, packageInfo) {
     const identity = await loadTelemetryIdentity({
         stderr: io.stderr,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaelio/ktx",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Standalone ktx context layer for data agents",
   "author": {
     "name": "Kaelio",