@cat-factory/executor-harness 1.43.8 → 1.47.0

package/dist/agent-runner.js

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process';
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
 import { killChildProcess, spawnDetached } from './process.js';
 import { redact, secretsToRedact } from './redact.js';
 function isObject(value) {
@@ -130,6 +130,31 @@ function streamCli(command, args, prompt, opts, env, secrets, onEvent) {
  * `TodoWrite` tool calls onto subtask progress and the terminal `result` event
  * onto the summary + usage.
  */
+/**
+ * Write a repo-sourced skill as a NATIVE Claude Code skill under `<skillsRoot>/<name>/`: a
+ * `SKILL.md` (YAML frontmatter `name`/`description` + the instructions body, the format the CLI
+ * expects) plus every resource file at its path within the skill directory. Resource sub-paths
+ * were sanitized at the job boundary (no traversal), so nested dirs are created as needed.
+ *
+ * The frontmatter `name`/`description` values are emitted as JSON-encoded (double-quoted) YAML
+ * scalars, not bare plain scalars: an author's description routinely contains `: ` (colon-space)
+ * or a leading YAML indicator (`#`, `-`, `[`, `{`, `"`, …), which is invalid as a plain scalar and
+ * would make the CLI fail to parse the frontmatter and silently skip the skill. A JSON string is a
+ * valid YAML double-quoted scalar, so quoting makes the manifest robust to arbitrary text.
+ */
+async function writeNativeSkill(skillsRoot, skill) {
+    const dir = join(skillsRoot, skill.name);
+    await mkdir(dir, { recursive: true });
+    const name = JSON.stringify(skill.name);
+    const description = JSON.stringify(skill.description.replace(/\r?\n/g, ' '));
+    const frontmatter = `---\nname: ${name}\ndescription: ${description}\n---\n`;
+    await writeFile(join(dir, 'SKILL.md'), `${frontmatter}\n${skill.instructions}\n`, 'utf8');
+    for (const resource of skill.resources) {
+        const dest = join(dir, resource.relPath);
+        await mkdir(dirname(dest), { recursive: true });
+        await writeFile(dest, resource.content, 'utf8');
+    }
+}
 export async function runClaudeCode(opts) {
     const stats = { toolCalls: 0, assistantChars: 0 };
     let summary = '';
@@ -219,6 +244,16 @@ export async function runClaudeCode(opts) {
             hasTrustDialogAccepted: true,
         }), { mode: 0o600 }).catch(() => { });
     }
+    // Repo-sourced Claude Skill (slice 2): install it as a native skill under the config dir's
+    // `skills/<name>/` so the CLI discovers and can invoke it. Written to the isolated per-run
+    // config home when present, else the developer's `~/.claude` (ambient/native mode). Best-effort:
+    // a write failure must not wedge the run — the prompt still names the skill.
+    if (opts.skill) {
+        const skillsRoot = configHome
+            ? join(configHome, 'skills')
+            : join(homedir(), '.claude', 'skills');
+        await writeNativeSkill(skillsRoot, opts.skill).catch(() => { });
+    }
     // Anthropic itself authenticates with the subscription OAuth token; a
     // non-Anthropic Claude-Code vendor (GLM via Z.ai, Kimi via Moonshot, DeepSeek)
     // points Claude Code at its Anthropic-compatible endpoint with an auth-token key.

package/dist/agent.js

@@ -654,6 +654,16 @@ async function runMultiRepoExplore(job, opts) {
         }, { infraSetupFields: {}, logger, signal: opts.signal });
     });
 }
