@cat-factory/executor-harness 1.31.0

package/dist/job.js

@@ -0,0 +1,409 @@
+function str(value, path) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`Invalid job: '${path}' must be a non-empty string`);
+    }
+    return value;
+}
+/** A positive finite integer, or undefined for any other input (silently ignored). */
+function posInt(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0
+        ? Math.floor(value)
+        : undefined;
+}
+/**
+ * A valid TCP port (1..65535), or undefined for anything else. The backend already validates
+ * frontend ports against this range, but the harness re-checks at its untrusted-body boundary:
+ * an out-of-range value can never bind, so dropping it falls back to the harness default rather
+ * than spawning a server that fails to listen.
+ */
+function port(value) {
+    const n = posInt(value);
+    return n !== undefined && n <= 65535 ? n : undefined;
+}
+/**
+ * Parse the optional per-job progress-guard overrides. Each knob must be a positive
+ * int; a malformed value is dropped (the run keeps the env / default for that knob).
+ * This only validates the SHAPE — it does NOT enforce loosen-only. The loosen-only
+ * guarantee (an override can only raise a knob, never tighten it below the base) is
+ * applied later, where the override meets the base, by {@link mergeGuardLimits}. So a
+ * tighter-than-default value parses fine here and is clamped back up to the base there.
+ * Returns undefined when nothing usable was supplied so the job body stays sparse.
+ */
+function parseGuardLimits(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const o = value;
+    const spec = {};
+    const noEdit = posInt(o.maxToolCallsWithoutEdit);
+    const errors = posInt(o.maxConsecutiveErrors);
+    const web = posInt(o.maxConsecutiveWebCalls);
+    if (noEdit !== undefined)
+        spec.maxToolCallsWithoutEdit = noEdit;
+    if (errors !== undefined)
+        spec.maxConsecutiveErrors = errors;
+    if (web !== undefined)
+        spec.maxConsecutiveWebCalls = web;
+    return Object.keys(spec).length > 0 ? spec : undefined;
+}
+/**
+ * Parse the shared per-job auth fields, validating per harness: a subscription
+ * harness (`claude-code` / `codex`) requires `subscriptionToken`; the default Pi
+ * harness requires `proxyBaseUrl` + `sessionToken`.
+ */
+function parseHarnessAuth(o) {
+    const harness = o.harness === 'claude-code' || o.harness === 'codex' || o.harness === 'pi'
+        ? o.harness
+        : undefined;
+    if (harness === 'claude-code' || harness === 'codex') {
+        // Native ambient auth uses the developer's own CLI login, so no leased token is
+        // required (and none should be sent); otherwise the subscription token is mandatory.
+        const ambientAuth = o.ambientAuth === true;
+        return {
+            harness,
+            ...(ambientAuth
+                ? { ambientAuth: true }
+                : { subscriptionToken: str(o.subscriptionToken, 'subscriptionToken') }),
+            ...(typeof o.subscriptionBaseUrl === 'string' && o.subscriptionBaseUrl
+                ? { subscriptionBaseUrl: o.subscriptionBaseUrl }
+                : {}),
+        };
+    }
+    return {
+        harness,
+        proxyBaseUrl: str(o.proxyBaseUrl, 'proxyBaseUrl'),
+        sessionToken: str(o.sessionToken, 'sessionToken'),
+    };
+}
+/**
+ * Coerce a body-supplied monorepo service directory into a SAFE relative path, or
+ * undefined when absent/empty. Normalises separators, strips leading/trailing
+ * slashes, and rejects anything that could escape the checkout (absolute paths or a
+ * `..` segment) — the agent's cwd is built from this, so a hostile value must never
+ * point outside the cloned repo.
+ */
+function sanitizeServiceDirectory(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value
+        .trim()
+        .replace(/\\/g, '/')
+        .replace(/^\/+|\/+$/g, '');
+    if (!normalized)
+        return undefined;
+    const segments = normalized.split('/').filter((s) => s !== '' && s !== '.');
+    if (segments.length === 0)
+        return undefined;
+    if (segments.some((s) => s === '..')) {
+        throw new Error("Invalid job: 'repo.serviceDirectory' must be a path inside the repo");
+    }
+    return segments.join('/');
+}
+/** Parse the shared repo spec, including the optional monorepo service subdirectory. */
+function parseRepoSpec(repo) {
+    const spec = {
+        owner: str(repo.owner, 'repo.owner'),
+        name: str(repo.name, 'repo.name'),
+        baseBranch: str(repo.baseBranch, 'repo.baseBranch'),
+        cloneUrl: str(repo.cloneUrl, 'repo.cloneUrl'),
+    };
+    const provider = parseVcsProvider(repo.provider);
+    if (provider)
+        spec.provider = provider;
+    const dir = sanitizeServiceDirectory(repo.serviceDirectory);
+    if (dir)
+        spec.serviceDirectory = dir;
+    return spec;
+}
+/** Parse the optional `repo.provider` discriminator (defaults to undefined ⇒ host inference). */
+function parseVcsProvider(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (value === 'github' || value === 'gitlab')
+        return value;
+    throw new Error("Invalid job: 'repo.provider' must be 'github' or 'gitlab'");
+}
+// ---- Host allowlist -------------------------------------------------------
+// The short-lived GitHub installation token is sent (a) to the clone/push remote
+// over HTTPS and (b) to the REST API base. A body-supplied URL pointing at an
+// attacker-named host would exfiltrate that token, so every such URL's host is
+// checked against an allowlist before use. Defaults to github.com /
+// api.github.com; a GitHub Enterprise deployment can add its host via env.
+/** Hosts the harness is willing to send the installation token to. */
+export function allowedGithubHosts(env = process.env) {
+    const hosts = new Set(['github.com', 'api.github.com']);
+    const enterprise = env.GITHUB_ENTERPRISE_HOST?.trim().toLowerCase();
+    if (enterprise)
+        hosts.add(enterprise);
+    // Optional extra allowlist (comma-separated) for tests / bespoke deployments.
+    for (const h of (env.GITHUB_ALLOWED_HOSTS ?? '').split(',')) {
+        const t = h.trim().toLowerCase();
+        if (t)
+            hosts.add(t);
+    }
+    return hosts;
+}
+/**
+ * Reject a URL whose host isn't an allowed GitHub host. `file://` clone sources
+ * are local (no token leaves the box) and so are always permitted; anything else
+ * must be http(s) to an allowlisted host.
+ */
+function assertAllowedHost(rawUrl, path, env = process.env) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new Error(`Invalid job: '${path}' must be a valid URL`);
+    }
+    if (url.protocol === 'file:')
+        return;
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new Error(`Invalid job: '${path}' must be an https or file URL`);
+    }
+    const host = url.hostname.toLowerCase();
+    if (!allowedGithubHosts(env).has(host)) {
+        throw new Error(`Invalid job: '${path}' host '${host}' is not an allowed GitHub host`);
+    }
+}
+/** Parse the coding-mode bootstrap spec, or undefined when absent. Validates the target. */
+function parseAgentBootstrapSpec(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const o = value;
+    const t = (typeof o.target === 'object' && o.target !== null ? o.target : {});
+    const target = {
+        owner: str(t.owner, 'bootstrap.target.owner'),
+        name: str(t.name, 'bootstrap.target.name'),
+        cloneUrl: str(t.cloneUrl, 'bootstrap.target.cloneUrl'),
+        defaultBranch: str(t.defaultBranch, 'bootstrap.target.defaultBranch'),
+    };
+    return {
+        target,
+        ...(o.fromScratch === true ? { fromScratch: true } : {}),
+    };
+}
+/**
+ * Sanitise a body-supplied context filename to a safe basename within CONTEXT_DIR:
+ * strip any directory part, allow only `[A-Za-z0-9._-]`, and reject empties / dotfiles
+ * / `..` so a hostile value can't escape the directory or clobber repo files.
+ */
+function sanitizeContextFileName(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const base = value.replace(/\\/g, '/').split('/').pop() ?? '';
+    const cleaned = base.replace(/[^A-Za-z0-9._-]/g, '');
+    if (!cleaned || cleaned === '.' || cleaned === '..' || cleaned.startsWith('.'))
+        return undefined;
+    return cleaned;
+}
+/** Parse the linked-context files, dropping any malformed/unsafe entry. */
+function parseContextFiles(value) {
+    if (!Array.isArray(value))
+        return [];
+    const files = [];
+    const used = new Set();
+    for (const entry of value) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const e = entry;
+        const path = sanitizeContextFileName(e.path);
+        if (!path || used.has(path))
+            continue;
+        if (typeof e.content !== 'string')
+            continue;
+        used.add(path);
+        files.push({
+            path,
+            title: typeof e.title === 'string' ? e.title : path,
+            url: typeof e.url === 'string' ? e.url : '',
+            content: e.content,
+        });
+    }
+    return files;
+}
+/** Parse the explore-mode infra stand-up spec, or undefined when absent/unrecognised. */
+function parseAgentInfraSpec(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const o = value;
+    if (o.kind === 'frontend')
+        return parseFrontendInfraSpec(o);
+    const environment = o.environment === 'local' ? 'local' : o.environment === 'ephemeral' ? 'ephemeral' : undefined;
+    if (!environment)
+        return undefined;
+    return {
+        environment,
+        ...(o.noInfraDependencies === true ? { noInfraDependencies: true } : {}),
+        ...(typeof o.composePath === 'string' && o.composePath ? { composePath: o.composePath } : {}),
+        ...(typeof o.environmentUrl === 'string' && o.environmentUrl
+            ? { environmentUrl: o.environmentUrl }
+            : {}),
+    };
+}
+/**
+ * Env-var names never injected from a frontend binding: spread over `process.env` at build
+ * time, so any of these would break the toolchain (or enable code execution / cert overrides)
+ * rather than name an upstream URL. Matched exactly (Linux env is case-sensitive); the
+ * {@link RESERVED_ENV_PREFIXES} below cover whole families (`npm_config_*`, `GIT_*`, …).
+ */
+const RESERVED_ENV_NAMES = new Set([
+    'PATH',
+    'HOME',
+    'NODE_OPTIONS',
+    'NODE_PATH',
+    'NODE_EXTRA_CA_CERTS',
+    'LD_PRELOAD',
+    'LD_LIBRARY_PATH',
+    'BASH_ENV',
+    'ENV',
+    'SHELL',
+    'IFS',
+]);
+/**
+ * Env-var name PREFIXES never injected from a frontend binding. `npm_config_*` reconfigures the
+ * package manager (registry, scripts, prefix), and `GIT_*` reconfigures git — both run during a
+ * frontend install/build, so a binding in either family is toolchain control, not an upstream URL.
+ * Compared case-INSENSITIVELY (lower-cased here, matched lower-cased below): npm reads its config
+ * env with a case-insensitive `/^npm_config_/i`, so `NPM_CONFIG_REGISTRY` is honoured just like
+ * `npm_config_registry` — a case-sensitive prefix match would let the upper-cased form slip through.
+ */
+const RESERVED_ENV_PREFIXES = ['npm_config_', 'git_'];
+/**
+ * Whether an env-var name is reserved (an exact name, or a reserved family prefix). The exact
+ * names are canonical upper-case env vars matched verbatim (Linux env is case-sensitive, so a
+ * distinct lower-cased `home` is a different, harmless var); the family PREFIXES are matched
+ * case-insensitively because npm interprets `npm_config_*` regardless of case (see above).
+ */
+function isReservedEnvName(key) {
+    if (RESERVED_ENV_NAMES.has(key))
+        return true;
+    const lower = key.toLowerCase();
+    return RESERVED_ENV_PREFIXES.some((p) => lower.startsWith(p));
+}
+/** Parse the frontend UI-test infra spec (`kind: 'frontend'`), tolerating missing knobs. */
+function parseFrontendInfraSpec(o) {
+    const packageManager = o.packageManager === 'pnpm' || o.packageManager === 'npm' || o.packageManager === 'yarn'
+        ? o.packageManager
+        : undefined;
+    const serveMode = o.serveMode === 'static' || o.serveMode === 'command' ? o.serveMode : undefined;
+    const envInjection = o.envInjection === 'build' || o.envInjection === 'runtime' ? o.envInjection : undefined;
+    // Only string→string entries survive; a non-string value is dropped so a malformed
+    // binding can't inject `[object Object]` (or undefined) as an upstream URL. Reserved names
+    // that would break the toolchain or enable injection (PATH, NODE_OPTIONS, LD_PRELOAD, …) are
+    // dropped too: they are spread over `process.env` at build time, so a binding named `PATH`
+    // would replace it with a URL and the build would no longer find its tools.
+    const env = {};
+    if (typeof o.env === 'object' && o.env !== null) {
+        for (const [key, val] of Object.entries(o.env)) {
+            if (key && !isReservedEnvName(key) && typeof val === 'string')
+                env[key] = val;
+        }
+    }
+    const servePort = port(o.servePort);
+    const wiremockPort = port(o.wiremockPort);
+    return {
+        kind: 'frontend',
+        ...(packageManager ? { packageManager } : {}),
+        ...(typeof o.install === 'string' && o.install ? { install: o.install } : {}),
+        ...(typeof o.buildScript === 'string' && o.buildScript ? { buildScript: o.buildScript } : {}),
+        ...(typeof o.outputDir === 'string' && o.outputDir ? { outputDir: o.outputDir } : {}),
+        ...(serveMode ? { serveMode } : {}),
+        ...(typeof o.serveScript === 'string' && o.serveScript ? { serveScript: o.serveScript } : {}),
+        ...(servePort !== undefined ? { servePort } : {}),
+        ...(envInjection ? { envInjection } : {}),
+        ...(Object.keys(env).length ? { env } : {}),
+        ...(typeof o.wiremockMappingsPath === 'string' && o.wiremockMappingsPath
+            ? { wiremockMappingsPath: o.wiremockMappingsPath }
+            : {}),
+        ...(wiremockPort !== undefined ? { wiremockPort } : {}),
+    };
+}
+/** Validate + narrow an untrusted body into an {@link AgentJob}, throwing on bad input. */
+export function parseAgentJob(input) {
+    if (typeof input !== 'object' || input === null) {
+        throw new Error('Invalid job: body must be an object');
+    }
+    const o = input;
+    const mode = o.mode === 'coding'
+        ? 'coding'
+        : o.mode === 'explore'
+            ? 'explore'
+            : o.mode === 'preview'
+                ? 'preview'
+                : undefined;
+    if (!mode)
+        throw new Error("Invalid job: 'mode' must be 'explore', 'coding' or 'preview'");
+    // Preview runs NO agent (it only builds + serves the frontend), so the agent-only fields
+    // (system/user prompt, model) are unused there — accept them absent rather than forcing the
+    // preview dispatch to send dummy values it has no reason to supply. Every other mode still
+    // requires them (throws when missing/empty), exactly as before.
+    const agentField = (value, path) => mode === 'preview' ? (typeof value === 'string' ? value : '') : str(value, path);
+    const repo = (o.repo ?? {});
+    const output = typeof o.output === 'object' && o.output !== null
+        ? (() => {
+            const so = o.output;
+            const kind = so.kind === 'structured' ? 'structured' : 'prose';
+            const spec = { kind };
+            if (typeof so.shapeHint === 'string')
+                spec.shapeHint = so.shapeHint;
+            // Carry an explicit `repair: false` through — the handler defaults to repair-on
+            // when absent, so dropping `false` would silently re-enable the repair call for a
+            // kind that opted out (it keys off `output.repair === false`).
+            if (typeof so.repair === 'boolean')
+                spec.repair = so.repair;
+            // Carry the opt-in truncation gate through (document producers set it); dropping
+            // it would silently re-enable laundering a cut-off reply into a half-baked doc.
+            if (so.failOnUnusableFinal === true)
+                spec.failOnUnusableFinal = true;
+            return spec;
+        })()
+        : undefined;
+    const pr = typeof o.pr === 'object' && o.pr !== null
+        ? (() => {
+            const p = o.pr;
+            return { title: str(p.title, 'pr.title'), body: typeof p.body === 'string' ? p.body : '' };
+        })()
+        : undefined;
+    const infra = parseAgentInfraSpec(o.infra);
+    const bootstrap = parseAgentBootstrapSpec(o.bootstrap);
+    const contextFiles = parseContextFiles(o.contextFiles);
+    const guardLimits = parseGuardLimits(o.guardLimits);
+    const job = {
+        jobId: str(o.jobId, 'jobId'),
+        mode,
+        systemPrompt: agentField(o.systemPrompt, 'systemPrompt'),
+        userPrompt: agentField(o.userPrompt, 'userPrompt'),
+        model: agentField(o.model, 'model'),
+        ...parseHarnessAuth(o),
+        ghToken: str(o.ghToken, 'ghToken'),
+        repo: parseRepoSpec(repo),
+        branch: str(o.branch, 'branch'),
+        ...(typeof o.githubApiBase === 'string' ? { githubApiBase: o.githubApiBase } : {}),
+        ...(typeof o.webToolsGuidance === 'string' ? { webToolsGuidance: o.webToolsGuidance } : {}),
+        ...(o.webSearch === true ? { webSearch: true } : {}),
+        ...(o.full === true ? { full: true } : {}),
+        ...(typeof o.mergeBase === 'string' && o.mergeBase ? { mergeBase: o.mergeBase } : {}),
+        ...(bootstrap ? { bootstrap } : {}),
+        ...(output ? { output } : {}),
+        ...(contextFiles.length ? { contextFiles } : {}),
+        ...(infra ? { infra } : {}),
+        ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),
+        ...(typeof o.pushBranch === 'string' && o.pushBranch ? { pushBranch: o.pushBranch } : {}),
+        ...(typeof o.commitMessage === 'string' && o.commitMessage
+            ? { commitMessage: o.commitMessage }
+            : {}),
+        ...(pr ? { pr } : {}),
+        ...(o.noChangesIsError === false ? { noChangesIsError: false } : {}),
+        ...(o.persistentCheckout === true ? { persistentCheckout: true } : {}),
+        ...(o.streamFollowUps === true ? { streamFollowUps: true } : {}),
+        ...(guardLimits ? { guardLimits } : {}),
+    };
+    assertAllowedHost(job.repo.cloneUrl, 'repo.cloneUrl');
+    if (job.githubApiBase)
+        assertAllowedHost(job.githubApiBase, 'githubApiBase');
+    // Bootstrap pushes the result to a SEPARATE target repo, so its clone URL must be an
+    // allowed GitHub host too (the installation token is sent to it on the force-push).
+    if (job.bootstrap)
+        assertAllowedHost(job.bootstrap.target.cloneUrl, 'bootstrap.target.cloneUrl');
+    return job;
+}

