@cat-factory/executor-harness 1.66.0 → 1.68.0

package/src/coding-agent.ts

@@ -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 type {
   AgentJob,
   AgentResult,
@@ -11,6 +9,7 @@ import type {
   ReferenceRepoSpec,
   RepoSpec,
   SkillSpec,
+  McpServerSpec,
 } from './job.js'
 import {
   branchAheadOfBase,
@@ -140,12 +139,18 @@ export interface CodingAgentSpec extends HarnessAuthFields {
    */
   reproduction?: ReproductionSpec
   /**
-   * 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: natively under the ISOLATED
-   * `CLAUDE_CONFIG_DIR` for a leased-credential claude-code run, `.cat-context/skill/` for everything
-   * else (Pi, codex, and ambient claude-code, which has no isolated config dir). Absent ⇒ no skill.
+   * The skills to make available for this run — a `skill` step's pick and/or the running kind's
+   * declared playbooks. Threaded into {@link runAgentInWorkspace}, which installs them
+   * harness-aware: natively under the ISOLATED `CLAUDE_CONFIG_DIR` for a leased-credential
+   * claude-code run, `.cat-context/skill/<name>/` for everything else (Pi, codex, and ambient
+   * claude-code, which has no isolated config dir). Absent ⇒ no skills.
    */
-  skill?: SkillSpec
+  skills?: SkillSpec[]
+  /**
+   * Tool servers (MCP) to wire into the agent CLI for this run. Forwarded verbatim — the backend
+   * has already dropped anything this harness cannot serve. Absent ⇒ built-in tools only.
+   */
+  mcpServers?: McpServerSpec[]
 }
 
 /** The outcome of a coding agent run, before each caller maps it to its own result shape. */
@@ -179,6 +184,8 @@ export interface CodingAgentOutcome {
     exitCode: number
     validationOutputTail?: string
     iteration?: number
+    /** The work-branch HEAD the command was judged against (absent when it could not be read). */
+    headSha?: string
   }
   /**
    * The pre-PR validation loop's LAST attempt (present only when {@link CodingAgentSpec.validationChecks}
@@ -350,7 +357,8 @@ export async function runCodingAgent(
             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,
         )
@@ -718,7 +726,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
@@ -796,22 +804,57 @@ function mergeAgentPasses<T extends Awaited<ReturnType<typeof runAgentInWorkspac
  * 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 {
+export function ralphValidationTimeoutMs(): number {
   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(): number {
+  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(
+export async function runRalphValidation(
+  repoDir: string,
   cwd: string,
   validation: { command: string; iteration?: number },
   logger: Logger,
@@ -821,66 +864,50 @@ async function runRalphValidation(
   exitCode: number
   validationOutputTail?: string
   iteration?: number
+  headSha?: string
 }> {
-  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], {
+  // 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: 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)
+  } 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: unknown) => {
+    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. */
@@ -1030,6 +1057,10 @@ export async function runMultiRepoCoding(
           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,

package/src/job.ts

@@ -12,6 +12,16 @@ import {
   type ReproductionReport,
   type ReproductionSpec,
 } from './reproduction-proof.js'
+import {
+  parseMcpServerSpecs,
+  parseSkillSpecs,
+  type McpServerSpec,
+  type SkillResourceSpec,
+  type SkillSpec,
+} from './agent-capabilities.js'
+
+// Re-exported so the job body stays the one import site for a harness handler describing a job.
+export type { McpServerSpec, SkillResourceSpec, SkillSpec }
 
 // The job the Worker's ContainerAgentExecutor POSTs to /run. Kept as plain
 // types with a hand-rolled validator so the image needs no schema dependency.
@@ -632,26 +642,6 @@ 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. */
@@ -739,11 +729,20 @@ export interface AgentJob extends HarnessAuthFields {
    */
   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.
+   * The skills to make available for this run (see {@link SkillSpec}) — a `skill` step's picked
+   * skill and/or the playbooks the running agent kind declares. Materialised harness-aware before
+   * the run: natively into `CLAUDE_CONFIG_DIR/skills/<name>/` for claude-code, or
+   * `.cat-context/skill/<name>/<relPath>` for Pi/codex. Absent ⇒ no skills installed.
+   */
+  skills?: SkillSpec[]
+  /**
+   * Tool servers (MCP) to wire into the agent CLI for this run (see {@link McpServerSpec}). The
+   * backend has already dropped anything this harness cannot serve, so every entry here is
+   * expected to work. SECRET-BEARING (`env`/`headers` carry resolved credentials), so the config
+   * files written from it live outside the checkout and are never logged. Absent ⇒ the CLI's
+   * built-in tools only.
    */
-  skill?: SkillSpec
+  mcpServers?: McpServerSpec[]
   /**
    * 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
@@ -942,6 +941,12 @@ export interface AgentResult {
     exitCode: number
     validationOutputTail?: string
     iteration?: number
+    /**
+     * The work-branch HEAD the command was judged against. The engine compares it across
+     * consecutive failing iterations to end a loop that has stopped committing anything,
+     * instead of spending the rest of its budget re-learning that. Absent when unreadable.
+     */
+    headSha?: string
   }
   /**
    * Coding mode (multi-repo): the PRs opened in the connected services' PEER repos, one per
@@ -1029,71 +1034,6 @@ 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
@@ -1335,7 +1275,8 @@ export function parseAgentJob(input: unknown): AgentJob {
     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),
@@ -1374,7 +1315,8 @@ interface ParsedAgentJobParts {
   bootstrap: ReturnType<typeof parseAgentBootstrapSpec>
   contextFiles: ReturnType<typeof parseContextFiles>
   packageRegistries: ReturnType<typeof parsePackageRegistries>
-  skill: ReturnType<typeof parseSkillSpec>
+  skills: ReturnType<typeof parseSkillSpecs>
+  mcpServers: ReturnType<typeof parseMcpServerSpecs>
   testSecrets: ReturnType<typeof parseTestSecrets>
   guardLimits: ReturnType<typeof parseGuardLimits>
   validation: ReturnType<typeof parseValidationSpec>
@@ -1428,7 +1370,8 @@ function assembleAgentJob(
     bootstrap,
     contextFiles,
     packageRegistries,
-    skill,
+    skills,
+    mcpServers,
     testSecrets,
     guardLimits,
     validation,
@@ -1452,7 +1395,8 @@ function assembleAgentJob(
     ...(output ? { output } : {}),
     ...(contextFiles.length ? { contextFiles } : {}),
     ...(packageRegistries.length ? { packageRegistries } : {}),
-    ...(skill ? { skill } : {}),
+    ...(skills ? { skills } : {}),
+    ...(mcpServers ? { mcpServers } : {}),
     ...(testSecrets.length ? { testSecrets } : {}),
     ...(infra ? { infra } : {}),
     ...(pr ? { pr } : {}),

package/src/pi-workspace.ts

@@ -1,7 +1,8 @@
 import { mkdir, mkdtemp, readdir, rm, stat } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import type { RepoSpec, SkillSpec } from './job.js'
+import type { RepoSpec } from './job.js'
+import type { McpServerSpec, SkillSpec } from './agent-capabilities.js'
 import { readEffortReport } from './effort.js'
 import { log } from './logger.js'
 import {
@@ -206,12 +207,20 @@ export interface AgentRunSpec {
    */
   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.
+   * The skills to make available for this run — a `skill` step's picked skill and/or the playbooks
+   * the running agent kind declares. Installed HARNESS-AWARE: the claude-code runner writes them
+   * natively into the config dir's `skills/`; for Pi/codex the resource files are materialised
+   * under `.cat-context/skill/<name>/` (their prompt already carries the folded-in instructions).
+   * Absent ⇒ no skills.
    */
-  skill?: SkillSpec
+  skills?: SkillSpec[]
+  /**
+   * Tool servers (MCP) to wire into the agent CLI. Served by the subscription harnesses only —
+   * Pi has no MCP client, and the BACKEND is what decides that (it drops an unservable server and
+   * tells the agent so), which is why this path simply forwards whatever it is given rather than
+   * re-deciding. Absent ⇒ the CLI's built-in tools only.
+   */
+  mcpServers?: McpServerSpec[]
   /**
    * 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
@@ -268,14 +277,14 @@ 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 into its ISOLATED config dir,
-  // so it reads from there. Everything else reads the checkout, so materialise the skill's
-  // resources under `.cat-context/skill/` (its instructions are folded into the prompt by the
-  // backend) — Pi, codex, and AMBIENT claude-code, which has no isolated config dir to install
-  // into (the runner refuses to write a repo's skill into the developer's own `~/.claude`; see
-  // `runClaudeCode`). A resource-free skill is a no-op here.
-  if (spec.skill && !installsSkillNatively(spec)) {
-    await materializeSkillResources(spec.dir, spec.skill)
+  // Skills: claude-code installs them natively into its ISOLATED config dir, so it reads from
+  // there. Everything else reads the checkout, so materialise each skill's resources under
+  // `.cat-context/skill/<name>/` (their instructions are folded into the prompt by the backend) —
+  // Pi, codex, and AMBIENT claude-code, which has no isolated config dir to install into (the
+  // runner refuses to write a skill into the developer's own `~/.claude`; see `runClaudeCode`).
+  // Resource-free skills are a no-op here.
+  if (spec.skills?.length && !installsSkillNatively(spec)) {
+    await materializeSkillResources(spec.dir, spec.skills)
   }
 
   // Subscription harnesses (Claude Code / Codex) authenticate with the leased
@@ -296,7 +305,8 @@ export async function runAgentInWorkspace(
       ...(spec.subscriptionToken ? { subscriptionToken: spec.subscriptionToken } : {}),
       subscriptionBaseUrl: spec.subscriptionBaseUrl,
       ...(spec.ambientAuth ? { ambientAuth: true } : {}),
-      ...(spec.skill ? { skill: spec.skill } : {}),
+      ...(spec.skills?.length ? { skills: spec.skills } : {}),
+      ...(spec.mcpServers?.length ? { mcpServers: spec.mcpServers } : {}),
       ...(opts.agentEnv ? { extraEnv: opts.agentEnv } : {}),
       signal: opts.signal,
       // Run the SAME no-progress guard Pi gets (previously claude-code/codex had none): env
@@ -367,12 +377,12 @@ export async function runAgentInWorkspace(
 }
 
 /**
- * Whether the claude-code runner will install this run's repo-sourced skill natively (into the
- * CLI's config dir) rather than the caller materialising it into the checkout. True ONLY for a
+ * Whether the claude-code runner will install this run's skills natively (into the CLI's config
+ * dir) rather than the caller materialising them into the checkout. True ONLY for a
  * leased-credential claude-code run, which gets a throwaway per-run config home. An AMBIENT run
- * uses the developer's own `~/.claude`, which the runner will not write a repo's skill into —
- * it would outlive the run in their personal setup, and two concurrent jobs carrying same-named
- * skills from different repos would overwrite each other's.
+ * uses the developer's own `~/.claude`, which the runner will not write a skill into — it would
+ * outlive the run in their personal setup, and two concurrent jobs carrying same-named skills
+ * would overwrite each other's.
  */
 export function installsSkillNatively(
   spec: Pick<AgentRunSpec, 'harness' | 'ambientAuth'>,

package/src/pi.ts

@@ -253,29 +253,37 @@ export async function materializeContextFiles(
   }
 }
 
-/** Subdirectory of {@link CONTEXT_DIR} where a repo-sourced skill's resources are materialised. */
+/** Subdirectory of {@link CONTEXT_DIR} where a skill's resources are materialised, per skill. */
 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 path for every run that does NOT get a native
- * install: Pi, codex, and ambient claude-code (no isolated `CLAUDE_CONFIG_DIR` to install into).
- * Their agents read the checkout, and the skill's instructions are folded into their prompt by the
- * backend (`renderSkillForHarness`, which keys off ambient auth as well as the harness). 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.
+ * Materialise the run's skills' RESOURCE files under `.cat-context/skill/<name>/` in the checkout
+ * — the path for every run that does NOT get a native install: Pi, codex, and ambient claude-code
+ * (no isolated `CLAUDE_CONFIG_DIR` to install into). Their agents read the checkout, and the
+ * skills' instructions are folded into their prompt by the backend (`renderSkillsForHarness`,
+ * which keys off ambient auth as well as the harness).
+ *
+ * Each skill gets its OWN subdirectory: several skills can apply to one run (a step's pick plus
+ * the kind's declared playbooks), and a flat directory would let two skills' `templates/report.md`
+ * overwrite each other — silently handing the agent the wrong template. The names were sanitized
+ * to a single safe path segment at the job boundary, as were the resource sub-paths (no
+ * traversal), so nested dirs are created as needed. Kept out of the agent's commits via the same
+ * `.cat-context/` git exclude entry. Skills with no resource bodies are a no-op.
  */
 export async function materializeSkillResources(
   cwd: string,
-  skill: { resources: { relPath: string; content: string }[] },
+  skills: { name: string; 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 withResources = skills.filter((s) => s.resources.length)
+  if (!withResources.length) return
+  for (const skill of withResources) {
+    const dir = join(cwd, CONTEXT_DIR, SKILL_CONTEXT_SUBDIR, skill.name)
+    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