+/**
+ * Whether a Ralph iteration ({@link AgentJob.validation} set) landed on a MULTI-REPO job (writable
+ * peer repos or read-only reference repos). The post-commit validation command is only wired into
+ * the single-repo flow, so a multi-repo run would silently skip it and degenerate the loop into a
+ * one-shot with no completion gate — multi-repo ralph is out of scope for v1 (see
+ * backend/docs/ralph-loop.md), so {@link runCodingMode} fails loudly on this instead.
+ */
+export function ralphUnsupportedOnMultiRepo(job) {
+    return Boolean(job.validation) && Boolean(job.peerRepos?.length || job.referenceRepos?.length);
+}
 /**
  * Edit-and-push coding, dispatching on job DATA: repo-bootstrap (force-push a fresh history to a
  * separate target repo), conflict-resolution (merge the base in, resolve, push back), multi-repo
@@ -678,7 +688,19 @@ async function runCodingMode(job, opts) {
     // all of them. Keyed off job DATA, not the agent kind — set for the implementer's writable
     // peer repos (service-connections phase 3, `peerRepos`) OR the doc-writer's READ-ONLY
     // reference repos (`referenceRepos`, cloned but never pushed).
-    const result = job.peerRepos?.length || job.referenceRepos?.length
+    const multiRepo = Boolean(job.peerRepos?.length || job.referenceRepos?.length);
+    // Ralph loop (v1): the post-commit validation command is only wired into the single-repo
+    // flow, so a multi-repo run would silently skip it and the loop would degenerate into a
+    // one-shot with no completion gate. Multi-repo ralph is deliberately out of scope for v1
+    // (see backend/docs/ralph-loop.md), so FAIL LOUDLY rather than run a validation-less pass.
+    if (ralphUnsupportedOnMultiRepo(job)) {
+        return {
+            error: 'Ralph loop is not supported on a multi-repo task (connected service repos). ' +
+                'Its validation command runs only in the single primary-repo checkout. ' +
+                'Run the Ralph loop on a task scoped to a single repo.',
+        };
+    }
+    const result = multiRepo
         ? await runMultiRepoCoding(job, opts)
         : await runSingleRepoCoding(job, opts);
     // Structured coding kind (repro-test): fold the final reply's JSON onto `custom` so the
@@ -700,7 +722,7 @@ async function runCodingMode(job, opts) {
  */
 async function runSingleRepoCoding(job, opts) {
     const pushBranch = job.pushBranch ?? job.newBranch ?? job.branch;
-    const { summary, stats, stderrTail, pushed, usage, callMetrics } = await runCodingAgent({
+    const { summary, stats, stderrTail, pushed, usage, callMetrics, validation } = await runCodingAgent({
         kind: 'agent',
         jobId: job.jobId,
         repo: job.repo,
@@ -724,7 +746,23 @@ async function runSingleRepoCoding(job, opts) {
         ...(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 } : {}),
+        // Ralph loop: run the completion command after the agent commits and report its verdict.
+        ...(job.validation
+            ? {
+                validation: {
+                    command: job.validation.command,
+                    ...(job.validation.iteration !== undefined
+                        ? { iteration: job.validation.iteration }
+                        : {}),
+                },
+            }
+            : {}),
     }, opts);
+    // Ralph loop: the harness-computed validation verdict, forwarded onto the coding result as
+    // `ralphVerdict` so the backend's `toRunResult` lifts it onto `AgentRunResult.ralphVerdict`.
+    const ralphVerdict = validation ? { ralphVerdict: validation } : {};
     if (!pushed) {
         // A no-op: a failure for the implementer, a clean non-event for the fixers.
         if (job.noChangesIsError === false) {
@@ -735,6 +773,7 @@ async function runSingleRepoCoding(job, opts) {
                 stats,
                 ...(usage ? { usage } : {}),
                 ...(callMetrics ? { callMetrics } : {}),
+                ...ralphVerdict,
             };
         }
         return {
@@ -799,6 +838,7 @@ async function runSingleRepoCoding(job, opts) {
             stats,
             ...(usage ? { usage } : {}),
             ...(callMetrics ? { callMetrics } : {}),
+            ...ralphVerdict,
         };
     }
     return {
@@ -808,6 +848,7 @@ async function runSingleRepoCoding(job, opts) {
         stats,
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
+        ...ralphVerdict,
     };
 }
 /**

package/dist/coding-agent.js

@@ -1,5 +1,8 @@
 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 { branchAheadOfBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, openPullRequest, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, runAgentInWorkspace, withWorkspace, } from './pi-workspace.js';
@@ -227,6 +230,7 @@ export async function runCodingAgent(spec, opts = {}) {
                 webToolsGuidance: spec.webToolsGuidance,
                 webSearchProxy: spec.webSearchProxy,
                 guardLimits: spec.guardLimits,
+                ...(spec.skill ? { skill: spec.skill } : {}),
             }, opts);
             // Stop tailing the follow-up sentinel and flush any items written after the last
             // tick, so a fast final burst still reaches the job view before the run is recorded.
@@ -299,6 +303,13 @@ export async function runCodingAgent(spec, opts = {}) {
                     ...(callMetrics ? { callMetrics } : {}),
                 };
             }
+            // Ralph loop: run the programmatic completion command against the pushed/committed
+            // state and attach its verdict (exit code = the loop's authoritative done signal).
+            // 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);
+            }
         }
         finally {
             // Safety net for the throw path (the happy path already cleared these above).
@@ -309,6 +320,83 @@ export async function runCodingAgent(spec, opts = {}) {
         return outcome;
     });
 }
+/**
+ * The Ralph-loop validation watchdog: the longest a completion command may run before it is
+ * 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() {
+    const n = Number(process.env.RALPH_VALIDATION_TIMEOUT_MS);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 15 * 60_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.
+ */
+async function runRalphValidation(cwd, validation, logger, opts) {
+    const timeoutMs = ralphValidationTimeoutMs();
+    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], {
+            cwd,
+            detached: spawnDetached,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        // 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)
+        });
+        child.on('close', (code) => finish(code ?? 1));
+    });
+}
 /** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
 export function safeDirSegment(value) {
     return value.replace(/[^A-Za-z0-9._-]/g, '-') || '_';

package/dist/job.js

@@ -45,6 +45,27 @@ function parseGuardLimits(value) {
         spec.maxConsecutiveWebCalls = web;
     return Object.keys(spec).length > 0 ? spec : undefined;
 }
+/**
+ * Parse the optional Ralph-loop validation spec. Requires a non-empty `command` string (the
+ * completion criterion the harness runs); `progressPath`/`iteration` are optional metadata.
+ * Returns undefined when absent or malformed (a coding run then behaves like any other — no
+ * post-commit validation). See {@link ValidationSpec}.
+ */
+function parseValidationSpec(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const o = value;
+    if (typeof o.command !== 'string' || o.command.trim() === '')
+        return undefined;
+    const iteration = posInt(o.iteration);
+    return {
+        command: o.command,
+        ...(typeof o.progressPath === 'string' && o.progressPath
+            ? { progressPath: o.progressPath }
+            : {}),
+        ...(iteration !== undefined ? { iteration } : {}),
+    };
+}
 /**
  * Parse the shared per-job auth fields, validating per harness: a subscription
  * harness (`claude-code` / `codex`) requires `subscriptionToken`; the default Pi
@@ -388,6 +409,78 @@ 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)
@@ -587,8 +680,10 @@ export function parseAgentJob(input) {
     const bootstrap = parseAgentBootstrapSpec(o.bootstrap);
     const contextFiles = parseContextFiles(o.contextFiles);
     const packageRegistries = parsePackageRegistries(o.packageRegistries);
+    const skill = parseSkillSpec(o.skill);
     const testSecrets = parseTestSecrets(o.testSecrets);
     const guardLimits = parseGuardLimits(o.guardLimits);
+    const validation = parseValidationSpec(o.validation);
     const job = {
         jobId: str(o.jobId, 'jobId'),
         mode,
@@ -608,6 +703,7 @@ export function parseAgentJob(input) {
         ...(output ? { output } : {}),
         ...(contextFiles.length ? { contextFiles } : {}),
         ...(packageRegistries.length ? { packageRegistries } : {}),
+        ...(skill ? { skill } : {}),
         ...(testSecrets.length ? { testSecrets } : {}),
         ...(infra ? { infra } : {}),
         ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),
@@ -623,6 +719,7 @@ export function parseAgentJob(input) {
         ...(o.persistentCheckout === true ? { persistentCheckout: true } : {}),
         ...(o.streamFollowUps === true ? { streamFollowUps: true } : {}),
         ...(guardLimits ? { guardLimits } : {}),
+        ...(validation ? { validation } : {}),
     };
     assertAllowedHost(job.repo.cloneUrl, 'repo.cloneUrl');
     if (job.githubApiBase)

package/dist/pi-workspace.js

@@ -2,7 +2,7 @@ import { mkdir, mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { log } from './logger.js';
-import { CONTEXT_DIR, materializeContextFiles, mergeGuardLimits, progressGuardLimitsFromEnv, runPi, webSearchConfigFromEnv, webSearchProxyEnv, writeAgentsContext, writePiModelsConfig, writeWebToolsConfig, } from './pi.js';
+import { CONTEXT_DIR, materializeContextFiles, materializeSkillResources, mergeGuardLimits, progressGuardLimitsFromEnv, runPi, webSearchConfigFromEnv, webSearchProxyEnv, writeAgentsContext, writePiModelsConfig, writeWebToolsConfig, } from './pi.js';
 import { runSubscriptionHarness } from './agent-runner.js';
 // The thin base every container agent shares: an ephemeral working directory, and
 // one Pi run inside it driven by the harness-written context. The agents differ in
@@ -117,6 +117,13 @@ export async function runAgentInWorkspace(spec, opts = {}) {
     // harness paths; kept out of the agent's commits via a local git exclude entry.
     const contextFiles = spec.contextFiles ?? [];
     await materializeContextFiles(spec.dir, contextFiles);
+    // Repo-sourced skill (slice 2): claude-code installs it natively (written by the runner into the
+    // config dir), so it reads from there. Every other harness (Pi/codex) reads the checkout, so
+    // materialise the skill's resources under `.cat-context/skill/` (its instructions are folded
+    // into the prompt by the backend). A resource-free skill is a no-op here.
+    if (spec.skill && spec.harness !== 'claude-code') {
+        await materializeSkillResources(spec.dir, spec.skill);
+    }
     // Subscription harnesses (Claude Code / Codex) authenticate with the leased
     // token and talk direct to the vendor — no proxy config, no AGENTS.md. The
     // system prompt is passed straight to the CLI; everything around this (clone,
@@ -135,6 +142,7 @@ export async function runAgentInWorkspace(spec, opts = {}) {
             ...(spec.subscriptionToken ? { subscriptionToken: spec.subscriptionToken } : {}),
             subscriptionBaseUrl: spec.subscriptionBaseUrl,
             ...(spec.ambientAuth ? { ambientAuth: true } : {}),
+            ...(spec.skill ? { skill: spec.skill } : {}),
             signal: opts.signal,
             onActivity: opts.onActivity,
             onProgress: opts.onProgress,

package/dist/pi.js

@@ -206,6 +206,36 @@ export async function materializeContextFiles(cwd, files) {
         // No writable .git/info; the files simply stay untracked (still not auto-added on most flows).
     }
 }
+/** Subdirectory of {@link CONTEXT_DIR} where a repo-sourced skill's resources are materialised. */
+export const SKILL_CONTEXT_SUBDIR = 'skill';
+/**
+ * Materialise a repo-sourced skill's RESOURCE files under `.cat-context/skill/` in the checkout
+ * (repo-sourced Claude Skills, slice 2) — the Pi/codex path, whose agents read the checkout rather
+ * than a native `~/.claude/skills` dir (the skill's instructions are folded into their prompt by
+ * the backend). Resource sub-paths were sanitized at the job boundary (no traversal), so nested
+ * dirs are created as needed. Kept out of the agent's commits via the same `.cat-context/` git
+ * exclude entry. A skill with no resource bodies is a no-op.
+ */
+export async function materializeSkillResources(cwd, skill) {
+    if (!skill.resources.length)
+        return;
+    const dir = join(cwd, CONTEXT_DIR, SKILL_CONTEXT_SUBDIR);
+    await mkdir(dir, { recursive: true });
+    for (const r of skill.resources) {
+        const dest = join(dir, r.relPath);
+        await mkdir(dirname(dest), { recursive: true });
+        await writeFile(dest, r.content, 'utf8');
+    }
+    const gitRoot = await findGitRoot(cwd);
+    if (!gitRoot)
+        return;
+    try {
+        await appendFile(join(gitRoot, '.git', 'info', 'exclude'), `\n${CONTEXT_DIR}/\n`, 'utf8');
+    }
+    catch {
+        // No writable .git/info; the files simply stay untracked.
+    }
+}
 /** Walk up from `dir` (bounded) to the directory containing a `.git` folder, or null. */
 async function findGitRoot(dir) {
     let current = dir;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.43.8",
+  "version": "1.47.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -26,8 +26,8 @@
     "hono": "^4.12.29",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/server": "0.122.0",
-    "@cat-factory/spend": "0.12.34"
+    "@cat-factory/server": "0.129.0",
+    "@cat-factory/spend": "0.12.41"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process'
-import { mkdtemp, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
 import type { HarnessCallMetric, PiRunOutcome, PiRunStats, TodoProgress } from './pi.js'
 import { killChildProcess, spawnDetached } from './process.js'
 import { redact, secretsToRedact } from './redact.js'
@@ -52,6 +52,18 @@ export interface SubscriptionRunOptions {
    * container.
    */
   ambientAuth?: boolean
+  /**
+   * A repo-sourced Claude Skill to install natively before launch (repo-sourced Claude Skills,
+   * slice 2). The claude-code runner writes it to `CLAUDE_CONFIG_DIR/skills/<name>/SKILL.md`
+   * (+ resource files) so the CLI loads it; the codex runner ignores it (codex reads the
+   * checkout's `.cat-context/skill/`, materialised by the caller). Absent ⇒ no skill installed.
+   */
+  skill?: {
+    name: string
+    description: string
+    instructions: string
+    resources: { relPath: string; content: string }[]
+  }
   /** Aborting this kills the CLI (the job's inactivity/max-duration watchdog). */
   signal?: AbortSignal
   /** Called on every chunk of CLI output, so the watchdog sees the agent is alive. */
@@ -202,6 +214,35 @@ function streamCli(
  * `TodoWrite` tool calls onto subtask progress and the terminal `result` event
  * onto the summary + usage.
  */
+/**
+ * Write a repo-sourced skill as a NATIVE Claude Code skill under `<skillsRoot>/<name>/`: a
+ * `SKILL.md` (YAML frontmatter `name`/`description` + the instructions body, the format the CLI
+ * expects) plus every resource file at its path within the skill directory. Resource sub-paths
+ * were sanitized at the job boundary (no traversal), so nested dirs are created as needed.
+ *
+ * The frontmatter `name`/`description` values are emitted as JSON-encoded (double-quoted) YAML
+ * scalars, not bare plain scalars: an author's description routinely contains `: ` (colon-space)
+ * or a leading YAML indicator (`#`, `-`, `[`, `{`, `"`, …), which is invalid as a plain scalar and
+ * would make the CLI fail to parse the frontmatter and silently skip the skill. A JSON string is a
+ * valid YAML double-quoted scalar, so quoting makes the manifest robust to arbitrary text.
+ */
+async function writeNativeSkill(
+  skillsRoot: string,
+  skill: NonNullable<SubscriptionRunOptions['skill']>,
+): Promise<void> {
+  const dir = join(skillsRoot, skill.name)
+  await mkdir(dir, { recursive: true })
+  const name = JSON.stringify(skill.name)
+  const description = JSON.stringify(skill.description.replace(/\r?\n/g, ' '))
+  const frontmatter = `---\nname: ${name}\ndescription: ${description}\n---\n`
+  await writeFile(join(dir, 'SKILL.md'), `${frontmatter}\n${skill.instructions}\n`, 'utf8')
+  for (const resource of skill.resources) {
+    const dest = join(dir, resource.relPath)
+    await mkdir(dirname(dest), { recursive: true })
+    await writeFile(dest, resource.content, 'utf8')
+  }
+}
+
 export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRunOutcome> {
   const stats: PiRunStats = { toolCalls: 0, assistantChars: 0 }
   let summary = ''
@@ -297,6 +338,17 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     ).catch(() => {})
   }
 
+  // Repo-sourced Claude Skill (slice 2): install it as a native skill under the config dir's
+  // `skills/<name>/` so the CLI discovers and can invoke it. Written to the isolated per-run
+  // config home when present, else the developer's `~/.claude` (ambient/native mode). Best-effort:
+  // a write failure must not wedge the run — the prompt still names the skill.
+  if (opts.skill) {
+    const skillsRoot = configHome
+      ? join(configHome, 'skills')
+      : join(homedir(), '.claude', 'skills')
+    await writeNativeSkill(skillsRoot, opts.skill).catch(() => {})
+  }
+
   // Anthropic itself authenticates with the subscription OAuth token; a
   // non-Anthropic Claude-Code vendor (GLM via Z.ai, Kimi via Moonshot, DeepSeek)
   // points Claude Code at its Anthropic-compatible endpoint with an auth-token key.

package/src/agent.ts

@@ -797,6 +797,19 @@ async function runMultiRepoExplore(job: AgentJob, opts: RunOptions): Promise<Age
   })
 }
 
