@kaelio/ktx 0.6.0 → 0.8.0

package/dist/context/ingest/ingest-bundle.runner.js

@@ -13,6 +13,7 @@ import { selectRelevantCanonicalPins } from './canonical-pins.js';
 import { finalGateRepairPaths, repairFinalGateFailure } from './final-gate-repair.js';
 import { compareFinalizationDeclarations, deriveFinalizationTouchedSources, deriveFinalizationWikiPageKeys, } from './finalization-scope.js';
 import { FileIngestTraceWriter, ingestTracePathForJob, traceTimed } from './ingest-trace.js';
+import { formatIngestProfile, formatIngestProfileJson, readIngestProfile, resolveIngestProfileMode } from './ingest-profile.js';
 import { integrateWorkUnitPatch } from './isolated-diff/patch-integrator.js';
 import { resolveTextualConflict } from './isolated-diff/textual-conflict-resolver.js';
 import { runIsolatedWorkUnit } from './isolated-diff/work-unit-executor.js';
@@ -34,7 +35,7 @@ import { createEvictionListTool } from './tools/eviction-list.tool.js';
 import { createReadRawSpanTool } from './tools/read-raw-span.tool.js';
 import { createStageDiffTool } from './tools/stage-diff.tool.js';
 import { createStageListTool } from './tools/stage-list.tool.js';
