@cat-factory/executor-harness 1.66.0 → 1.68.0

package/dist/agent.js

@@ -1,16 +1,18 @@
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { mkdir, mkdtemp, opendir, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { standUpFrontend, tearDownFrontend } from './frontend-infra.js';
 import { configurePackageRegistries } from './package-registries.js';
 import { captureRedactedOutput, redactSecrets, registerKnownSecrets } from './redact.js';
-import { cloneRepo, commitAll, conflictDiff, fetchPullRequestHead, fetchReferenceBranches, hasAgentChanges, headCommit, mergeBranch, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
+import { cloneRepo, commitAll, conflictDiff, fetchPullRequestHead, fetchReferenceBranches, headCommit, mergeBranch, prepareExistingCheckout, pushBranch, unmergedPaths, } from './git.js';
 import { inferVcsProvider, openPullRequest } from './vcs-api.js';
 import { applyPrDescription } from './pr-description.js';
 import { makeDirClaimer, noChangesReason, runCodingAgent, runMultiRepoCoding, } from './coding-agent.js';
 import { validationFailureMessage } from './validation-checks.js';
+import { agentCapabilities, mergeEffort } from './agent-shared.js';
+import { runBootstrap } from './bootstrap-mode.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, unusableFinalAnswerCause, withWorkspace, } from './pi-workspace.js';
 import { diagnosticsSuffix, resolveStructuredOutput, } from './structured-output.js';
 import { log } from './logger.js';
@@ -231,14 +233,6 @@ async function cloneServiceCheckout(dir, job, signal) {
     });
     return deriveWorkDir(dir, job.repo.serviceDirectory);
 }
-/**
- * Fold an agent's effort self-assessment (lifted from its sentinel file by `runAgentInWorkspace`)
- * onto its final result. Every container mode routes its result through this so the report reaches
- * the backend uniformly. A run that wrote no report passes through unchanged.
- */
-function mergeEffort(result, effortReport) {
-    return effortReport ? { ...result, effortReport } : result;
-}
 /** Run one generic agent job end to end, dispatching on `mode`. */
 export async function handleAgent(job, opts = {}) {
     // An `ambientAuth` job runs in the SHARED native host process on the developer's own HOME
@@ -503,6 +497,7 @@ async function runExploreMode(job, opts) {
                 webSearchProxy: job.webSearch,
                 contextFiles: job.contextFiles,
                 guardLimits: job.guardLimits,
+                ...agentCapabilities(job),
             }, agentOpts);
             return mergeEffort(await finalizeExploreResult(job, { summary, stats, stderrTail, usage, callMetrics, runDiag }, { infra, infraSetupFields, logger, signal: opts.signal }), effortReport);
         }