+/**
+ * Whether a Ralph iteration ({@link AgentJob.validation} set) landed on a MULTI-REPO job (writable
+ * peer repos or read-only reference repos). The post-commit validation command is only wired into
+ * the single-repo flow, so a multi-repo run would silently skip it and degenerate the loop into a
+ * one-shot with no completion gate — multi-repo ralph is out of scope for v1 (see
+ * backend/docs/ralph-loop.md), so {@link runCodingMode} fails loudly on this instead.
+ */
+export function ralphUnsupportedOnMultiRepo(
+  job: Pick<AgentJob, 'validation' | 'peerRepos' | 'referenceRepos'>,
+): boolean {
+  return Boolean(job.validation) && Boolean(job.peerRepos?.length || job.referenceRepos?.length)
+}
+
 /**
  * Edit-and-push coding, dispatching on job DATA: repo-bootstrap (force-push a fresh history to a
  * separate target repo), conflict-resolution (merge the base in, resolve, push back), multi-repo
@@ -819,10 +832,22 @@ async function runCodingMode(job: AgentJob, opts: RunOptions): Promise<AgentResu
   // all of them. Keyed off job DATA, not the agent kind — set for the implementer's writable
   // peer repos (service-connections phase 3, `peerRepos`) OR the doc-writer's READ-ONLY
   // reference repos (`referenceRepos`, cloned but never pushed).
-  const result =
-    job.peerRepos?.length || job.referenceRepos?.length
-      ? await runMultiRepoCoding(job, opts)
-      : await runSingleRepoCoding(job, opts)
+  const multiRepo = Boolean(job.peerRepos?.length || job.referenceRepos?.length)
+  // Ralph loop (v1): the post-commit validation command is only wired into the single-repo
+  // flow, so a multi-repo run would silently skip it and the loop would degenerate into a
+  // one-shot with no completion gate. Multi-repo ralph is deliberately out of scope for v1
+  // (see backend/docs/ralph-loop.md), so FAIL LOUDLY rather than run a validation-less pass.
+  if (ralphUnsupportedOnMultiRepo(job)) {
+    return {
+      error:
+        'Ralph loop is not supported on a multi-repo task (connected service repos). ' +
+        'Its validation command runs only in the single primary-repo checkout. ' +
+        'Run the Ralph loop on a task scoped to a single repo.',
+    }
+  }
+  const result = multiRepo
+    ? await runMultiRepoCoding(job, opts)
+    : await runSingleRepoCoding(job, opts)
 
   // Structured coding kind (repro-test): fold the final reply's JSON onto `custom` so the
   // backend post-completion resolver records the outcome. Skipped on a failed run (its `error`
@@ -843,34 +868,51 @@ async function runCodingMode(job: AgentJob, opts: RunOptions): Promise<AgentResu
  */
 async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<AgentResult> {
   const pushBranch = job.pushBranch ?? job.newBranch ?? job.branch
-  const { summary, stats, stderrTail, pushed, usage, callMetrics } = await runCodingAgent(
-    {
-      kind: 'agent',
-      jobId: job.jobId,
-      repo: job.repo,
-      cloneBranch: job.branch,
-      ...(job.newBranch ? { newBranch: job.newBranch } : {}),
-      pushBranch,
-      ghToken: job.ghToken,
-      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,
-      commitMessage: job.commitMessage ?? job.pr?.title ?? 'Agent changes',
-      webToolsGuidance: job.webToolsGuidance,
-      webSearchProxy: job.webSearch,
-      guardLimits: job.guardLimits,
-      ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
-      ...(job.streamFollowUps ? { streamFollowUps: true } : {}),
-      ...(job.referenceBranches?.length ? { referenceBranches: job.referenceBranches } : {}),
-    },
-    opts,
-  )
+  const { summary, stats, stderrTail, pushed, usage, callMetrics, validation } =
+    await runCodingAgent(
+      {
+        kind: 'agent',
+        jobId: job.jobId,
+        repo: job.repo,
+        cloneBranch: job.branch,
+        ...(job.newBranch ? { newBranch: job.newBranch } : {}),
+        pushBranch,
+        ghToken: job.ghToken,
+        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,
+        commitMessage: job.commitMessage ?? job.pr?.title ?? 'Agent changes',
+        webToolsGuidance: job.webToolsGuidance,
+        webSearchProxy: job.webSearch,
+        guardLimits: job.guardLimits,
+        ...(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 } : {}),
+        // Ralph loop: run the completion command after the agent commits and report its verdict.
+        ...(job.validation
+          ? {
+              validation: {
+                command: job.validation.command,
+                ...(job.validation.iteration !== undefined
+                  ? { iteration: job.validation.iteration }
+                  : {}),
+              },
+            }
+          : {}),
+      },
+      opts,
+    )
+  // Ralph loop: the harness-computed validation verdict, forwarded onto the coding result as
+  // `ralphVerdict` so the backend's `toRunResult` lifts it onto `AgentRunResult.ralphVerdict`.
+  const ralphVerdict = validation ? { ralphVerdict: validation } : {}
 
   if (!pushed) {
     // A no-op: a failure for the implementer, a clean non-event for the fixers.
@@ -882,6 +924,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
         stats,
         ...(usage ? { usage } : {}),
         ...(callMetrics ? { callMetrics } : {}),
+        ...ralphVerdict,
       }
     }
     return {
@@ -951,6 +994,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       stats,
       ...(usage ? { usage } : {}),
       ...(callMetrics ? { callMetrics } : {}),
+      ...ralphVerdict,
     }
   }
   return {
@@ -960,6 +1004,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
     stats,
     ...(usage ? { usage } : {}),
     ...(callMetrics ? { callMetrics } : {}),
+    ...ralphVerdict,
   }
 }
 

