@ai-sdlc/orchestrator 0.5.0 → 0.9.0

package/dist/runners/claude-code.js

@@ -2,14 +2,35 @@
  * Claude Code runner — invokes Claude Code CLI in --print mode
  * and collects the result via git diff.
  */
-import { spawn, execFile } from 'node:child_process';
-import { promisify } from 'node:util';
+import { spawn } from 'node:child_process';
 import { DEFAULT_MODEL, DEFAULT_ALLOWED_TOOLS, DEFAULT_RUNNER_TIMEOUT_MS, DEFAULT_LINT_COMMAND, DEFAULT_FORMAT_COMMAND, DEFAULT_COMMIT_MESSAGE_TEMPLATE, DEFAULT_COMMIT_CO_AUTHOR, } from '../defaults.js';
 import { formatContextForPrompt } from '../analysis/context-builder.js';
-const execFileAsync = promisify(execFile);
+import { gitExec, detectChangedFiles, runAutoFix, snapshotWorktree, detectCrossRepoWrites, } from './git-utils.js';
+/**
+ * Build verification step instructions (lint, format, typecheck).
+ * Returns an array of numbered step strings starting from the given step number.
+ */
+function buildVerificationSteps(startStep, lintCmd, fmtCmd, typecheckCmd) {
+    let step = startStep;
+    const lines = [];
+    if (lintCmd && fmtCmd) {
+        lines.push(`${++step}. After making code changes, run \`${lintCmd}\` and \`${fmtCmd}\` to catch issues before committing.`);
+    }
+    else if (lintCmd) {
+        lines.push(`${++step}. After making code changes, run \`${lintCmd}\` to catch issues before committing.`);
+    }
+    else if (fmtCmd) {
+        lines.push(`${++step}. After making code changes, run \`${fmtCmd}\` to catch issues before committing.`);
+    }
+    if (typecheckCmd) {
+        lines.push(`${++step}. IMPORTANT: Run \`${typecheckCmd}\` to verify there are no TypeScript errors. The pre-commit hook will reject your commit if there are type errors. Fix ALL type errors before committing.`);
+    }
+    return { lines, nextStep: step };
+}
 export function buildPrompt(ctx) {
     const lintCmd = ctx.lintCommand ?? DEFAULT_LINT_COMMAND;
     const fmtCmd = ctx.formatCommand ?? DEFAULT_FORMAT_COMMAND;
+    const typecheckCmd = ctx.typecheckCommand;
     const lines = [
         `You are fixing issue ${/^\d+$/.test(ctx.issueId) ? '#' : ''}${ctx.issueId}: ${ctx.issueTitle}`,
         '',
@@ -23,29 +44,25 @@ export function buildPrompt(ctx) {
         if (fmtCmd) {
             lines.push(`${++step}. If the failure is a formatting/prettier error, run \`${fmtCmd}\` to auto-fix it.`);
         }
-        if (lintCmd && fmtCmd) {
-            lines.push(`${++step}. After making ANY code changes, always run \`${lintCmd}\` and \`${fmtCmd}\` to catch issues before committing.`);
-        }
-        else if (lintCmd) {
-            lines.push(`${++step}. After making ANY code changes, always run \`${lintCmd}\` to catch issues before committing.`);
-        }
-        else if (fmtCmd) {
-            lines.push(`${++step}. After making ANY code changes, always run \`${fmtCmd}\` to catch issues before committing.`);
-        }
+        const ciVerify = buildVerificationSteps(step, lintCmd, fmtCmd, typecheckCmd);
+        lines.push(...ciVerify.lines);
+        step = ciVerify.nextStep;
         lines.push(`${++step}. Write or update tests if needed to cover your fix.`, `${++step}. NEVER modify files matching the blocked paths below — violations will be automatically detected and the change will be rejected.`, `${++step}. Keep your changes to at most ${ctx.constraints.maxFilesPerChange} files.`);
     }
+    else if (ctx.reviewFindings) {
+        let step = 0;
+        lines.push('## Review Findings', '', ctx.reviewFindings, '', '## Instructions', `${++step}. Read the review findings above carefully.`, `${++step}. Read the relevant source files to understand the context.`, `${++step}. Address all the review findings by making necessary code changes.`, `${++step}. Write or update tests if requested by the reviewers.`);
+        const reviewVerify = buildVerificationSteps(step, lintCmd, fmtCmd, typecheckCmd);
+        lines.push(...reviewVerify.lines);
+        step = reviewVerify.nextStep;
+        lines.push(`${++step}. NEVER modify files matching the blocked paths below — violations will be automatically detected and the change will be rejected.`, `${++step}. Keep your changes to at most ${ctx.constraints.maxFilesPerChange} files.`);
+    }
     else {
         let step = 0;
         lines.push('## Instructions', `${++step}. Read the relevant source files to understand the codebase.`, `${++step}. Implement the fix or feature described in the issue.`, `${++step}. Write or update tests to cover your changes.`);
-        if (lintCmd && fmtCmd) {
-            lines.push(`${++step}. After making code changes, run \`${lintCmd}\` and \`${fmtCmd}\` to ensure CI will pass.`);
-        }
-        else if (lintCmd) {
-            lines.push(`${++step}. After making code changes, run \`${lintCmd}\` to ensure CI will pass.`);
-        }
-        else if (fmtCmd) {
-            lines.push(`${++step}. After making code changes, run \`${fmtCmd}\` to ensure CI will pass.`);
-        }
+        const defaultVerify = buildVerificationSteps(step, lintCmd, fmtCmd, typecheckCmd);
+        lines.push(...defaultVerify.lines);
+        step = defaultVerify.nextStep;
         lines.push(`${++step}. NEVER modify files matching the blocked paths below — violations will be automatically detected and the change will be rejected.`, `${++step}. Keep your changes to at most ${ctx.constraints.maxFilesPerChange} files.`);
     }
     lines.push('', '## Constraints (enforced — violations will be automatically rejected)', `- Maximum files to change: ${ctx.constraints.maxFilesPerChange}`, `- Tests required: ${ctx.constraints.requireTests}`, `- Blocked paths (NEVER modify — changes will be rejected): ${ctx.constraints.blockedPaths.join(', ') || 'none'}`);
@@ -72,20 +89,161 @@ export function buildPrompt(ctx) {
     }
     return lines.join('\n');
 }
-async function gitExec(workDir, args) {
-    const { stdout } = await execFileAsync('git', args, { cwd: workDir });
-    return stdout.trim();
+/**
+ * Format a stream-json event into a concise, human-readable log line.
+ */
+function formatEventForLog(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    const type = parsed.type;
+    if (type === 'system') {
+        return `init session=${parsed.session_id?.slice(0, 8)}`;
+    }
+    if (type === 'assistant') {
+        const message = parsed.message;
+        const content = message?.content;
+        if (!content?.length)
+            return null;
+        const parts = [];
+        for (const block of content) {
+            if (block.type === 'thinking') {
+                const text = String(block.thinking ?? '');
+                parts.push(`thinking: ${text.slice(0, 120)}${text.length > 120 ? '...' : ''}`);
+            }
+            else if (block.type === 'text') {
+                const text = String(block.text ?? '');
+                parts.push(`text: ${text.slice(0, 120)}${text.length > 120 ? '...' : ''}`);
+            }
+            else if (block.type === 'tool_use') {
+                const name = String(block.name ?? '');
+                const input = (block.input ?? {});
+                const file = extractFilePath(input);
+                parts.push(file ? `${name}: ${file}` : name);
+            }
+        }
+        return parts.join(' | ');
+    }
+    if (type === 'user') {
+        const message = parsed.message;
+        const content = message?.content;
+        if (!content?.length)
+            return null;
+        const block = content[0];
+        if (block.type === 'tool_result') {
+            const text = String(block.content ?? '');
+            const truncated = text.slice(0, 80);
+            return `result: ${truncated}${text.length > 80 ? '...' : ''}`;
+        }
+        return null;
+    }
+    if (type === 'result') {
+        const cost = parsed.total_cost_usd;
+        const turns = parsed.num_turns;
+        const duration = parsed.duration_ms;
+        return `done — ${turns ?? '?'} turns, ${duration ? Math.round(duration / 1000) + 's' : '?'}, $${cost?.toFixed(4) ?? '?'}`;
+    }
+    return null;
+}
+/**
+ * Extract a file path from a tool_use input object.
+ */
+function extractFilePath(input) {
+    return ((typeof input.file_path === 'string' ? input.file_path : undefined) ??
+        (typeof input.path === 'string' ? input.path : undefined) ??
+        (typeof input.pattern === 'string' ? input.pattern : undefined) ??
+        (typeof input.command === 'string' ? input.command.slice(0, 80) : undefined));
+}
+/**
+ * Parse a single NDJSON line from Claude Code stream-json output
+ * and emit a progress event if applicable.
+ */
+function parseStreamEvent(line, onProgress) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    const type = parsed.type;
+    if (type === 'assistant') {
+        const message = parsed.message;
+        const content = message?.content;
+        if (!content)
+            return undefined;
+        for (const block of content) {
+            if (block.type === 'tool_use') {
+                const toolName = String(block.name ?? '');
+                const input = (block.input ?? {});
+                const filePath = extractFilePath(input);
+                onProgress({
+                    type: 'tool_start',
+                    tool: toolName,
+                    file: filePath,
+                    message: filePath ? `${toolName}: ${filePath}` : toolName,
+                });
+            }
+            else if (block.type === 'text') {
+                const text = String(block.text ?? '');
+                if (text.length > 0) {
+                    onProgress({
+                        type: 'text',
+                        message: text.slice(0, 200),
+                    });
+                }
+            }
+        }
+    }
+    if (type === 'result') {
+        const resultText = parsed.result;
+        const costUsd = parsed.total_cost_usd;
+        // Extract token usage from result event
+        const modelUsage = parsed.modelUsage;
+        let tokenUsage;
+        if (modelUsage) {
+            const firstModel = Object.keys(modelUsage)[0];
+            if (firstModel) {
+                const usage = modelUsage[firstModel];
+                tokenUsage = {
+                    inputTokens: usage.inputTokens ?? 0,
+                    outputTokens: usage.outputTokens ?? 0,
+                    cacheReadTokens: usage.cacheReadInputTokens ?? undefined,
+                    model: firstModel,
+                };
+            }
+        }
+        if (costUsd !== undefined) {
+            onProgress({ type: 'cost', costUsd, message: `Total cost: $${costUsd.toFixed(4)}` });
+        }
+        return { resultText: resultText ?? undefined, costUsd, tokenUsage };
+    }
+    return undefined;
 }
 function runClaude(prompt, workDir, opts) {
     const tools = opts?.allowedTools?.join(',') ?? DEFAULT_ALLOWED_TOOLS;
     const timeoutMs = opts?.timeoutMs ?? DEFAULT_RUNNER_TIMEOUT_MS;
     return new Promise((resolve, reject) => {
         const model = opts?.model ?? process.env.AI_SDLC_MODEL ?? DEFAULT_MODEL;
-        const claudeArgs = ['-p', '--model', model, '--allowedTools', tools];
-        // When running inside an OpenShell sandbox, prefix with sandbox connect
+        const claudeArgs = [
+            '-p',
+            '--output-format',
+            'stream-json',
+            '--verbose',
+            '--model',
+            model,
+            '--allowedTools',
+            tools,
+        ];
+        // When running inside an OpenShell sandbox, prefix with sandbox connect.
+        const useOpenShell = opts?.sandboxId && process.env.AI_SDLC_SANDBOX_PROVIDER === 'openshell';
         let cmd;
         let args;
-        if (opts?.sandboxId) {
+        if (useOpenShell) {
             cmd = 'openshell';
             args = ['sandbox', 'connect', opts.sandboxId, '--', 'claude', ...claudeArgs];
         }
@@ -93,27 +251,114 @@ function runClaude(prompt, workDir, opts) {
             cmd = 'claude';
             args = claudeArgs;
         }
+        const startTime = Date.now();
+        const logPrefix = `[ai-sdlc:runner]`;
+        process.stderr.write(`${logPrefix} spawning: ${cmd} ${args.join(' ')}\n`);
+        process.stderr.write(`${logPrefix} workDir: ${workDir}\n`);
+        process.stderr.write(`${logPrefix} timeout: ${timeoutMs}ms\n`);
         const child = spawn(cmd, args, {
             cwd: workDir,
             stdio: ['pipe', 'pipe', 'pipe'],
             env: { ...process.env },
             timeout: timeoutMs,
         });
-        const chunks = [];
+        process.stderr.write(`${logPrefix} pid: ${child.pid}\n`);
+        let lastActivity = Date.now();
+        let resultText;
+        let resultCost;
+        let resultTokenUsage;
+        // Buffer for incomplete NDJSON lines
+        let lineBuffer = '';
+        const onProgress = opts?.onProgress;
+        child.stdout.on('data', (data) => {
+            lastActivity = Date.now();
+            // Parse NDJSON lines from stream-json output
+            lineBuffer += data.toString('utf-8');
+            const lines = lineBuffer.split('\n');
+            // Keep the last (possibly incomplete) line in the buffer
+            lineBuffer = lines.pop() ?? '';
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                // Log formatted events to stderr for CI visibility
+                const formatted = formatEventForLog(trimmed);
+                if (formatted) {
+                    process.stderr.write(`${logPrefix} ${formatted}\n`);
+                }
+                if (onProgress) {
+                    const result = parseStreamEvent(trimmed, onProgress);
+                    if (result) {
+                        if (result.resultText !== undefined)
+                            resultText = result.resultText;
+                        if (result.costUsd !== undefined)
+                            resultCost = result.costUsd;
+                        if (result.tokenUsage)
+                            resultTokenUsage = result.tokenUsage;
+                    }
+                }
+                else {
+                    // Still parse result event even without progress callback
+                    try {
+                        const parsed = JSON.parse(trimmed);
+                        if (parsed.type === 'result') {
+                            resultText = parsed.result;
+                            resultCost = parsed.total_cost_usd;
+                            const modelUsage = parsed.modelUsage;
+                            if (modelUsage) {
+                                const firstModel = Object.keys(modelUsage)[0];
+                                if (firstModel) {
+                                    const usage = modelUsage[firstModel];
+                                    resultTokenUsage = {
+                                        inputTokens: usage.inputTokens ?? 0,
+                                        outputTokens: usage.outputTokens ?? 0,
+                                        cacheReadTokens: usage.cacheReadInputTokens ?? undefined,
+                                        model: firstModel,
+                                    };
+                                }
+                            }
+                        }
+                    }
+                    catch {
+                        // Not JSON — ignore
+                    }
+                }
+            }
+        });
         const errChunks = [];
-        child.stdout.on('data', (data) => chunks.push(data));
-        child.stderr.on('data', (data) => errChunks.push(data));
+        child.stderr.on('data', (data) => {
+            errChunks.push(data);
+            lastActivity = Date.now();
+            process.stderr.write(data);
+        });
+        // Heartbeat: log progress every 30s so CI knows the process is alive
+        const heartbeat = setInterval(() => {
+            const elapsed = Math.round((Date.now() - startTime) / 1000);
+            const idle = Math.round((Date.now() - lastActivity) / 1000);
+            process.stderr.write(`${logPrefix} heartbeat: ${elapsed}s elapsed, ${idle}s idle\n`);
+        }, 30_000);
         child.on('close', (code) => {
-            const stdout = Buffer.concat(chunks).toString('utf-8');
+            clearInterval(heartbeat);
+            const elapsed = Math.round((Date.now() - startTime) / 1000);
             const stderr = Buffer.concat(errChunks).toString('utf-8');
+            process.stderr.write(`${logPrefix} exited: code=${code} elapsed=${elapsed}s\n`);
             if (code === 0) {
-                resolve({ stdout, stderr, model });
+                resolve({
+                    stdout: resultText ?? '',
+                    stderr,
+                    model: resultTokenUsage?.model ?? model,
+                    costUsd: resultCost,
+                });
             }
             else {
-                reject(new Error(`claude exited with code ${code}: ${stderr || stdout}`));
+                reject(new Error(`claude exited with code ${code}: ${stderr || resultText || ''}`));
             }
         });
-        child.on('error', reject);
+        child.on('error', (err) => {
+            clearInterval(heartbeat);
+            process.stderr.write(`${logPrefix} spawn error: ${err.message}\n`);
+            reject(err);
+        });
         // Send prompt via stdin and close it
         child.stdin.write(prompt);
         child.stdin.end();
@@ -152,50 +397,28 @@ export function parseTokenUsage(stderr, model) {
 /**
  * Run lint --fix and format commands (best-effort) so pre-commit hooks pass.
  */
-async function runAutoFix(workDir, lintCmd, fmtCmd) {
-    if (fmtCmd) {
-        try {
-            const [bin, ...args] = fmtCmd.split(' ');
-            await execFileAsync(bin, args, { cwd: workDir });
-        }
-        catch {
-            // Format failures are non-fatal — the commit hook will catch remaining issues
-        }
-    }
-    if (lintCmd) {
-        try {
-            const [bin, ...args] = lintCmd.split(' ');
-            await execFileAsync(bin, args, { cwd: workDir });
-        }
-        catch {
-            // Lint --fix failures are non-fatal
-        }
-    }
-}
 export class ClaudeCodeRunner {
     async run(ctx) {
         const prompt = buildPrompt(ctx);
         try {
-            // Invoke Claude Code CLI in print mode, sending prompt via stdin
+            // Snapshot the worktree BEFORE invoking the agent so we can subtract any
+            // pre-existing untracked noise (sqlite working files, draft files the user
+            // hasn't decided to commit yet, in-flight edits) from the agent's diff.
+            // Without this, `git add` would sweep them into the agent's commit.
+            const baseline = await snapshotWorktree(ctx.workDir);
+            // Invoke Claude Code CLI with stream-json for real-time progress
             const result = await runClaude(prompt, ctx.workDir, {
                 allowedTools: ctx.allowedTools,
                 timeoutMs: ctx.timeoutMs,
                 model: ctx.model,
                 sandboxId: ctx.sandboxId,
+                onProgress: ctx.onProgress,
             });
-            // Parse token usage from stderr
+            // Token usage from stream-json result event (falls back to stderr parsing)
             const tokenUsage = parseTokenUsage(result.stderr, result.model);
-            // Collect changed files
-            const diffOutput = await gitExec(ctx.workDir, ['diff', '--name-only']);
-            const untrackedOutput = await gitExec(ctx.workDir, [
-                'ls-files',
-                '--others',
-                '--exclude-standard',
-            ]);
-            const filesChanged = [
-                ...diffOutput.split('\n').filter(Boolean),
-                ...untrackedOutput.split('\n').filter(Boolean),
-            ];
+            // Collect changed files (uncommitted + agent-committed), excluding
+            // pre-existing untracked noise.
+            const { filesChanged, agentAlreadyCommitted } = await detectChangedFiles(ctx.workDir, baseline);
             if (filesChanged.length === 0) {
                 return {
                     success: false,
@@ -205,14 +428,26 @@ export class ClaudeCodeRunner {
                     tokenUsage,
                 };
             }
-            // Stage, lint/format, and commit
-            await gitExec(ctx.workDir, ['add', '-A']);
+            // If the agent already committed, skip our commit step
+            if (agentAlreadyCommitted) {
+                return {
+                    success: true,
+                    filesChanged,
+                    summary: result.stdout.slice(0, 2000),
+                    tokenUsage,
+                };
+            }
+            // Stage only the files the agent touched (NOT `git add -A`, which
+            // would include pre-existing untracked noise per the AISDLC-68 incident).
+            await gitExec(ctx.workDir, ['add', '--', ...filesChanged]);
             // Run lint and format before committing to avoid pre-commit hook failures
             const lintCmd = ctx.lintCommand ?? DEFAULT_LINT_COMMAND;
             const fmtCmd = ctx.formatCommand ?? DEFAULT_FORMAT_COMMAND;
             await runAutoFix(ctx.workDir, lintCmd, fmtCmd);
-            // Re-stage after auto-fix may have modified files
-            await gitExec(ctx.workDir, ['add', '-A']);
+            // Re-stage the same set in case auto-fix re-modified them. Auto-fix should
+            // not touch files outside the agent's diff, but if it does, those changes
+            // are the user's problem to commit separately.
+            await gitExec(ctx.workDir, ['add', '--', ...filesChanged]);
             const tmpl = ctx.commitMessageTemplate ?? DEFAULT_COMMIT_MESSAGE_TEMPLATE;
             const coAuthor = ctx.commitCoAuthor ?? DEFAULT_COMMIT_CO_AUTHOR;
             const commitMsg = tmpl
@@ -222,11 +457,22 @@ export class ClaudeCodeRunner {
                 await gitExec(ctx.workDir, ['commit', '-m', `${commitMsg}\n\nCo-Authored-By: ${coAuthor}`]);
             }
             catch {
-                // Pre-commit hook may have auto-fixed files — re-stage and retry once
+                // Pre-commit hook may have auto-fixed files — re-stage the agent's
+                // file set and retry once.
                 await runAutoFix(ctx.workDir, lintCmd, fmtCmd);
-                await gitExec(ctx.workDir, ['add', '-A']);
+                await gitExec(ctx.workDir, ['add', '--', ...filesChanged]);
                 await gitExec(ctx.workDir, ['commit', '-m', `${commitMsg}\n\nCo-Authored-By: ${coAuthor}`]);
             }
+            // Detect cross-repo writes (e.g., agent edited files in ../sister-repo)
+            // and surface them as a stderr warning so the operator knows to commit
+            // them in the sibling repo separately. Not a hard failure — sometimes
+            // cross-repo work is intended (the AISDLC-68 docs sync, for example).
+            const crossRepoWrites = await detectCrossRepoWrites(ctx.workDir);
+            for (const write of crossRepoWrites) {
+                process.stderr.write(`[ai-sdlc:runner] WARNING: agent wrote ${write.files.length} file(s) into sibling repo ` +
+                    `${write.repoPath} — those changes are NOT in this PR. ` +
+                    `Files: ${write.files.slice(0, 5).join(', ')}${write.files.length > 5 ? ` (+${write.files.length - 5} more)` : ''}\n`);
+            }
             return {
                 success: true,
                 filesChanged,

package/dist/runners/codex.js

@@ -6,10 +6,13 @@ import { spawn, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { DEFAULT_RUNNER_TIMEOUT_MS, DEFAULT_CODEX_MODEL, DEFAULT_COMMIT_MESSAGE_TEMPLATE, DEFAULT_COMMIT_CO_AUTHOR, } from '../defaults.js';
 import { buildPrompt } from './claude-code.js';
+import { cleanGitEnv } from '../runtime/git-env.js';
 export { buildPrompt };
 const execFileAsync = promisify(execFile);
+// Strip GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE so git resolves against
+// `workDir`'s own .git rather than whatever a parent process leaked (AISDLC-72).
 async function gitExec(workDir, args) {
-    const { stdout } = await execFileAsync('git', args, { cwd: workDir });
+    const { stdout } = await execFileAsync('git', args, { cwd: workDir, env: cleanGitEnv() });
     return stdout.trim();
 }
 /**

package/dist/runners/copilot.js

@@ -6,10 +6,13 @@ import { spawn, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { DEFAULT_RUNNER_TIMEOUT_MS, DEFAULT_COPILOT_MODEL, DEFAULT_COMMIT_MESSAGE_TEMPLATE, DEFAULT_COMMIT_CO_AUTHOR, } from '../defaults.js';
 import { buildPrompt } from './claude-code.js';
+import { cleanGitEnv } from '../runtime/git-env.js';
 export { buildPrompt };
 const execFileAsync = promisify(execFile);
+// Strip GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE so git resolves against
+// `workDir`'s own .git rather than whatever a parent process leaked (AISDLC-72).
 async function gitExec(workDir, args) {
-    const { stdout } = await execFileAsync('git', args, { cwd: workDir });
+    const { stdout } = await execFileAsync('git', args, { cwd: workDir, env: cleanGitEnv() });
     return stdout.trim();
 }
 /**

package/dist/runners/cursor.js

@@ -6,10 +6,13 @@ import { spawn, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { DEFAULT_RUNNER_TIMEOUT_MS, DEFAULT_CURSOR_MODEL, DEFAULT_COMMIT_MESSAGE_TEMPLATE, DEFAULT_COMMIT_CO_AUTHOR, } from '../defaults.js';
 import { buildPrompt } from './claude-code.js';
+import { cleanGitEnv } from '../runtime/git-env.js';
 export { buildPrompt };
 const execFileAsync = promisify(execFile);
+// Strip GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE so git resolves against
+// `workDir`'s own .git rather than whatever a parent process leaked (AISDLC-72).
 async function gitExec(workDir, args) {
-    const { stdout } = await execFileAsync('git', args, { cwd: workDir });
+    const { stdout } = await execFileAsync('git', args, { cwd: workDir, env: cleanGitEnv() });
     return stdout.trim();
 }
 /**

package/dist/runners/git-utils.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Shared git utilities for agent runners.
+ */
+/**
+ * Run a git command in the given directory.
+ *
+ * Always passes `-c core.quotePath=false` so paths containing non-ASCII
+ * characters (e.g. ↔, é, 中) come back as raw UTF-8 instead of git's default
+ * octal-escaped form (`"file with \342\206\224.md"`). Without this, the AISDLC-68
+ * task file (which has ↔ in its name) showed up in `git diff --name-only`
+ * as a quoted+escaped string and the subsequent `git add -- <file>` rejected
+ * with "pathspec did not match".
+ *
+ * Uses `cleanGitEnv()` (AISDLC-72) so git resolves against `workDir`'s own
+ * .git rather than whatever a parent process (husky pre-push hook running
+ * in another worktree) leaked into GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE.
+ */
+export declare function gitExec(workDir: string, args: string[]): Promise<string>;
+export interface DetectedChanges {
+    filesChanged: string[];
+    agentAlreadyCommitted: boolean;
+}
+export interface WorktreeBaseline {
+    /** Set of paths that were untracked BEFORE the agent ran. */
+    untracked: Set<string>;
+    /** Set of paths that had unstaged modifications BEFORE the agent ran. */
+    modified: Set<string>;
+}
+/**
+ * Snapshot the untracked + modified file lists in the worktree. Captured before
+ * the agent runs so detectChangedFiles can subtract pre-existing noise (SQLite
+ * working files, draft RFCs the user hasn't decided to commit yet, in-flight
+ * edits on the previous branch). Without this, `git add -A` sweeps everything
+ * into the agent's commit (the AISDLC-68 incident).
+ *
+ * Failures degrade gracefully to an empty baseline — never block the pipeline
+ * because the snapshot couldn't run.
+ */
+export declare function snapshotWorktree(workDir: string): Promise<WorktreeBaseline>;
+/**
+ * Detect files changed by an agent. Three signals contribute:
+ *
+ *   - **Unstaged working-tree changes** (`git diff --name-only`)
+ *   - **Staged but uncommitted changes** (`git diff --name-only --cached`) — the
+ *     agent sometimes runs `git add` itself before yielding control. Without
+ *     this signal the orchestrator returned "Agent made no changes" and bailed
+ *     even though the agent's work was sitting in the index (the AISDLC-68
+ *     fourth-rerun bug).
+ *   - **Untracked files** (`git ls-files --others`)
+ *
+ * When `baseline` is provided, untracked files that existed BEFORE the agent
+ * ran are excluded — they belong to the user, not the agent's diff.
+ *
+ * Also checks whether the agent self-committed (compares HEAD to merge-base
+ * with origin/main). Self-committed runs short-circuit the orchestrator's
+ * commit step.
+ */
+export declare function detectChangedFiles(workDir: string, baseline?: WorktreeBaseline): Promise<DetectedChanges>;
+export interface CrossRepoWrite {
+    /** Sibling repository absolute path. */
+    repoPath: string;
+    /** Files modified or added in that sibling, relative to its root. */
+    files: string[];
+}
+/**
+ * Detect writes the agent made into sibling git repositories (i.e., directories
+ * adjacent to `workDir` that are themselves git repos). Surfaced as a warning,
+ * not a hard failure — the AISDLC-68 task LEGITIMATELY needed to sync into
+ * `../ai-sdlc-io/`, and we don't want to forbid that. The orchestrator just
+ * needs to surface that the changes exist so the operator knows to commit them
+ * separately in the sibling repo.
+ *
+ * Returns one entry per dirty sibling repo, with the list of changed files.
+ * Empty array when no siblings are dirty (the common case).
+ */
+export declare function detectCrossRepoWrites(workDir: string): Promise<CrossRepoWrite[]>;
+/**
+ * Run lint and format auto-fix commands (best-effort, non-fatal).
+ */
+export declare function runAutoFix(workDir: string, lintCmd?: string, fmtCmd?: string): Promise<void>;
+//# sourceMappingURL=git-utils.d.ts.map