@kaelio/ktx 0.8.0 → 0.10.0

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

@@ -115,6 +115,10 @@ export class IngestBundleRunner {
         this.logger = deps.logger ?? noopLogger;
     }
     async run(job, ctx) {
+        const unsubscribeRateLimitGovernor = this.subscribeRateLimitGovernor({
+            trace: this.createTrace(job),
+            memoryFlow: ctx?.memoryFlow,
+        });
         const key = job.connectionId;
         const previous = this.chainByConnection.get(key);
         if (previous) {
@@ -139,9 +143,64 @@ export class IngestBundleRunner {
             throw error;
         }
         finally {
+            unsubscribeRateLimitGovernor();
             await this.maybeEmitIngestProfile(job.jobId);
         }
     }
+    formatRateLimitWait(state) {
+        const seconds = Math.ceil(state.remainingMs / 1_000);
+        const minutes = Math.floor(seconds / 60);
+        const remainder = seconds % 60;
+        const duration = minutes > 0 ? `${minutes}m${String(remainder).padStart(2, '0')}s` : `${seconds}s`;
+        const type = state.rateLimitType ? ` ${state.rateLimitType}` : '';
+        return `Rate-limited (${state.provider}${type}); resuming in ${duration}; Ctrl+C to stop`;
+    }
+    subscribeRateLimitGovernor(input) {
+        const governor = this.deps.settings.rateLimitGovernor;
+        if (!governor) {
+            return () => undefined;
+        }
+        return governor.subscribe((state) => {
+            if (state.kind === 'rate_limit_observed') {
+                void input.trace.event('info', 'rate_limit', 'rate_limit_observed', { ...state });
+                return;
+            }
+            if (state.kind === 'concurrency_adjusted') {
+                void input.trace.event('info', 'rate_limit', 'concurrency_adjusted', { ...state });
+                return;
+            }
+            void input.trace.event('info', 'rate_limit', state.kind, { ...state });
+            if (state.kind === 'wait_tick' || state.kind === 'wait_started') {
+                input.memoryFlow?.emit({
+                    type: 'rate_limit_wait',
+                    provider: state.provider,
+                    ...(state.rateLimitType ? { rateLimitType: state.rateLimitType } : {}),
+                    resumeAtMs: state.resumeAtMs,
+                    remainingMs: state.remainingMs,
+                });
+                input.memoryFlow?.emit({
+                    type: 'stage_progress',
+                    stage: 'integration',
+                    percent: 50,
+                    message: this.formatRateLimitWait(state),
+                    transient: true,
+                });
+            }
+        });
+    }
+    async withRateLimitWorkSlot(abortSignal, fn) {
+        const governor = this.deps.settings.rateLimitGovernor;
+        if (!governor) {
+            return fn();
+        }
+        const release = await governor.acquireWorkSlot(abortSignal);
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    }
     /**
      * When profiling is enabled — via the `KTX_PROFILE_INGEST` env var or the
      * `ingest.profile` config setting — read the job's trace + tool transcripts
@@ -711,7 +770,6 @@ export class IngestBundleRunner {
             type: 'work_unit_started',
             unitKey: input.wu.unitKey,
             skills: input.wuSkillNames,
-            stepBudget: input.workUnitSettings.stepBudget,
         });
         return executeWorkUnit({
             sessionWorktreeGit: input.worktree.git,
@@ -731,14 +789,30 @@ export class IngestBundleRunner {
                 slIndex: input.slIndex,
                 priorProvenance: input.priorProvenance,
             }),
-            buildToolSet: (wuInner) => wrapToolsWithLogger(buildWuToolSet({
-                sourceKey: input.job.sourceKey,
-                stagedDir: input.stagedDir,
-                wu: wuInner,
-                loadSkillTool,
-                emitUnmappedFallbackTool: wuEmitUnmappedFallbackTool,
-                toolsetTools: wuToolset.toRuntimeTools(wuToolContext),
-            }), join(input.transcriptDir, `${wuInner.unitKey}.jsonl`), wuInner.unitKey, { onEntry: input.recordTranscriptEntry(join(input.transcriptDir, `${wuInner.unitKey}.jsonl`)) }),
+            buildToolSet: (wuInner) => {
+                const transcriptPath = join(input.transcriptDir, `${wuInner.unitKey}.jsonl`);
+                const record = input.recordTranscriptEntry(transcriptPath);
+                return wrapToolsWithLogger(buildWuToolSet({
+                    sourceKey: input.job.sourceKey,
+                    stagedDir: input.stagedDir,
+                    wu: wuInner,
+                    loadSkillTool,
+                    emitUnmappedFallbackTool: wuEmitUnmappedFallbackTool,
+                    toolsetTools: wuToolset.toRuntimeTools(wuToolContext),
+                }), transcriptPath, wuInner.unitKey, {
+                    // Drive the live HUD heartbeat from real tool calls: each invocation
+                    // ticks the running per-unit count. This is an observed signal, not a
+                    // re-derived turn count, so it can never overshoot a budget.
+                    onEntry: (entry) => {
+                        const summary = record(entry);
+                        input.memoryFlow?.emit({
+                            type: 'work_unit_step',
+                            unitKey: wuInner.unitKey,
+                            toolCalls: summary.toolCallCount,
+                        });
+                    },
+                });
+            },
             captureSession: session,
             sessionActions,
             modelRole: 'candidateExtraction',
@@ -747,7 +821,7 @@ export class IngestBundleRunner {
             connectionId: input.job.connectionId,
             jobId: input.job.jobId,
             toolFailureCount: (unitKey) => input.transcriptSummaries.get(unitKey)?.fatalErrorCount ?? 0,
-            onStepFinish: input.onStepFinish,
+            abortSignal: input.abortSignal,
         }, input.wu);
     }
     async runInner(job, ctx) {
@@ -797,6 +871,7 @@ export class IngestBundleRunner {
                 const current = transcriptSummaries.get(entry.wuKey) ?? createMutableToolTranscriptSummary(entry.wuKey, path);
                 recordToolTranscriptEntry(current, entry);
                 transcriptSummaries.set(entry.wuKey, current);
+                return current;
             };
             const overrideReport = await this.loadOverrideReport(job);
             const stage1 = ctx?.startPhase(0.08);
@@ -1111,7 +1186,7 @@ export class IngestBundleRunner {
                         await stage3?.updateProgress(1.0, '0 of 0 work units complete');
                     }
                     try {
-                        await Promise.all(workUnits.map((wu, index) => limitWorkUnit(async () => {
+                        await Promise.all(workUnits.map((wu, index) => limitWorkUnit(() => this.withRateLimitWorkSlot(ctx?.abortSignal, async () => {
                             const outcome = await runIsolatedWorkUnit({
                                 unitIndex: index,
                                 ingestionBaseSha,
@@ -1119,6 +1194,7 @@ export class IngestBundleRunner {
                                 patchDir,
                                 trace: runTrace,
                                 workUnit: wu,
+                                abortSignal: ctx?.abortSignal,
                                 afterSuccess: (child) => copyTransientIngestEvidence(child.workdir, sessionWorktree.workdir),
                                 run: async (child) => {
                                     const scopedWikiService = this.deps.wikiService.forWorktree(child.workdir);
@@ -1147,11 +1223,9 @@ export class IngestBundleRunner {
                                         stageIndex,
                                         includeContextEvidenceTools: adapter.evidenceIndexing === 'documents' && !!contextReport,
                                         currentTableExists: (tableRef) => this.tableRefExistsInSemanticLayer(scopedSemanticLayerService, slConnectionIds, tableRef),
+                                        abortSignal: ctx?.abortSignal,
                                         memoryFlow,
                                         wuSkillNames,
-                                        onStepFinish: ({ stepIndex, stepBudget }) => {
-                                            memoryFlow?.emit({ type: 'work_unit_step', unitKey: wu.unitKey, stepIndex, stepBudget });
-                                        },
                                     });
                                 },
                             });
@@ -1173,7 +1247,7 @@ export class IngestBundleRunner {
                             });
                             completedWorkUnits += 1;
                             await stage3?.updateProgress(completedWorkUnits / workUnits.length, `${completedWorkUnits} of ${workUnits.length} work units complete`);
-                        })));
+                        }))));
                     }
                     catch (error) {
                         await this.deps.runs.markFailed(runRow.id);
@@ -1250,6 +1324,7 @@ export class IngestBundleRunner {
                                     reason: context.reason,
                                     maxAttempts: 1,
                                     stepBudget: 12,
+                                    abortSignal: ctx?.abortSignal,
                                 });
                                 emitStageProgress('integration', 82, result.status === 'repaired'
                                     ? `Resolved text conflict for ${context.unitKey}`
@@ -1267,6 +1342,7 @@ export class IngestBundleRunner {
                                     repairKind: 'patch_semantic_gate',
                                     maxAttempts: 1,
                                     stepBudget: 16,
+                                    abortSignal: ctx?.abortSignal,
                                 });
                                 emitStageProgress('integration', 83, result.status === 'repaired'
                                     ? `Repaired semantic gate for ${context.unitKey}`
@@ -1451,6 +1527,37 @@ export class IngestBundleRunner {
                 let curatorReport = null;
                 let curatorWarnings = [];
                 let reconcileOutcome;
+                // Reconcile shares the work-unit liveness model: the HUD heartbeat is driven
+                // by real tool calls (a monotonic, observed count), not a re-derived turn
+                // counter. The soft cap only paces the phase progress bar; it is never shown
+                // to the user, so it cannot read as a misleading "X/Y" fraction.
+                const reconcileTranscriptPath = join(transcriptDir, 'reconcile.jsonl');
+                const reconcileProgressSoftCap = 40;
+                const buildReconcileToolSetWithHeartbeat = () => {
+                    const record = recordTranscriptEntry(reconcileTranscriptPath);
+                    return wrapToolsWithLogger(buildReconcileToolSet({
+                        loadSkillTool: rcLoadSkill,
+                        stageListTool: rcStageListTool,
+                        stageDiffTool: rcStageDiffTool,
+                        evictionListTool: rcEvictionListTool,
+                        emitConflictResolutionTool: rcEmitConflictResolutionTool,
+                        emitEvictionDecisionTool: rcEmitEvictionDecisionTool,
+                        emitArtifactResolutionTool: rcEmitArtifactResolutionTool,
+                        emitUnmappedFallbackTool: rcEmitUnmappedFallbackTool,
+                        readRawSpanTool: rcRawSpanTool,
+                        toolsetTools: rcToolset.toRuntimeTools(rcToolContext),
+                    }), reconcileTranscriptPath, 'reconcile', {
+                        onEntry: (entry) => {
+                            const summary = record(entry);
+                            if (!stage4) {
+                                return;
+                            }
+                            const label = `Reconciling results · ${summary.toolCallCount} action${summary.toolCallCount === 1 ? '' : 's'}`;
+                            emitStageProgress('reconciliation', 85, label, { transient: true });
+                            void stage4.updateProgress(Math.min(0.95, summary.toolCallCount / reconcileProgressSoftCap), label);
+                        },
+                    });
+                };
                 const reconcileStartedAt = Date.now();
                 const reconcileMode = contextReport && this.deps.curatorPagination ? 'curator' : 'single';
                 if (contextReport && this.deps.curatorPagination) {
@@ -1471,25 +1578,9 @@ export class IngestBundleRunner {
                             canonicalPins: relevantCanonicalPins,
                         }),
                         buildUserPrompt: ({ summary, items, runState }) => buildReconcileUserPrompt(stageIndex, eviction, { summary, items }, reconcileNotes, runState),
-                        buildToolSet: (_passNumber) => wrapToolsWithLogger(buildReconcileToolSet({
-                            loadSkillTool: rcLoadSkill,
-                            stageListTool: rcStageListTool,
-                            stageDiffTool: rcStageDiffTool,
-                            evictionListTool: rcEvictionListTool,
-                            emitConflictResolutionTool: rcEmitConflictResolutionTool,
-                            emitEvictionDecisionTool: rcEmitEvictionDecisionTool,
-                            emitArtifactResolutionTool: rcEmitArtifactResolutionTool,
-                            emitUnmappedFallbackTool: rcEmitUnmappedFallbackTool,
-                            readRawSpanTool: rcRawSpanTool,
-                            toolsetTools: rcToolset.toRuntimeTools(rcToolContext),
-                        }), join(transcriptDir, 'reconcile.jsonl'), 'reconcile', { onEntry: recordTranscriptEntry(join(transcriptDir, 'reconcile.jsonl')) }),
+                        buildToolSet: (_passNumber) => buildReconcileToolSetWithHeartbeat(),
                         getReconciliationActions: () => reconcileActions,
-                        onStepFinish: stage4
-                            ? ({ passNumber, stepIndex, stepBudget }) => {
-                                emitStageProgress('reconciliation', 85, `Reconciling results: pass ${passNumber} step ${stepIndex}/${stepBudget}`, { transient: true });
-                                void stage4.updateProgress(stepIndex / stepBudget, `Reconciling results · pass ${passNumber} step ${stepIndex}`);
-                            }
-                            : undefined,
+                        abortSignal: ctx?.abortSignal,
                     });
                     curatorReport = curatorOutcome.report;
                     curatorWarnings = curatorOutcome.warnings;
@@ -1512,31 +1603,13 @@ export class IngestBundleRunner {
                             canonicalPins: relevantCanonicalPins,
                         }),
                         buildUserPrompt: (idx, ev) => buildReconcileUserPrompt(idx, ev, undefined, reconcileNotes),
-                        buildToolSet: () => wrapToolsWithLogger(buildReconcileToolSet({
-                            loadSkillTool: rcLoadSkill,
-                            stageListTool: rcStageListTool,
-                            stageDiffTool: rcStageDiffTool,
-                            evictionListTool: rcEvictionListTool,
-                            emitConflictResolutionTool: rcEmitConflictResolutionTool,
-                            emitEvictionDecisionTool: rcEmitEvictionDecisionTool,
-                            emitArtifactResolutionTool: rcEmitArtifactResolutionTool,
-                            emitUnmappedFallbackTool: rcEmitUnmappedFallbackTool,
-                            readRawSpanTool: rcRawSpanTool,
-                            toolsetTools: rcToolset.toRuntimeTools(rcToolContext),
-                        }), join(transcriptDir, 'reconcile.jsonl'), 'reconcile', { onEntry: recordTranscriptEntry(join(transcriptDir, 'reconcile.jsonl')) }),
+                        buildToolSet: () => buildReconcileToolSetWithHeartbeat(),
                         modelRole: 'reconcile',
                         stepBudget: 60,
                         sourceKey: job.sourceKey,
                         jobId: job.jobId,
                         force: !!overrideReport,
-                        onStepFinish: stage4
-                            ? ({ stepIndex, stepBudget }) => {
-                                emitStageProgress('reconciliation', 85, `Reconciling results: step ${stepIndex}/${stepBudget}`, {
-                                    transient: true,
-                                });
-                                void stage4.updateProgress(stepIndex / stepBudget, `Reconciling results · step ${stepIndex}`);
-                            }
-                            : undefined,
+                        abortSignal: ctx?.abortSignal,
                     });
                 }
                 await runTrace.event('debug', 'reconciliation', 'reconciliation_executed', {
@@ -1890,6 +1963,7 @@ export class IngestBundleRunner {
                         repairKind: 'final_artifact_gate',
                         maxAttempts: 1,
                         stepBudget: 16,
+                        abortSignal: ctx?.abortSignal,
                     });
                     isolatedDiffSummary.gateRepairAttempts += gateRepair.attempts;
                     if (gateRepair.status === 'failed') {

package/dist/context/ingest/isolated-diff/patch-integrator.js

@@ -85,18 +85,88 @@ export async function integrateWorkUnitPatch(input) {
             });
         }
         catch (semanticError) {
-            if (preApplyHead) {
-                await input.integrationGit.resetHardTo(preApplyHead);
-            }
+            const reason = errorMessage(semanticError);
             await input.trace.event('error', 'integration', 'patch_semantic_conflict_after_textual_resolution', {
                 unitKey: input.unitKey,
                 patchPath: input.patchPath,
                 touchedPaths: textualResolution.changedPaths,
-                reason: errorMessage(semanticError),
+                reason,
             });
+            // A textual conflict and a semantic-gate failure can co-occur: the resolver
+            // reconciles the text but can leave wiki sl_refs pointing at measures the
+            // merged source no longer defines. Recover via the same gate repair the
+            // clean-apply branch uses, instead of hard-failing the whole job.
+            if (input.repairGateFailure) {
+                const gateRepair = await input.repairGateFailure({
+                    unitKey: input.unitKey,
+                    patchPath: input.patchPath,
+                    touchedPaths: textualResolution.changedPaths,
+                    reason,
+                });
+                if (gateRepair.status !== 'failed') {
+                    // The resolver wrote its merge to the worktree (unstaged); the repair
+                    // edited a subset on top. Commit the union so neither is dropped.
+                    const resolvedAndRepairedPaths = [
+                        ...new Set([...textualResolution.changedPaths, ...gateRepair.changedPaths]),
+                    ].sort();
+                    try {
+                        await traceTimed(input.trace, 'integration', 'semantic_gate_after_gate_repair', { unitKey: input.unitKey, touchedPaths: gateRepair.changedPaths }, async () => {
+                            await input.validateAppliedTree(gateRepair.changedPaths);
+                        });
+                        const commit = await input.integrationGit.commitFiles(resolvedAndRepairedPaths, `ingest: resolve WorkUnit ${input.unitKey} conflict`, input.author.name, input.author.email);
+                        if (commit.created) {
+                            await input.trace.event('debug', 'integration', 'patch_accepted_after_textual_resolution', {
+                                unitKey: input.unitKey,
+                                commitSha: commit.commitHash,
+                                touchedPaths: resolvedAndRepairedPaths,
+                                attempts: textualResolution.attempts,
+                                gateRepairAttempts: gateRepair.attempts,
+                            });
+                            return {
+                                status: 'accepted',
+                                commitSha: commit.commitHash,
+                                touchedPaths: resolvedAndRepairedPaths,
+                                textualResolution,
+                                gateRepair,
+                            };
+                        }
+                    }
+                    catch (repairValidationError) {
+                        if (preApplyHead) {
+                            await input.integrationGit.resetHardTo(preApplyHead);
+                        }
+                        await input.trace.event('error', 'integration', 'patch_semantic_conflict_after_textual_resolution', {
+                            unitKey: input.unitKey,
+                            patchPath: input.patchPath,
+                            touchedPaths: gateRepair.changedPaths,
+                            reason: errorMessage(repairValidationError),
+                        });
+                        return {
+                            status: 'semantic_conflict',
+                            reason: errorMessage(repairValidationError),
+                            touchedPaths: gateRepair.changedPaths,
+                            textualResolution,
+                            gateRepair,
+                        };
+                    }
+                }
+                if (preApplyHead) {
+                    await input.integrationGit.resetHardTo(preApplyHead);
+                }
+                return {
+                    status: 'semantic_conflict',
+                    reason: gateRepair.status === 'failed' ? gateRepair.reason : reason,
+                    touchedPaths: textualResolution.changedPaths,
+                    textualResolution,
+                    gateRepair,
+                };
+            }
+            if (preApplyHead) {
+                await input.integrationGit.resetHardTo(preApplyHead);
+            }
             return {
                 status: 'semantic_conflict',
-                reason: errorMessage(semanticError),
+                reason,
                 touchedPaths: textualResolution.changedPaths,
                 textualResolution,
             };

package/dist/context/ingest/isolated-diff/textual-conflict-resolver.d.ts

@@ -19,5 +19,6 @@ export interface ResolveTextualConflictInput {
     reason: string;
     maxAttempts?: number;
     stepBudget?: number;
+    abortSignal?: AbortSignal;
 }
 export declare function resolveTextualConflict(input: ResolveTextualConflictInput): Promise<TextualConflictResolutionResult>;

package/dist/context/ingest/isolated-diff/textual-conflict-resolver.js

@@ -165,6 +165,7 @@ export async function resolveTextualConflict(input) {
                 jobId: input.trace.context.jobId,
                 unitKey: input.unitKey,
             },
+            abortSignal: input.abortSignal,
         }));
         if (result.stopReason === 'error') {
             lastFailure = result.error?.message ?? 'resolver agent loop errored';

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

@@ -9,6 +9,7 @@ export interface RunIsolatedWorkUnitInput {
     patchDir: string;
     trace: IngestTraceWriter;
     workUnit: WorkUnit;
+    abortSignal?: AbortSignal;
     run(child: IngestSessionWorktree): Promise<WorkUnitOutcome>;
     afterSuccess?(child: IngestSessionWorktree): Promise<void>;
 }

package/dist/context/ingest/local-adapters.js

@@ -7,6 +7,7 @@ import { DbtSourceAdapter } from './adapters/dbt/dbt.adapter.js';
 import { FakeSourceAdapter } from './adapters/fake/fake.adapter.js';
 import { HistoricSqlSourceAdapter } from './adapters/historic-sql/historic-sql.adapter.js';
 import { PostgresPgssReader } from './adapters/historic-sql/postgres-pgss-reader.js';
+import { resolveQueryHistoryScopeFloor } from './adapters/historic-sql/scope-floor.js';
 import { HISTORIC_SQL_SOURCE_KEY, historicSqlUnifiedPullConfigSchema, } from './adapters/historic-sql/types.js';
 import { createDaemonLiveDatabaseIntrospection, } from './adapters/live-database/daemon-introspection.js';
 import { LiveDatabaseSourceAdapter } from './adapters/live-database/live-database.adapter.js';
@@ -113,14 +114,30 @@ function queryHistoryRecord(connection) {
     const queryHistory = isRecord(context?.queryHistory) ? context.queryHistory : null;
     return queryHistory;
 }
-function queryHistoryPullConfig(connection) {
+async function queryHistoryPullConfig(project, connectionId, connection) {
     const queryHistory = queryHistoryRecord(connection);
     if (queryHistory?.enabled !== true || !isRecord(connection))
         return null;
-    const dialect = historicSqlDialectByDriver.get(String(connection.driver ?? '').toLowerCase());
+    const driver = String(connection.driver ?? '').toLowerCase();
+    const dialect = historicSqlDialectByDriver.get(driver);
     if (!dialect)
         return null;
-    return { ...queryHistory, dialect };
+    const scopeFloor = await resolveQueryHistoryScopeFloor({
+        projectDir: project.projectDir,
+        connectionId,
+        driver,
+        connection,
+        storedQueryHistory: queryHistory,
+    });
+    const { enabled: _enabled, dialect: _dialect, enabledTables: _enabledTables, enabledSchemas: _enabledSchemas, scopeFloorWarnings: _scopeFloorWarnings, ...stored } = queryHistory;
+    return {
+        ...stored,
+        dialect,
+        ...(scopeFloor.enabledTables.length > 0 ? { enabledTables: scopeFloor.enabledTables } : {}),
+        ...(scopeFloor.enabledSchemas.length > 0 ? { enabledSchemas: scopeFloor.enabledSchemas } : {}),
+        ...(scopeFloor.modeledTableCatalog.length > 0 ? { modeledTableCatalog: scopeFloor.modeledTableCatalog } : {}),
+        ...(scopeFloor.warnings.length > 0 ? { scopeFloorWarnings: scopeFloor.warnings } : {}),
+    };
 }
 function stringField(value) {
     return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
@@ -168,7 +185,7 @@ export async function localPullConfigForAdapter(project, adapter, connectionId,
         if (options.historicSqlPullConfigOverride) {
             return historicSqlUnifiedPullConfigSchema.parse(options.historicSqlPullConfigOverride);
         }
-        const queryHistory = queryHistoryPullConfig(connection);
+        const queryHistory = await queryHistoryPullConfig(project, connectionId, connection);
         if (!queryHistory) {
             throw new Error(`Connection "${connectionId}" does not have context.queryHistory.enabled: true`);
         }

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

@@ -8,6 +8,7 @@ import { SessionWorktreeService } from '../../context/core/session-worktree.serv
 import { createRuntimeToolDescriptorFromAiTool } from '../../context/llm/runtime-tools.js';
 import { createLocalKtxLlmRuntimeFromConfig } from '../../context/llm/local-config.js';
 import { KtxIngestEmbeddingPortAdapter } from '../../context/llm/embedding-port.js';
+import { createRateLimitGovernorConfig, RateLimitGovernor } from '../../context/llm/rate-limit-governor.js';
 import { RuntimeAgentRunner } from '../../context/llm/runtime-port.js';
 import { ktxLocalStateDbPath } from '../../context/project/local-state-db.js';
 import { PromptService } from '../../context/prompts/prompt.service.js';
@@ -488,17 +489,19 @@ function nextLocalJobId() {
 }
 function localIngestLlmProviderGuardMessage(projectDir) {
     return [
-        'ktx ingest requires llm.provider.backend: anthropic, vertex, gateway, or claude-code, or an injected agentRunner.',
-        'Configure a local Claude Code session or API-backed LLM, then rerun ingest:',
+        'ktx ingest requires llm.provider.backend: anthropic, vertex, gateway, claude-code, or codex, or an injected agentRunner.',
+        'Configure a local Claude Code/Codex session or API-backed LLM, then rerun ingest:',
         `  ktx setup --project-dir ${projectDir} --llm-backend claude-code --no-input`,
-        `  ktx setup --project-dir ${projectDir} --llm-backend anthropic --anthropic-api-key-env ANTHROPIC_API_KEY --llm-model claude-sonnet-4-6 --no-input`,
+        `  ktx setup --project-dir ${projectDir} --llm-backend codex --no-input`,
+        `  ktx setup --project-dir ${projectDir} --llm-backend anthropic --anthropic-api-key-env ANTHROPIC_API_KEY --no-input`,
     ].join('\n');
 }
-function resolveAgentRunner(options) {
+function resolveAgentRunner(options, rateLimitGovernor) {
     const llmRuntime = options.llmRuntime ??
         (options.createLlmRuntime ?? createLocalKtxLlmRuntimeFromConfig)(options.project.config.llm, {
             projectDir: options.project.projectDir,
             env: process.env,
+            rateLimitGovernor,
         }) ??
         undefined;
     if (options.agentRunner) {
@@ -535,7 +538,11 @@ export function createLocalBundleIngestRuntime(options) {
     const knowledgeIndex = new LocalKnowledgeIndex(options.project, embedding);
     const knowledgeEvents = new NoopKnowledgeEventPort();
     const wikiService = new KnowledgeWikiService(rootFileStore, embedding, knowledgeIndex, options.project.git, logger);
-    const { agentRunner, llmRuntime } = resolveAgentRunner(options);
+    const rateLimitGovernor = new RateLimitGovernor(createRateLimitGovernorConfig({
+        ...options.project.config.ingest.rateLimit,
+        maxConcurrency: options.project.config.ingest.workUnits.maxConcurrency,
+    }));
+    const { agentRunner, llmRuntime } = resolveAgentRunner(options, rateLimitGovernor);
     const promptService = new PromptService({ promptsDir, partials: [], logger });
     const storage = new LocalIngestStorage(options.project);
     const registry = registerAdapters(options.adapters);
@@ -574,6 +581,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,
+            rateLimitGovernor,
             profileIngest: options.project.config.ingest.profile,
             ingestTraceLevel: ingestTraceLevelFromEnv(),
         },

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

@@ -25,6 +25,7 @@ export interface RunLocalIngestOptions {
     queryExecutor?: KtxSqlQueryExecutorPort;
     logger?: KtxLogger;
     embeddingProvider?: import('../../llm/types.js').KtxEmbeddingProvider | null;
+    abortSignal?: AbortSignal;
 }
 export interface LocalIngestResult {
     result: IngestBundleResult;

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

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { cp, mkdir, rm } from 'node:fs/promises';
 import { isAbsolute, resolve } from 'node:path';
+import { createAbortError, isAbortError } from '../../context/core/abort.js';
 import { ktxLocalStateDbPath } from '../../context/project/local-state-db.js';
 import { planMetabaseFanoutChildren } from './adapters/metabase/fanout-planner.js';
 import { KtxYamlMetabaseSourceStateReader, LocalMetabaseDiscoveryCache } from './adapters/metabase/local-source-state-store.js';
@@ -36,10 +37,11 @@ function findAdapter(adapters, source) {
     }
     return adapter;
 }
-function localJobContext(jobId, memoryFlow) {
+function localJobContext(jobId, memoryFlow, abortSignal) {
     return {
         jobId,
         ...(memoryFlow ? { memoryFlow } : {}),
+        ...(abortSignal ? { abortSignal } : {}),
         startPhase() {
             return new LocalIngestPhase();
         },
@@ -62,7 +64,7 @@ async function runScheduledPullJob(options) {
         sourceKey: options.adapter.source,
         trigger: options.trigger ?? 'manual_resync',
         bundleRef: { kind: 'scheduled_pull', config: options.pullConfig },
-    }, localJobContext(jobId, options.memoryFlow));
+    }, localJobContext(jobId, options.memoryFlow, options.abortSignal));
     const report = await runtime.store.findByJobId(jobId);
     if (!report) {
         throw new Error(`Local ingest report for job "${jobId}" was not created`);
@@ -102,6 +104,7 @@ export async function runLocalIngest(options) {
             queryExecutor: options.queryExecutor,
             logger: options.logger,
             embeddingProvider: options.embeddingProvider,
+            abortSignal: options.abortSignal,
         });
     }
     const result = await runtime.runner.run({
@@ -110,7 +113,7 @@ export async function runLocalIngest(options) {
         sourceKey: adapter.source,
         trigger: options.trigger ?? (options.sourceDir ? 'upload' : 'manual_resync'),
         bundleRef,
-    }, localJobContext(jobId, options.memoryFlow));
+    }, localJobContext(jobId, options.memoryFlow, options.abortSignal));
     const report = await runtime.store.findByJobId(jobId);
     if (!report) {
         throw new Error(`Local ingest report for job "${jobId}" was not created`);
@@ -226,6 +229,9 @@ export async function runLocalMetabaseIngest(options) {
     });
     const children = [];
     for (const childPlan of childPlans) {
+        if (options.abortSignal?.aborted) {
+            throw createAbortError();
+        }
         const targetConnectionId = safeSegment('target connection id', childPlan.targetConnectionId);
         if (!options.project.config.connections[targetConnectionId]) {
             throw new Error(`Target connection "${targetConnectionId}" is not configured in ktx.yaml`);
@@ -255,9 +261,13 @@ export async function runLocalMetabaseIngest(options) {
                 queryExecutor: options.queryExecutor,
                 logger: options.logger,
                 embeddingProvider: options.embeddingProvider,
+                abortSignal: options.abortSignal,
             });
         }
         catch (error) {
+            if (isAbortError(error)) {
+                throw error;
+            }
             child = await recordLocalMetabaseChildFailure({
                 project: options.project,
                 jobId: childJobId,

package/dist/context/ingest/memory-flow/events.js

@@ -127,7 +127,7 @@ export function ingestReportToMemoryFlowReplay(report, options = {}) {
     }
     const actions = allReportActions(report);
     const workUnitEvents = report.body.workUnits.flatMap((workUnit) => [
-        { type: 'work_unit_started', unitKey: workUnit.unitKey, skills: [], stepBudget: 0 },
+        { type: 'work_unit_started', unitKey: workUnit.unitKey, skills: [] },
         ...workUnit.actions.map((action) => ({
             type: 'candidate_action',
             unitKey: workUnit.unitKey,

package/dist/context/ingest/memory-flow/schema.js

@@ -64,17 +64,22 @@ const memoryFlowEventSchema = z.discriminatedUnion('type', [
         message: z.string().min(1),
         transient: z.boolean().optional(),
     }),
+    eventSchema({
+        type: z.literal('rate_limit_wait'),
+        provider: z.string(),
+        rateLimitType: z.string().optional(),
+        resumeAtMs: z.number().int().nonnegative(),
+        remainingMs: z.number().int().nonnegative(),
+    }),
     eventSchema({
         type: z.literal('work_unit_started'),
         unitKey: z.string().min(1),
         skills: z.array(z.string().min(1)),
-        stepBudget: z.number().int().min(0),
     }),
     eventSchema({
         type: z.literal('work_unit_step'),
         unitKey: z.string().min(1),
-        stepIndex: z.number().int().min(0),
-        stepBudget: z.number().int().min(0),
+        toolCalls: z.number().int().min(0),
     }),
     eventSchema({
         type: z.literal('candidate_action'),