package/src/coding-agent.ts

@@ -1,5 +1,8 @@
 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 type {
   AgentJob,
   AgentResult,
@@ -7,6 +10,7 @@ import type {
   PeerRepoSpec,
   ReferenceRepoSpec,
   RepoSpec,
+  SkillSpec,
 } from './job.js'
 import {
   branchAheadOfBase,
@@ -36,7 +40,7 @@ import {
 } from './pi-workspace.js'
 import type { ProgressGuardLimits } from './pi.js'
 import type { RunOptions } from './runner.js'
-import { log } from './logger.js'
+import { log, type Logger } from './logger.js'
 
 // The shared skeleton for the container coding agents that clone a repo, run Pi
 // against it and push the result on a branch. The implementation (`/run`) and
@@ -92,6 +96,18 @@ export interface CodingAgentSpec extends HarnessAuthFields {
    * them. Best-effort per branch. Absent/empty ⇒ none fetched.
    */
   referenceBranches?: string[]
+  /**
+   * Ralph loop: run this programmatic completion command in the checkout AFTER the agent
+   * commits + pushes, capturing its exit code + a bounded output tail (the loop's exit
+   * condition — computed by the harness, never the model). Absent for every non-`ralph` run.
+   */
+  validation?: { command: string; iteration?: number }
+  /**
+   * A repo-sourced Claude Skill to make available for this run (a `skill` step, slice 2). Threaded
+   * into {@link runAgentInWorkspace}, which installs it harness-aware (native `~/.claude/skills`
+   * for claude-code, `.cat-context/skill/` for Pi/codex). Absent ⇒ no skill.
+   */
+  skill?: SkillSpec
 }
 
 /** The outcome of a coding agent run, before each caller maps it to its own result shape. */
@@ -107,6 +123,17 @@ export interface CodingAgentOutcome {
   usage?: { inputTokens: number; outputTokens: number }
   /** Per-model-call telemetry from a subscription harness's CLI stream (absent for Pi). */
   callMetrics?: HarnessCallMetric[]
+  /**
+   * Ralph loop: the verdict of the post-commit validation command (whether it exited 0, the
+   * exit code, and a bounded/redacted output tail). Present only when {@link CodingAgentSpec.validation}
+   * was set. The exit code is the loop's authoritative completion signal.
+   */
+  validation?: {
+    validationPassed: boolean
+    exitCode: number
+    validationOutputTail?: string
+    iteration?: number
+  }
 }
 
 /**
@@ -350,6 +377,7 @@ export async function runCodingAgent(
             webToolsGuidance: spec.webToolsGuidance,
             webSearchProxy: spec.webSearchProxy,
             guardLimits: spec.guardLimits,
+            ...(spec.skill ? { skill: spec.skill } : {}),
           },
           opts,
         )
@@ -425,6 +453,14 @@ export async function runCodingAgent(
             ...(callMetrics ? { callMetrics } : {}),
           }
         }
+
+        // Ralph loop: run the programmatic completion command against the pushed/committed
+        // state and attach its verdict (exit code = the loop's authoritative done signal).
+        // 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)
+        }
       } finally {
         // Safety net for the throw path (the happy path already cleared these above).
         clearInterval(checkpoint)
@@ -435,6 +471,94 @@ export async function runCodingAgent(
   )
 }
 
+/**
+ * The Ralph-loop validation watchdog: the longest a completion command may run before it is
+ * 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(): number {
+  const n = Number(process.env.RALPH_VALIDATION_TIMEOUT_MS)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 15 * 60_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.
+ */
+async function runRalphValidation(
+  cwd: string,
+  validation: { command: string; iteration?: number },
+  logger: Logger,
+  opts: RunOptions,
+): Promise<{
+  validationPassed: boolean
+  exitCode: number
+  validationOutputTail?: string
+  iteration?: number
+}> {
+  const timeoutMs = ralphValidationTimeoutMs()
+  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], {
+      cwd,
+      detached: spawnDetached,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    // Keep only the tail; guard against unbounded buffering on a chatty command.
+    const capture = (chunk: Buffer): void => {
+      out = (out + chunk.toString('utf8')).slice(-MAX_CAPTURED_OUTPUT_CHARS)
+    }
+    child.stdout?.on('data', capture)
+    child.stderr?.on('data', capture)
+    const finish = (exitCode: number): void => {
+      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 = (): void => {
+      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)
+    })
+    child.on('close', (code) => finish(code ?? 1))
+  })
+}
+
 /** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
 export function safeDirSegment(value: string): string {
   return value.replace(/[^A-Za-z0-9._-]/g, '-') || '_'

package/src/job.ts

@@ -153,6 +153,26 @@ function parseGuardLimits(value: unknown): GuardLimitsSpec | undefined {
   return Object.keys(spec).length > 0 ? spec : undefined
 }
 
+/**
+ * Parse the optional Ralph-loop validation spec. Requires a non-empty `command` string (the
+ * completion criterion the harness runs); `progressPath`/`iteration` are optional metadata.
+ * Returns undefined when absent or malformed (a coding run then behaves like any other — no
+ * post-commit validation). See {@link ValidationSpec}.
+ */
+function parseValidationSpec(value: unknown): ValidationSpec | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const o = value as Record<string, unknown>
+  if (typeof o.command !== 'string' || o.command.trim() === '') return undefined
+  const iteration = posInt(o.iteration)
+  return {
+    command: o.command,
+    ...(typeof o.progressPath === 'string' && o.progressPath
+      ? { progressPath: o.progressPath }
+      : {}),
+    ...(iteration !== undefined ? { iteration } : {}),
+  }
+}
+
 /**
  * Parse the shared per-job auth fields, validating per harness: a subscription
  * harness (`claude-code` / `codex`) requires `subscriptionToken`; the default Pi
@@ -601,6 +621,26 @@ export interface ContextFileSpec {
   content: string
 }
 
+/** One materialisable resource file of a skill (repo-sourced Claude Skills). */
+export interface SkillResourceSpec {
+  /** Path within the skill directory, e.g. `templates/report.md` (subdirs preserved, no traversal). */
+  relPath: string
+  content: string
+}
+
+/**
+ * A repo-sourced Claude Skill to make available for a `skill` step. Materialised HARNESS-AWARE:
+ * `CLAUDE_CONFIG_DIR/skills/<name>/SKILL.md` (+ resources) for the claude-code CLI to load
+ * natively, or `.cat-context/skill/<relPath>` for the Pi/codex checkout (their prompt carries the
+ * instructions). A dedicated top-level body field (like `packageRegistries`), never a context file.
+ */
+export interface SkillSpec {
+  name: string
+  description: string
+  instructions: string
+  resources: SkillResourceSpec[]
+}
+
 /** How an explore agent's reply is consumed. */
 export interface AgentOutputSpec {
   /** `prose` keeps the reply text; `structured` parses (and optionally repairs) it to JSON. */
@@ -627,6 +667,23 @@ export interface AgentOutputSpec {
  * RUNNING — no agent runs and the serve is deliberately not torn down when the job returns
  * (see {@link AgentResult.preview}).
  */
+/**
+ * Coding mode (Ralph loop): the programmatic completion criterion. After the coding agent
+ * commits + pushes, the harness runs {@link command} in the checkout and reports its exit
+ * code back on {@link AgentResult.ralphVerdict} — exit 0 means the loop is done. This is the
+ * whole point of a Ralph loop's exit condition being a REAL check: the harness runs it, not
+ * the model. The command runs only inside the sandboxed run container (same trust boundary
+ * as the coding agent). Absent for every non-`ralph` coding run.
+ */
+export interface ValidationSpec {
+  /** The shell command the harness runs against the checkout (exit 0 = the criterion is met). */
+  command: string
+  /** Repo-relative progress-log path the agent maintains (informational; the harness doesn't write it). */
+  progressPath?: string
+  /** 1-based iteration number, echoed back on the verdict for the engine's attempt log. */
+  iteration?: number
+}
+
 export interface AgentJob extends HarnessAuthFields {
   jobId: string
   mode: AgentMode
@@ -670,6 +727,12 @@ export interface AgentJob extends HarnessAuthFields {
    * job on a reused container is removed.
    */
   packageRegistries?: PackageRegistrySpec[]
+  /**
+   * A repo-sourced Claude Skill to make available for a `skill` step (see {@link SkillSpec}).
+   * Materialised harness-aware before the run: natively into `CLAUDE_CONFIG_DIR/skills/<name>/`
+   * for claude-code, or `.cat-context/skill/<relPath>` for Pi/codex. Absent ⇒ no skill installed.
+   */
+  skill?: SkillSpec
   /**
    * Tester kinds only: sensitive test credentials injected into the run's ENVIRONMENT (out of
    * band) as `{ key, value }` env pairs, so the tester's shell can read `$KEY` without the value
@@ -753,6 +816,11 @@ export interface AgentJob extends HarnessAuthFields {
    * killed for a kind's normal working pattern. Absent ⇒ env/default for all knobs.
    */
   guardLimits?: GuardLimitsSpec
+  /**
+   * Coding mode (Ralph loop): the programmatic completion command the harness runs after the
+   * agent commits + pushes. Present only for a `ralph` iteration. See {@link ValidationSpec}.
+   */
+  validation?: ValidationSpec
 }
 
 /** Per-job, per-knob progress-guard overrides (see {@link AgentJob.guardLimits}). */
@@ -809,6 +877,18 @@ export interface AgentResult {
   pushed?: boolean
   prUrl?: string
   branch?: string
+  /**
+   * Coding mode (Ralph loop): the harness-computed verdict of the post-commit validation
+   * command — whether it exited 0, its exit code, and a bounded, redacted output tail. The
+   * engine reads this (never a model self-report) to decide whether the loop is done or must
+   * iterate again. Present only for a `ralph` iteration ({@link AgentJob.validation} set).
+   */
+  ralphVerdict?: {
+    validationPassed: boolean
+    exitCode: number
+    validationOutputTail?: string
+    iteration?: number
+  }
   /**
    * Coding mode (multi-repo): the PRs opened in the connected services' PEER repos, one per
    * repo the run actually changed (service-connections phase 3). Beside the own-service
@@ -889,6 +969,71 @@ function parseContextFiles(value: unknown): ContextFileSpec[] {
   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: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const segments = value.replace(/\\/g, '/').split('/')
+  const clean: string[] = []
+  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: unknown): string | undefined {
+  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: unknown): SkillSpec | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const o = value as Record<string, unknown>
+  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: SkillResourceSpec[] = []
+  if (Array.isArray(o.resources)) {
+    const used = new Set<string>()
+    for (const entry of o.resources) {
+      if (typeof entry !== 'object' || entry === null) continue
+      const e = entry as Record<string, unknown>
+      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: unknown): AgentInfraSpec | undefined {
   if (typeof value !== 'object' || value === null) return undefined
@@ -1128,8 +1273,10 @@ export function parseAgentJob(input: unknown): AgentJob {
   const bootstrap = parseAgentBootstrapSpec(o.bootstrap)
   const contextFiles = parseContextFiles(o.contextFiles)
   const packageRegistries = parsePackageRegistries(o.packageRegistries)
+  const skill = parseSkillSpec(o.skill)
   const testSecrets = parseTestSecrets(o.testSecrets)
   const guardLimits = parseGuardLimits(o.guardLimits)
+  const validation = parseValidationSpec(o.validation)
   const job: AgentJob = {
     jobId: str(o.jobId, 'jobId'),
     mode,
@@ -1149,6 +1296,7 @@ export function parseAgentJob(input: unknown): AgentJob {
     ...(output ? { output } : {}),
     ...(contextFiles.length ? { contextFiles } : {}),
     ...(packageRegistries.length ? { packageRegistries } : {}),
+    ...(skill ? { skill } : {}),
     ...(testSecrets.length ? { testSecrets } : {}),
     ...(infra ? { infra } : {}),
     ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),
@@ -1164,6 +1312,7 @@ export function parseAgentJob(input: unknown): AgentJob {
     ...(o.persistentCheckout === true ? { persistentCheckout: true } : {}),
     ...(o.streamFollowUps === true ? { streamFollowUps: true } : {}),
     ...(guardLimits ? { guardLimits } : {}),
+    ...(validation ? { validation } : {}),
   }
   assertAllowedHost(job.repo.cloneUrl, 'repo.cloneUrl')
   if (job.githubApiBase) assertAllowedHost(job.githubApiBase, 'githubApiBase')

package/src/pi-workspace.ts

@@ -1,7 +1,7 @@
 import { mkdir, mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import type { RepoSpec } from './job.js'
+import type { RepoSpec, SkillSpec } from './job.js'
 import { log } from './logger.js'
 import {
   type ContextFileInfo,
@@ -11,6 +11,7 @@ import {
   type RunDiagnostics,
   CONTEXT_DIR,
   materializeContextFiles,
+  materializeSkillResources,
   mergeGuardLimits,
   progressGuardLimitsFromEnv,
   runPi,
@@ -201,6 +202,13 @@ export interface AgentRunSpec {
    * from AGENTS.md, so the agent reads them on demand. Absent ⇒ none.
    */
   contextFiles?: ContextFileInfo[]
+  /**
+   * A repo-sourced Claude Skill to make available for this run (slice 2). Installed HARNESS-AWARE:
+   * the claude-code runner writes it natively into the config dir's `skills/`; for Pi/codex the
+   * resource files are materialised under `.cat-context/skill/` (their prompt already carries the
+   * folded-in instructions). Absent ⇒ no skill.
+   */
+  skill?: SkillSpec
   /**
    * Enable proxy-backed web search: point the rpiv-web-tools SearXNG provider at the
    * backend's search proxy (`${proxyBaseUrl}/web-search`) with the session token as
@@ -232,6 +240,13 @@ export async function runAgentInWorkspace(
   // harness paths; kept out of the agent's commits via a local git exclude entry.
   const contextFiles = spec.contextFiles ?? []
   await materializeContextFiles(spec.dir, contextFiles)
+  // Repo-sourced skill (slice 2): claude-code installs it natively (written by the runner into the
+  // config dir), so it reads from there. Every other harness (Pi/codex) reads the checkout, so
+  // materialise the skill's resources under `.cat-context/skill/` (its instructions are folded
+  // into the prompt by the backend). A resource-free skill is a no-op here.
+  if (spec.skill && spec.harness !== 'claude-code') {
+    await materializeSkillResources(spec.dir, spec.skill)
+  }
 
   // Subscription harnesses (Claude Code / Codex) authenticate with the leased
   // token and talk direct to the vendor — no proxy config, no AGENTS.md. The
@@ -251,6 +266,7 @@ export async function runAgentInWorkspace(
       ...(spec.subscriptionToken ? { subscriptionToken: spec.subscriptionToken } : {}),
       subscriptionBaseUrl: spec.subscriptionBaseUrl,
       ...(spec.ambientAuth ? { ambientAuth: true } : {}),
+      ...(spec.skill ? { skill: spec.skill } : {}),
       signal: opts.signal,
       onActivity: opts.onActivity,
       onProgress: opts.onProgress,

package/src/pi.ts

@@ -244,6 +244,38 @@ export async function materializeContextFiles(
   }
 }
 
+/** Subdirectory of {@link CONTEXT_DIR} where a repo-sourced skill's resources are materialised. */
+export const SKILL_CONTEXT_SUBDIR = 'skill'
+
+/**
+ * Materialise a repo-sourced skill's RESOURCE files under `.cat-context/skill/` in the checkout
+ * (repo-sourced Claude Skills, slice 2) — the Pi/codex path, whose agents read the checkout rather
+ * than a native `~/.claude/skills` dir (the skill's instructions are folded into their prompt by
+ * the backend). Resource sub-paths were sanitized at the job boundary (no traversal), so nested
+ * dirs are created as needed. Kept out of the agent's commits via the same `.cat-context/` git
+ * exclude entry. A skill with no resource bodies is a no-op.
+ */
+export async function materializeSkillResources(
+  cwd: string,
+  skill: { resources: { relPath: string; content: string }[] },
+): Promise<void> {
+  if (!skill.resources.length) return
+  const dir = join(cwd, CONTEXT_DIR, SKILL_CONTEXT_SUBDIR)
+  await mkdir(dir, { recursive: true })
+  for (const r of skill.resources) {
+    const dest = join(dir, r.relPath)
+    await mkdir(dirname(dest), { recursive: true })
+    await writeFile(dest, r.content, 'utf8')
+  }
+  const gitRoot = await findGitRoot(cwd)
+  if (!gitRoot) return
+  try {
+    await appendFile(join(gitRoot, '.git', 'info', 'exclude'), `\n${CONTEXT_DIR}/\n`, 'utf8')
+  } catch {
+    // No writable .git/info; the files simply stay untracked.
+  }
+}
+
 /** Walk up from `dir` (bounded) to the directory containing a `.git` folder, or null. */
 async function findGitRoot(dir: string): Promise<string | null> {
   let current = dir