@kaelio/ktx 0.11.0 → 0.12.0

package/dist/context/core/git.service.d.ts

@@ -20,6 +20,23 @@ export interface WorktreeEntry {
     branch: string | null;
     head: string | null;
 }
+export type KtxRepoOwnership = 'unowned' | 'ktx-managed' | 'foreign';
+export declare class KtxForeignGitRepositoryError extends Error {
+    constructor(configDir: string);
+}
+/**
+ * Classify whether ktx may own a git repository rooted exactly at `dir`. A root
+ * `ktx.yaml` is the ownership signal; the working tree decides, not git history,
+ * because older ktx versions left `ktx.yaml` uncommitted (it holds secret refs).
+ *
+ * - `unowned`: no repo here (including a missing or non-directory path) → ktx may `git init`.
+ * - `ktx-managed`: `<dir>/.git` is a directory and `ktx.yaml` sits at the root.
+ * - `foreign`: any other repo — no root `ktx.yaml`, or a `.git` *file* (a linked
+ *   worktree). ktx must never adopt or mutate it.
+ *
+ * Reads only `<dir>` itself; never walks up, so a parent repo cannot change the answer.
+ */
+export declare function classifyKtxRepoOwnership(dir: string): Promise<KtxRepoOwnership>;
 export type SquashMergeResult = {
     ok: true;
     squashSha: string;
@@ -102,6 +119,12 @@ export declare class GitService {
         path: string;
     }>>;
     changedPaths(): Promise<string[]>;
+    /**
+     * List all paths matching `pathSpec` as they exist at `commitHash`. Reads from
+     * git object storage, so it's safe against concurrent working-tree mutations
+     * and can recover paths (e.g. a human-renamed file) that no longer exist on disk.
+     */
+    listFilesAtCommit(pathSpec: string, commitHash: string): Promise<string[]>;
     /**
      * List all paths under the working tree that match `pathSpec`, scoped to HEAD.
      * Used for the reconciler's first-ever run when there's no watermark to diff from.

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

@@ -2,6 +2,53 @@ import { promises as fs } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { noopLogger, resolveConfigDir } from './config.js';
 import { createSimpleGit } from './git-env.js';
+export class KtxForeignGitRepositoryError extends Error {
+    constructor(configDir) {
+        super(`${configDir} is already a git repository that ktx did not create. ` +
+            'ktx maintains its context in a repository it owns; run ktx in a dedicated directory or move the existing repository aside.');
+        this.name = 'KtxForeignGitRepositoryError';
+    }
+}
+function isNodeErrnoException(error) {
+    return error instanceof Error && 'code' in error;
+}
+/**
+ * Classify whether ktx may own a git repository rooted exactly at `dir`. A root
+ * `ktx.yaml` is the ownership signal; the working tree decides, not git history,
+ * because older ktx versions left `ktx.yaml` uncommitted (it holds secret refs).
+ *
+ * - `unowned`: no repo here (including a missing or non-directory path) → ktx may `git init`.
+ * - `ktx-managed`: `<dir>/.git` is a directory and `ktx.yaml` sits at the root.
+ * - `foreign`: any other repo — no root `ktx.yaml`, or a `.git` *file* (a linked
+ *   worktree). ktx must never adopt or mutate it.
+ *
+ * Reads only `<dir>` itself; never walks up, so a parent repo cannot change the answer.
+ */
+export async function classifyKtxRepoOwnership(dir) {
+    let dotGitIsDirectory;
+    try {
+        dotGitIsDirectory = (await fs.lstat(join(dir, '.git'))).isDirectory();
+    }
+    catch (error) {
+        // ENOENT: `<dir>/.git` is absent. ENOTDIR: `<dir>` itself is a file, so it
+        // can hold no repo. Either way there is nothing for ktx to avoid here.
+        if (isNodeErrnoException(error) && (error.code === 'ENOENT' || error.code === 'ENOTDIR')) {
+            return 'unowned';
+        }
+        throw error;
+    }
+    if (!dotGitIsDirectory) {
+        return 'foreign';
+    }
+    try {
+        // stat (not lstat): follow symlinks, matching what `loadKtxProject`'s
+        // readFile accepts — a dir that loads as a ktx project classifies as one.
+        return (await fs.stat(join(dir, 'ktx.yaml'))).isFile() ? 'ktx-managed' : 'foreign';
+    }
+    catch {
+        return 'foreign';
+    }
+}
 function mergeErrorMessage(error) {
     if (error instanceof Error) {
         return error.message;
@@ -58,12 +105,15 @@ export class GitService {
     }
     async initialize() {
         try {
-            // Check if already initialized
-            const isRepo = await this.git.checkIsRepo();
-            if (!isRepo) {
+            const ownership = await classifyKtxRepoOwnership(this.configDir);
+            if (ownership === 'foreign') {
+                throw new KtxForeignGitRepositoryError(this.configDir);
+            }
+            if (ownership === 'unowned') {
                 await this.git.init();
-                this.logger.log('Initialized git repository');
+                this.logger.log('Initialized ktx-managed git repository');
             }
+            // ownership === 'ktx-managed' → ktx's own repo; proceed with the normal re-run path.
             // Keep any auto-maintenance triggered by writes in-process. Detached maintenance can
             // keep object-pack directories alive briefly after awaited git commands complete,
             // which makes temp-project cleanup flaky in CI.
@@ -81,6 +131,11 @@ export class GitService {
             }
         }
         catch (error) {
+            // The foreign-repo error is already typed and actionable; surface it verbatim so every
+            // command that loads the project shows the same clear guidance instead of a generic wrapper.
+            if (error instanceof KtxForeignGitRepositoryError) {
+                throw error;
+            }
             this.logger.error('Failed to initialize git repository', error);
             // Preserve the underlying git error: the generic message alone is undiagnosable in
             // telemetry and unactionable for the user. The exception reporter walks `cause` and
@@ -442,12 +497,13 @@ export class GitService {
         return [...new Set(paths)].sort();
     }
     /**
-     * List all paths under the working tree that match `pathSpec`, scoped to HEAD.
-     * Used for the reconciler's first-ever run when there's no watermark to diff from.
+     * List all paths matching `pathSpec` as they exist at `commitHash`. Reads from
+     * git object storage, so it's safe against concurrent working-tree mutations
+     * and can recover paths (e.g. a human-renamed file) that no longer exist on disk.
      */
-    async listFilesAtHead(pathSpec) {
+    async listFilesAtCommit(pathSpec, commitHash) {
         try {
-            const raw = await this.git.raw(['ls-tree', '-r', '-z', '--name-only', 'HEAD', '--', pathSpec]);
+            const raw = await this.git.raw(['ls-tree', '-r', '-z', '--name-only', commitHash, '--', pathSpec]);
             if (!raw) {
                 return [];
             }
@@ -457,6 +513,13 @@ export class GitService {
             return [];
         }
     }
+    /**
+     * List all paths under the working tree that match `pathSpec`, scoped to HEAD.
+     * Used for the reconciler's first-ever run when there's no watermark to diff from.
+     */
+    async listFilesAtHead(pathSpec) {
+        return this.listFilesAtCommit(pathSpec, 'HEAD');
+    }
     /**
      * Collapse all commits between `preHead` and current HEAD into a single commit with the given
      * message. Used by the memory agent to squash N per-tool-call commits into one ingest commit.

package/dist/context/ingest/adapters/historic-sql/projection.js

@@ -2,6 +2,7 @@ import { access, mkdir, readdir, readFile, rename, writeFile } from 'node:fs/pro
 import { dirname, join, relative } from 'node:path';
 import YAML from 'yaml';
 import { rawSourcesDirForSync } from '../../raw-sources-paths.js';
+import { isSlYamlPath } from '../../../sl/source-files.js';
 import { mergeUsagePreservingExternal } from '../live-database/manifest.js';
 import { historicSqlEvidenceEnvelopeSchema } from './evidence.js';
 import { stagedManifestSchema } from './types.js';
@@ -197,7 +198,7 @@ export async function projectHistoricSqlEvidence(input) {
     const tableEvidence = evidence.filter((entry) => entry.kind === 'table_usage');
     const patternEvidence = evidence.filter((entry) => entry.kind === 'pattern');
     const schemaRoot = join(input.workdir, 'semantic-layer', input.connectionId, '_schema');
-    for (const file of (await walkFiles(schemaRoot)).filter((candidate) => candidate.endsWith('.yaml') || candidate.endsWith('.yml'))) {
+    for (const file of (await walkFiles(schemaRoot)).filter(isSlYamlPath)) {
         const path = join(schemaRoot, file);
         const before = await readFile(path, 'utf-8');
         const shard = (YAML.parse(before) ?? {});

package/dist/context/ingest/adapters/looker/client.js

@@ -12,13 +12,18 @@ const defaultLogger = {
 class InlineLookerSettings extends NodeSettings {
     params;
     constructor(params) {
-        super('', {
+        // @looker/sdk-rtl boundary: NodeSettings consumes a string-valued config
+        // section (read back via the readConfig override below), but its constructor
+        // is typed to accept a fully-realized IApiSettings. The string record is the
+        // shape the library actually reads, so narrow to IApiSection first.
+        const settings = {
             base_url: normalizeBaseUrl(params.base_url),
             client_id: params.client_id,
             client_secret: params.client_secret, // pragma: allowlist secret
             verify_ssl: 'true',
             timeout: '120',
-        });
+        };
+        super('', settings);
         this.params = params;
     }
     readConfig(_section) {

package/dist/context/ingest/adapters/looker/factory.d.ts

@@ -1,5 +1,5 @@
 import type { FetchContext } from '../../types.js';
-import { type LookerClientDeps, type LookerConnectionParams } from './client.js';
+import { LookerClient, type LookerClientDeps, type LookerConnectionParams } from './client.js';
 import type { LookerClientFactory, LookerRuntimeClient } from './fetch.js';
 import type { LookerPullConfig } from './types.js';
 export interface LookerCredentialResolver {
@@ -14,6 +14,13 @@ export declare class DefaultLookerConnectionClientFactory implements LookerConne
     private readonly deps;
     constructor(resolver: LookerCredentialResolver, deps?: LookerClientDeps);
     createClient(lookerConnectionId: string): Promise<LookerRuntimeClient>;
+    /**
+     * Like {@link createClient} but preserves the concrete {@link LookerClient}
+     * type, so callers that need methods outside the `LookerRuntimeClient`
+     * contract (e.g. `listLookerConnections`, `testConnection`) keep them without
+     * a cast.
+     */
+    createLookerClient(lookerConnectionId: string): Promise<LookerClient>;
 }
 /** @internal */
 export declare class DefaultLookerClientFactory implements LookerClientFactory {

package/dist/context/ingest/adapters/looker/factory.js

@@ -7,6 +7,15 @@ export class DefaultLookerConnectionClientFactory {
         this.deps = deps;
     }
     async createClient(lookerConnectionId) {
+        return this.createLookerClient(lookerConnectionId);
+    }
+    /**
+     * Like {@link createClient} but preserves the concrete {@link LookerClient}
+     * type, so callers that need methods outside the `LookerRuntimeClient`
+     * contract (e.g. `listLookerConnections`, `testConnection`) keep them without
+     * a cast.
+     */
+    async createLookerClient(lookerConnectionId) {
         const credentials = await this.resolver.resolve(lookerConnectionId);
         return new LookerClient(credentials, this.deps);
     }

package/dist/context/ingest/adapters/looker/mapping.js

@@ -120,7 +120,7 @@ export function validateLookerMappings(args) {
         if (!args.knownKtxConnectionIds.has(mapping.ktxConnectionId)) {
             errors.push({
                 key: mapping.lookerConnectionName,
-                reason: `KTX connection ${mapping.ktxConnectionId} does not exist`,
+                reason: `ktx connection ${mapping.ktxConnectionId} does not exist`,
             });
             continue;
         }

package/dist/context/ingest/adapters/looker/types.d.ts

@@ -12,6 +12,7 @@ export declare const lookerPullConfigSchema: z.ZodObject<{
     lookUpdatedSince: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
     connectionMappings: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     connectionTypes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        PLAIN: "PLAIN";
         BIGQUERY: "BIGQUERY";
         SNOWFLAKE: "SNOWFLAKE";
         MYSQL: "MYSQL";
@@ -31,7 +32,6 @@ export declare const lookerPullConfigSchema: z.ZodObject<{
         METABASE: "METABASE";
         LOOKER: "LOOKER";
         NOTION: "NOTION";
-        PLAIN: "PLAIN";
         BETTERSTACK: "BETTERSTACK";
     }>>>;
     parsedTargetTables: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{

package/dist/context/ingest/adapters/metabase/client.d.ts

@@ -18,7 +18,7 @@ export declare const DEFAULT_METABASE_CLIENT_CONFIG: MetabaseClientConfig;
  * Strip Metabase `[[ ... {{ var }} ... ]]` optional-clause blocks from native SQL.
  *
  * The bracketed blocks are emitted only when the embedded `{{ var }}` is supplied at
- * Metabase query time. For KTX semantic-layer ingest there's no such runtime
+ * Metabase query time. For ktx semantic-layer ingest there's no such runtime
  * parameter — chat-time filters are composed by the SL query planner — so the optional
  * block must be removed before the SQL becomes a permanent SL source. Substituting a
  * dummy value (the alternative) bakes a placeholder filter into the source and silently

package/dist/context/ingest/adapters/metabase/client.js

@@ -30,7 +30,7 @@ class MetabaseApiError extends Error {
  * Strip Metabase `[[ ... {{ var }} ... ]]` optional-clause blocks from native SQL.
  *
  * The bracketed blocks are emitted only when the embedded `{{ var }}` is supplied at
- * Metabase query time. For KTX semantic-layer ingest there's no such runtime
+ * Metabase query time. For ktx semantic-layer ingest there's no such runtime
  * parameter — chat-time filters are composed by the SL query planner — so the optional
  * block must be removed before the SQL becomes a permanent SL source. Substituting a
  * dummy value (the alternative) bakes a placeholder filter into the source and silently

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

@@ -15,7 +15,7 @@ export function metabaseRuntimeConfigFromLocalConnection(connectionId, connectio
         throw new Error(`Connection "${connectionId}" is not a Metabase connection`);
     }
     if (hasNetworkProxy(connection)) {
-        throw new Error(`Standalone KTX does not support proxy-bearing Metabase connections yet. Use hosted Metabase ingest for "${connectionId}" until the KTX Metabase proxy support spec lands.`);
+        throw new Error(`Standalone ktx does not support proxy-bearing Metabase connections yet. Use hosted Metabase ingest for "${connectionId}" until the ktx Metabase proxy support spec lands.`);
     }
     const apiUrl = stringField(connection.api_url);
     const literalApiKey = stringField(connection.api_key);

package/dist/context/ingest/adapters/metabase/mapping.js

@@ -93,7 +93,7 @@ export function validateMetabaseMappings(args) {
             continue;
         }
         if (!args.knownKtxConnectionIds.has(connectionId)) {
-            errors.push({ key, reason: `KTX connection ${connectionId} does not exist` });
+            errors.push({ key, reason: `ktx connection ${connectionId} does not exist` });
         }
     }
     return errors.length === 0 ? { ok: true } : { ok: false, errors };
@@ -108,13 +108,13 @@ export function validateMappingPhysicalMatch(mapping, target) {
         return null;
     }
     if (target.connection_type !== expectedType) {
-        return `Metabase database engine '${engine}' does not match KTX connection type '${target.connection_type}'`;
+        return `Metabase database engine '${engine}' does not match ktx connection type '${target.connection_type}'`;
     }
     const metabaseDb = normalizeName(mapping.metabaseDbName);
     const targetDb = normalizeName(getTargetDatabase(target));
     if (engine === 'snowflake' || engine === 'bigquery' || engine === 'bigquery-cloud-sdk') {
         if (metabaseDb && targetDb && metabaseDb !== targetDb) {
-            return `Metabase database '${mapping.metabaseDbName}' does not match KTX connection database '${displayValue(getTargetDatabase(target))}'`;
+            return `Metabase database '${mapping.metabaseDbName}' does not match ktx connection database '${displayValue(getTargetDatabase(target))}'`;
         }
         return null;
     }
@@ -122,10 +122,10 @@ export function validateMappingPhysicalMatch(mapping, target) {
         const metabaseHost = normalizeHost(mapping.metabaseHost);
         const targetHost = normalizeHost(target.host);
         if (metabaseHost && targetHost && metabaseHost !== targetHost) {
-            return `Metabase host '${mapping.metabaseHost}' does not match KTX connection host '${displayValue(target.host)}'`;
+            return `Metabase host '${mapping.metabaseHost}' does not match ktx connection host '${displayValue(target.host)}'`;
         }
         if (metabaseDb && targetDb && metabaseDb !== targetDb) {
-            return `Metabase database '${mapping.metabaseDbName}' does not match KTX connection database '${displayValue(getTargetDatabase(target))}'`;
+            return `Metabase database '${mapping.metabaseDbName}' does not match ktx connection database '${displayValue(getTargetDatabase(target))}'`;
         }
         return null;
     }
@@ -157,7 +157,7 @@ export async function refreshMetabaseMapping(args) {
         if (!target) {
             physicalMismatches.push({
                 mappingId: String(mapping.id),
-                reason: `KTX connection ${mapping.ktxConnectionId} does not exist`,
+                reason: `ktx connection ${mapping.ktxConnectionId} does not exist`,
             });
             continue;
         }

package/dist/context/ingest/artifact-gates.d.ts

@@ -1,17 +1,14 @@
 import type { SemanticLayerService } from '../../context/sl/semantic-layer.service.js';
 import type { TouchedSlSource } from '../../context/tools/touched-sl-sources.js';
 import type { KnowledgeWikiService } from '../../context/wiki/knowledge-wiki.service.js';
-interface TouchedValidationResult {
-    invalidSources: string[];
-    validSources: string[];
-}
+import type { WuValidationResult } from './stages/validate-wu-sources.js';
 export interface FinalArtifactGateInput {
     connectionIds: string[];
     changedWikiPageKeys: string[];
     touchedSlSources: TouchedSlSource[];
     wikiService: KnowledgeWikiService;
     semanticLayerService: SemanticLayerService;
-    validateTouchedSources(touched: TouchedSlSource[]): Promise<TouchedValidationResult>;
+    validateTouchedSources(touched: TouchedSlSource[]): Promise<WuValidationResult>;
     tableExists(connectionId: string, tableRef: string): Promise<boolean>;
 }
 export interface ProvenanceRawPathValidationInput {
@@ -23,4 +20,3 @@ export interface ProvenanceRawPathValidationInput {
 }
 export declare function validateFinalIngestArtifacts(input: FinalArtifactGateInput): Promise<void>;
 export declare function validateProvenanceRawPaths(input: ProvenanceRawPathValidationInput): void;
-export {};

package/dist/context/ingest/artifact-gates.js

@@ -13,50 +13,6 @@ function slEntityNames(source) {
         ...(source.segments ?? []).map((segment) => segment.name),
     ]);
 }
-function uniqueTouchedSources(sources) {
-    const seen = new Set();
-    const unique = [];
-    for (const source of sources) {
-        const key = `${source.connectionId}:${source.sourceName}`;
-        if (seen.has(key)) {
-            continue;
-        }
-        seen.add(key);
-        unique.push(source);
-    }
-    return unique.sort((left, right) => {
-        const byConnection = left.connectionId.localeCompare(right.connectionId);
-        return byConnection === 0 ? left.sourceName.localeCompare(right.sourceName) : byConnection;
-    });
-}
-async function expandTouchedSlSourcesWithDirectJoinNeighbors(input) {
-    const expanded = [...input.touchedSlSources];
-    const touchedByConnection = new Map();
-    for (const source of input.touchedSlSources) {
-        const bucket = touchedByConnection.get(source.connectionId) ?? new Set();
-        bucket.add(source.sourceName);
-        touchedByConnection.set(source.connectionId, bucket);
-    }
-    for (const connectionId of input.connectionIds) {
-        const touched = touchedByConnection.get(connectionId);
-        if (!touched || touched.size === 0) {
-            continue;
-        }
-        const { sources } = await input.semanticLayerService.loadAllSources(connectionId);
-        for (const source of sources) {
-            const sourceIsTouched = touched.has(source.name);
-            if (sourceIsTouched) {
-                for (const join of source.joins ?? []) {
-                    expanded.push({ connectionId, sourceName: join.to });
-                }
-            }
-            if ((source.joins ?? []).some((join) => touched.has(join.to))) {
-                expanded.push({ connectionId, sourceName: source.name });
-            }
-        }
-    }
-    return uniqueTouchedSources(expanded);
-}
 async function validateWikiSlRefs(input) {
     const errors = [];
     const sourcesByConnection = new Map();
@@ -112,9 +68,11 @@ async function validateWikiRefs(input) {
     return dangling;
 }
 export async function validateFinalIngestArtifacts(input) {
-    const touchedWithDependencies = await expandTouchedSlSourcesWithDirectJoinNeighbors(input);
-    const validation = await input.validateTouchedSources(touchedWithDependencies);
-    const errors = validation.invalidSources.map((source) => `semantic-layer validation failed for ${source}`);
+    // Join-neighbor expansion happens inside validateTouchedSources so work-unit
+    // validation and this gate check the same set — a source that passes one
+    // passes the other.
+    const validation = await input.validateTouchedSources(input.touchedSlSources);
+    const errors = validation.invalidSources.map((invalid) => `semantic-layer validation failed for ${invalid.source}: ${invalid.errors.join('; ')}`);
     errors.push(...(await validateWikiSlRefs(input)));
     const danglingWikiRefs = await validateWikiRefs(input);
     if (danglingWikiRefs.length > 0) {

package/dist/context/ingest/constrained-repair.d.ts

@@ -0,0 +1,55 @@
+import type { AgentRunnerPort, KtxRuntimeToolSet } from '../../context/llm/runtime-port.js';
+import type { IngestTraceWriter } from './ingest-trace.js';
+/**
+ * Shared loop for the two integration-time repair agents (semantic gate
+ * repair, textual conflict resolution). Success is decided by re-running the
+ * failed check — `verify` — never by whether the agent edited files: an
+ * ineffective edit fails, and an explicit no-change declaration that verifies
+ * succeeds.
+ */
+export type RepairVerification = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export type ConstrainedRepairResult = {
+    status: 'repaired';
+    attempts: number;
+    changedPaths: string[];
+} | {
+    status: 'failed';
+    attempts: number;
+    reason: string;
+};
+export interface ConstrainedRepairToolContext {
+    workdir: string;
+    allowedPaths: ReadonlySet<string>;
+    editedPaths: Set<string>;
+    declareNoChange(reason: string): void;
+}
+export interface ConstrainedRepairLoopInput {
+    agentRunner: AgentRunnerPort;
+    workdir: string;
+    allowedPaths: string[];
+    trace: IngestTraceWriter;
+    tracePhase: string;
+    traceEventName: string;
+    traceData: Record<string, unknown>;
+    systemPrompt: string;
+    buildUserPrompt(input: {
+        attempt: number;
+        maxAttempts: number;
+        previousFailure: string | null;
+    }): string;
+    buildExtraTools?(context: ConstrainedRepairToolContext): KtxRuntimeToolSet;
+    verify(changedPaths: string[]): Promise<RepairVerification>;
+    /** Failure reason when an attempt neither edits nor declares no-change. */
+    noChangeFailureReason: string;
+    telemetryTags: Record<string, string>;
+    maxAttempts?: number;
+    stepBudget?: number;
+    abortSignal?: AbortSignal;
+}
+export declare function buildDeleteRepairFileTool(context: ConstrainedRepairToolContext): KtxRuntimeToolSet;
+export declare function runConstrainedRepairLoop(input: ConstrainedRepairLoopInput): Promise<ConstrainedRepairResult>;

package/dist/context/ingest/constrained-repair.js

@@ -0,0 +1,167 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { traceTimed } from './ingest-trace.js';
+const readRepairFileSchema = z.object({
+    path: z.string().min(1),
+});
+const writeRepairFileSchema = z.object({
+    path: z.string().min(1),
+    content: z.string(),
+});
+function normalizeRepoPath(path) {
+    const normalized = path.replace(/\\/g, '/').replace(/^\/+/, '');
+    const parts = normalized.split('/').filter((part) => part.length > 0);
+    if (parts.length === 0 || parts.some((part) => part === '.' || part === '..')) {
+        throw new Error(`repair path must be a repository-relative path: ${path}`);
+    }
+    return parts.join('/');
+}
+function assertAllowedPath(path, allowedPaths) {
+    const normalized = normalizeRepoPath(path);
+    if (!allowedPaths.has(normalized)) {
+        throw new Error(`repair path not allowed: ${normalized}`);
+    }
+    return normalized;
+}
+async function readOptionalFile(path) {
+    try {
+        return { exists: true, content: await readFile(path, 'utf-8') };
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+            return { exists: false, content: '' };
+        }
+        throw error;
+    }
+}
+function buildRepairFileTools(context) {
+    return {
+        read_repair_file: {
+            name: 'read_repair_file',
+            description: 'Read one allowed file from the integration worktree.',
+            inputSchema: readRepairFileSchema,
+            execute: async ({ path }) => {
+                const normalized = assertAllowedPath(path, context.allowedPaths);
+                const file = await readOptionalFile(join(context.workdir, normalized));
+                return {
+                    markdown: file.exists ? file.content : `(missing file: ${normalized})`,
+                    structured: { path: normalized, exists: file.exists },
+                };
+            },
+        },
+        write_repair_file: {
+            name: 'write_repair_file',
+            description: 'Replace one allowed integration worktree file with repaired text content.',
+            inputSchema: writeRepairFileSchema,
+            execute: async ({ path, content }) => {
+                const normalized = assertAllowedPath(path, context.allowedPaths);
+                const fullPath = join(context.workdir, normalized);
+                await mkdir(dirname(fullPath), { recursive: true });
+                await writeFile(fullPath, content, 'utf-8');
+                context.editedPaths.add(normalized);
+                return {
+                    markdown: `Wrote ${normalized}`,
+                    structured: { path: normalized, bytes: Buffer.byteLength(content) },
+                };
+            },
+        },
+    };
+}
+export function buildDeleteRepairFileTool(context) {
+    const deleteRepairFileSchema = z.object({
+        path: z.string().min(1),
+    });
+    return {
+        delete_repair_file: {
+            name: 'delete_repair_file',
+            description: 'Delete one allowed integration worktree file when the failed patch proves the deletion is correct.',
+            inputSchema: deleteRepairFileSchema,
+            execute: async ({ path }) => {
+                const normalized = assertAllowedPath(path, context.allowedPaths);
+                await rm(join(context.workdir, normalized), { force: true });
+                context.editedPaths.add(normalized);
+                return {
+                    markdown: `Deleted ${normalized}`,
+                    structured: { path: normalized },
+                };
+            },
+        },
+    };
+}
+export async function runConstrainedRepairLoop(input) {
+    const allowedPaths = new Set(input.allowedPaths.map(normalizeRepoPath));
+    const sortedAllowedPaths = [...allowedPaths].sort();
+    const maxAttempts = input.maxAttempts ?? 2;
+    const stepBudget = input.stepBudget ?? 16;
+    // Edits persist in the worktree across attempts, so the verified set and the
+    // reported changedPaths accumulate over the whole loop.
+    const editedPaths = new Set();
+    let lastFailure = 'repair did not run';
+    let previousFailure = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        let noChangeDeclaration = null;
+        const toolContext = {
+            workdir: input.workdir,
+            allowedPaths,
+            editedPaths,
+            declareNoChange: (reason) => {
+                noChangeDeclaration = reason;
+            },
+        };
+        const traceData = {
+            ...input.traceData,
+            attempt,
+            maxAttempts,
+            allowedPaths: sortedAllowedPaths,
+        };
+        const result = await traceTimed(input.trace, input.tracePhase, input.traceEventName, traceData, async () => input.agentRunner.runLoop({
+            modelRole: 'repair',
+            systemPrompt: input.systemPrompt,
+            userPrompt: input.buildUserPrompt({ attempt, maxAttempts, previousFailure }),
+            toolSet: {
+                ...buildRepairFileTools(toolContext),
+                ...(input.buildExtraTools?.(toolContext) ?? {}),
+            },
+            stepBudget,
+            telemetryTags: input.telemetryTags,
+            abortSignal: input.abortSignal,
+        }));
+        if (result.stopReason === 'error') {
+            lastFailure = result.error?.message ?? 'repair agent loop errored';
+            previousFailure = lastFailure;
+            await input.trace.event('error', input.tracePhase, `${input.traceEventName}_failed`, traceData, result.error);
+            continue;
+        }
+        const changedPaths = [...editedPaths].sort();
+        if (changedPaths.length === 0 && noChangeDeclaration === null) {
+            // Nothing changed and nothing was claimed: the failed check would fail
+            // identically, so skip verification and retry.
+            lastFailure = input.noChangeFailureReason;
+            previousFailure = lastFailure;
+            await input.trace.event('error', input.tracePhase, `${input.traceEventName}_failed`, {
+                ...traceData,
+                reason: lastFailure,
+            });
+            continue;
+        }
+        const verification = await input.verify(changedPaths);
+        if (!verification.ok) {
+            lastFailure = verification.reason;
+            previousFailure = lastFailure;
+            await input.trace.event('error', input.tracePhase, `${input.traceEventName}_failed`, {
+                ...traceData,
+                changedPaths,
+                reason: lastFailure,
+            });
+            continue;
+        }
+        await input.trace.event('debug', input.tracePhase, `${input.traceEventName}_repaired`, {
+            ...traceData,
+            changedPaths,
+            ...(noChangeDeclaration !== null ? { noChangeDeclaration } : {}),
+        });
+        return { status: 'repaired', attempts: attempt, changedPaths };
+    }
+    return { status: 'failed', attempts: maxAttempts, reason: lastFailure };
+}