@cat-factory/executor-harness 1.100.0 → 1.104.0

package/src/coding-agent.ts

@@ -1,12 +1,14 @@
 import { mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
 import { runCapturedCommand } from './captured-command.js'
+import { makeDirClaimer } from './checkout-dir.js'
 import type {
   AgentJob,
   AgentResult,
   HarnessAuthFields,
   PeerRepoSpec,
   ReferenceRepoSpec,
+  ReferenceScreenshotsSpec,
   RepoSpec,
   SkillSpec,
   McpServerSpec,
@@ -179,6 +181,14 @@ export interface CodingAgentSpec extends HarnessAuthFields {
    * has already dropped anything this harness cannot serve. Absent ⇒ built-in tools only.
    */
   mcpServers?: McpServerSpec[]
+  /**
+   * The task's reference design images, downloaded into `.cat-context/reference-screenshots/`
+   * before the agent's first turn. Carried on the coding path as well as the explore one because
+   * what earns a run its references is the KIND's declared `ui` image, and a deployment's own
+   * UI-facing kind may well be a coding one, and nothing here switches on which built-in it is.
+   * Absent ⇒ none (the normal case).
+   */
+  referenceScreenshots?: ReferenceScreenshotsSpec
 }
 
 /** The outcome of a coding agent run, before each caller maps it to its own result shape. */
@@ -457,6 +467,9 @@ export async function runCodingAgent(
             guardLimits: spec.guardLimits,
             ...(spec.skills?.length ? { skills: spec.skills } : {}),
             ...(spec.mcpServers?.length ? { mcpServers: spec.mcpServers } : {}),
+            ...(spec.referenceScreenshots
+              ? { referenceScreenshots: spec.referenceScreenshots }
+              : {}),
           },
           opts,
         )
@@ -1018,25 +1031,6 @@ export async function runRalphValidation(
   }
 }
 