-import { wrapToolsWithLogger } from './tools/tool-call-logger.js';
+import { flushToolCallLogs, wrapToolsWithLogger } from './tools/tool-call-logger.js';
 import { createMutableToolTranscriptSummary, recordToolTranscriptEntry, } from './tools/tool-transcript-summary.js';
 import { repairWikiSlRefs } from './wiki-sl-ref-repair.js';
 async function copyTransientIngestEvidence(sourceWorkdir, targetWorkdir) {
@@ -137,6 +138,36 @@ export class IngestBundleRunner {
             ctx?.memoryFlow?.finish('error', [sanitizeMemoryFlowError(error)]);
             throw error;
         }
+        finally {
+            await this.maybeEmitIngestProfile(job.jobId);
+        }
+    }
+    /**
+     * When profiling is enabled — via the `KTX_PROFILE_INGEST` env var or the
+     * `ingest.profile` config setting — read the job's trace + tool transcripts
+     * and print a rolled-up timing breakdown to stderr. `json` emits the raw
+     * structured profile for coding agents; `table` emits a human summary.
+     * Best-effort: profiling never affects the run outcome.
+     */
+    async maybeEmitIngestProfile(jobId) {
+        const mode = resolveIngestProfileMode(this.deps.settings.profileIngest);
+        if (mode === 'off') {
+            return;
+        }
+        try {
+            // Tool transcripts are appended fire-and-forget; flush them so per-work-unit
+            // toolMs (and the derived model-vs-tool split) is complete before we read.
+            await flushToolCallLogs();
+            const storage = this.deps.storage;
+            const profile = await readIngestProfile(jobId, {
+                tracePath: storage.resolveTracePath?.(jobId) ?? ingestTracePathForJob(this.deps.storage.homeDir, jobId),
+                transcriptDir: this.deps.storage.resolveTranscriptDir(jobId),
+            });
+            process.stderr.write(`\n${mode === 'json' ? formatIngestProfileJson(profile) : formatIngestProfile(profile)}`);
+        }
+        catch (error) {
+            this.logger.warn(`[ingest-bundle] ingest profile unavailable for job=${jobId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
     stageRawFilesStage1 = stageRawFilesStage1;
     async syncKnowledgeSlRefsFromActions(connectionId, actions) {
@@ -789,7 +820,7 @@ export class IngestBundleRunner {
                 }));
             const fetchReport = adapter.readFetchReport ? await adapter.readFetchReport(stagedDir) : null;
             const scopeDescriptor = adapter.describeScope ? await adapter.describeScope(stagedDir) : null;
-            const sessionWorktree = await this.deps.lockingService.withLock('config:repo', () => this.deps.sessionWorktreeService.create(job.jobId, baseSha));
+            const sessionWorktree = await traceTimed(trace, 'worktree', 'session_worktree_created', { jobId: job.jobId }, () => this.deps.lockingService.withLock('config:repo', () => this.deps.sessionWorktreeService.create(job.jobId, baseSha)));
             let cleanupOutcome = 'crash';
             try {
                 activePhase = 'stage_raw_files';
@@ -916,26 +947,26 @@ export class IngestBundleRunner {
                     sourceContextReport = chunk.contextReport;
                     parseArtifacts = chunk.parseArtifacts;
                     reconcileNotes = chunk.reconcileNotes ?? [];
+                    const pageTriage = this.deps.pageTriage;
+                    const triageRunId = runRow.id;
                     triageResult =
-                        contextReport && adapter.triageSupported && this.deps.pageTriage
-                            ? await this.deps.pageTriage.triageRun({
+                        contextReport && adapter.triageSupported && pageTriage
+                            ? await traceTimed(runTrace, 'triage', 'page_triage', { sourceKey: job.sourceKey }, () => pageTriage.triageRun({
                                 stagedDir,
-                                runId: runRow.id,
+                                runId: triageRunId,
                                 connectionId: job.connectionId,
                                 sourceKey: job.sourceKey,
                                 syncId,
                                 jobId: job.jobId,
                                 diffSet,
                                 adapter,
-                            })
+                            }))
                             : null;
                     workUnits = this.filterWorkUnitsForTriage(workUnits, triageResult);
-                    if (adapter.clusterWorkUnits && workUnits.length > 0) {
-                        workUnits = await adapter.clusterWorkUnits({
-                            workUnits,
-                            stagedDir,
-                            embedding: this.deps.embedding,
-                        });
+                    const clusterWorkUnits = adapter.clusterWorkUnits;
+                    if (clusterWorkUnits && workUnits.length > 0) {
+                        const preClusterCount = workUnits.length;
+                        workUnits = await traceTimed(runTrace, 'clustering', 'cluster_work_units', { workUnitCount: preClusterCount }, () => clusterWorkUnits({ workUnits, stagedDir, embedding: this.deps.embedding }));
                     }
                     await stage2?.updateProgress(1.0, `Planned ${workUnits.length} update${workUnits.length === 1 ? '' : 's'}`);
                 }
@@ -968,7 +999,7 @@ export class IngestBundleRunner {
                     connectionIds: slConnectionIds,
                 });
                 // Build shared per-job context.
-                const [wikiIndex, slIndex] = await Promise.all([this.buildWikiIndex(), this.buildSlIndex(slConnectionIds)]);
+                const [wikiIndex, slIndex] = await traceTimed(runTrace, 'index_build', 'build_indexes', { connectionCount: slConnectionIds.length }, () => Promise.all([this.buildWikiIndex(), this.buildSlIndex(slConnectionIds)]));
                 const baseFraming = await this.deps.promptService.loadPrompt('memory_agent_bundle_ingest_work_unit');
                 const wuSkillNames = Array.from(new Set([...adapter.skillNames, 'ingest_triage', 'sl_capture', 'wiki_capture']));
                 const wuSkills = await this.deps.skillsRegistry.listSkills(wuSkillNames, 'memory_agent');
@@ -1420,6 +1451,8 @@ export class IngestBundleRunner {
                 let curatorReport = null;
                 let curatorWarnings = [];
                 let reconcileOutcome;
+                const reconcileStartedAt = Date.now();
+                const reconcileMode = contextReport && this.deps.curatorPagination ? 'curator' : 'single';
                 if (contextReport && this.deps.curatorPagination) {
                     const curatorOutcome = await this.deps.curatorPagination.reconcile({
                         runId: runRow.id,
@@ -1506,6 +1539,26 @@ export class IngestBundleRunner {
                             : undefined,
                     });
                 }
+                await runTrace.event('debug', 'reconciliation', 'reconciliation_executed', {
+                    mode: reconcileMode,
+                    skipped: reconcileOutcome.skipped,
+                    ...(reconcileOutcome.stopReason ? { stopReason: reconcileOutcome.stopReason } : {}),
+                    ...(reconcileOutcome.metrics
+                        ? {
+                            agentLoopMs: reconcileOutcome.metrics.totalMs,
+                            stepCount: reconcileOutcome.metrics.stepCount,
+                            ...(reconcileOutcome.metrics.usage.inputTokens !== undefined
+                                ? { inputTokens: reconcileOutcome.metrics.usage.inputTokens }
+                                : {}),
+                            ...(reconcileOutcome.metrics.usage.outputTokens !== undefined
+                                ? { outputTokens: reconcileOutcome.metrics.usage.outputTokens }
+                                : {}),
+                            ...(reconcileOutcome.metrics.usage.totalTokens !== undefined
+                                ? { totalTokens: reconcileOutcome.metrics.usage.totalTokens }
+                                : {}),
+                        }
+                        : {}),
+                }, undefined, Date.now() - reconcileStartedAt);
                 latestReconciliationSkipped = reconcileOutcome.skipped;
                 const danglingReconcileWikiRefs = await findDanglingWikiRefsForActions({
                     wikiService: rcScopedWiki,
@@ -1544,6 +1597,7 @@ export class IngestBundleRunner {
                 activePhase = 'finalization';
                 if (adapter.finalize) {
                     const stageFinalization = ctx?.startPhase(0.04);
+                    const finalizationStartedAt = Date.now();
                     emitStageProgress('finalization', 87, 'Running deterministic finalization');
                     await stageFinalization?.updateProgress(0.0, 'Running deterministic finalization');
                     await runTrace.event('debug', 'finalization', 'finalization_started', { sourceKey: job.sourceKey });
@@ -1706,7 +1760,7 @@ export class IngestBundleRunner {
                         touchedSources: finalizationTouchedSources,
                         changedWikiPageKeys: finalizationChangedWikiPageKeys,
                         warnings: result.warnings,
-                    });
+                    }, undefined, Date.now() - finalizationStartedAt);
                 }
                 else {
                     await runTrace.event('debug', 'finalization', 'finalization_skipped', { sourceKey: job.sourceKey });
@@ -1933,6 +1987,7 @@ export class IngestBundleRunner {
                 const stage6 = ctx?.startPhase(0.04);
                 emitStageProgress('save', 91, 'Saving changes');
                 await stage6?.updateProgress(0.0, 'Saving changes');
+                const squashStartedAt = Date.now();
                 try {
                     await sessionWorktree.git.assertWorktreeClean();
                 }
@@ -1955,7 +2010,7 @@ export class IngestBundleRunner {
                 await runTrace.event('debug', 'squash', 'squash_finished', {
                     commitSha,
                     touchedPaths: mergeResult.touchedPaths,
-                });
+                }, undefined, Date.now() - squashStartedAt);
                 const memoryFlowSavedActions = stageIndex.workUnits
                     .flatMap((wu) => wu.actions)
                     .concat(reconcileActions)
@@ -1971,6 +2026,7 @@ export class IngestBundleRunner {
                 // transaction. If this throws, the run fails and no partial index state
                 // survives (thanks to the transactional upsert in applyDiffTransactional).
                 if (commitSha) {
+                    const indexSyncStartedAt = Date.now();
                     // Multi-file squash → omit path so the handler diffs the whole commit
                     // (a comma-joined pathspec would match nothing and the job would no-op).
                     const pathFilter = mergeResult.touchedPaths.length === 1 ? mergeResult.touchedPaths[0] : '';
@@ -1992,6 +2048,7 @@ export class IngestBundleRunner {
                             this.logger.warn(`[ingest-bundle] post-squash SL reindex failed for connection=${connectionId}: ${err instanceof Error ? err.message : String(err)}`);
                         }
                     }
+                    await runTrace.event('debug', 'index_sync', 'post_squash_index_sync_finished', { connectionCount: touchedConnections.length }, undefined, Date.now() - indexSyncStartedAt);
                 }
                 const stage5 = ctx?.startPhase(0.04);
                 emitStageProgress('provenance', 95, 'Recording history');

package/dist/context/ingest/ingest-profile.d.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+export interface IngestProfilePaths {
+    tracePath: string;
+    transcriptDir: string;
+}
+/**
+ * Post-processor over the ingest trace (`<home>/ingest-traces/<jobId>/trace.jsonl`)
+ * and per-work-unit tool transcripts. Turns the durations recorded during a run
+ * into a rolled-up "where did the time go" view. Gated for display by
+ * `KTX_PROFILE_INGEST`; the durations themselves are always written to the trace.
+ */
+declare const traceEventSchema: z.ZodObject<{
+    at: z.ZodOptional<z.ZodString>;
+    phase: z.ZodString;
+    event: z.ZodString;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+/** @internal */
+export type ProfiledTraceEvent = z.infer<typeof traceEventSchema>;
+export interface IngestProfile {
+    jobId: string;
+    totalWallMs?: number;
+    phases: Array<{
+        phase: string;
+        totalMs: number;
+        /** Number of timed (durationMs-bearing) events that contributed to this phase. */
+        count: number;
+    }>;
+    workUnits: Array<{
+        unitKey: string;
+        status?: string;
+        /** Wall-clock for the whole work-unit run (agent loop + validation + git). */
+        totalMs?: number;
+        /** Pure `generateText` agent-loop time reported by the runtime. */
+        agentLoopMs?: number;
+        /** Summed tool-execution time from the work-unit transcript. */
+        toolMs?: number;
+        /** Derived model "thinking" time = agentLoopMs - toolMs (clamped at 0). */
+        modelMs?: number;
+        /** Worktree create time. */
+        createMs?: number;
+        /** Worktree teardown time. */
+        cleanupMs?: number;
+        stepCount?: number;
+        totalTokens?: number;
+    }>;
+    workUnitCount: number;
+    failedWorkUnitCount: number;
+    /**
+     * Plain-language diagnosis plus the raw numbers behind it, so a reader (human
+     * or coding agent) gets the conclusion without re-deriving it from the tables.
+     */
+    summary: {
+        /** One-sentence conclusion, e.g. which phase dominated and whether work was model- or tool-bound. */
+        headline: string;
+        dominantPhase?: {
+            phase: string;
+            totalMs: number;
+            pctOfWall?: number;
+        };
+        /** Aggregate across all work units, in milliseconds. */
+        workUnits?: {
+            count: number;
+            failed: number;
+            agentLoopMs: number;
+            modelMs: number;
+            toolMs: number;
+            /** Percent of agent-loop time spent in model generation vs tool execution. */
+            modelPct?: number;
+        };
+    };
+}
+/** @internal */
+export declare function parseTraceEvents(traceText: string): ProfiledTraceEvent[];
+/** @internal */
+export declare function aggregateIngestProfile(input: {
+    jobId: string;
+    events: ProfiledTraceEvent[];
+    toolMsByUnit: Record<string, number>;
+}): IngestProfile;
+/** Read the trace and tool transcripts for a job and aggregate them into a profile. */
+export declare function readIngestProfile(jobId: string, paths: IngestProfilePaths): Promise<IngestProfile>;
+/** Render a human-readable profile table for stderr / the admin command. */
+export declare function formatIngestProfile(profile: IngestProfile, options?: {
+    topWorkUnits?: number;
+}): string;
+/**
+ * Machine-readable rendering for coding agents: the full structured profile
+ * (raw milliseconds and token counts, stable keys) as a single JSON object
+ * under a stable marker line so it is easy to locate and parse in stderr.
+ */
+export declare function formatIngestProfileJson(profile: IngestProfile): string;
+export type IngestProfileMode = 'off' | 'table' | 'json';
+/**
+ * Resolve how (and whether) to emit the ingest profile, from the
+ * `ingest.profile` config value and the `KTX_PROFILE_INGEST` env var. Either
+ * source may request `json` (raw, agent-friendly) or a human `table`; `json`
+ * wins if either asks for it.
+ */
+export declare function resolveIngestProfileMode(configValue: boolean | 'json' | undefined, env?: NodeJS.ProcessEnv): IngestProfileMode;
+export {};

package/dist/context/ingest/ingest-profile.js

@@ -0,0 +1,306 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+/**
+ * Post-processor over the ingest trace (`<home>/ingest-traces/<jobId>/trace.jsonl`)
+ * and per-work-unit tool transcripts. Turns the durations recorded during a run
+ * into a rolled-up "where did the time go" view. Gated for display by
+ * `KTX_PROFILE_INGEST`; the durations themselves are always written to the trace.
+ */
+const traceEventSchema = z
+    .object({
+    at: z.string().optional(),
+    phase: z.string(),
+    event: z.string(),
+    durationMs: z.number().optional(),
+    data: z.record(z.string(), z.unknown()).optional(),
+})
+    .loose();
+function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+/** @internal */
+export function parseTraceEvents(traceText) {
+    const events = [];
+    for (const line of traceText.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        let json;
+        try {
+            json = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const parsed = traceEventSchema.safeParse(json);
+        if (parsed.success) {
+            events.push(parsed.data);
+        }
+    }
+    return events;
+}
+/** @internal */
+export function aggregateIngestProfile(input) {
+    const { jobId, events, toolMsByUnit } = input;
+    const phaseTotals = new Map();
+    const workUnits = new Map();
+    const wu = (unitKey) => {
+        let existing = workUnits.get(unitKey);
+        if (!existing) {
+            existing = { unitKey };
+            workUnits.set(unitKey, existing);
+        }
+        return existing;
+    };
+    let minAt = Number.POSITIVE_INFINITY;
+    let maxAt = Number.NEGATIVE_INFINITY;
+    for (const event of events) {
+        const at = event.at ? Date.parse(event.at) : Number.NaN;
+        if (!Number.isNaN(at)) {
+            minAt = Math.min(minAt, at);
+            maxAt = Math.max(maxAt, at);
+        }
+        if (event.durationMs !== undefined) {
+            const bucket = phaseTotals.get(event.phase) ?? { totalMs: 0, count: 0 };
+            bucket.totalMs += event.durationMs;
+            bucket.count += 1;
+            phaseTotals.set(event.phase, bucket);
+        }
+        const data = event.data ?? {};
+        const unitKey = asString(data.unitKey);
+        if (unitKey) {
+            const entry = wu(unitKey);
+            if (event.event === 'work_unit_executed') {
+                entry.totalMs = event.durationMs;
+                entry.agentLoopMs = asNumber(data.agentLoopMs);
+                entry.stepCount = asNumber(data.stepCount);
+                entry.totalTokens = asNumber(data.totalTokens);
+                entry.status = asString(data.status) ?? entry.status;
+            }
+            else if (event.event === 'work_unit_child_created') {
+                entry.createMs = event.durationMs;
+            }
+            else if (event.event === 'work_unit_child_cleanup') {
+                entry.cleanupMs = event.durationMs;
+            }
+            else if (event.event === 'work_unit_failed_before_patch') {
+                entry.status = entry.status ?? 'failed';
+            }
+        }
+    }
+    for (const [unitKey, entry] of workUnits) {
+        const toolMs = toolMsByUnit[unitKey];
+        if (toolMs !== undefined) {
+            entry.toolMs = toolMs;
+            if (entry.agentLoopMs !== undefined) {
+                entry.modelMs = Math.max(0, entry.agentLoopMs - toolMs);
+            }
+        }
+        else if (entry.agentLoopMs !== undefined) {
+            entry.modelMs = entry.agentLoopMs;
+        }
+    }
+    const phases = [...phaseTotals.entries()]
+        .map(([phase, { totalMs, count }]) => ({ phase, totalMs, count }))
+        .sort((a, b) => b.totalMs - a.totalMs);
+    const workUnitList = [...workUnits.values()].sort((a, b) => (b.totalMs ?? 0) - (a.totalMs ?? 0));
+    const totalWallMs = Number.isFinite(minAt) && Number.isFinite(maxAt) && maxAt >= minAt ? maxAt - minAt : undefined;
+    const failedWorkUnitCount = workUnitList.filter((entry) => entry.status === 'failed').length;
+    return {
+        jobId,
+        ...(totalWallMs !== undefined ? { totalWallMs } : {}),
+        phases,
+        workUnits: workUnitList,
+        workUnitCount: workUnitList.length,
+        failedWorkUnitCount,
+        summary: buildSummary(phases, workUnitList, failedWorkUnitCount, totalWallMs),
+    };
+}
+function buildSummary(phases, workUnits, failed, totalWallMs) {
+    const dominant = phases[0];
+    const dominantPhase = dominant
+        ? {
+            phase: dominant.phase,
+            totalMs: dominant.totalMs,
+            ...(totalWallMs && totalWallMs > 0
+                ? { pctOfWall: Math.round((dominant.totalMs / totalWallMs) * 100) }
+                : {}),
+        }
+        : undefined;
+    const agentLoopMs = workUnits.reduce((sum, wu) => sum + (wu.agentLoopMs ?? 0), 0);
+    const toolMs = workUnits.reduce((sum, wu) => sum + (wu.toolMs ?? 0), 0);
+    const modelMs = workUnits.reduce((sum, wu) => sum + (wu.modelMs ?? 0), 0);
+    const workUnitAggregate = workUnits.length > 0
+        ? {
+            count: workUnits.length,
+            failed,
+            agentLoopMs,
+            modelMs,
+            toolMs,
+            ...(agentLoopMs > 0 ? { modelPct: Math.round((modelMs / agentLoopMs) * 100) } : {}),
+        }
+        : undefined;
+    const parts = [];
+    if (dominantPhase) {
+        const pct = dominantPhase.pctOfWall !== undefined ? `, ${dominantPhase.pctOfWall}% of wall time` : '';
+        parts.push(`Slowest phase: ${dominantPhase.phase} (${formatMs(dominantPhase.totalMs)}${pct})`);
+    }
+    if (workUnitAggregate) {
+        const split = workUnitAggregate.modelPct !== undefined
+            ? `, ~${workUnitAggregate.modelPct}% model generation vs ~${100 - workUnitAggregate.modelPct}% tools`
+            : '';
+        parts.push(`${workUnitAggregate.count} work unit${workUnitAggregate.count === 1 ? '' : 's'}${failed > 0 ? ` (${failed} failed)` : ''}${split}`);
+    }
+    const headline = parts.length > 0 ? parts.join('. ') + '.' : 'No timed phases recorded.';
+    return {
+        headline,
+        ...(dominantPhase ? { dominantPhase } : {}),
+        ...(workUnitAggregate ? { workUnits: workUnitAggregate } : {}),
+    };
+}
+/** Read the trace and tool transcripts for a job and aggregate them into a profile. */
+export async function readIngestProfile(jobId, paths) {
+    const traceText = await readFile(paths.tracePath, 'utf-8');
+    const events = parseTraceEvents(traceText);
+    const toolMsByUnit = await readToolMsByUnit(paths.transcriptDir);
+    return aggregateIngestProfile({ jobId, events, toolMsByUnit });
+}
+async function listTranscriptFiles(dir) {
+    // Work-unit keys can contain slashes (e.g. "cards/marketing"), so the runner
+    // writes nested transcript files (".../cards/marketing.jsonl"). Walk
+    // recursively and bucket by the `wuKey` field inside each entry rather than
+    // by file name.
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => null);
+    if (!entries) {
+        return [];
+    }
+    const files = [];
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listTranscriptFiles(full)));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.jsonl')) {
+            files.push(full);
+        }
+    }
+    return files;
+}
+async function readToolMsByUnit(transcriptDir) {
+    const toolMs = {};
+    for (const file of await listTranscriptFiles(transcriptDir)) {
+        let text;
+        try {
+            text = await readFile(file, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed) {
+                continue;
+            }
+            try {
+                const entry = JSON.parse(trimmed);
+                const wuKey = asString(entry.wuKey);
+                const ms = asNumber(entry.durationMs);
+                if (wuKey && ms !== undefined) {
+                    toolMs[wuKey] = (toolMs[wuKey] ?? 0) + ms;
+                }
+            }
+            catch {
+                // skip malformed line
+            }
+        }
+    }
+    return toolMs;
+}
+function formatMs(ms) {
+    if (ms === undefined) {
+        return '—';
+    }
+    if (ms < 1000) {
+        return `${Math.round(ms)}ms`;
+    }
+    const seconds = ms / 1000;
+    if (seconds < 60) {
+        return `${seconds.toFixed(1)}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const rem = Math.round(seconds - minutes * 60);
+    return `${minutes}m ${String(rem).padStart(2, '0')}s`;
+}
+function formatTokens(tokens) {
+    if (tokens === undefined) {
+        return '—';
+    }
+    if (tokens < 1000) {
+        return String(tokens);
+    }
+    return `${(tokens / 1000).toFixed(1)}k`;
+}
+function pad(value, width) {
+    return value.length >= width ? value : value + ' '.repeat(width - value.length);
+}
+function padStart(value, width) {
+    return value.length >= width ? value : ' '.repeat(width - value.length) + value;
+}
+/** Render a human-readable profile table for stderr / the admin command. */
+export function formatIngestProfile(profile, options = {}) {
+    const topWorkUnits = options.topWorkUnits ?? 10;
+    const lines = [];
+    lines.push(`ktx ingest profile — job ${profile.jobId}`);
+    if (profile.totalWallMs !== undefined) {
+        lines.push(`  total wall time: ${formatMs(profile.totalWallMs)}`);
+    }
+    lines.push(`  ${profile.summary.headline}`);
+    const wall = profile.totalWallMs;
+    lines.push('');
+    lines.push('  Phase breakdown (by total duration):');
+    if (profile.phases.length === 0) {
+        lines.push('    (no timed phases recorded)');
+    }
+    for (const phase of profile.phases) {
+        const pct = wall && wall > 0 ? `(${((phase.totalMs / wall) * 100).toFixed(1)}%)` : '';
+        lines.push(`    ${pad(phase.phase, 22)}${padStart(formatMs(phase.totalMs), 9)}  ${padStart(pct, 8)}  ${padStart(String(phase.count), 4)} event${phase.count === 1 ? '' : 's'}`);
+    }
+    if (profile.workUnits.length > 0) {
+        lines.push('');
+        lines.push(`  Work units (top ${Math.min(topWorkUnits, profile.workUnits.length)} slowest):`);
+        lines.push(`    ${pad('unitKey', 30)}${padStart('total', 9)}${padStart('model', 9)}${padStart('tool', 9)}${padStart('steps', 8)}${padStart('tokens', 9)}  status`);
+        for (const entry of profile.workUnits.slice(0, topWorkUnits)) {
+            const steps = entry.stepCount !== undefined ? String(entry.stepCount) : '—';
+            lines.push(`    ${pad(entry.unitKey.slice(0, 30), 30)}${padStart(formatMs(entry.totalMs), 9)}${padStart(formatMs(entry.modelMs), 9)}${padStart(formatMs(entry.toolMs), 9)}${padStart(steps, 8)}${padStart(formatTokens(entry.totalTokens), 9)}  ${entry.status ?? '—'}`);
+        }
+        lines.push(`    (${profile.workUnitCount} work unit${profile.workUnitCount === 1 ? '' : 's'} total; ${profile.failedWorkUnitCount} failed)`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Machine-readable rendering for coding agents: the full structured profile
+ * (raw milliseconds and token counts, stable keys) as a single JSON object
+ * under a stable marker line so it is easy to locate and parse in stderr.
+ */
+export function formatIngestProfileJson(profile) {
+    return `ktx ingest profile (json)\n${JSON.stringify(profile, null, 2)}\n`;
+}
+/**
+ * Resolve how (and whether) to emit the ingest profile, from the
+ * `ingest.profile` config value and the `KTX_PROFILE_INGEST` env var. Either
+ * source may request `json` (raw, agent-friendly) or a human `table`; `json`
+ * wins if either asks for it.
+ */
+export function resolveIngestProfileMode(configValue, env = process.env) {
+    const envValue = env.KTX_PROFILE_INGEST;
+    if (configValue === 'json' || envValue === 'json') {
+        return 'json';
+    }
+    const wantsTable = configValue === true || envValue === '1' || envValue === 'true' || envValue === 'table';
+    return wantsTable ? 'table' : 'off';
+}

package/dist/context/ingest/isolated-diff/work-unit-executor.js

@@ -8,15 +8,37 @@ function patchFileName(unitIndex, unitKey) {
 export async function runIsolatedWorkUnit(input) {
     const sessionKey = `${input.trace.context.jobId}-${input.workUnit.unitKey}`;
     let cleanupOutcome = 'crash';
+    const createStartedAt = Date.now();
     const child = await input.sessionWorktreeService.create(sessionKey, input.ingestionBaseSha);
     await input.trace.event('debug', 'work_unit', 'work_unit_child_created', {
         unitKey: input.workUnit.unitKey,
         unitIndex: input.unitIndex,
         worktreePath: child.workdir,
         baseSha: input.ingestionBaseSha,
-    });
+    }, undefined, Date.now() - createStartedAt);
     try {
+        const runStartedAt = Date.now();
         const outcome = await input.run(child);
+        await input.trace.event('debug', 'work_unit', 'work_unit_executed', {
+            unitKey: input.workUnit.unitKey,
+            unitIndex: input.unitIndex,
+            status: outcome.status,
+            ...(outcome.metrics
+                ? {
+                    agentLoopMs: outcome.metrics.totalMs,
+                    stepCount: outcome.metrics.stepCount,
+                    ...(outcome.metrics.usage.inputTokens !== undefined
+                        ? { inputTokens: outcome.metrics.usage.inputTokens }
+                        : {}),
+                    ...(outcome.metrics.usage.outputTokens !== undefined
+                        ? { outputTokens: outcome.metrics.usage.outputTokens }
+                        : {}),
+                    ...(outcome.metrics.usage.totalTokens !== undefined
+                        ? { totalTokens: outcome.metrics.usage.totalTokens }
+                        : {}),
+                }
+                : {}),
+        }, undefined, Date.now() - runStartedAt);
         if (outcome.status !== 'success') {
             cleanupOutcome = 'success';
             await input.trace.event('error', 'work_unit', 'work_unit_failed_before_patch', {
@@ -51,11 +73,12 @@ export async function runIsolatedWorkUnit(input) {
         throw error;
     }
     finally {
+        const cleanupStartedAt = Date.now();
         await input.sessionWorktreeService.cleanup(child, cleanupOutcome);
         await input.trace.event('trace', 'work_unit', 'work_unit_child_cleanup', {
             unitKey: input.workUnit.unitKey,
             outcome: cleanupOutcome,
             worktreePath: child.workdir,
-        });
+        }, undefined, Date.now() - cleanupStartedAt);
     }
 }

package/dist/context/ingest/local-bundle-runtime.js

@@ -574,6 +574,7 @@ export function createLocalBundleIngestRuntime(options) {
             workUnitMaxConcurrency: options.project.config.ingest.workUnits.maxConcurrency,
             workUnitStepBudget: options.project.config.ingest.workUnits.stepBudget,
             workUnitFailureMode: options.project.config.ingest.workUnits.failureMode,
+            profileIngest: options.project.config.ingest.profile,
             ingestTraceLevel: ingestTraceLevelFromEnv(),
         },
         skillsRegistry: new SkillsRegistryService({ skillsDir, logger }),

package/dist/context/ingest/local-ingest.d.ts

@@ -67,7 +67,7 @@ export interface LocalMetabaseFanoutProgress {
         metabaseDatabaseId: number;
         targetConnectionId: string;
         jobId: string;
-        status: 'done' | 'failed';
+        status: 'done' | 'partial' | 'failed';
     }): void;
 }
 export interface RunLocalMetabaseIngestOptions extends Omit<RunLocalIngestOptions, 'adapter' | 'connectionId' | 'sourceDir' | 'jobId'> {