@lythos/cold-pool 0.9.48 → 0.9.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/cold-pool",
-  "version": "0.9.48",
+  "version": "0.9.49",
   "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",

package/src/fetch-plan.ts

@@ -10,6 +10,7 @@
  * `executeFetchPlan` will refuse to clone (status: 'failed').
  */
 import { existsSync } from 'node:fs'
+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'
@@ -29,7 +30,7 @@ export function buildFetchPlan(
     locator,
     cloneUrl,
     targetDir,
-    ref: opts?.ref,
+    ref: opts?.ref ?? locator.ref,  // explicit opts override locator's #ref
     alreadyExists: existsSync(targetDir),
   }
 }
@@ -48,6 +49,19 @@ export function executeFetchPlan(plan: FetchPlan, io?: FetchIO): FetchResult {
   }
 
   if (exists(plan.targetDir)) {
+    if (plan.ref) {
+      if (plan.ref.startsWith('-')) {
+        log(`⚠️  Ref "${plan.ref}" starts with dash — refusing to avoid git option injection`)
+      } else {
+        try {
+          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`)
+        }
+      }
+    }
     log(`✓ already present: ${plan.targetDir}`)
     return {
       status: 'already-present',

package/src/parse-locator.test.ts

@@ -11,6 +11,7 @@ describe('parseLocator — accepted forms', () => {
       repo: 'skills',
       skill: 'skills/pdf',
       isLocalhost: false,
+      ref: null,
     })
   })
 
@@ -35,6 +36,7 @@ describe('parseLocator — accepted forms', () => {
       repo: 'design-doc-mermaid',
       skill: null,
       isLocalhost: false,
+      ref: null,
     })
   })
 
@@ -52,6 +54,7 @@ describe('parseLocator — accepted forms', () => {
       repo: 'my-skill',
       skill: null,
       isLocalhost: true,
+      ref: null,
     })
   })
 
@@ -99,6 +102,7 @@ describe('parseLocator — rejected forms (per ADR-20260502012643244 FQ-only)',
       repo: 'skills',
       skill: 'my-skill',
       isLocalhost: true,
+      ref: null,
     })
   })
 

package/src/parse-locator.ts

@@ -3,6 +3,7 @@
  *
  * Three accepted forms (everything else returns null):
  *   - `host.tld/owner/repo[/skill]`        — remote skill
+ *   - `host.tld/owner/repo[/skill]#ref`    — remote skill at branch/tag/commit
  *   - `host.tld/owner/repo`                — remote standalone (skill = null)
  *   - `localhost/owner/repo[/skill]`       — local skill, same shape as remote
  *
@@ -13,6 +14,9 @@
  *
  * Single-name `localhost/<name>` is rejected — that's a post-compaction
  * agent invention, not the canonical form.
+ *
+ * `#ref` suffix (branch/tag/commit) is compatible with skills.sh's
+ * `parseFragmentRef`. The ref is passed to gitClone for checkout.
  */
 import type { Locator } from './types.js'
 
@@ -20,7 +24,22 @@ export function parseLocator(input: string): Locator | null {
   const trimmed = input.trim()
   if (!trimmed) return null
 
-  const parts = trimmed.split('/').filter(Boolean)
+  // Extract #ref suffix (branch/tag/commit)
+  let ref: string | null = null
+  let pathPart = trimmed
+  const hashIdx = trimmed.indexOf('#')
+  if (hashIdx >= 0) {
+    pathPart = trimmed.slice(0, hashIdx)
+    ref = trimmed.slice(hashIdx + 1) || null
+    // Reject refs that look like git option injection or path traversal
+    if (ref && (ref.startsWith('-') || ref.includes('..'))) {
+      return null
+    }
+  }
+
+  const parts = pathPart.split('/')
+  // Reject empty segments (double slashes) and path traversal
+  if (parts.some(p => p === '' || p === '..' || p === '.')) return null
   // Need at least host/owner/repo (3 segments) for any FQ form
   if (parts.length < 3) return null
 
@@ -34,6 +53,7 @@ export function parseLocator(input: string): Locator | null {
     owner: parts[1],
     repo: parts[2],
     skill: parts.length > 3 ? parts.slice(3).join('/') : null,
+    ref,
     isLocalhost,
   }
 }
@@ -41,5 +61,6 @@ export function parseLocator(input: string): Locator | null {
 /** Recompose an FQ locator string from a parsed `Locator`. */
 export function formatLocator(locator: Locator): string {
   const base = `${locator.host}/${locator.owner}/${locator.repo}`
-  return locator.skill ? `${base}/${locator.skill}` : base
+  const withSkill = locator.skill ? `${base}/${locator.skill}` : base
+  return locator.ref ? `${withSkill}#${locator.ref}` : withSkill
 }

package/src/types.ts

@@ -22,6 +22,7 @@ export interface Locator {
   readonly owner: string
   readonly repo: string
   readonly skill: string | null
+  readonly ref: string | null          // optional branch/tag/commit (#ref suffix)
   readonly isLocalhost: boolean
 }