@lythos/cold-pool 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/cold-pool",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Cold pool service layer — dedicated resource holder for skill repositories with intent/plan/execute primitives. Single owner of git side-effects; consumed by deck/curator/arena.",
   "keywords": [
     "ai-agent",
@@ -42,7 +42,7 @@
   },
   "homepage": "https://github.com/lythos-labs/lythoskill/tree/main/packages/lythoskill-cold-pool#readme",
   "dependencies": {
-    "@lythos/infra": "^0.9.36",
+    "@lythos/infra": "workspace:*",
     "simple-git": "^3.36.0"
   },
   "engines": {

package/src/cold-pool.ts

@@ -128,7 +128,10 @@ export class ColdPool {
 
     function walk(dir: string, push: (d: string) => void): void {
       let dirents: ReturnType<typeof readdirSync>
-      try { dirents = readdirSync(dir, { withFileTypes: true }) } catch { return }
+      try { dirents = readdirSync(dir, { withFileTypes: true }) } catch (e: any) {
+        if (e.code !== 'ENOENT') console.warn(`walk: readdir failed for ${dir}: ${e.message}`)
+        return
+      }
       for (const d of dirents) {
         if (!d.isDirectory() || d.name.startsWith('.')) continue
         const sub = join(dir, d.name)
@@ -154,7 +157,8 @@ export class ColdPool {
       let dirents: ReturnType<typeof readdirSync>
       try {
         dirents = readdirSync(dir, { withFileTypes: true })
-      } catch {
+      } catch (e: any) {
+        if (e.code !== 'ENOENT') console.warn(`collectRecursive: readdir failed for ${dir}: ${e.message}`)
         return
       }
       for (const d of dirents) {

package/src/fetch-plan.ts

@@ -14,6 +14,7 @@ import { execFileSync } from 'node:child_process'
 import type { ColdPool } from './cold-pool.js'
 import type { Locator, FetchPlan, FetchResult, FetchIO } from './types.js'
 import { gitClone } from './git-io.js'
+import { getMirror, rewriteUrl } from './mirror.js'
 
 export function buildFetchPlan(
   pool: ColdPool,
@@ -22,9 +23,11 @@ export function buildFetchPlan(
 ): FetchPlan {
   const targetDir = pool.resolveDir(locator)
   const protocol = process.env.LYTHOS_GIT_PROTOCOL || 'https'
-  const cloneUrl = locator.isLocalhost
+  const rawCloneUrl = locator.isLocalhost
     ? ''
     : `${protocol}://${locator.host}/${locator.owner}/${locator.repo}.git`
+  const mirror = getMirror()
+  const cloneUrl = rawCloneUrl ? rewriteUrl(rawCloneUrl, mirror) : ''
 
   return {
     locator,
@@ -57,8 +60,8 @@ export function executeFetchPlan(plan: FetchPlan, io?: FetchIO): FetchResult {
           log(`🔄 checking out ${plan.ref} in ${plan.targetDir}`)
           execFileSync('git', ['-C', plan.targetDir, 'fetch', '--depth', '1', 'origin', plan.ref], { stdio: 'pipe' })
           execFileSync('git', ['-C', plan.targetDir, 'checkout', plan.ref], { stdio: 'pipe' })
-        } catch {
-          log(`⚠️  Could not checkout ${plan.ref} — using current HEAD`)
+        } catch (e: any) {
+          log(`⚠️  Could not checkout ${plan.ref}: ${e.message} — using current HEAD`)
         }
       }
     }

package/src/git-io.test.ts

@@ -1,21 +1,28 @@
-import { describe, expect, test } from 'bun:test'
+import { describe, expect, test, beforeEach, afterEach } from 'bun:test'
 import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
-import { detectGitRoot } from './git-io'
+import { detectGitRoot, gitClone, gitPull, type GitExec } from './git-io.js'
 
-// Note: gitClone() and gitPull() wrap external `git` invocations and are
-// tested indirectly via executeFetchPlan + integration scenarios. Direct
-// tests would require a fixture remote and slow the CI loop. detectGitRoot
-// is pure fs traversal and is fully tested here.
+// ── Injectable mock exec for IO-layer tests ──
+
+function createMockExec() {
+  const calls: Array<{ file: string; args: string[]; opts: unknown }> = []
+  const mockExec: GitExec = ((file: string, args: string[], opts?: object) => {
+    calls.push({ file, args, opts: opts ?? {} })
+    return Buffer.from('')
+  }) as GitExec
+  return { mockExec, calls }
+}
+
+// ── detectGitRoot tests (pure fs, no mock needed) ──
 
 describe('detectGitRoot', () => {
   const root = mkdtempSync(join(tmpdir(), 'git-root-test-'))
   const repoDir = join(root, 'pool/host/owner/repo')
   const subDir = join(repoDir, 'src/deep')
   mkdirSync(subDir, { recursive: true })
-  writeFileSync(join(repoDir, '.git'), '') // .git can be a file (worktree marker) or dir; existsSync covers both
-  // Sibling dir without .git
+  writeFileSync(join(repoDir, '.git'), '')
   const orphanDir = join(root, 'pool/orphan')
   mkdirSync(orphanDir, { recursive: true })
 
@@ -36,7 +43,6 @@ describe('detectGitRoot', () => {
   })
 
   test('respects coldPool boundary — outside-cold-pool when crossing out', () => {
-    // Fresh tmpdir to ensure no .git anywhere on the path back to /
     const isolated = mkdtempSync(join(tmpdir(), 'git-root-isolated-'))
     const inner = join(isolated, 'inner')
     const coldPool = join(isolated, 'pool')
@@ -52,3 +58,72 @@ describe('detectGitRoot', () => {
     expect(r.gitRoot).toBe(resolve(repoDir))
   })
 })
+
+// ── gitClone / gitPull tests — verify SOCKS proxy CLI contract via IO injection ──
+
+describe('gitClone — SOCKS proxy args', () => {
+  beforeEach(() => {
+    delete process.env.LYTHOS_SOCKS_PROXY
+  })
+
+  afterEach(() => {
+    delete process.env.LYTHOS_SOCKS_PROXY
+  })
+
+  test('without LYTHOS_SOCKS_PROXY: no proxy flags in git args', () => {
+    const { mockExec, calls } = createMockExec()
+    gitClone('https://github.com/example/repo.git', '/tmp/repo', undefined, mockExec)
+    const call = calls.find((c) => c.args.includes('clone'))
+    expect(call).toBeDefined()
+    expect(call!.args).not.toContain('-c')
+    expect(call!.args).not.toContain('http.proxy')
+  })
+
+  test('with LYTHOS_SOCKS_PROXY: injects -c http.proxy and -c https.proxy', () => {
+    process.env.LYTHOS_SOCKS_PROXY = 'proxy.example.com:1080'
+    const { mockExec, calls } = createMockExec()
+    gitClone('https://github.com/example/repo.git', '/tmp/repo', undefined, mockExec)
+    const call = calls.find((c) => c.args.includes('clone'))
+    expect(call).toBeDefined()
+    expect(call!.args).toContain('-c')
+    expect(call!.args).toContain('http.proxy=socks5://proxy.example.com:1080')
+    expect(call!.args).toContain('https.proxy=socks5://proxy.example.com:1080')
+  })
+
+  test('with LYTHOS_SOCKS_PROXY already including socks5://: does not double-prefix', () => {
+    process.env.LYTHOS_SOCKS_PROXY = 'socks5://proxy.example.com:1080'
+    const { mockExec, calls } = createMockExec()
+    gitClone('https://github.com/example/repo.git', '/tmp/repo', undefined, mockExec)
+    const call = calls.find((c) => c.args.includes('clone'))
+    expect(call!.args).toContain('http.proxy=socks5://proxy.example.com:1080')
+    expect(call!.args).not.toContain('http.proxy=socks5://socks5://proxy.example.com:1080')
+  })
+
+  test('ref checkout also receives proxy flags', () => {
+    process.env.LYTHOS_SOCKS_PROXY = 'proxy.example.com:1080'
+    const { mockExec, calls } = createMockExec()
+    gitClone('https://github.com/example/repo.git', '/tmp/repo', { ref: 'v1.0.0' }, mockExec)
+    const checkoutCall = calls.find((c) => c.args.includes('checkout'))
+    expect(checkoutCall).toBeDefined()
+    expect(checkoutCall!.args).toContain('http.proxy=socks5://proxy.example.com:1080')
+  })
+})
+
+describe('gitPull — SOCKS proxy args', () => {
+  beforeEach(() => {
+    delete process.env.LYTHOS_SOCKS_PROXY
+  })
+
+  afterEach(() => {
+    delete process.env.LYTHOS_SOCKS_PROXY
+  })
+
+  test('with LYTHOS_SOCKS_PROXY: injects proxy flags', () => {
+    process.env.LYTHOS_SOCKS_PROXY = 'proxy.example.com:1080'
+    const { mockExec, calls } = createMockExec()
+    gitPull('/tmp/repo', 30000, mockExec)
+    const call = calls.find((c) => c.args.includes('pull'))
+    expect(call).toBeDefined()
+    expect(call!.args).toContain('http.proxy=socks5://proxy.example.com:1080')
+  })
+})

package/src/git-io.ts

@@ -11,6 +11,17 @@ import { execFileSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 
+/** Injectable exec for testing. Matches node:child_process execFileSync signature. */
+export type GitExec = typeof execFileSync
+
+/** Read LYTHOS_SOCKS_PROXY env var and return git-config args if present. */
+function socksProxyArgs(): string[] {
+  const proxy = process.env.LYTHOS_SOCKS_PROXY?.trim()
+  if (!proxy) return []
+  const url = proxy.startsWith('socks5://') ? proxy : `socks5://${proxy}`
+  return ['-c', `http.proxy=${url}`, '-c', `https.proxy=${url}`]
+}
+
 export interface GitCloneOptions {
   /** Default 1 (shallow). Set to 0 to disable depth (full history). */
   depth?: number
@@ -22,18 +33,23 @@ export interface GitCloneOptions {
   timeout?: number
 }
 
-export function gitClone(url: string, dir: string, opts?: GitCloneOptions): void {
-  const args = ['clone']
+export function gitClone(
+  url: string,
+  dir: string,
+  opts?: GitCloneOptions,
+  exec: GitExec = execFileSync,
+): void {
+  const args = [...socksProxyArgs(), 'clone']
   const depth = opts?.depth ?? 1
   if (depth > 0) {
     args.push('--depth', String(depth))
   }
   args.push(url, dir)
   const timeout = opts?.timeout ?? 120_000
-  execFileSync('git', args, { stdio: opts?.stdio ?? 'pipe', timeout })
+  exec('git', args, { stdio: opts?.stdio ?? 'pipe', timeout })
 
   if (opts?.ref && opts.ref !== 'HEAD') {
-    execFileSync('git', ['checkout', opts.ref], { cwd: dir, stdio: opts?.stdio ?? 'pipe', timeout })
+    exec('git', [...socksProxyArgs(), 'checkout', opts.ref], { cwd: dir, stdio: opts?.stdio ?? 'pipe', timeout })
   }
 }
 
@@ -42,9 +58,13 @@ export interface GitPullResult {
   message: string
 }
 
-export function gitPull(dir: string, timeoutMs: number = 30000): GitPullResult {
+export function gitPull(
+  dir: string,
+  timeoutMs: number = 30000,
+  exec: GitExec = execFileSync,
+): GitPullResult {
   try {
-    const output = execFileSync('git', ['pull'], {
+    const output = exec('git', [...socksProxyArgs(), 'pull'], {
       cwd: dir,
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],

package/src/github-naming.ts

@@ -0,0 +1,139 @@
+/**
+ * GitHub naming convention validators — guard layer for locator parsing.
+ *
+ * Rejects inputs that violate GitHub's published naming rules before they
+ * reach git operations. Practical security over theoretical compatibility:
+ * we target GitHub-hosted skills; inputs that GitHub itself would reject
+ * should not reach git clone/checkout.
+ *
+ * Reference: playground/github-user-repo-validation.txt
+ * Design: multi-guard (卫语句) over monster regex — each rule is independently
+ * readable, maintainable, and produces specific error messages.
+ */
+
+// ── Username (Owner) ─────────────────────────────────────────────────
+
+const RESERVED_USERNAMES = new Set([
+  'admin', 'support', 'help', 'about', 'pricing',
+  'api', 'www', 'mail', 'ftp', 'smtp', 'imap',
+  'signup', 'login', 'logout', 'settings',
+  'dashboard', 'explore', 'trending', 'collections',
+  'topics', 'marketplace', 'security', 'insights',
+  'github', 'git', 'null', 'undefined', 'new',
+  'notifications', 'sessions', 'oauth', 'enterprise',
+  'features', 'team', 'teams', 'organizations',
+  'users', 'repos', 'search', 'gist', 'gists',
+  'blog', 'downloads', 'contact', 'jobs', 'issues',
+  'pulls', 'commits', 'branches', 'releases',
+  'tags', 'labels', 'milestones', 'wiki', 'graphs',
+])
+
+export interface NameResult {
+  valid: boolean
+  errors: string[]
+}
+
+export function validateGitHubOwner(owner: string): NameResult {
+  const errors: string[] = []
+
+  if (!owner || owner.length === 0) {
+    errors.push('owner cannot be empty')
+    return { valid: false, errors }
+  }
+
+  if (owner.length > 39) {
+    errors.push(`owner "${owner}" exceeds 39 characters (${owner.length})`)
+  }
+
+  if (!/^[a-zA-Z0-9-]+$/.test(owner)) {
+    errors.push(`owner "${owner}" contains invalid characters (only a-z, A-Z, 0-9, - allowed)`)
+  }
+
+  if (owner.startsWith('-')) {
+    errors.push(`owner "${owner}" cannot start with hyphen`)
+  }
+
+  if (owner.endsWith('-')) {
+    errors.push(`owner "${owner}" cannot end with hyphen`)
+  }
+
+  if (owner.includes('--')) {
+    errors.push(`owner "${owner}" cannot contain consecutive hyphens`)
+  }
+
+  if (RESERVED_USERNAMES.has(owner.toLowerCase())) {
+    errors.push(`"${owner}" is a reserved GitHub username`)
+  }
+
+  return { valid: errors.length === 0, errors }
+}
+
+// ── Repository Name ──────────────────────────────────────────────────
+
+export function validateGitHubRepo(repo: string): NameResult {
+  const errors: string[] = []
+
+  if (!repo || repo.length === 0) {
+    errors.push('repo cannot be empty')
+    return { valid: false, errors }
+  }
+
+  if (repo.length > 100) {
+    errors.push(`repo "${repo}" exceeds 100 characters (${repo.length})`)
+  }
+
+  if (!/^[a-zA-Z0-9._-]+$/.test(repo)) {
+    errors.push(`repo "${repo}" contains invalid characters (only a-z, A-Z, 0-9, ., _, - allowed)`)
+  }
+
+  if (repo === '.' || repo === '..') {
+    errors.push('repo cannot be "." or ".."')
+  }
+
+  if (repo.toLowerCase().endsWith('.git')) {
+    errors.push(`repo "${repo}" cannot end with ".git"`)
+  }
+
+  return { valid: errors.length === 0, errors }
+}
+
+// ── Directory / Skill Path Segment ───────────────────────────────────
+
+export function validateSkillSegment(segment: string): NameResult {
+  const errors: string[] = []
+
+  if (!segment || segment.length === 0) {
+    errors.push('directory segment cannot be empty')
+    return { valid: false, errors }
+  }
+
+  if (segment.startsWith('.')) {
+    errors.push(`directory "${segment}" cannot start with "." (hidden dir)`)
+  }
+
+  if (segment.endsWith('.lock')) {
+    errors.push(`directory "${segment}" cannot end with ".lock" (Git reserved)`)
+  }
+
+  if (segment.includes('..')) {
+    errors.push(`directory "${segment}" cannot contain ".."`)
+  }
+
+  if (segment.includes('@{')) {
+    errors.push(`directory "${segment}" cannot contain "@{" (Git syntax conflict)`)
+  }
+
+  if (/[\\/:*?"<>|]/.test(segment)) {
+    errors.push(`directory "${segment}" contains OS-forbidden characters`)
+  }
+
+  if (/[\x00-\x1f]/.test(segment)) {
+    errors.push(`directory "${segment}" contains control characters`)
+  }
+
+  if (segment === '@') {
+    errors.push('directory cannot be "@"')
+  }
+
+  return { valid: errors.length === 0, errors }
+}

package/src/index.ts

@@ -15,6 +15,7 @@ export type {
   FetchIO,
 } from './types.js'
 
+export { getMirror, rewriteUrl, mirrorUrls } from './mirror.js'
 export { parseLocator, formatLocator } from './parse-locator.js'
 export type { DirEntry, ListPlan, ListPlanEntry } from './cold-pool.js'
 export { ColdPool, DEFAULT_COLD_POOL_PATH, buildListPlan } from './cold-pool.js'

package/src/mirror.test.ts

@@ -0,0 +1,137 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test'
+import { probeConnectivity } from './mirror.js'
+
+describe('probeConnectivity', () => {
+  let originalFetch: typeof fetch
+  let fetchCalls: Array<{ url: string; options: RequestInit }>
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch
+    fetchCalls = []
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  function mockFetch(
+    responses: Map<string, Response>,
+    defaultDelay = 0,
+  ) {
+    globalThis.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input)
+      fetchCalls.push({ url, options: init ?? {} })
+
+      if (defaultDelay > 0) {
+        await new Promise((r) => setTimeout(r, defaultDelay))
+      }
+
+      const res = responses.get(url)
+      if (res) return res
+      throw new Error(`ENOTFOUND ${url}`)
+    }
+  }
+
+  // ── Tracer Bullet ──
+  test('direct reachable → returns direct path', async () => {
+    mockFetch(
+      new Map([
+        ['https://example.com/skill', new Response(null, { status: 200 })],
+      ]),
+    )
+
+    const result = await probeConnectivity('https://example.com/skill')
+
+    expect(result).toMatchObject({
+      path: 'direct',
+      url: 'https://example.com/skill',
+      latencyMs: expect.any(Number),
+    })
+  })
+
+  // ── Vertical Slice 2 ──
+  test('direct fails, mirror ok → returns mirror path', async () => {
+    mockFetch(
+      new Map([
+        ['https://example.com/skill', new Response(null, { status: 500 })],
+        ['https://ghfast.top/https://example.com/skill', new Response(null, { status: 200 })],
+      ]),
+    )
+
+    const result = await probeConnectivity('https://example.com/skill')
+
+    expect(result).toMatchObject({
+      path: 'mirror',
+      url: 'https://ghfast.top/https://example.com/skill',
+      latencyMs: expect.any(Number),
+    })
+  })
+
+  // ── Vertical Slice 3 ──
+  test('all paths fail → returns undefined', async () => {
+    mockFetch(new Map())
+
+    const result = await probeConnectivity('https://example.com/skill')
+
+    expect(result).toBeUndefined()
+  })
+
+  // ── Vertical Slice 4 ──
+  test('404 is treated as reachable (server alive)', async () => {
+    mockFetch(
+      new Map([
+        ['https://example.com/skill', new Response(null, { status: 404 })],
+      ]),
+    )
+
+    const result = await probeConnectivity('https://example.com/skill')
+
+    expect(result?.path).toBe('direct')
+  })
+
+  // ── Vertical Slice 5: Racing behavior ──
+  test('probes race concurrently, not sequentially', async () => {
+    const start = performance.now()
+
+    mockFetch(
+      new Map([
+        ['https://example.com/skill', new Response(null, { status: 500 })],
+        ['https://ghfast.top/https://example.com/skill', new Response(null, { status: 200 })],
+        ['https://ghproxy.com/https://example.com/skill', new Response(null, { status: 200 })],
+        ['https://mirror.ghproxy.com/https://example.com/skill', new Response(null, { status: 200 })],
+      ]),
+      50, // each mock fetch takes 50ms
+    )
+
+    const result = await probeConnectivity('https://example.com/skill')
+
+    const elapsed = performance.now() - start
+
+    expect(result?.path).toBe('mirror')
+    // Sequential would take ~200ms (4 × 50ms). Racing should be ~50-100ms.
+    expect(elapsed).toBeLessThan(150)
+  })
+
+  // ── Vertical Slice 6: Timeout honored ──
+  test('timeout aborts slow probes', async () => {
+    globalThis.fetch = async (_input, init?) => {
+      return new Promise((_, reject) => {
+        const timer = setTimeout(
+          () => reject(new Error('The operation timed out.')),
+          10_000,
+        )
+        init?.signal?.addEventListener('abort', () => {
+          clearTimeout(timer)
+          reject(new Error('The operation was aborted.'))
+        })
+      })
+    }
+
+    const start = performance.now()
+    const result = await probeConnectivity('https://example.com/skill', 100)
+    const elapsed = performance.now() - start
+
+    expect(result).toBeUndefined()
+    expect(elapsed).toBeLessThan(500) // 100ms timeout + overhead
+  })
+})

package/src/mirror.ts

@@ -0,0 +1,128 @@
+/**
+ * Mirror URL rewriting for restricted networks.
+ *
+ * Three layers, checked in order:
+ *   1. LYTHOSKILL_GH_MIRROR env var (explicit user choice)
+ *   2. HTTPS_PROXY / HTTP_PROXY (standard — Bun fetch and git respect these natively)
+ *   3. Known public mirrors (auto-fallback when GitHub is unreachable)
+ *
+ * Per ADR-20260512191438745.
+ */
+
+// ── Known public mirrors (tried in order when GitHub is unreachable) ──
+
+const KNOWN_MIRRORS = [
+  'https://ghfast.top',            // commonly used in CN
+  'https://ghproxy.com',           // commonly used in CN
+  'https://mirror.ghproxy.com',    // ghproxy alternative domain
+]
+
+// ── Explicit user mirror ──────────────────────────────────────────────
+
+export function getMirror(): string | undefined {
+  const v = process.env.LYTHOSKILL_GH_MIRROR?.trim()
+  if (!v) return undefined
+  if (v.startsWith('http://') || v.startsWith('https://')) {
+    return v.replace(/\/+$/, '')
+  }
+  return `https://${v.replace(/\/+$/, '')}`
+}
+
+// ── URL rewriting ─────────────────────────────────────────────────────
+
+export function rewriteUrl(url: string, mirror?: string): string {
+  if (!mirror) return url
+  return `${mirror}/${url}`
+}
+
+export function mirrorUrls(url: string): string[] {
+  const mirrors = [...KNOWN_MIRRORS]
+  const explicit = getMirror()
+  if (explicit) mirrors.unshift(explicit)
+  return mirrors.map(m => rewriteUrl(url, m))
+}
+
+export function isLikelyGitHubBlock(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err)
+  return /fetch.*failed|ENOTFOUND|ETIMEDOUT|ECONNREFUSED|network.*unreachable/i.test(msg)
+}
+
+// ── Connectivity probe ────────────────────────────────────────────────
+
+export interface ProbeResult {
+  path: 'direct' | 'mirror'
+  url: string
+  latencyMs: number
+}
+
+export interface ProbeFailure {
+  url: string
+  reason: string
+}
+
+/**
+ * Quick connectivity probe: race direct + all mirrors concurrently.
+ * Uses short timeout (default 3s) to fail fast instead of waiting for
+ * the full git clone / fetch timeout.
+ *
+ * Returns the first success, or undefined with failures recorded.
+ */
+export async function probeConnectivity(
+  url: string,
+  timeoutMs = 3000,
+): Promise<ProbeResult & { failures?: ProbeFailure[] } | undefined> {
+  const start = performance.now()
+  const failures: ProbeFailure[] = []
+
+  async function tryFetch(
+    targetUrl: string,
+    pathLabel: 'direct' | 'mirror',
+  ): Promise<ProbeResult | undefined> {
+    const t0 = performance.now()
+    try {
+      const res = await fetch(targetUrl, {
+        method: 'HEAD',
+        signal: AbortSignal.timeout(timeoutMs),
+        redirect: 'follow',
+      })
+      if (res.ok || res.status === 404) {
+        // 404 means server reachable, resource may not exist
+        return { path: pathLabel, url: targetUrl, latencyMs: Math.round(performance.now() - t0) }
+      }
+      failures.push({ url: targetUrl, reason: `HTTP ${res.status}` })
+    } catch (err) {
+      failures.push({
+        url: targetUrl,
+        reason: err instanceof Error ? err.message : String(err),
+      })
+    }
+    return undefined
+  }
+
+  // Build all probe promises (direct + mirrors) and race for first success
+  const probes = [tryFetch(url, 'direct')]
+  for (const mirrorUrl of mirrorUrls(url)) {
+    probes.push(tryFetch(mirrorUrl, 'mirror'))
+  }
+
+  let result: ProbeResult | undefined
+  let pending = probes.length
+
+  await new Promise<void>((resolve) => {
+    for (const p of probes) {
+      p.then((res) => {
+        if (!result && res) {
+          result = res
+          resolve()
+        }
+        pending--
+        if (pending === 0) resolve()
+      })
+    }
+  })
+
+  if (result) {
+    return { ...result, failures }
+  }
+  return undefined
+}

package/src/parse-locator.ts

@@ -18,6 +18,7 @@
  * `#ref` suffix (branch/tag/commit) is compatible with skills.sh's
  * `parseFragmentRef`. The ref is passed to gitClone for checkout.
  */
+import { validateGitHubOwner, validateGitHubRepo, validateSkillSegment } from './github-naming.js'
 import type { Locator } from './types.js'
 
 export function parseLocator(input: string): Locator | null {
@@ -47,12 +48,33 @@ export function parseLocator(input: string): Locator | null {
   const isLocalhost = parts[0] === 'localhost'
   if (!isLocalhost && !parts[0].includes('.')) return null
 
+  const owner = parts[1]
+  const repo = parts[2]
+  const skill = parts.length > 3 ? parts.slice(3).join('/') : null
+
+  // Validate naming conventions for remote locators (GitHub rules).
+  // localhost gets relaxed validation — local filesystem, not GitHub.
+  if (!isLocalhost) {
+    const ownerCheck = validateGitHubOwner(owner)
+    if (!ownerCheck.valid) return null
+
+    const repoCheck = validateGitHubRepo(repo)
+    if (!repoCheck.valid) return null
+
+    if (skill) {
+      for (const segment of skill.split('/')) {
+        const segCheck = validateSkillSegment(segment)
+        if (!segCheck.valid) return null
+      }
+    }
+  }
+
   return {
     raw: input,
     host: parts[0],
-    owner: parts[1],
-    repo: parts[2],
-    skill: parts.length > 3 ? parts.slice(3).join('/') : null,
+    owner,
+    repo,
+    skill,
     ref,
     isLocalhost,
   }

package/src/prune-plan.ts

@@ -61,7 +61,9 @@ function calculateDirSize(dir: string): number {
         total += statSync(p).size
       }
     }
-  } catch {}
+  } catch (e: any) {
+    if (e.code !== 'ENOENT') console.warn(`calculateDirSize: failed for ${dir}: ${e.message}`)
+  }
   return total
 }