@lythos/cold-pool 0.9.47 → 0.9.48

package/package.json

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

@@ -20,9 +20,10 @@ 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,

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/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/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({