-/** 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, '-') || '_'
-}
-
-/**
- * A sibling-directory allocator for a multi-repo run: returns the checkout directory name for a
- * repo under the workspace root. Deterministic (`owner__name`) and collision-free by construction
- * — the checkout set is deduped by `owner/name` upstream and GitHub owners contain no `_`, so the
- * `owner__name` join is unique per repo without a stateful collision dance. Kept as a factory so
- * the coding + read-only explore fan-outs share ONE scheme, and it MUST stay byte-identical to the
- * backend's `siblingCheckoutDir` / `renderMultiRepoWorkspaceSection` in `@cat-factory/server`
- * (jobBody.ts), which names this exact directory in the agent's prompt — the two are computed
- * independently, so a divergent rule would point the agent at a directory that does not exist.
- */
-export function makeDirClaimer(): (repo: Pick<RepoSpec, 'name' | 'owner'>) => string {
-  return (repo) => `${safeDirSegment(repo.owner)}__${safeDirSegment(repo.name)}`
-}
-
 /** One repository participating in a multi-repo run: where to clone it + what to do after. */
 interface RepoLeg {
   repo: RepoSpec
@@ -1086,8 +1080,9 @@ export async function runMultiRepoCoding(
   const references: ReferenceRepoSpec[] = job.referenceRepos ?? []
   const primaryWorkBranch = job.pushBranch ?? job.newBranch ?? job.branch
 
-  // Assign the sibling directory per repo via the shared deterministic allocator (`owner__name`,
-  // matching the backend prompt's `siblingCheckoutDir`), shared with the read-only explore fan-out.
+  // Assign the sibling directory per repo via the shared deterministic allocator
+  // (`owner__name__digest`, matching the backend prompt's `siblingCheckoutDir`), shared with the
+  // read-only explore fan-out.
   const claimDir = makeDirClaimer()
   const legs: RepoLeg[] = [
     {
@@ -1207,6 +1202,7 @@ export async function runMultiRepoCoding(
           // are properties of the AGENT KIND, not of the checkout layout.
           ...(job.skills?.length ? { skills: job.skills } : {}),
           ...(job.mcpServers?.length ? { mcpServers: job.mcpServers } : {}),
+          ...(job.referenceScreenshots ? { referenceScreenshots: job.referenceScreenshots } : {}),
           multiRepo: true,
         },
         opts,

package/src/context-manifests.ts

@@ -0,0 +1,156 @@
+// ---------------------------------------------------------------------------
+// The two manifests of FILES the backend stages into a checkout before the agent's first turn:
+// the linked-context documents it materialises under CONTEXT_DIR, and the reference design images
+// it has the harness download beside them.
+//
+// One module because they are the same kind of thing parsed the same defensive way, and because
+// they share the basename rule below: both name files the container writes into a directory it
+// then points the agent at, so both are held to a value that cannot escape it or clobber a repo
+// file. Split out of `job.ts`, which parses everything else a job body carries.
+// ---------------------------------------------------------------------------
+
+/**
+ * A linked-context file the backend prepared (requirements / RFC / PRD / tracker issue)
+ * for the harness to materialise under CONTEXT_DIR in the checkout, so the agent can read
+ * it on demand. The harness can't reach Jira/GitHub itself, so all such context is fetched
+ * and shipped here up front. `path` is sanitised to a safe basename on parse.
+ */
+export interface ContextFileSpec {
+  path: string
+  title: string
+  url: string
+  content: string
+}
+
+/**
+ * The REFERENCE DESIGN IMAGES the backend holds for this task, for the harness to download into
+ * `.cat-context/reference-screenshots/` before the agent runs: the directory a UI tester's prompt
+ * names and, until now, nothing wrote.
+ *
+ * A manifest rather than the bytes: a design frame is a full-page PNG, and a job body is JSON
+ * that crosses every transport and is persisted with the dispatch. The bytes come back over the
+ * SAME container session token the run already holds (`GET ${url}/<artifactId>`), so this needs
+ * no extra credential and no publicly reachable URL.
+ *
+ * `view` is what the backend's gate pairs on, and `fileName` is the name the BACKEND chose for it,
+ * never derived here. The file name is how the agent learns the view name, so deriving it in the
+ * container would let a harness image the deployment has not rolled out yet rename every view a
+ * run reports, and the pairing would come apart with nothing failing.
+ */
+export interface ReferenceScreenshotsSpec {
+  /** Base URL of the reference download route; the artifact id is appended as a path segment. */
+  url: string
+  /** The run's container session token (the same one the LLM proxy is called with). */
+  token: string
+  files: ReferenceScreenshotSpec[]
+  /**
+   * View names the task holds a reference for that this job was NOT sent a file for, because the
+   * set was capped. Stated to the agent beside the transfers that failed: from where it stands
+   * both are a view to capture with no image to compare against.
+   *
+   * Two producers, and they mean the same thing here: the BACKEND's own ceiling (the number that
+   * should ever actually bind, chosen where the precedence between an upload and a design frame
+   * is known), and this parser's backstop against a body claiming more files than any real set
+   * has. A drop with no entry here is the bug this field exists to prevent.
+   */
+  omitted: string[]
+}
+
+/** One reference image in a {@link ReferenceScreenshotsSpec}. `fileName` is sanitised on parse. */
+export interface ReferenceScreenshotSpec {
+  artifactId: string
+  fileName: string
+  view: string
+}
+
+/**
+ * Sanitise a body-supplied context filename to a safe basename within CONTEXT_DIR:
+ * strip any directory part, allow only `[A-Za-z0-9._-]`, and reject empties / dotfiles
+ * / `..` so a hostile value can't escape the directory or clobber repo files.
+ */
+export function sanitizeContextFileName(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
+}
+
+/** Parse the linked-context files, dropping any malformed/unsafe entry. */
+export function parseContextFiles(value: unknown): ContextFileSpec[] {
+  if (!Array.isArray(value)) return []
+  const files: ContextFileSpec[] = []
+  const used = new Set<string>()
+  for (const entry of value) {
+    if (typeof entry !== 'object' || entry === null) continue
+    const e = entry as Record<string, unknown>
+    const path = sanitizeContextFileName(e.path)
+    if (!path || used.has(path)) continue
+    if (typeof e.content !== 'string') continue
+    used.add(path)
+    files.push({
+      path,
+      title: typeof e.title === 'string' ? e.title : path,
+      url: typeof e.url === 'string' ? e.url : '',
+      content: e.content,
+    })
+  }
+  return files
+}
+
+/**
+ * How many reference images one job may be handed. The backend caps the set it sends well below
+ * this, so this is the harness's own backstop against a malformed or hostile body turning the
+ * pre-run setup into an unbounded download, never the ceiling a real run meets.
+ *
+ * Hitting it is REPORTED rather than silently obeyed: an entry past the ceiling is dropped from
+ * `files` and its view named on `omitted`, so an agent facing a truncated set is still told which
+ * views to capture. A cap that shortened the list and said nothing would be indistinguishable, on
+ * disk and in the prompt, from a design that simply has no such screen.
+ */
+const MAX_REFERENCE_SCREENSHOTS = 40
+
+/**
+ * Parse the reference-design manifest, or undefined when absent/unusable.
+ *
+ * The whole manifest is dropped when its transport half is unusable (no absolute http(s) URL, no
+ * token): every file would fail the same way, and one stated cause beats N identical ones. An
+ * individual entry is dropped only when it cannot name a file safely: the same basename
+ * sanitisation every context file gets, so a hostile `fileName` can neither escape the directory
+ * nor clobber a repo file.
+ */
+export function parseReferenceScreenshots(value: unknown): ReferenceScreenshotsSpec | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const o = value as Record<string, unknown>
+  const url = typeof o.url === 'string' ? o.url.trim() : ''
+  const token = typeof o.token === 'string' ? o.token : ''
+  if (!url || !token || !/^https?:\/\//i.test(url)) return undefined
+  if (!Array.isArray(o.files)) return undefined
+  const files: ReferenceScreenshotSpec[] = []
+  // The backend's own dropped views come first; anything this parser drops joins them below.
+  const omitted = Array.isArray(o.omitted)
+    ? o.omitted.filter((view): view is string => typeof view === 'string' && view.length > 0)
+    : []
+  const used = new Set<string>()
+  for (const entry of o.files) {
+    if (typeof entry !== 'object' || entry === null) continue
+    const e = entry as Record<string, unknown>
+    const fileName = sanitizeContextFileName(e.fileName)
+    const artifactId = typeof e.artifactId === 'string' ? e.artifactId.trim() : ''
+    // The id becomes a path segment on the download URL, so it is held to the shape the platform
+    // mints rather than encoded and hoped for: anything else cannot be a real artifact anyway.
+    if (!fileName || used.has(fileName) || !/^[A-Za-z0-9_-]{1,64}$/.test(artifactId)) continue
+    const view = typeof e.view === 'string' ? e.view : fileName
+    // Past the backstop the entry is NAMED, not dropped: it stays a view the agent must capture.
+    // Checked here rather than at the top of the loop so a malformed entry is refused on its own
+    // terms (it names no usable view to report) instead of being counted against the ceiling.
+    if (files.length >= MAX_REFERENCE_SCREENSHOTS) {
+      omitted.push(view)
+      continue
+    }
+    used.add(fileName)
+    files.push({ artifactId, fileName, view })
+  }
+  if (!files.length && !omitted.length) return undefined
+  return { url: url.replace(/\/+$/, ''), token, files, omitted }
+}

package/src/job.ts

@@ -22,6 +22,13 @@ import {
   type SkillSpec,
 } from './agent-capabilities.js'
 import { type TestSecretSpec, parseInfraEnv, parseSecretEnvPairs, str } from './job-env.js'
+import {
+  parseContextFiles,
+  parseReferenceScreenshots,
+  type ContextFileSpec,
+  type ReferenceScreenshotSpec,
+  type ReferenceScreenshotsSpec,
+} from './context-manifests.js'
 
 // Re-exported so a handler describing a job keeps ONE import site (the env-pair shape is a job
 // body field like any other; only its VALIDATION moved out).
@@ -30,6 +37,10 @@ export type { TestSecretSpec }
 // Re-exported so the job body stays the one import site for a harness handler describing a job.
 export type { McpServerSpec, SkillResourceSpec, SkillSpec }
 
+// Same rule for the two staged-file manifests: their shapes and their defensive parsing moved to
+// `context-manifests.ts`, but they remain job body fields, so this stays the import site.
+export type { ContextFileSpec, ReferenceScreenshotSpec, ReferenceScreenshotsSpec }
+
 // 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.
 // `ghToken`, `sessionToken` and `subscriptionToken` are secrets: they are
@@ -610,19 +621,6 @@ export interface AgentBootstrapSpec {
   fromScratch?: boolean
 }
 
-/**
- * A linked-context file the backend prepared (requirements / RFC / PRD / tracker issue)
- * for the harness to materialise under CONTEXT_DIR in the checkout, so the agent can read
- * it on demand. The harness can't reach Jira/GitHub itself, so all such context is fetched
- * and shipped here up front. `path` is sanitised to a safe basename on parse.
- */
-export interface ContextFileSpec {
-  path: string
-  title: string
-  url: string
-  content: string
-}
-
 /** How an explore agent's reply is consumed. */
 export interface AgentOutputSpec {
   /** `prose` keeps the reply text; `structured` parses (and optionally repairs) it to JSON. */
@@ -712,6 +710,13 @@ export interface AgentJob extends HarnessAuthFields {
    * The agent reads them on demand; they are kept out of any commit. Absent ⇒ none.
    */
   contextFiles?: ContextFileSpec[]
+  /**
+   * The task's reference design images, downloaded into `.cat-context/reference-screenshots/`
+   * before the agent runs (see {@link ReferenceScreenshotsSpec}). Sent only for a kind that
+   * CAPTURES views and only when the task actually has references, so absent is the normal case
+   * and means the agent names its own views.
+   */
+  referenceScreenshots?: ReferenceScreenshotsSpec
   /**
    * Private package-registry auth (npm private orgs, GitHub Packages), rendered into
    * `~/.npmrc` before the run so the checkout's installs — the agent's own and the
@@ -1015,41 +1020,6 @@ function parseAgentBootstrapSpec(value: unknown): AgentBootstrapSpec | undefined
   }
 }
 
-/**
- * Sanitise a body-supplied context filename to a safe basename within CONTEXT_DIR:
- * strip any directory part, allow only `[A-Za-z0-9._-]`, and reject empties / dotfiles
- * / `..` so a hostile value can't escape the directory or clobber repo files.
- */
-function sanitizeContextFileName(value: 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
-}
-
-/** Parse the linked-context files, dropping any malformed/unsafe entry. */
-function parseContextFiles(value: unknown): ContextFileSpec[] {
-  if (!Array.isArray(value)) return []
-  const files: ContextFileSpec[] = []
-  const used = new Set<string>()
-  for (const entry of value) {
-    if (typeof entry !== 'object' || entry === null) continue
-    const e = entry as Record<string, unknown>
-    const path = sanitizeContextFileName(e.path)
-    if (!path || used.has(path)) continue
-    if (typeof e.content !== 'string') continue
-    used.add(path)
-    files.push({
-      path,
-      title: typeof e.title === 'string' ? e.title : path,
-      url: typeof e.url === 'string' ? e.url : '',
-      content: e.content,
-    })
-  }
-  return files
-}
-
 /** Parse the explore-mode infra stand-up spec, or undefined when absent/unrecognised. */
 function parseAgentInfraSpec(value: unknown): AgentInfraSpec | undefined {
   if (typeof value !== 'object' || value === null) return undefined
@@ -1230,6 +1200,7 @@ export function parseAgentJob(input: unknown): AgentJob {
     referenceBranches: parseReferenceBranches(o.referenceBranches),
     bootstrap: parseAgentBootstrapSpec(o.bootstrap),
     contextFiles: parseContextFiles(o.contextFiles),
+    referenceScreenshots: parseReferenceScreenshots(o.referenceScreenshots),
     packageRegistries: parsePackageRegistries(o.packageRegistries),
     skills: parseSkillSpecs(o.skills),
     mcpServers: parseMcpServerSpecs(o.mcpServers),
@@ -1272,6 +1243,7 @@ interface ParsedAgentJobParts {
   referenceBranches: ReturnType<typeof parseReferenceBranches>
   bootstrap: ReturnType<typeof parseAgentBootstrapSpec>
   contextFiles: ReturnType<typeof parseContextFiles>
+  referenceScreenshots: ReturnType<typeof parseReferenceScreenshots>
   packageRegistries: ReturnType<typeof parsePackageRegistries>
   skills: ReturnType<typeof parseSkillSpecs>
   mcpServers: ReturnType<typeof parseMcpServerSpecs>
@@ -1329,6 +1301,7 @@ function assembleAgentJob(
     referenceBranches,
     bootstrap,
     contextFiles,
+    referenceScreenshots,
     packageRegistries,
     skills,
     mcpServers,
@@ -1356,6 +1329,7 @@ function assembleAgentJob(
     ...(bootstrap ? { bootstrap } : {}),
     ...(output ? { output } : {}),
     ...(contextFiles.length ? { contextFiles } : {}),
+    ...(referenceScreenshots ? { referenceScreenshots } : {}),
     ...(packageRegistries.length ? { packageRegistries } : {}),
     ...(skills ? { skills } : {}),
     ...(mcpServers ? { mcpServers } : {}),

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 } from './job.js'
+import type { RepoSpec, ReferenceScreenshotsSpec } from './job.js'
+import { deliverReferenceScreenshots } from './reference-screenshots.js'
 import type { McpServerSpec, SkillSpec } from './agent-capabilities.js'
 import { readEffortReport } from './effort.js'
 import { log } from './logger.js'
@@ -212,6 +213,12 @@ export interface AgentRunSpec {
    * from AGENTS.md, so the agent reads them on demand. Absent ⇒ none.
    */
   contextFiles?: ContextFileInfo[]
+  /**
+   * The task's reference design images. Downloaded into `.cat-context/reference-screenshots/`
+   * before the run and named in the agent's prompt, so a capturing agent can compare against them
+   * and use their view names. Absent ⇒ nothing is downloaded and nothing is said.
+   */
+  referenceScreenshots?: ReferenceScreenshotsSpec
   /**
    * 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
@@ -283,6 +290,21 @@ 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)
+  // The task's reference designs, fetched into `.cat-context/reference-screenshots/` for the kinds
+  // that capture views. Delivered here (beside the linked context, before either harness path
+  // branches) so the Pi and subscription runs are handed the SAME directory and the SAME view
+  // names; a per-path copy is how one of them would end up silently without it.
+  //
+  // This runs once per PASS, not once per job: a coding flow re-enters its workspace for every
+  // repair round. That is safe because the delivery is idempotent over the checkout (a file
+  // already on disk is counted, never re-fetched), so a later round costs a stat per reference and
+  // cannot report a view an earlier round successfully delivered as absent. A view that MISSED is
+  // retried, which is the behaviour worth having: the next round is a fresh chance at a blob
+  // backend that was briefly down.
+  const referenceGuidance = await deliverReferenceScreenshots(spec.dir, spec.referenceScreenshots, {
+    ...(opts.signal ? { signal: opts.signal } : {}),
+    log: opts.log ?? log,
+  })
   // 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) —
@@ -306,7 +328,7 @@ export async function runAgentInWorkspace(
     const subOutcome = await runSubscriptionHarness(spec.harness, {
       cwd: spec.dir,
       model: spec.model,
-      systemPrompt: subscriptionSystemPrompt(spec.systemPrompt, contextFiles),
+      systemPrompt: `${subscriptionSystemPrompt(spec.systemPrompt, contextFiles)}${referenceGuidance}`,
       userPrompt: spec.userPrompt,
       ...(spec.subscriptionToken ? { subscriptionToken: spec.subscriptionToken } : {}),
       subscriptionBaseUrl: spec.subscriptionBaseUrl,
@@ -376,6 +398,7 @@ export async function runAgentInWorkspace(
     serviceDirectory: spec.serviceDirectory,
     contextFiles,
     hasBlueprints,
+    ...(referenceGuidance ? { referenceGuidance } : {}),
     ...(spec.multiRepo ? { multiRepo: true } : {}),
   })
   // Pi's calls are metered server-side by the LLM proxy, which sees only an HTTP request — so

package/src/pi.ts

@@ -218,6 +218,13 @@ export async function writeAgentsContext(
      * every turn) pointing at files that don't exist. Absent/false ⇒ the note is omitted.
      */
     hasBlueprints?: boolean
+    /**
+     * The reference-design block composed by `referenceScreenshotGuidance`: which files the run
+     * was handed and which it could not fetch. Composed by the caller (it is the only side that
+     * knows what actually landed on disk) and appended verbatim. Absent/'' ⇒ nothing is said,
+     * which is the normal case: only a capturing kind is sent references at all.
+     */
+    referenceGuidance?: string
   } = {},
 ): Promise<void> {
   const dir = join(homedir(), '.pi', 'agent')
@@ -246,9 +253,13 @@ export async function writeAgentsContext(
   // (see the note above `writeAgentsContext`): it comes solely from the backend `spec-aware`
   // trait, so a spec-aware run no longer carries it twice.
   const blueprint = opts.hasBlueprints ? BLUEPRINT_GUIDANCE : ''
+  // The reference designs the harness downloaded for a capturing kind, listed with their view
+  // names (and the ones that could not be fetched). Last, beside the linked-context list it is the
+  // sibling of: both point the agent at files already on disk.
+  const references = opts.referenceGuidance ?? ''
   await writeFile(
     join(dir, 'AGENTS.md'),
-    `${systemPrompt}${blueprint}${TODO_GUIDANCE}${monorepo}${multiRepo}${webTools}${context}`,
+    `${systemPrompt}${blueprint}${TODO_GUIDANCE}${monorepo}${multiRepo}${webTools}${context}${references}`,
     'utf8',
   )
 }
@@ -312,9 +323,22 @@ export async function materializeContextFiles(
   const dir = join(cwd, CONTEXT_DIR)
   await mkdir(dir, { recursive: true })
   for (const f of files) await writeFile(join(dir, f.path), f.content, 'utf8')
-  // The exclude pattern has no leading slash, so it matches `.cat-context/` at any depth
-  // — covering the monorepo case where cwd is a service subdirectory below the repo root.
-  // Walk up to find the repo's `.git` (best-effort; a from-scratch scaffold has none).
+  await excludeContextDir(cwd)
+}
+
+/**
+ * Add the LOCAL git exclude entry for {@link CONTEXT_DIR}, so nothing the harness materialises
+ * there can be committed into the agent's PR by a `git add -A`.
+ *
+ * The exclude pattern has no leading slash, so it matches `.cat-context/` at any depth, covering
+ * the monorepo case where cwd is a service subdirectory below the repo root. Best-effort: a
+ * scaffold-from-scratch checkout has no `.git` yet, and the files then simply stay untracked.
+ *
+ * One helper rather than a copy per materialiser: every writer into that directory owes the same
+ * exclude, and a new one that forgot it would leak the platform's own files into a customer's
+ * repository with nothing failing.
+ */
+export async function excludeContextDir(cwd: string): Promise<void> {
   const gitRoot = await findGitRoot(cwd)
   if (!gitRoot) return
   try {
@@ -356,13 +380,7 @@ export async function materializeSkillResources(
       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.
-  }
+  await excludeContextDir(cwd)
 }
 
 /** Walk up from `dir` (bounded) to the directory containing a `.git` folder, or null. */