package/dist/logger.js

@@ -0,0 +1,27 @@
+// Minimal zero-dependency structured logger. The container image installs no npm
+// packages at runtime (see Dockerfile — it compiles the TS against standalone
+// typescript/@types/node and ships only Node built-ins + the global Pi CLI), so
+// pino can't live here. This emits pino-shaped JSON lines (level/time/msg +
+// fields) which the platform captures from stdout/stderr. The Worker uses pino.
+function emit(level, msg, bound, fields) {
+    // Bound (per-job context) fields first so a call-site field can override a bound one; the
+    // envelope keys (level/time/msg) go LAST so neither bound nor call-site fields can corrupt
+    // them — a stray field named `level` must never disagree with the stream the line routes to.
+    const line = JSON.stringify({ ...bound, ...fields, level, time: new Date().toISOString(), msg });
+    // Errors/warnings to stderr, everything else to stdout — mirrors pino routing.
+    if (level === 'error' || level === 'warn')
+        process.stderr.write(`${line}\n`);
+    else
+        process.stdout.write(`${line}\n`);
+}
+/** Build a logger whose every emit folds in `bound`. The root logger binds nothing. */
+function makeLogger(bound) {
+    return {
+        debug: (msg, fields) => emit('debug', msg, bound, fields),
+        info: (msg, fields) => emit('info', msg, bound, fields),
+        warn: (msg, fields) => emit('warn', msg, bound, fields),
+        error: (msg, fields) => emit('error', msg, bound, fields),
+        child: (extra) => makeLogger({ ...bound, ...extra }),
+    };
+}
+export const log = makeLogger({});