@@ -690,6 +685,7 @@ async function runMultiRepoExplore(job, opts) {
             webSearchProxy: job.webSearch,
             ...(job.contextFiles ? { contextFiles: job.contextFiles } : {}),
             guardLimits: job.guardLimits,
+            ...agentCapabilities(job),
             multiRepo: true,
         }, opts);
         return mergeEffort(await finalizeExploreResult(job, {
@@ -792,8 +788,8 @@ function buildSingleRepoCodingSpec(job, pushBranch) {
         ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
         ...(job.streamFollowUps ? { streamFollowUps: true } : {}),
         ...(job.referenceBranches?.length ? { referenceBranches: job.referenceBranches } : {}),
-        // Repo-sourced skill (slice 2): installed harness-aware by runAgentInWorkspace.
-        ...(job.skill ? { skill: job.skill } : {}),
+        // Skills + tool servers: installed/wired harness-aware by runAgentInWorkspace.
+        ...agentCapabilities(job),
         // Ralph loop: run the completion command after the agent commits and report its verdict.
         ...(job.validation
             ? {
@@ -1039,6 +1035,7 @@ async function runConflictResolution(job, opts) {
             sessionToken: job.sessionToken,
             contextFiles: job.contextFiles,
             guardLimits: job.guardLimits,
+            ...agentCapabilities(job),
         }, 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.
@@ -1115,133 +1112,6 @@ function unresolvedReason(unresolved, stats, stderrTail) {
         `(${unresolved.length} file(s) still conflicted: ${sample}).${cause}` +
         agentOutputTail(stderrTail));
 }
-/**
- * Repo-bootstrap coding flow (the bootstrapper): with a reference architecture, clone it →
- * the agent adapts it in place per the instructions; without one (`fromScratch`), start from
- * an empty directory → the agent scaffolds the new service. Either way the result's history
- * is reset to a single commit and force-pushed to the SEPARATE, pre-created target repo's
- * default branch. Diverges from the ordinary coding flow in pushing to a different repo with
- * a reinitialised history rather than a work branch + PR on the cloned repo.
- */
-async function runBootstrap(job, opts) {
-    const { signal } = opts;
-    const boot = job.bootstrap;
-    const fromScratch = boot.fromScratch === true;
-    const logger = (opts.log ?? log).child({ target: `${boot.target.owner}/${boot.target.name}` });
-    return withWorkspace('boot', async (dir) => {
-        if (!fromScratch) {
-            opts.onPhase?.('clone');
-            logger.info('agent(bootstrap): cloning reference architecture', {
-                reference: `${job.repo.owner}/${job.repo.name}`,
-            });
-            await cloneRepo({
-                repo: { ...job.repo, baseBranch: job.branch },
-                ghToken: job.ghToken,
-                dir,
-                signal,
-            });
-        }
-        else {
-            logger.info('agent(bootstrap): scaffolding from scratch (no reference)');
-        }
-        opts.onPhase?.('agent');
-        logger.info('agent(bootstrap): running agent');
-        const { summary, stats, stderrTail, usage, callMetrics, effortReport } = await runAgentInWorkspace({
-            dir,
-            systemPrompt: job.systemPrompt,
-            userPrompt: job.userPrompt,
-            model: job.model,
-            harness: job.harness,
-            subscriptionToken: job.subscriptionToken,
-            subscriptionBaseUrl: job.subscriptionBaseUrl,
-            ambientAuth: job.ambientAuth,
-            proxyBaseUrl: job.proxyBaseUrl,
-            sessionToken: job.sessionToken,
-            guardLimits: job.guardLimits,
-        }, opts);
-        // Guard against a no-op run: Pi can exit cleanly having done nothing (e.g. it never
-        // reached the model), and a force-push would then publish 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, !fromScratch, signal))) {
-            const error = bootstrapNoOpReason(!fromScratch, stats, summary, stderrTail);
-            logger.error('agent(bootstrap): agent produced no content, refusing to push', { ...stats });
-            return mergeEffort({
-                summary,
-                stats,
-                error,
-                failureCause: 'agent',
-                ...(usage ? { usage } : {}),
-                ...(callMetrics ? { callMetrics } : {}),
-            }, effortReport);
-        }
-        opts.onPhase?.('push');
-        logger.info('agent(bootstrap): pushing bootstrapped contents', { ...stats });
-        // Bootstrap always resets history to one commit + force-pushes (the fresh history
-        // shares no ancestor with whatever boilerplate the new repo was created with).
-        await reinitAndPush({
-            dir,
-            target: boot.target,
-            ghToken: job.ghToken,
-            message: fromScratch
-                ? 'Bootstrap new repository'
-                : `Bootstrap from ${job.repo.owner}/${job.repo.name}`,
-        });
-        logger.info('agent(bootstrap): complete', { defaultBranch: boot.target.defaultBranch });
-        return mergeEffort({
-            defaultBranch: boot.target.defaultBranch,
-            summary,
-            stats,
-            ...(usage ? { usage } : {}),
-            ...(callMetrics ? { callMetrics } : {}),
-        }, effortReport);
-    });
-}
-/**
- * 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);
-    return containsAnyFile(dir);
-}
-/**
- * Whether `dir` contains at least one regular file anywhere in its tree, walking
- * depth-first and stopping at the FIRST file found — so the cost is bounded by how
- * quickly a file turns up (a scaffold almost always writes a root-level file), not by
- * the size of the produced tree (a full recursive `readdir` would materialise every
- * entry before the check).
- */
-async function containsAnyFile(dir) {
-    const handle = await opendir(dir);
-    try {
-        for await (const entry of handle) {
-            if (entry.isFile())
-                return true;
-            if (entry.isDirectory() && (await containsAnyFile(join(dir, entry.name))))
-                return true;
-        }
-    }
-    catch {
-        // A directory that vanished mid-walk has nothing to contribute.
-    }
-    return false;
-}
-/** Human-readable bootstrap no-op reason, embedding what the agent did so the cause is visible. */
-function bootstrapNoOpReason(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));
-}
 /** Human-readable reason a read-only run produced no usable output. */
 function noOutputReason(stats, stderrTail) {
     const cause = agentNeverActed(stats)

package/dist/bootstrap-mode.js

@@ -0,0 +1,141 @@
+import { opendir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { NEVER_ACTED_CAUSE, agentNeverActed, agentOutputTail, runAgentInWorkspace, withWorkspace, } from './pi-workspace.js';
+import { cloneRepo, hasAgentChanges, reinitAndPush } from './git.js';
+import { log } from './logger.js';
+import { agentCapabilities, mergeEffort } from './agent-shared.js';
+// ---------------------------------------------------------------------------
+// The repo-BOOTSTRAP mode: adapt a reference architecture (or scaffold from scratch) into a
+// pre-created empty repo and force-push it as a single commit. Extracted from `agent.ts` as a
+// cohesive collaborator — it is a whole MODE with its own push semantics (a separate target repo
+// and a reinitialised history, not a work branch + PR), and it shares only the small agent-run
+// helpers in `agent-shared.ts` with the coding/explore flows.
+// ---------------------------------------------------------------------------
+/**
+ * Repo-bootstrap coding flow (the bootstrapper): with a reference architecture, clone it →
+ * the agent adapts it in place per the instructions; without one (`fromScratch`), start from
+ * an empty directory → the agent scaffolds the new service. Either way the result's history
+ * is reset to a single commit and force-pushed to the SEPARATE, pre-created target repo's
+ * default branch. Diverges from the ordinary coding flow in pushing to a different repo with
+ * a reinitialised history rather than a work branch + PR on the cloned repo.
+ */
+export async function runBootstrap(job, opts) {
+    const { signal } = opts;
+    const boot = job.bootstrap;
+    const fromScratch = boot.fromScratch === true;
+    const logger = (opts.log ?? log).child({ target: `${boot.target.owner}/${boot.target.name}` });
+    return withWorkspace('boot', async (dir) => {
+        if (!fromScratch) {
+            opts.onPhase?.('clone');
+            logger.info('agent(bootstrap): cloning reference architecture', {
+                reference: `${job.repo.owner}/${job.repo.name}`,
+            });
+            await cloneRepo({
+                repo: { ...job.repo, baseBranch: job.branch },
+                ghToken: job.ghToken,
+                dir,
+                signal,
+            });
+        }
+        else {
+            logger.info('agent(bootstrap): scaffolding from scratch (no reference)');
+        }
+        opts.onPhase?.('agent');
+        logger.info('agent(bootstrap): running agent');
+        const { summary, stats, stderrTail, usage, callMetrics, effortReport } = await runAgentInWorkspace({
+            dir,
+            systemPrompt: job.systemPrompt,
+            userPrompt: job.userPrompt,
+            model: job.model,
+            harness: job.harness,
+            subscriptionToken: job.subscriptionToken,
+            subscriptionBaseUrl: job.subscriptionBaseUrl,
+            ambientAuth: job.ambientAuth,
+            proxyBaseUrl: job.proxyBaseUrl,
+            sessionToken: job.sessionToken,
+            guardLimits: job.guardLimits,
+            ...agentCapabilities(job),
+        }, opts);
+        // Guard against a no-op run: Pi can exit cleanly having done nothing (e.g. it never
+        // reached the model), and a force-push would then publish 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, !fromScratch, signal))) {
+            const error = bootstrapNoOpReason(!fromScratch, stats, summary, stderrTail);
+            logger.error('agent(bootstrap): agent produced no content, refusing to push', { ...stats });
+            return mergeEffort({
+                summary,
+                stats,
+                error,
+                failureCause: 'agent',
+                ...(usage ? { usage } : {}),
+                ...(callMetrics ? { callMetrics } : {}),
+            }, effortReport);
+        }
+        opts.onPhase?.('push');
+        logger.info('agent(bootstrap): pushing bootstrapped contents', { ...stats });
+        // Bootstrap always resets history to one commit + force-pushes (the fresh history
+        // shares no ancestor with whatever boilerplate the new repo was created with).
+        await reinitAndPush({
+            dir,
+            target: boot.target,
+            ghToken: job.ghToken,
+            message: fromScratch
+                ? 'Bootstrap new repository'
+                : `Bootstrap from ${job.repo.owner}/${job.repo.name}`,
+        });
+        logger.info('agent(bootstrap): complete', { defaultBranch: boot.target.defaultBranch });
+        return mergeEffort({
+            defaultBranch: boot.target.defaultBranch,
+            summary,
+            stats,
+            ...(usage ? { usage } : {}),
+            ...(callMetrics ? { callMetrics } : {}),
+        }, effortReport);
+    });
+}
+/**
+ * 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);
+    return containsAnyFile(dir);
+}
+/**
+ * Whether `dir` contains at least one regular file anywhere in its tree, walking
+ * depth-first and stopping at the FIRST file found — so the cost is bounded by how
+ * quickly a file turns up (a scaffold almost always writes a root-level file), not by
+ * the size of the produced tree (a full recursive `readdir` would materialise every
+ * entry before the check).
+ */
+async function containsAnyFile(dir) {
+    const handle = await opendir(dir);
+    try {
+        for await (const entry of handle) {
+            if (entry.isFile())
+                return true;
+            if (entry.isDirectory() && (await containsAnyFile(join(dir, entry.name))))
+                return true;
+        }
+    }
+    catch {
+        // A directory that vanished mid-walk has nothing to contribute.
+    }
+    return false;
+}
+/** Human-readable bootstrap no-op reason, embedding what the agent did so the cause is visible. */
+function bootstrapNoOpReason(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));
+}

package/dist/coding-agent.js

@@ -1,8 +1,6 @@
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { spawn } from 'node:child_process';
-import { killChildProcess, spawnDetached } from './process.js';
-import { MAX_CAPTURED_OUTPUT_CHARS, redactSecrets } from './redact.js';
+import { runCapturedCommand } from './captured-command.js';
 import { branchAheadOfBase, changedFilesSinceBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
 import { openPullRequest } from './vcs-api.js';
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js';
@@ -153,7 +151,8 @@ export async function runCodingAgent(spec, opts = {}) {
             webToolsGuidance: spec.webToolsGuidance,
             webSearchProxy: spec.webSearchProxy,
             guardLimits: spec.guardLimits,
-            ...(spec.skill ? { skill: spec.skill } : {}),
+            ...(spec.skills?.length ? { skills: spec.skills } : {}),
+            ...(spec.mcpServers?.length ? { mcpServers: spec.mcpServers } : {}),
         }, opts);
         let outcome;
         try {
@@ -457,7 +456,7 @@ async function finalizeCodingRun(args) {
     // Runs regardless of whether this pass pushed — a no-op iteration must still be able
     // to report that the criterion is (already) met. The harness runs it, never the model.
     if (spec.validation) {
-        outcome.validation = await runRalphValidation(workDir, spec.validation, logger, opts);
+        outcome.validation = await runRalphValidation(dir, workDir, spec.validation, logger, opts);
     }
     // Pre-PR validation: the loop already ran (before this finalize, so a red checkout never
     // reaches the PR-opening caller); attach its verdict for the caller to gate on and for the
@@ -525,81 +524,96 @@ function mergeAgentPasses(previous, next) {
  * killed and treated as a failure (a hung `pnpm test` must never block the loop forever).
  * Overridable via env for tests; defaults to 15 minutes.
  */
-function ralphValidationTimeoutMs() {
+export function ralphValidationTimeoutMs() {
     const n = Number(process.env.RALPH_VALIDATION_TIMEOUT_MS);
     return Number.isFinite(n) && n > 0 ? Math.floor(n) : 15 * 60_000;
 }
+/**
+ * How often the Ralph validation feeds the run's inactivity watchdog while its command runs.
+ * The command is exactly the activity-SILENT kind — a full `pnpm test`, a cold install-then-build
+ * — and the harness spawns it ITSELF rather than through the agent, so it emits no activity
+ * events of its own. `JOB_INACTIVITY_MS` (default 10 min) is TIGHTER than the command's own
+ * watchdog ({@link ralphValidationTimeoutMs}, default 15 min), so without this heartbeat any
+ * validation running past 10 minutes aborted the whole iteration as "inactivity" — mislabelling
+ * a healthy test suite as a wedge, and making the 15-minute watchdog unreachable at stock
+ * settings. The two sibling harness-run phases (pre-PR validation, reproduction proof) have
+ * always fed it; this one did not. Overridable via env for tests.
+ */
+export function ralphHeartbeatMs() {
+    const n = Number(process.env.RALPH_VALIDATION_HEARTBEAT_MS);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 30_000;
+}
+/**
+ * Bound on the validation output tail that crosses the wire. Deliberately smaller than
+ * `MAX_CAPTURED_OUTPUT_CHARS` (`redact.ts`) and equal to the two sibling phases' budgets, for
+ * the same reason: this tail is persisted on the step (and on EVERY iteration of the attempt
+ * log) inside the run's `detail` JSON blob, which is re-serialized on every step-progress write.
+ */
+export const RALPH_VALIDATION_TAIL_CHARS = 4_000;
 /**
  * Ralph loop: run the programmatic completion command in the checkout and return its exit
- * code plus a bounded, redacted tail of its output. The EXIT CODE is the loop's authoritative
- * done signal (0 = the criterion is met) — computed here by the harness, never self-reported
- * by the model, which is the whole point of a programmatic exit condition. Runs
- * `sh -c <command>` in `cwd`; a watchdog kills the whole process tree on timeout (a hung
- * command counts as a failure so the loop is never blocked), and an aborted run resolves to a
- * non-zero code too. The command runs INSIDE the sandboxed run container (the same trust
- * boundary as the coding agent) — there is no host/backend execution.
+ * code, a bounded + redacted tail of its output, and the work branch's HEAD it ran against.
+ * The EXIT CODE is the loop's authoritative done signal (0 = the criterion is met) — computed
+ * here by the harness, never self-reported by the model, which is the whole point of a
+ * programmatic exit condition. The command runs INSIDE the sandboxed run container (the same
+ * trust boundary as the coding agent) — there is no host/backend execution.
+ *
+ * The spawn itself goes through {@link runCapturedCommand}, the ONE seam for a harness-run
+ * command, rather than the near-verbatim copy this used to be. That copy had drifted in two
+ * ways the seam exists to prevent: it scrubbed secrets AFTER the rolling truncation with no
+ * margin (so a credential straddling the cut lost its `KEY=` prefix and survived redaction as
+ * an unrecognised partial, on a tail that reaches the step, the notification and the SPA), and
+ * it published the full 16k capture where both siblings deliberately bound the wire tail.
+ *
+ * `headSha` is what lets the engine tell a loop that is iterating from one that is merely
+ * repeating: two consecutive failing iterations against an unchanged head means the agent
+ * committed nothing, and the loop is ended early instead of spending the rest of its budget.
+ * Best-effort — a head that cannot be read is simply omitted, and the engine's check fails open.
  */
-async function runRalphValidation(cwd, validation, logger, opts) {
-    const timeoutMs = ralphValidationTimeoutMs();
+export async function runRalphValidation(repoDir, cwd, validation, logger, opts) {
     logger.info('coding-agent(ralph): running validation command', {
         iteration: validation.iteration,
     });
-    return new Promise((resolve) => {
-        let out = '';
-        let settled = false;
-        const child = spawn('sh', ['-c', validation.command], {
+    // Keep the run's inactivity watchdog fed for the whole command — see `ralphHeartbeatMs`.
+    const heartbeat = setInterval(() => opts.onActivity?.(), ralphHeartbeatMs());
+    heartbeat.unref?.();
+    let captured;
+    try {
+        captured = await runCapturedCommand({
             cwd,
-            detached: spawnDetached,
-            stdio: ['ignore', 'pipe', 'pipe'],
-            // The job's own env (see `RunOptions.agentEnv`): a validation command typically installs
-            // before it tests, and this is spawned by the HARNESS rather than the agent, so it does not
-            // otherwise inherit the job's private-registry npmrc pointer on the native path.
-            env: { ...process.env, ...opts.agentEnv },
+            command: validation.command,
+            timeoutMs: ralphValidationTimeoutMs(),
+            reportTailChars: RALPH_VALIDATION_TAIL_CHARS,
+            logLabel: 'coding-agent(ralph): validation',
+            logFields: { iteration: validation.iteration },
+            logger,
+            opts,
         });
-        // Keep only the tail; guard against unbounded buffering on a chatty command.
-        const capture = (chunk) => {
-            out = (out + chunk.toString('utf8')).slice(-MAX_CAPTURED_OUTPUT_CHARS);
-        };
-        child.stdout?.on('data', capture);
-        child.stderr?.on('data', capture);
-        const finish = (exitCode) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            opts.signal?.removeEventListener('abort', onAbort);
-            const trimmed = out.trim();
-            const tail = trimmed ? redactSecrets(trimmed) : undefined;
-            logger.info('coding-agent(ralph): validation finished', {
-                exitCode,
-                iteration: validation.iteration,
-            });
-            resolve({
-                validationPassed: exitCode === 0,
-                exitCode,
-                ...(tail ? { validationOutputTail: tail } : {}),
-                ...(validation.iteration !== undefined ? { iteration: validation.iteration } : {}),
-            });
-        };
-        const timer = setTimeout(() => {
-            logger.warn('coding-agent(ralph): validation command timed out', { timeoutMs });
-            killChildProcess(child, undefined, logger);
-            finish(124); // conventional timeout exit code (a non-zero fail)
-        }, timeoutMs);
-        timer.unref?.();
-        const onAbort = () => {
-            killChildProcess(child, undefined, logger);
-            finish(130); // aborted (a non-zero fail)
-        };
-        opts.signal?.addEventListener('abort', onAbort, { once: true });
-        child.on('error', (err) => {
-            logger.warn('coding-agent(ralph): validation command failed to spawn', {
-                error: err instanceof Error ? err.message : String(err),
-            });
-            finish(127); // spawn error / command not found (a non-zero fail)
+    }
+    finally {
+        clearInterval(heartbeat);
+    }
+    // The commit the criterion was judged against. Read AFTER the command so a validation that
+    // itself commits (a formatter check that rewrites files, say) is attributed to what it left.
+    // Best-effort: an unreadable head only costs the engine's no-progress guard, never the
+    // verdict — but it is REPORTED, or a guard that quietly stopped firing leaves no trace.
+    const headSha = await headCommit(repoDir, opts.signal).catch((err) => {
+        logger.warn('coding-agent(ralph): could not read the work-branch head', {
+            error: err instanceof Error ? err.message : String(err),
         });
-        child.on('close', (code) => finish(code ?? 1));
+        return '';
     });
+    logger.info('coding-agent(ralph): validation finished', {
+        exitCode: captured.exitCode,
+        iteration: validation.iteration,
+    });
+    return {
+        validationPassed: captured.passed,
+        exitCode: captured.exitCode,
+        ...(captured.outputTail ? { validationOutputTail: captured.outputTail } : {}),
+        ...(validation.iteration !== undefined ? { iteration: validation.iteration } : {}),
+        ...(headSha ? { headSha } : {}),
+    };
 }
 /** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
 export function safeDirSegment(value) {
@@ -707,6 +721,10 @@ export async function runMultiRepoCoding(job, opts = {}) {
             webSearchProxy: job.webSearch,
             guardLimits: job.guardLimits,
             ...(job.contextFiles ? { contextFiles: job.contextFiles } : {}),
+            // Skills + tool servers apply to a multi-repo run exactly as to a single-repo one: they
+            // are properties of the AGENT KIND, not of the checkout layout.
+            ...(job.skills?.length ? { skills: job.skills } : {}),
+            ...(job.mcpServers?.length ? { mcpServers: job.mcpServers } : {}),
             multiRepo: true,
         }, opts);
         // Commit forgotten tracked edits, then push + open a PR for each repo the run actually changed.

package/dist/job.js

@@ -1,5 +1,6 @@
 import { parseValidationChecksSpec, } from './validation-checks.js';
 import { parseReproductionSpec, } from './reproduction-proof.js';
+import { parseMcpServerSpecs, parseSkillSpecs, } from './agent-capabilities.js';
 function str(value, path) {
     if (typeof value !== 'string' || value.length === 0) {
         throw new Error(`Invalid job: '${path}' must be a non-empty string`);
@@ -411,78 +412,6 @@ function parseContextFiles(value) {
     }
     return files;
 }
-/**
- * Sanitize a skill resource's relative path: keep the subdirectory structure (so
- * `templates/report.md` materialises nested) but reject anything that could escape the skill
- * directory — absolute paths, `..` traversal, backslashes, empty/dot segments. Returns undefined
- * for an unsafe path (the resource is then dropped).
- */
-function sanitizeSkillRelPath(value) {
-    if (typeof value !== 'string')
-        return undefined;
-    const segments = value.replace(/\\/g, '/').split('/');
-    const clean = [];
-    for (const seg of segments) {
-        if (seg === '' || seg === '.')
-            continue;
-        if (seg === '..')
-            return undefined;
-        // Same character class as a context-file name, per segment.
-        const c = seg.replace(/[^A-Za-z0-9._-]/g, '');
-        if (!c || c === '.' || c === '..' || c.startsWith('.'))
-            return undefined;
-        clean.push(c);
-    }
-    return clean.length ? clean.join('/') : undefined;
-}
-/**
- * Fallback native-skill directory name when the authored name has no id-safe characters (e.g. a
- * purely non-ASCII skill name). The name is only a path segment / manifest label, so a safe
- * default keeps the skill installable rather than dropping it — which, on the claude-code path,
- * would leave the prompt pointing at a skill that was never installed (a blind run).
- */
-const FALLBACK_SKILL_NAME = 'skill';
-/** A skill's own directory name, sanitized to a safe single path segment (undefined if empty). */
-function sanitizeSkillName(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;
-}
-/** Validate the optional `skill` field, or undefined when absent/malformed. */
-function parseSkillSpec(value) {
-    if (typeof value !== 'object' || value === null)
-        return undefined;
-    const o = value;
-    const instructions = typeof o.instructions === 'string' ? o.instructions : undefined;
-    // No instructions ⇒ there is nothing to run — drop the skill (the prompt still carries the
-    // folded-in directive on the Pi/codex path). An unsafe/empty NAME only affects the install
-    // directory, so fall back to a safe default rather than dropping the whole skill.
-    if (!instructions)
-        return undefined;
-    const name = sanitizeSkillName(o.name) ?? FALLBACK_SKILL_NAME;
-    const description = typeof o.description === 'string' ? o.description : '';
-    const resources = [];
-    if (Array.isArray(o.resources)) {
-        const used = new Set();
-        for (const entry of o.resources) {
-            if (typeof entry !== 'object' || entry === null)
-                continue;
-            const e = entry;
-            const relPath = sanitizeSkillRelPath(e.relPath);
-            if (!relPath || used.has(relPath))
-                continue;
-            if (typeof e.content !== 'string')
-                continue;
-            used.add(relPath);
-            resources.push({ relPath, content: e.content });
-        }
-    }
-    return { name, description, instructions, resources };
-}
 /** Parse the explore-mode infra stand-up spec, or undefined when absent/unrecognised. */
 function parseAgentInfraSpec(value) {
     if (typeof value !== 'object' || value === null)
@@ -669,7 +598,8 @@ export function parseAgentJob(input) {
         bootstrap: parseAgentBootstrapSpec(o.bootstrap),
         contextFiles: parseContextFiles(o.contextFiles),
         packageRegistries: parsePackageRegistries(o.packageRegistries),
-        skill: parseSkillSpec(o.skill),
+        skills: parseSkillSpecs(o.skills),
+        mcpServers: parseMcpServerSpecs(o.mcpServers),
         testSecrets: parseTestSecrets(o.testSecrets),
         guardLimits: parseGuardLimits(o.guardLimits),
         validation: parseValidationSpec(o.validation),
@@ -731,7 +661,7 @@ function parseAgentPrSpec(raw) {
  * literal doesn't blow the complexity budget; behaviour is byte-identical (spread order preserved).
  */
 function assembleAgentJob(o, mode, agentField, parts) {
-    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, packageRegistries, skill, testSecrets, guardLimits, validation, validationChecks, reproduction, reviewPrNumber, } = parts;
+    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, packageRegistries, skills, mcpServers, testSecrets, guardLimits, validation, validationChecks, reproduction, reviewPrNumber, } = parts;
     const repo = (o.repo ?? {});
     return {
         jobId: str(o.jobId, 'jobId'),
@@ -748,7 +678,8 @@ function assembleAgentJob(o, mode, agentField, parts) {
         ...(output ? { output } : {}),
         ...(contextFiles.length ? { contextFiles } : {}),
         ...(packageRegistries.length ? { packageRegistries } : {}),
-        ...(skill ? { skill } : {}),
+        ...(skills ? { skills } : {}),
+        ...(mcpServers ? { mcpServers } : {}),
         ...(testSecrets.length ? { testSecrets } : {}),
         ...(infra ? { infra } : {}),
         ...(pr ? { pr } : {}),