@lythos/cold-pool 0.9.47 → 0.9.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/cold-pool",
-  "version": "0.9.47",
+  "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/cli.ts

@@ -13,6 +13,7 @@ import { join } from 'node:path'
 import { ColdPool, DEFAULT_COLD_POOL_PATH } from './cold-pool.js'
 import { buildPrunePlan, executePrunePlan } from './prune-plan.js'
 import { parseLocator } from './parse-locator.js'
+import type { ReconcileDesiredState } from './reconcile-plan.js'
 
 const CMD = 'cold-pool'
 
@@ -111,12 +112,7 @@ async function main(): Promise<void> {
     // ── validate (plan-only, no --apply) ────────────────────────
     case 'validate': {
       const lockIdx = args.indexOf('--lock')
-      const lockPath = lockIdx >= 0 ? args[lockIdx + 1] : undefined
-
-      if (!lockPath) {
-        console.error('❌ Missing --lock <path>. Usage: cold-pool validate --lock ./skill-deck.lock')
-        process.exit(1)
-      }
+      const lockPath = lockIdx >= 0 ? args[lockIdx + 1] : './skill-deck.lock'
 
       if (!existsSync(lockPath)) {
         console.error(`❌ Lock file not found: ${lockPath}`)
@@ -128,11 +124,21 @@ async function main(): Promise<void> {
         lock = JSON.parse(readFileSync(lockPath, 'utf-8'))
       } catch (e: any) {
         console.error(`❌ Failed to parse lock file: ${e.message}`)
+        console.error('')
+        console.error('This usually means the lock file is corrupt or was written by an older version.')
+        console.error('To fix:')
+        console.error('  deck link          # regenerate the lock file')
+        console.error('  cold-pool validate # retry after lock is rebuilt')
         process.exit(1)
       }
 
       if (!lock.skills || !Array.isArray(lock.skills)) {
-        console.error('❌ Lock file has no "skills" array. Run deck link first.')
+        console.error('❌ Lock file has no "skills" array.')
+        console.error('')
+        console.error('The lock file is missing the expected structure. This can happen after a')
+        console.error('schema migration or if the file was manually edited.')
+        console.error('To fix:')
+        console.error('  deck link    # regenerate with current schema')
         process.exit(1)
       }
 
@@ -165,9 +171,15 @@ async function main(): Promise<void> {
       const declaredSources = new Set(lock.skills.map((s: any) => s.source))
       for (const repoPath of allRepos) {
         const repoRel = repoPath.slice(coldPoolPath.length + 1)
-        const isReferenced = [...declaredSources].some(
-          (src) => src === repoRel || src.startsWith(repoRel + '/'),
-        )
+        // Compare as (host, owner, repo) tuple to avoid prefix collisions
+        const repoParts = repoRel.split('/')
+        const isReferenced = [...declaredSources].some((src) => {
+          const srcParts = src.split('/')
+          if (repoParts.length >= 3 && srcParts.length >= 3) {
+            return repoParts[0] === srcParts[0] && repoParts[1] === srcParts[1] && repoParts[2] === srcParts[2]
+          }
+          return src === repoRel
+        })
         if (!isReferenced) {
           extra.push(repoRel)
         }
@@ -212,5 +224,12 @@ async function main(): Promise<void> {
 
 main().catch((e: Error) => {
   console.error(`❌ ${e.message}`)
+  console.error('')
+  console.error('If this is a configuration issue:')
+  console.error('  cold-pool validate --lock ./skill-deck.lock   # check lock consistency')
+  console.error('If you suspect a bug:')
+  console.error('  cold-pool prune --dry-run                      # safe diagnostic, no deletes')
+  console.error('For full help:')
+  console.error('  cold-pool --help')
   process.exit(1)
 })

package/src/cold-pool.ts

@@ -43,6 +43,10 @@ export interface ListPlan {
 export function buildListPlan(rootPath: string, allEntries: DirEntry[]): ListPlan {
   const plan: ListPlanEntry[] = []
   const dirSet = new Set(allEntries.filter(e => e.isDirectory).map(e => e.relPath))
+  // Pre-compute: O(1) lookup for "does this dir have a SKILL.md?"
+  const skillMdPaths = new Set(
+    allEntries.filter(e => !e.isDirectory && e.relPath.endsWith('/SKILL.md')).map(e => e.relPath)
+  )
 
   function isTerminal(relPath: string): boolean {
     const prefix = relPath + '/'
@@ -53,7 +57,7 @@ export function buildListPlan(rootPath: string, allEntries: DirEntry[]): ListPla
   }
 
   function hasSkillMd(dirRel: string): boolean {
-    return allEntries.some(e => e.relPath === `${dirRel}/SKILL.md` && !e.isDirectory)
+    return skillMdPaths.has(`${dirRel}/SKILL.md`)
   }
 
   // Phase 1: Process terminal dirs (backward compat, but only WITH SKILL.md)

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'
@@ -20,15 +21,16 @@ export function buildFetchPlan(
   opts?: { ref?: string },
 ): FetchPlan {
   const targetDir = pool.resolveDir(locator)
+  const protocol = process.env.LYTHOS_GIT_PROTOCOL || 'https'
   const cloneUrl = locator.isLocalhost
     ? ''
-    : `https://${locator.host}/${locator.owner}/${locator.repo}.git`
+    : `${protocol}://${locator.host}/${locator.owner}/${locator.repo}.git`
 
   return {
     locator,
     cloneUrl,
     targetDir,
-    ref: opts?.ref,
+    ref: opts?.ref ?? locator.ref,  // explicit opts override locator's #ref
     alreadyExists: existsSync(targetDir),
   }
 }
@@ -47,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/git-io.ts

@@ -7,7 +7,7 @@
  * side-effects. Direct `execFileSync('git', ...)` calls in other
  * packages are an anti-pattern (controller bypassing service to DAO).
  */
-import { execFileSync, execSync } from 'node:child_process'
+import { execFileSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 
@@ -18,6 +18,8 @@ export interface GitCloneOptions {
   ref?: string
   /** stdio mode for the spawned git process. Default 'pipe' (capture). */
   stdio?: 'pipe' | 'inherit' | 'ignore'
+  /** Timeout in ms for clone + checkout. Default 120000 (2 min). */
+  timeout?: number
 }
 
 export function gitClone(url: string, dir: string, opts?: GitCloneOptions): void {
@@ -27,10 +29,11 @@ export function gitClone(url: string, dir: string, opts?: GitCloneOptions): void
     args.push('--depth', String(depth))
   }
   args.push(url, dir)
-  execFileSync('git', args, { stdio: opts?.stdio ?? 'pipe' })
+  const timeout = opts?.timeout ?? 120_000
+  execFileSync('git', args, { stdio: opts?.stdio ?? 'pipe', timeout })
 
   if (opts?.ref && opts.ref !== 'HEAD') {
-    execFileSync('git', ['checkout', opts.ref], { cwd: dir, stdio: opts?.stdio ?? 'pipe' })
+    execFileSync('git', ['checkout', opts.ref], { cwd: dir, stdio: opts?.stdio ?? 'pipe', timeout })
   }
 }
 
@@ -41,7 +44,7 @@ export interface GitPullResult {
 
 export function gitPull(dir: string, timeoutMs: number = 30000): GitPullResult {
   try {
-    const output = execSync('git pull', {
+    const output = execFileSync('git', ['pull'], {
       cwd: dir,
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],

package/src/metadata-db.ts

@@ -326,6 +326,7 @@ export class MetadataDB extends SqliteDb {
     deckPath: string,
     declaredSkills: Array<{ locator: string; alias: string | null }>,
   ): void {
+    const now = this.now()
     this.db.transaction(() => {
       // Get current refs for this deck (any state)
       const currentRefs = this.queryAll<{ skill_locator: string; state: string | null }>(
@@ -344,7 +345,7 @@ export class MetadataDB extends SqliteDb {
           this.exec(
             `UPDATE deck_refs SET state = 'removed', removed_at = $now
              WHERE deck_path = $deck AND skill_locator = $locator`,
-            { $deck: deckPath, $locator: ref.skill_locator, $now: this.now() },
+            { $deck: deckPath, $locator: ref.skill_locator, $now: now },
           )
         }
       }
@@ -355,7 +356,7 @@ export class MetadataDB extends SqliteDb {
         VALUES ($locator, $deck, $alias, 'linked', $now, NULL)
       `)
       for (const skill of declaredSkills) {
-        insert.run({ $locator: skill.locator, $deck: deckPath, $alias: skill.alias, $now: this.now() })
+        insert.run({ $locator: skill.locator, $deck: deckPath, $alias: skill.alias, $now: now })
       }
       insert.finalize()
     })()

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/prune-plan.ts

@@ -54,6 +54,7 @@ function calculateDirSize(dir: string): number {
   try {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
       const p = join(dir, entry.name)
+      if (entry.isSymbolicLink()) continue
       if (entry.isDirectory()) {
         total += calculateDirSize(p)
       } else if (entry.isFile()) {

package/src/reconcile-plan.ts

@@ -35,7 +35,7 @@ export interface ReconcileEntry {
 export interface ReconcilePlan {
   /** Skills whose repo dir doesn't exist in the cold pool. */
   missing: ReconcileEntry[]
-  /** Skills whose repo exists but git HEAD doesn't match the metadata record. */
+  /** Skills whose repo was previously fetched (metadata record exists) but HEAD hasn't been verified against upstream. The async executor must git-fetch to determine if they're actually behind. */
   behind: ReconcileEntry[]
   /** Repos in the cold pool not referenced by any skill in the desired state. */
   extra: ReconcileEntry[]

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
 }
 

package/src/validate-plan.ts

@@ -100,7 +100,19 @@ export async function executeValidationPlan(
     io?.fetch,
   )
 
-  io?.log?.(`tree fetch: ${tree.status} (http ${tree.httpStatus})`)
+  io?.log?.(`tree fetch: ${tree.status} (http ${tree.httpStatus})${tree.truncated ? ' ⚠️ truncated (incomplete)' : ''}`)
+
+  if (tree.truncated && tree.status === 'ok') {
+    return {
+      status: 'incomplete',
+      items: [],
+      fixes: [{
+        action: 'retry-later',
+        confidence: 0.9,
+        message: 'GitHub Tree API returned truncated result (>7MB or >100k entries). Skill discovery may be incomplete — retry with non-recursive paging.',
+      }],
+    }
+  }
 
   if (tree.status === 'not-found') {
     fixes.push({