@cat-factory/executor-harness 1.31.0 → 1.31.6

package/dist/blueprint.js

@@ -1,367 +0,0 @@
-import { createHash } from 'node:crypto';
-import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { cloneRepo, commitAll, pushBranch } from './git.js';
-import { agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, unusableFinalAnswerCause, withWorkspace, } from './pi-workspace.js';
-import { diagnosticsSuffix, resolveStructuredOutput, } from './structured-output.js';
-import { log } from './logger.js';
-/** Compact description of the blueprint-tree shape, fed to the JSON repair call. */
-const BLUEPRINT_SHAPE_HINT = 'Expected a service tree: {"type": string, "name": string, "summary": string, ' +
-    '"references": string[], "modules": [{"name": string, "summary": string, ' +
-    '"references": string[]}]}.';
-// Runs one "service blueprint" job end to end. The Blueprinter agent gets a fresh
-// clone of the target branch, (re)decomposes the repository into the canonical
-// service → modules tree, and the harness deterministically renders that tree into
-// the in-repo `blueprints/` folder (a machine-readable `blueprint.json` plus a
-// high-level `overview.md` and one deep-dive markdown per module), then commits the
-// result back onto the same branch. The tree is also returned to the Worker so it
-// can persist + reconcile the board from it.
-//
-// Mirrors handleBootstrap's secret handling and watchdog wiring: the per-job
-// GitHub + proxy tokens arrive in the request body and live only for the job's
-// duration in an ephemeral workspace; `opts` carry the watchdog signal and the
-// progress callback so the Worker can poll live "N/M done" subtask counts.
-// The folder + file layout, kept in lockstep with @cat-factory/contracts
-// (BLUEPRINT_DIR / BLUEPRINT_JSON_PATH / …). Duplicated here because the harness
-// image is deliberately self-contained (no @cat-factory/contracts dependency).
-const BLUEPRINT_DIR = 'blueprints';
-const BLUEPRINT_JSON_PATH = `${BLUEPRINT_DIR}/blueprint.json`;
-const BLUEPRINT_OVERVIEW_PATH = `${BLUEPRINT_DIR}/overview.md`;
-const BLUEPRINT_MODULES_DIR = `${BLUEPRINT_DIR}/modules`;
-/** Tiny manifest read for quick staleness checks without parsing the full tree. */
-const BLUEPRINT_VERSION_PATH = `${BLUEPRINT_DIR}/version.json`;
-// Coercion limits, mirroring core's board-scan.logic so a committed blueprint can
-// never balloon past what the board/schema accept.
-const MAX_MODULES = 40;
-const MAX_REFERENCES = 40;
-const BLOCK_TYPES = [
-    'frontend',
-    'service',
-    'api',
-    'database',
-    'queue',
-    'integration',
-    'external',
-    'environment',
-];
-function asString(value) {
-    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
-}
-function coerceReferences(value) {
-    if (!Array.isArray(value))
-        return [];
-    const seen = new Set();
-    for (const raw of value) {
-        const path = asString(raw);
-        if (path)
-            seen.add(path);
-        if (seen.size >= MAX_REFERENCES)
-            break;
-    }
-    return [...seen];
-}
-function coerceModule(value) {
-    if (typeof value !== 'object' || value === null)
-        return null;
-    const obj = value;
-    const name = asString(obj.name);
-    if (!name)
-        return null;
-    return {
-        name,
-        summary: asString(obj.summary) ?? '',
-        references: coerceReferences(obj.references),
-    };
-}
-/**
- * Coerce an agent's parsed JSON into a well-formed {@link BlueprintServiceTree},
- * dropping anything malformed. Returns null when no usable service name remains.
- * Tolerates either a bare service object or `{ service: {...} }`. Mirrors core's
- * `coerceService`; the Worker re-validates the returned tree against the strict
- * Valibot schema before it touches the board.
- */
-export function coerceService(parsed, fallbackName) {
-    if (typeof parsed !== 'object' || parsed === null)
-        return null;
-    const root = parsed;
-    const obj = typeof root.service === 'object' && root.service !== null
-        ? root.service
-        : root;
-    const name = asString(obj.name) ?? asString(fallbackName);
-    if (!name)
-        return null;
-    const type = BLOCK_TYPES.includes(obj.type)
-        ? obj.type
-        : 'service';
-    const modules = (Array.isArray(obj.modules) ? obj.modules : [])
-        .map(coerceModule)
-        .filter((m) => m !== null)
-        .slice(0, MAX_MODULES);
-    return {
-        type,
-        name,
-        summary: asString(obj.summary) ?? '',
-        references: coerceReferences(obj.references),
-        modules,
-    };
-}
-/** Turn a module name into a stable, filesystem-safe slug for its deep-dive file. */
-export function moduleSlug(name) {
-    const slug = name
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-    return slug || 'module';
-}
-/** The exact canonical JSON bytes written to `blueprint.json` (and hashed). */
-export function canonicalBlueprintJson(service) {
-    return `${JSON.stringify(service, null, 2)}\n`;
-}
-/** A stable content hash of the blueprint tree, used for quick staleness checks. */
-export function hashBlueprint(service) {
-    return createHash('sha256').update(canonicalBlueprintJson(service)).digest('hex');
-}
-/** Render the lightweight `version.json` manifest for `service`. */
-export function renderVersionFile(service, meta) {
-    const manifest = {
-        version: meta.version,
-        generatedAt: meta.generatedAt,
-        hash: hashBlueprint(service),
-        modules: service.modules.length,
-    };
-    return { path: BLUEPRINT_VERSION_PATH, content: `${JSON.stringify(manifest, null, 2)}\n` };
-}
-function renderReferences(references) {
-    if (references.length === 0)
-        return [];
-    return ['', '**Code references:**', ...references.map((r) => `- \`${r}\``)];
-}
-/**
- * Deterministically render a blueprint tree into the in-repo artifact files: the
- * canonical `blueprint.json`, a high-level `overview.md` (service + each module
- * with a one-line summary — what agents read first), and one `modules/<slug>.md`
- * deep-dive per module (summary + code references — read only when a task touches
- * that module). Pure: same tree → same bytes.
- */
-export function renderBlueprintFiles(service) {
-    const files = [];
-    // Canonical machine-readable tree (trailing newline for clean diffs).
-    files.push({ path: BLUEPRINT_JSON_PATH, content: canonicalBlueprintJson(service) });
-    // High-level overview — the default read.
-    const overview = [`# ${service.name}`, ''];
-    overview.push('> Generated service blueprint. Read this overview first for the');
-    overview.push('> high-level structure; open `modules/<name>.md` only for a module');
-    overview.push('> directly relevant to your task.');
-    overview.push('');
-    if (service.summary)
-        overview.push(service.summary, '');
-    if (service.modules.length === 0) {
-        overview.push('_No modules mapped yet._');
-    }
-    else {
-        overview.push('## Modules', '');
-        for (const m of service.modules) {
-            const slug = moduleSlug(m.name);
-            overview.push(`### [${m.name}](modules/${slug}.md)`);
-            if (m.summary)
-                overview.push('', m.summary);
-            overview.push('');
-        }
-    }
-    files.push({ path: BLUEPRINT_OVERVIEW_PATH, content: `${overview.join('\n').trimEnd()}\n` });
-    // Per-module deep dives — the drill-down layer.
-    for (const m of service.modules) {
-        const slug = moduleSlug(m.name);
-        const lines = [`# ${m.name}`, ''];
-        if (m.summary)
-            lines.push(m.summary, '');
-        lines.push(...renderReferences(m.references));
-        files.push({
-            path: `${BLUEPRINT_MODULES_DIR}/${slug}.md`,
-            content: `${lines.join('\n').trimEnd()}\n`,
-        });
-    }
-    return files;
-}
-/** Read + parse the existing canonical blueprint, if any (for an `update` run). */
-async function readExistingBlueprint(dir, fallbackName) {
-    try {
-        const raw = await readFile(join(dir, BLUEPRINT_JSON_PATH), 'utf8');
-        // A hand-edited file that no longer parses is treated as absent (regenerate),
-        // mirroring the strict re-validation the Worker applies on ingest.
-        return coerceService(JSON.parse(raw), fallbackName);
-    }
-    catch {
-        return null;
-    }
-}
-/** Read the prior version manifest, if any (to bump the counter / detect no-ops). */
-async function readExistingVersion(dir) {
-    try {
-        const raw = await readFile(join(dir, BLUEPRINT_VERSION_PATH), 'utf8');
-        const parsed = JSON.parse(raw);
-        if (typeof parsed.version !== 'number' || typeof parsed.hash !== 'string')
-            return null;
-        return {
-            version: parsed.version,
-            generatedAt: typeof parsed.generatedAt === 'string' ? parsed.generatedAt : '',
-            hash: parsed.hash,
-            modules: typeof parsed.modules === 'number' ? parsed.modules : 0,
-        };
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Decide the version manifest for a freshly generated tree: when the content is
- * byte-identical to the previous generation, the version + timestamp are kept (so
- * an unchanged blueprint produces no diff and no commit); otherwise the counter is
- * bumped and the timestamp refreshed.
- */
-export function nextVersion(service, previous, now) {
-    if (previous && previous.hash === hashBlueprint(service)) {
-        return { version: previous.version, generatedAt: previous.generatedAt };
-    }
-    return { version: (previous?.version ?? 0) + 1, generatedAt: now.toISOString() };
-}
-/** Extract the first JSON object from an agent's final message (tolerating fences/prose). */
-export function extractJsonObject(text) {
-    const trimmed = text.trim();
-    // Strip a single ```json … ``` (or ``` … ```) fence if the whole reply is fenced.
-    const fenced = /^```(?:json)?\s*([\s\S]*?)\s*```$/i.exec(trimmed);
-    const body = fenced ? (fenced[1] ?? '') : trimmed;
-    try {
-        return JSON.parse(body);
-    }
-    catch {
-        // Fall back to the first balanced { … } span in the text.
-        const start = body.indexOf('{');
-        const end = body.lastIndexOf('}');
-        if (start === -1 || end === -1 || end <= start) {
-            throw new Error('agent did not return a JSON object');
-        }
-        return JSON.parse(body.slice(start, end + 1));
-    }
-}
-/** Compose the task prompt: the worker's guidance plus any prior tree to refine. */
-function buildUserPrompt(job, existing) {
-    const lines = [job.instructions.trim()];
-    if (job.mode === 'update' && existing) {
-        lines.push('', 'An existing blueprint is present. Update it to reflect the current code:', 'keep accurate modules, add new ones, refine summaries and code', 'references. Return the COMPLETE updated tree (not a diff).', '', 'Existing blueprint:', '```json', JSON.stringify(existing, null, 2), '```');
-    }
-    lines.push('', 'Respond with ONLY the JSON object for the service tree — no prose, no code fences.');
-    return lines.join('\n');
-}
-/** Write the rendered files under `dir`, replacing any previous `blueprints/` folder. */
-async function writeBlueprintFiles(dir, files) {
-    // The whole folder is a generated artifact: wipe it first so a module removed
-    // from the tree doesn't leave a stale deep-dive file behind.
-    await rm(join(dir, BLUEPRINT_DIR), { recursive: true, force: true });
-    for (const file of files) {
-        const abs = join(dir, file.path);
-        await mkdir(dirname(abs), { recursive: true });
-        await writeFile(abs, file.content, 'utf8');
-    }
-}
-/** Run one blueprint job end to end. */
-export async function handleBlueprint(job, opts = {}) {
-    const { signal } = opts;
-    const trace = { jobId: job.jobId, repo: `${job.repo.owner}/${job.repo.name}`, branch: job.branch };
-    return withWorkspace('blueprint', async (dir) => {
-        log.info('blueprint: cloning target branch', trace);
-        await cloneRepo({
-            repo: { ...job.repo, baseBranch: job.branch },
-            ghToken: job.ghToken,
-            dir,
-            signal,
-        });
-        const existing = job.mode === 'update' ? await readExistingBlueprint(dir, job.repo.name) : null;
-        // The prior version manifest is read regardless of mode so the counter keeps
-        // climbing across runs (and an unchanged tree stays at the same version).
-        const previousVersion = await readExistingVersion(dir);
-        log.info('blueprint: running agent', { ...trace, mode: job.mode });
-        const { summary, stats, stderrTail, usage, diagnostics: runDiag, } = await runAgentInWorkspace({
-            dir,
-            systemPrompt: job.systemPrompt,
-            userPrompt: buildUserPrompt(job, existing),
-            model: job.model,
-            harness: job.harness,
-            subscriptionToken: job.subscriptionToken,
-            subscriptionBaseUrl: job.subscriptionBaseUrl,
-            proxyBaseUrl: job.proxyBaseUrl,
-            sessionToken: job.sessionToken,
-            // The Blueprinter explores the repo and RETURNS the service tree as JSON —
-            // the harness renders + commits the `blueprints/` files (below), the agent
-            // itself never calls an edit/write tool. So the no-edit guard must be off
-            // (like the merger), or mapping a non-trivial repo would trip it after many
-            // read calls and kill the run before it could emit the tree.
-            expectsEdits: false,
-        }, opts);
-        // The tree is HANDED OFF to be reconciled onto the board (and reviewed), so an
-        // unusable final answer (cut off at the ceiling, or an empty completion) fails
-        // loudly here rather than being laundered into a half tree by the repair below —
-        // the same opt-in document-producer guard the spec-writer uses.
-        const unusable = unusableFinalAnswerCause(runDiag);
-        if (unusable) {
-            log.warn('blueprint: unusable final answer', { ...trace, ...stats, ...runDiag });
-            return {
-                summary,
-                stats,
-                error: `the blueprint agent did not return a usable service tree: ${unusable}.${agentOutputTail(stderrTail, summary)}`,
-                ...(usage ? { usage } : {}),
-            };
-        }
-        // Parse the agent's tree; on a malformed reply, make ONE structured repair call
-        // (see json-repair) before giving up. The failure + repair outcome are logged and
-        // folded into the failure reason for observability.
-        const { value: service, diagnostics } = await resolveStructuredOutput({
-            label: 'blueprint',
-            shapeHint: BLUEPRINT_SHAPE_HINT,
-            parse: (text) => coerceService(extractJsonObject(text), job.repo.name),
-        }, summary, {
-            harness: job.harness,
-            subscriptionToken: job.subscriptionToken,
-            subscriptionBaseUrl: job.subscriptionBaseUrl,
-            proxyBaseUrl: job.proxyBaseUrl,
-            sessionToken: job.sessionToken,
-            model: job.model,
-            jobId: job.jobId,
-            signal,
-        });
-        if (!service) {
-            return {
-                summary,
-                stats,
-                error: noBlueprintReason(stats, summary, stderrTail, diagnostics),
-                ...(usage ? { usage } : {}),
-            };
-        }
-        const version = nextVersion(service, previousVersion, new Date());
-        await writeBlueprintFiles(dir, [
-            ...renderBlueprintFiles(service),
-            renderVersionFile(service, version),
-        ]);
-        // Add one commit onto the branch (no history reset, no force). An unchanged
-        // blueprint produces no commit — we still return the tree so the board ingest
-        // is idempotent.
-        const message = job.mode === 'update' ? 'Update service blueprint' : 'Add service blueprint';
-        const committed = await commitAll(dir, message, signal);
-        if (committed) {
-            log.info('blueprint: pushing regenerated blueprint', { ...trace, ...stats });
-            await pushBranch(dir, job.branch, job.ghToken, signal);
-        }
-        else {
-            log.info('blueprint: no changes to push (blueprint unchanged)', trace);
-        }
-        return { service, summary, stats, ...(usage ? { usage } : {}) };
-    });
-}
-/** Human-readable reason a blueprint run produced no usable tree. */
-function noBlueprintReason(stats, summary, stderrTail, diagnostics) {
-    const cause = agentNeverActed(stats) ? NEVER_ACTED_CAUSE : '';
-    return (`the blueprint agent produced no usable decomposition ` +
-        `(tool calls: ${stats.toolCalls}, assistant output: ${stats.assistantChars} chars).${cause}` +
-        (diagnostics ? diagnosticsSuffix(diagnostics) : '') +
-        agentOutputTail(stderrTail, summary));
-}

package/dist/bootstrap.js

@@ -1,99 +0,0 @@
-import { readdir } from 'node:fs/promises';
-import { cloneRepo, hasAgentChanges, reinitAndPush } from './git.js';
-import { agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, withWorkspace, } from './pi-workspace.js';
-import { log } from './logger.js';
-/**
- * Whether the bootstrapper actually produced repository content, so a no-op run
- * (the agent never reached the model / never wrote anything) is failed rather
- * than force-pushed as an empty repo. With a reference architecture, "produced
- * content" means the agent changed the clone; scaffolding from scratch, it means
- * at least one file now exists in the working directory. (The harness writes its
- * prompt context to Pi's global `~/.pi/agent/AGENTS.md`, never into `dir`, so
- * nothing here needs to be filtered out as harness boilerplate.)
- */
-export async function producedRepoContent(dir, hasReference, signal) {
-    if (hasReference)
-        return hasAgentChanges(dir, signal);
-    const entries = await readdir(dir, { recursive: true, withFileTypes: true });
-    return entries.some((entry) => entry.isFile());
-}
-/** Human-readable no-op reason, embedding what the agent did so the cause is visible. */
-function noOpReason(hasReference, stats, summary, stderrTail) {
-    const what = hasReference
-        ? 'made no changes to the reference architecture'
-        : 'scaffolded no files';
-    const cause = agentNeverActed(stats) ? NEVER_ACTED_CAUSE : '';
-    return (`the bootstrapper agent ${what} ` +
-        `(tool calls: ${stats.toolCalls}, assistant output: ${stats.assistantChars} chars).${cause}` +
-        agentOutputTail(stderrTail, summary));
-}
-// Runs one repo-bootstrap job end to end. With a reference architecture: clone it
-// → the bootstrapper agent adapts it in place per the instructions. Without one:
-// start from an empty directory → the agent scaffolds the new service from the
-// instructions alone. Either way the result's history is reset to a single commit
-// and pushed to the new repository. Mirrors handleRun's secret handling: the
-// per-job GitHub + proxy tokens arrive in the request body and live only for the
-// job's duration in an ephemeral workspace. Like /run it is driven as a background
-// job: the `opts` carry the watchdog signal + the progress callback so the Worker
-// can poll live "N/M done" subtask counts and surface them on the board.
-/** Run one bootstrap job end to end. */
-export async function handleBootstrap(job, opts = {}) {
-    const { signal } = opts;
-    // The worker keys the background job on `jobId`; thread it through every log
-    // line so a bootstrap can be traced end to end in the Cloudflare dashboard.
-    const trace = { jobId: job.jobId, target: `${job.target.owner}/${job.target.name}` };
-    return withWorkspace('boot', async (dir) => {
-        if (job.reference) {
-            log.info('bootstrap: cloning reference architecture', {
-                ...trace,
-                reference: `${job.reference.owner}/${job.reference.name}`,
-            });
-            await cloneRepo({
-                repo: {
-                    owner: job.reference.owner,
-                    name: job.reference.name,
-                    baseBranch: job.reference.baseBranch,
-                    cloneUrl: job.reference.cloneUrl,
-                },
-                ghToken: job.ghToken,
-                dir,
-                signal,
-            });
-        }
-        else {
-            log.info('bootstrap: scaffolding from scratch (no reference)', trace);
-        }
-        log.info('bootstrap: running agent', trace);
-        const { summary, stats, stderrTail } = await runAgentInWorkspace({
-            dir,
-            systemPrompt: job.systemPrompt,
-            userPrompt: job.instructions,
-            model: job.model,
-            harness: job.harness,
-            subscriptionToken: job.subscriptionToken,
-            subscriptionBaseUrl: job.subscriptionBaseUrl,
-            proxyBaseUrl: job.proxyBaseUrl,
-            sessionToken: job.sessionToken,
-        }, opts);
-        // Guard against a no-op run: Pi can exit cleanly having done nothing (e.g. it
-        // never reached the model), and reinitAndPush would then force-push an empty
-        // tree — leaving the run "succeeded" but the repo bare. Fail with a structured
-        // error (carrying what the agent did) instead of pushing nothing.
-        if (!(await producedRepoContent(dir, !!job.reference, signal))) {
-            const error = noOpReason(!!job.reference, stats, summary, stderrTail);
-            log.error('bootstrap: agent produced no content — refusing to push', { ...trace, ...stats });
-            return { summary, stats, error };
-        }
-        log.info('bootstrap: force-pushing bootstrapped contents', { ...trace, ...stats });
-        await reinitAndPush({
-            dir,
-            target: job.target,
-            ghToken: job.ghToken,
-            message: job.reference
-                ? `Bootstrap from ${job.reference.owner}/${job.reference.name}`
-                : 'Bootstrap new repository',
-        });
-        log.info('bootstrap: complete', { ...trace, defaultBranch: job.target.defaultBranch });
-        return { defaultBranch: job.target.defaultBranch, summary, stats };
-    });
-}

package/dist/ci-fixer.js

@@ -1,46 +0,0 @@
-import { noChangesReason, runCodingAgent } from './coding-agent.js';
-// Async job execution for the CI-fixer. When a PR's CI is red the engine
-// dispatches this: clone the PR HEAD branch, run Pi to make the failing
-// build/tests pass, then commit + push back onto the SAME branch (no new branch,
-// no new PR) so CI re-runs. The engine re-polls CI after the push and loops the
-// fixer up to the task's attempt budget. A run that produced no change pushes
-// nothing and reports `pushed: false`.
-//
-// The clone/Pi/push mechanics are shared with implementation via runCodingAgent;
-// the CI-fixer only differs in working ON the existing PR branch (no new branch /
-// PR) and treating a no-op as non-fatal rather than an implementation failure.
-/** Run one CI-fixer job end to end: clone branch → Pi fixes → push (same branch). */
-export async function handleCiFixer(job, opts = {}) {
-    const { summary, stats, stderrTail, pushed, usage } = await runCodingAgent({
-        kind: 'ci-fix',
-        jobId: job.jobId,
-        repo: job.repo,
-        // Work directly on the PR head branch — no new branch, no new PR.
-        cloneBranch: job.branch,
-        pushBranch: job.branch,
-        ghToken: job.ghToken,
-        systemPrompt: job.systemPrompt,
-        userPrompt: job.userPrompt,
-        model: job.model,
-        harness: job.harness,
-        subscriptionToken: job.subscriptionToken,
-        subscriptionBaseUrl: job.subscriptionBaseUrl,
-        proxyBaseUrl: job.proxyBaseUrl,
-        sessionToken: job.sessionToken,
-        commitMessage: 'Fix failing CI',
-        webToolsGuidance: job.webToolsGuidance,
-        webSearchProxy: job.webSearch,
-    }, opts);
-    // Not an error: the engine re-checks CI regardless and loops/exhausts. We report
-    // `pushed: false` so the (unused) result is still meaningful.
-    if (!pushed) {
-        return {
-            pushed: false,
-            summary,
-            stats,
-            error: noChangesReason('No CI fix produced', stats, stderrTail),
-            ...(usage ? { usage } : {}),
-        };
-    }
-    return { pushed: true, summary, stats, ...(usage ? { usage } : {}) };
-}

package/dist/conflict-resolver.js

@@ -1,138 +0,0 @@
-import { cloneRepo, commitAll, conflictDiff, headCommit, mergeBranch, pushBranch, unmergedPaths, } from './git.js';
-import { agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, withWorkspace, } from './pi-workspace.js';
-import { log } from './logger.js';
-// Async job execution for the merge-conflict resolver. When a PR cannot be merged
-// because it conflicts with its base, the engine dispatches this: clone the PR head
-// branch (full history), merge the base branch into it to surface the conflicts,
-// run Pi to resolve them, complete the merge commit and push back onto the SAME
-// branch (no new branch / PR) so the PR becomes mergeable and CI re-runs.
-//
-// Shares the thin workspace/Pi base (withWorkspace + runAgentInWorkspace) with the
-// other agents; it diverges only in needing a full clone, a base→branch merge to
-// produce the conflicts, and a guard that refuses to push a half-resolved tree.
-/** Run one conflict-resolver job: clone → merge base → Pi resolves → push (same branch). */
-export async function handleConflictResolver(job, opts = {}) {
-    const { signal } = opts;
-    const trace = { jobId: job.jobId, repo: `${job.repo.owner}/${job.repo.name}`, branch: job.branch };
-    return withWorkspace('conflict', async (dir) => {
-        log.info('conflict: cloning PR branch (full history)', trace);
-        // Full clone so the merge base + `origin/<base>` are present for the merge.
-        await cloneRepo({
-            repo: { ...job.repo, baseBranch: job.branch },
-            ghToken: job.ghToken,
-            dir,
-            signal,
-            full: true,
-        });
-        const prTip = await headCommit(dir, signal);
-        log.info('conflict: merging base into PR branch', { ...trace, base: job.repo.baseBranch });
-        const clean = await mergeBranch(dir, job.repo.baseBranch, signal);
-        // No conflicts to resolve. If base brought new commits the merge advanced the
-        // branch, so push it; otherwise the branch is already up to date — a no-op we
-        // leave alone (re-dispatching it never changes the PR, so a gate that keeps
-        // seeing GitHub report this branch as "conflicting" is a base-resolution problem,
-        // not the agent's — logged here so that loop is diagnosable).
-        if (clean) {
-            if ((await headCommit(dir, signal)) === prTip) {
-                log.info('conflict: base merged clean and branch already up to date — nothing to push', {
-                    ...trace,
-                    base: job.repo.baseBranch,
-                });
-                return {
-                    resolved: true,
-                    summary: 'No conflicts: the branch is already up to date with its base.',
-                    stats: { toolCalls: 0, assistantChars: 0 },
-                };
-            }
-            log.info('conflict: base merged clean — pushing the merge commit', trace);
-            await pushBranch(dir, job.branch, job.ghToken, signal);
-            return {
-                resolved: true,
-                summary: 'Merged the base in cleanly (no conflicts to resolve).',
-                stats: { toolCalls: 0, assistantChars: 0 },
-            };
-        }
-        // The merge left conflicts in the working tree. Surface the EXACT files + hunks
-        // to the agent: the generic task prompt alone never told it which files conflict
-        // (or even that there were conflicts), so it would drift onto the original feature
-        // task. Lead with the conflict; keep the task only as trailing reference.
-        const conflicted = await unmergedPaths(dir, signal);
-        log.info('conflict: resolving conflicts with agent', { ...trace, conflicted });
-        const diff = await conflictDiff(dir, conflicted, signal);
-        const userPrompt = buildConflictPrompt(job.repo.baseBranch, job.branch, conflicted, diff, job.userPrompt);
-        const { summary, stats, stderrTail, usage } = await runAgentInWorkspace({
-            dir,
-            systemPrompt: job.systemPrompt,
-            userPrompt,
-            model: job.model,
-            harness: job.harness,
-            subscriptionToken: job.subscriptionToken,
-            subscriptionBaseUrl: job.subscriptionBaseUrl,
-            proxyBaseUrl: job.proxyBaseUrl,
-            sessionToken: job.sessionToken,
-        }, opts);
-        // Never push a half-resolved tree: if any conflict markers / unmerged paths
-        // remain, the PR would still be broken. Fail so the engine can retry / notify.
-        const unresolved = await unmergedPaths(dir, signal);
-        if (unresolved.length > 0) {
-            log.error('conflict: unresolved conflicts remain — refusing to push', {
-                ...trace,
-                unresolved: unresolved.length,
-            });
-            return {
-                resolved: false,
-                summary,
-                stats,
-                error: unresolvedReason(unresolved, stats, stderrTail),
-                ...(usage ? { usage } : {}),
-            };
-        }
-        // Complete the merge commit with the agent's resolution staged, then push.
-        await commitAll(dir, `Merge ${job.repo.baseBranch} into ${job.branch}`, signal);
-        log.info('conflict: pushing resolved branch', { ...trace, ...stats });
-        await pushBranch(dir, job.branch, job.ghToken, signal);
-        return { resolved: true, summary, stats, ...(usage ? { usage } : {}) };
-    });
-}
-/**
- * The conflict-focused user prompt: lead with the exact conflicted files and their
- * hunks (so the model acts on the real conflict, not the original feature task), then
- * carry the task only as trailing reference. The role/system prompt frames it as a
- * merge-conflict resolution; this gives it the concrete material.
- */
-function buildConflictPrompt(baseBranch, prBranch, conflicted, diff, taskReference) {
-    const fileList = conflicted.map((p) => `- ${p}`).join('\n');
-    const parts = [
-        `The base branch \`${baseBranch}\` was merged into this pull-request branch ` +
-            `\`${prBranch}\` and left Git merge conflicts in the following ${conflicted.length} ` +
-            `file(s):`,
-        '',
-        fileList,
-        '',
-        'Resolve EVERY conflict in these files: open each one, understand both sides of each ' +
-            '`<<<<<<<` / `=======` / `>>>>>>>` region, and edit it to a correct result that ' +
-            "preserves the intent of BOTH the base changes and this PR's changes — never just " +
-            'discard one side. Remove every conflict marker and leave the project building. Do ' +
-            'not create a new branch or PR; the harness completes the merge commit and pushes once ' +
-            'no conflict markers remain.',
-        '',
-        'Conflict hunks (`git diff` of the conflicted files):',
-        '',
-        '```diff',
-        diff,
-        '```',
-    ];
-    const ref = taskReference.trim();
-    if (ref) {
-        parts.push('', 'For reference, the task this pull request implements:', '', ref);
-    }
-    return parts.join('\n');
-}
-/** Human-readable reason the agent failed to fully resolve the conflicts. */
-function unresolvedReason(unresolved, stats, stderrTail) {
-    const cause = agentNeverActed(stats) ? NEVER_ACTED_CAUSE : '';
-    const sample = unresolved.slice(0, 10).join(', ');
-    return (`The agent did not resolve all merge conflicts ` +
-        `(${unresolved.length} file(s) still conflicted: ${sample}).${cause}` +
-        agentOutputTail(stderrTail));
-}