package/dist/merger.js

@@ -0,0 +1,135 @@
+import { cloneRepo, hasDiffAgainstBase } from './git.js';
+import { extractJsonObject } from './blueprint.js';
+import { agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, withWorkspace, } from './pi-workspace.js';
+import { diagnosticsSuffix, resolveStructuredOutput, } from './structured-output.js';
+import { log } from './logger.js';
+/** Compact description of the merge-assessment shape, fed to the JSON repair call. */
+const ASSESSMENT_SHAPE_HINT = 'Expected a merge assessment: {"complexity": number 0..1, "risk": number 0..1, ' +
+    '"impact": number 0..1, "rationale": string}.';
+/** Clamp a value to a 0..1 number, defaulting to `fallback` when not finite. */
+function clamp01(value, fallback) {
+    const n = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.min(1, Math.max(0, n));
+}
+/**
+ * Coerce the agent's JSON into a well-formed assessment. Missing/garbage scores
+ * default to a CONSERVATIVE 1 (treat as severe → routes to human review rather
+ * than a silent auto-merge); the rationale falls back to the raw summary.
+ */
+function coerceAssessment(raw, summary) {
+    const o = (typeof raw === 'object' && raw !== null ? raw : {});
+    return {
+        complexity: clamp01(o.complexity, 1),
+        risk: clamp01(o.risk, 1),
+        impact: clamp01(o.impact, 1),
+        rationale: typeof o.rationale === 'string' && o.rationale ? o.rationale : summary.slice(0, 2000),
+    };
+}
+/** Build the merger task prompt: assess the PR branch against the base. */
+function buildUserPrompt(job) {
+    const pr = job.prNumber !== undefined ? ` (PR #${job.prNumber})` : '';
+    return [
+        job.instructions,
+        '',
+        `The pull request${pr} is on branch \`${job.branch}\`; the base branch is ` +
+            `\`${job.repo.baseBranch}\`. Inspect the change (e.g. \`git fetch origin ${job.repo.baseBranch}\` ` +
+            `then \`git diff origin/${job.repo.baseBranch}...HEAD\`) and score complexity, risk and impact.`,
+        '',
+        'Respond with ONLY a JSON object {"complexity":0.0,"risk":0.0,"impact":0.0,"rationale":"…"}.',
+    ].join('\n');
+}
+/** Run one merger job end to end: clone branch → Pi assesses → return scores (no commit). */
+export async function handleMerger(job, opts = {}) {
+    const trace = { jobId: job.jobId, repo: `${job.repo.owner}/${job.repo.name}`, branch: job.branch };
+    return withWorkspace('merge', async (dir) => {
+        log.info('merge: cloning PR branch', trace);
+        await cloneRepo({
+            repo: { ...job.repo, baseBranch: job.branch },
+            ghToken: job.ghToken,
+            dir,
+            // Full clone: scoring the PR means diffing it against the base, which needs the
+            // base branch's remote-tracking ref (origin/<base>) AND the merge base present. A
+            // shallow single-branch clone has neither, so `git diff origin/<base>...HEAD` fails
+            // with "branch not found" and the agent is left to GUESS scores (it tends to emit
+            // 0/0/0, which then auto-merges). The full clone gives the merger a real diff.
+            full: true,
+            signal: opts.signal,
+        });
+        // Guard the auto-merge path: confirm a real diff against the base is examinable. If
+        // it is not (missing base ref / empty diff), the agent's scores can't be trusted —
+        // we force a CONSERVATIVE assessment below so the engine routes to human review
+        // rather than auto-merging on bogus low scores.
+        const diffExaminable = await hasDiffAgainstBase(dir, job.repo.baseBranch, opts.signal);
+        if (!diffExaminable) {
+            log.warn('merge: no examinable diff against base; will assess conservatively', trace);
+        }
+        log.info('merge: running agent', trace);
+        const { summary, stats, stderrTail, usage } = await runAgentInWorkspace({
+            dir,
+            systemPrompt: job.systemPrompt,
+            userPrompt: buildUserPrompt(job),
+            model: job.model,
+            harness: job.harness,
+            subscriptionToken: job.subscriptionToken,
+            subscriptionBaseUrl: job.subscriptionBaseUrl,
+            proxyBaseUrl: job.proxyBaseUrl,
+            sessionToken: job.sessionToken,
+            // The merger only assesses (no commits/edits), so the no-edit guard must
+            // not fire on its legitimately edit-free run.
+            expectsEdits: false,
+        }, opts);
+        // Parse the agent's assessment; on a malformed reply, make ONE structured repair
+        // call (see structured-output) before giving up. `coerceAssessment` only yields
+        // null when no JSON object could be extracted at all (it defaults conservatively
+        // otherwise), so a usable-but-vague reply still routes to human review as before.
+        const { value: assessment, diagnostics } = await resolveStructuredOutput({
+            label: 'merger',
+            shapeHint: ASSESSMENT_SHAPE_HINT,
+            parse: (text) => coerceAssessment(extractJsonObject(text), text),
+        }, summary, {
+            harness: job.harness,
+            subscriptionToken: job.subscriptionToken,
+            subscriptionBaseUrl: job.subscriptionBaseUrl,
+            proxyBaseUrl: job.proxyBaseUrl,
+            sessionToken: job.sessionToken,
+            model: job.model,
+            jobId: job.jobId,
+            signal: opts.signal,
+        });
+        if (!assessment) {
+            return {
+                summary,
+                stats,
+                error: noAssessmentReason(stats, stderrTail, diagnostics),
+                ...(usage ? { usage } : {}),
+            };
+        }
+        // The agent could not actually examine the change: its scores are not trustworthy
+        // (a failed diff retrieval typically yields a bogus 0/0/0 that would auto-merge).
+        // Return a CONSERVATIVE assessment (max on every axis) so the engine's threshold
+        // check fails and the PR is routed to a human merge review instead.
+        if (!diffExaminable) {
+            const conservative = {
+                complexity: 1,
+                risk: 1,
+                impact: 1,
+                rationale: `Could not examine a real diff of \`${job.branch}\` against \`${job.repo.baseBranch}\` ` +
+                    `(the base ref was missing or the diff was empty), so this PR was NOT auto-assessed ` +
+                    `and needs a human merge review.`,
+            };
+            log.info('merge: assessed conservatively (no examinable diff)', { ...trace, ...conservative });
+            return { assessment: conservative, summary, stats, ...(usage ? { usage } : {}) };
+        }
+        log.info('merge: assessed', { ...trace, ...assessment });
+        return { assessment, summary, stats, ...(usage ? { usage } : {}) };
+    });
+}
+/** Human-readable reason a merger run produced no usable assessment. */
+function noAssessmentReason(stats, stderrTail, diagnostics) {
+    const cause = agentNeverActed(stats)
+        ? NEVER_ACTED_CAUSE
+        : ' The agent did not return a parseable JSON assessment.';
+    return `Merger produced no assessment.${cause}${diagnostics ? diagnosticsSuffix(diagnostics) : ''}${agentOutputTail(stderrTail)}`;
+}