@lythos/cold-pool 0.9.45 → 0.9.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/cold-pool",
-  "version": "0.9.45",
+  "version": "0.9.46",
   "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",
@@ -24,6 +24,9 @@
   },
   "main": "src/index.ts",
   "types": "src/index.ts",
+  "bin": {
+    "cold-pool": "src/cli.ts"
+  },
   "files": [
     "src",
     "README.md",

package/src/cli.ts

@@ -0,0 +1,216 @@
+#!/usr/bin/env bun
+/**
+ * @lythos/cold-pool CLI — cold pool management commands.
+ *
+ * Commands:
+ *   prune       Scan cold pool for unreferenced repos (uses metadata DB FSM)
+ *   reconcile   Compare a lock file's desired state against cold pool
+ */
+
+import { existsSync, readFileSync, rmSync } from 'node:fs'
+import { homedir } from 'node:os'
+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'
+
+const CMD = 'cold-pool'
+
+function help(): void {
+  console.log(`@lythos/cold-pool — Cold pool management CLI
+
+Usage: bunx @lythos/cold-pool <command> [options]
+
+Commands:
+  prune [--yes] [--dry-run]
+    Scan cold pool for repos with no active deck references and
+    offer to delete them. Uses metadata DB deck_refs FSM for
+    cross-deck reference counting (only prunes if ALL refs are removed).
+
+    --yes       Skip confirmation
+    --dry-run   Report only, no deletion
+
+  reconcile [--lock <path>]
+    Read a skill-deck.lock file and compare its desired state against
+    the cold pool. Plan-only (report drift). Use individual deck
+    commands to converge.
+
+    --lock <path>  Path to skill-deck.lock (default: ./skill-deck.lock)
+
+  help     Show this help
+`)
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2)
+  const command = args[0]
+
+  if (!command || command === 'help' || command === '--help') {
+    help()
+    process.exit(0)
+  }
+
+  // Resolve cold pool path (env var > default)
+  const coldPoolPath = process.env.LYTHOS_COLD_POOL ?? DEFAULT_COLD_POOL_PATH
+
+  switch (command) {
+    // ── prune ─────────────────────────────────────────────────
+    case 'prune': {
+      const yes = args.includes('--yes')
+      const dryRun = args.includes('--dry-run')
+
+      if (!existsSync(coldPoolPath)) {
+        console.log('📭 Cold pool does not exist. Nothing to prune.')
+        process.exit(0)
+      }
+
+      const plan = buildPrunePlan(coldPoolPath)
+
+      if (plan.candidates.length === 0) {
+        console.log('✅ All cold pool repositories are referenced. Nothing to prune.')
+        process.exit(0)
+      }
+
+      if (dryRun) {
+        executePrunePlan(plan, { log: console.log })
+        process.exit(0)
+      }
+
+      // Interactive confirmation
+      if (!yes) {
+        const { createInterface } = await import('node:readline')
+        const rl = createInterface({ input: process.stdin, output: process.stdout })
+        const answer = await new Promise<string>((resolve) => {
+          rl.question(`\nDelete ${plan.candidates.length} unreferenced repo(s)? [y/N] `, resolve)
+        })
+        rl.close()
+        if (answer.trim().toLowerCase() !== 'y') {
+          console.log('❎ Prune cancelled.')
+          process.exit(0)
+        }
+
+        const results = executePrunePlan(plan, {
+          delete: (p: string) => rmSync(p, { recursive: true, force: true }),
+          log: console.log,
+        })
+
+        if (results.some((r) => !r.deleted)) process.exit(1)
+        break
+      }
+
+      // Non-interactive (--yes)
+      const results = executePrunePlan(plan, {
+        delete: (p: string) => rmSync(p, { recursive: true, force: true }),
+        log: console.log,
+      })
+
+      if (results.some((r) => !r.deleted)) process.exit(1)
+      break
+    }
+
+    // ── reconcile ─────────────────────────────────────────────
+    case 'reconcile': {
+      const lockIdx = args.indexOf('--lock')
+      const lockPath = lockIdx >= 0 ? args[lockIdx + 1] : undefined
+
+      if (!lockPath) {
+        console.error('❌ Missing --lock <path>. Usage: cold-pool reconcile --lock ./skill-deck.lock')
+        process.exit(1)
+      }
+
+      if (!existsSync(lockPath)) {
+        console.error(`❌ Lock file not found: ${lockPath}`)
+        process.exit(1)
+      }
+
+      let lock: any
+      try {
+        lock = JSON.parse(readFileSync(lockPath, 'utf-8'))
+      } catch (e: any) {
+        console.error(`❌ Failed to parse lock file: ${e.message}`)
+        process.exit(1)
+      }
+
+      if (!lock.skills || !Array.isArray(lock.skills)) {
+        console.error('❌ Lock file has no "skills" array. Run deck link first.')
+        process.exit(1)
+      }
+
+      if (!existsSync(coldPoolPath)) {
+        console.log('📭 Cold pool does not exist. Nothing to reconcile.')
+        process.exit(0)
+      }
+
+      const pool = new ColdPool(coldPoolPath)
+      const desired: ReconcileDesiredState = {
+        deckPath: lockPath,
+        skills: lock.skills.map((s: any) => ({ locator: s.source, alias: s.alias })),
+      }
+
+      const missing: string[] = []
+      const behind: string[] = []
+      const extra: string[] = []
+
+      // Reconcile: check each declared skill
+      for (const skill of lock.skills) {
+        const parsed = parseLocator(skill.source)
+        if (!parsed) continue
+        if (!pool.has(parsed)) {
+          missing.push(`${skill.alias} (${skill.source})`)
+        }
+      }
+
+      // Scan cold pool for extras: repos not referenced by this lock
+      const allRepos = pool.list()
+      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 + '/'),
+        )
+        if (!isReferenced) {
+          extra.push(repoRel)
+        }
+      }
+
+      pool.metadata.close()
+
+      // Report
+      console.log(`\n📊 Reconcile Report`)
+      console.log(`   Cold pool: ${coldPoolPath}`)
+      console.log(`   Skills declared: ${lock.skills.length}`)
+
+      if (missing.length === 0 && behind.length === 0 && extra.length === 0) {
+        console.log(`\n✅ No drift detected — cold pool matches desired state.`)
+        process.exit(0)
+      }
+
+      console.log(`\n🔍 Drift detected:`)
+      console.log(`   ❌ Missing: ${missing.length}`)
+      console.log(`   ⚠️  Behind:  ${behind.length}`)
+      console.log(`   📦 Extra:   ${extra.length}`)
+
+      if (missing.length > 0) {
+        console.log(`\n   ❌ Missing repos (declared but not in cold pool):`)
+        for (const m of missing) console.log(`      ${m}`)
+      }
+      if (extra.length > 0) {
+        console.log(`\n   📦 Extra repos (in cold pool but not declared):`)
+        for (const e of extra) console.log(`      ${e}`)
+      }
+
+      console.log(`\n💡 Plan-only. Use 'deck add <locator>' to restore missing, or 'cold-pool prune' to remove extras.`)
+      break
+    }
+
+    default:
+      console.error(`❌ Unknown command: ${command}`)
+      help()
+      process.exit(1)
+  }
+}
+
+main().catch((e: Error) => {
+  console.error(`❌ ${e.message}`)
+  process.exit(1)
+})

package/src/cold-pool.test.ts

@@ -46,7 +46,9 @@ describe('ColdPool — fs-backed read accessors', () => {
   // "Directory layers = FQ locator segments."
   const root = mkdtempSync(join(tmpdir(), 'cold-pool-test-'))
   mkdirSync(join(root, 'github.com/owner/repo-a'), { recursive: true })
+  writeFileSync(join(root, 'github.com/owner/repo-a/SKILL.md'), '# a')
   mkdirSync(join(root, 'github.com/owner/repo-b'), { recursive: true })
+  writeFileSync(join(root, 'github.com/owner/repo-b/SKILL.md'), '# b')
   mkdirSync(join(root, 'localhost/me/skill-x'), { recursive: true })
   writeFileSync(join(root, 'localhost/me/skill-x/SKILL.md'), '# x')
   // Hidden dir should be skipped
@@ -111,6 +113,7 @@ describe('buildListPlan — pure classification (no IO)', () => {
       dir('github.com'),
       dir('github.com/owner'),
       dir('github.com/owner/repo-a'),
+      file('github.com/owner/repo-a/SKILL.md'),
     ]
     const plan = buildListPlan(root, entries)
     expect(plan.entries).toEqual([
@@ -124,6 +127,7 @@ describe('buildListPlan — pure classification (no IO)', () => {
       dir('github.com'),
       dir('github.com/owner'),
       dir('github.com/owner/repo-a'),
+      file('github.com/owner/repo-a/SKILL.md'),
       dir('github.com/owner/.DS_Store'),
     ]
     const plan = buildListPlan(root, entries)
@@ -160,6 +164,7 @@ describe('buildListPlan — pure classification (no IO)', () => {
       dir('github.com'),
       dir('github.com/owner'),
       dir('github.com/owner/repo-a'),
+      file('github.com/owner/repo-a/SKILL.md'),
       dir('localhost'),
       dir('localhost/old-skill'),
       file('localhost/old-skill/SKILL.md'),
@@ -175,8 +180,11 @@ describe('buildListPlan — pure classification (no IO)', () => {
       dir('github.com'),
       dir('github.com/owner'),
       dir('github.com/owner/repo-a'),
+      file('github.com/owner/repo-a/SKILL.md'),
       dir('github.com/owner/repo-b'),
+      file('github.com/owner/repo-b/SKILL.md'),
       dir('github.com/owner/repo-c'),
+      file('github.com/owner/repo-c/SKILL.md'),
     ]
     const plan = buildListPlan(root, entries)
     expect(plan.entries).toHaveLength(3)
@@ -188,9 +196,11 @@ describe('buildListPlan — pure classification (no IO)', () => {
       dir('github.com'),
       dir('github.com/a'),
       dir('github.com/a/r1'),
+      file('github.com/a/r1/SKILL.md'),
       dir('gitlab.com'),
       dir('gitlab.com/b'),
       dir('gitlab.com/b/r2'),
+      file('gitlab.com/b/r2/SKILL.md'),
     ]
     const plan = buildListPlan(root, entries)
     expect(plan.entries).toHaveLength(2)

package/src/cold-pool.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync } from 'node:fs'
+import { existsSync, readdirSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, relative } from 'node:path'
 import type { Locator } from './types.js'
@@ -28,17 +28,22 @@ export interface ListPlan {
 
 /**
  * Pure: given a cold-pool root path and a flat list of all fs entries
- * (with relPath), classify every terminal repo directory.
+ * (with relPath), classify every directory containing SKILL.md.
  *
- * Canonical:  <pool>/<host>/<owner>/<repo>           (3 segments, no SKILL.md mid-tree)
- * Legacy:     <pool>/<host>/SKILL.md                  (depth 1 — no owner/repo)
- *             <pool>/<host>/<name>/SKILL.md            (depth 2 — no repo segment)
+ * Walk ordering:
+ *   1. Terminal repos at depth 3+ (canonical — host/owner/repo)
+ *   2. Legacy depth-2 <host>/<name>/SKILL.md (monorepo roots)
+ *   3. Legacy depth-1 <host>/SKILL.md (flat repos)
+ *   4. Fallback: any other directory with SKILL.md at any depth
+ *
+ * SKILL.md presence is the single authoritative marker for a skill
+ * directory. Terminal-depth heuristics alone miss real-world layouts
+ * like monorepos with subdirs, multi-skill repos, and mixed-depth clones.
  */
 export function buildListPlan(rootPath: string, allEntries: DirEntry[]): ListPlan {
   const plan: ListPlanEntry[] = []
   const dirSet = new Set(allEntries.filter(e => e.isDirectory).map(e => e.relPath))
 
-  // Determine whether a dir is terminal (no child dirs)
   function isTerminal(relPath: string): boolean {
     const prefix = relPath + '/'
     for (const d of dirSet) {
@@ -47,37 +52,39 @@ export function buildListPlan(rootPath: string, allEntries: DirEntry[]): ListPla
     return true
   }
 
-  // Check whether a dir directly contains SKILL.md
   function hasSkillMd(dirRel: string): boolean {
     return allEntries.some(e => e.relPath === `${dirRel}/SKILL.md` && !e.isDirectory)
   }
 
-  // Walk only terminal dirs — they are the leaves (repo-level entries)
+  // Phase 1: Process terminal dirs (backward compat, but only WITH SKILL.md)
   for (const d of dirSet) {
     if (d.startsWith('.') || d.split('/').some(s => s.startsWith('.'))) continue
-    if (!isTerminal(d)) continue
+    if (!isTerminal(d) || !hasSkillMd(d)) continue
 
     const segments = d.split('/')
 
-    // Legacy depth-1: <host>/SKILL.md — terminal dir with SKILL.md, depth=1
-    if (segments.length === 1 && hasSkillMd(d)) {
+    if (segments.length >= 3) {
+      // Canonical or deeper: host/owner/repo[ /sub...]
+      plan.push({ path: join(rootPath, d), kind: 'canonical' })
+    } else if (segments.length === 2) {
+      plan.push({ path: join(rootPath, d), kind: 'legacy-depth2' })
+    } else if (segments.length === 1) {
       plan.push({ path: join(rootPath, d), kind: 'legacy-depth1' })
-      continue
     }
+  }
 
-    // Legacy depth-2: <host>/<name>/SKILL.md — terminal dir with SKILL.md, depth=2
-    if (segments.length === 2 && hasSkillMd(d)) {
-      plan.push({ path: join(rootPath, d), kind: 'legacy-depth2' })
-      continue
-    }
+  // Phase 2: Non-terminal dirs with SKILL.md (monorepo roots, multi-skill repos)
+  // These are missed by phase 1 because they have subdirectories.
+  for (const d of dirSet) {
+    if (d.startsWith('.') || d.split('/').some(s => s.startsWith('.'))) continue
+    if (isTerminal(d)) continue
+    if (!hasSkillMd(d)) continue
 
-    // Canonical: <host>/<owner>/<repo> — terminal dir at depth 3, no SKILL.md mid-tree
-    if (segments.length === 3) {
-      // Verify no SKILL.md at intermediate levels (depth 1 or 2)
-      const parent = segments.slice(0, 2).join('/')
-      if (!hasSkillMd(segments[0]) && !hasSkillMd(parent)) {
-        plan.push({ path: join(rootPath, d), kind: 'canonical' })
-      }
+    const segments = d.split('/')
+    const kind = segments.length >= 3 ? 'canonical' : segments.length === 2 ? 'legacy-depth2' : 'legacy-depth1'
+    // Deduplicate (phase 1 may have already added this path)
+    if (!plan.some(e => e.path === join(rootPath, d))) {
+      plan.push({ path: join(rootPath, d), kind })
     }
   }
 
@@ -103,6 +110,36 @@ export class ColdPool {
     return existsSync(this.resolveDir(locator))
   }
 
+  /**
+   * Find all skill directories by scanning for SKILL.md in the cold pool.
+   * Returns absolute paths.
+   *
+   * Both `list()` (and its underlying `buildListPlan()`) and this method now
+   * converge on SKILL.md presence as the authoritative marker. `list()`
+   * additionally classifies entries by canonical/legacy kind.
+   */
+  findSkillDirectories(): string[] {
+    const dirs: string[] = []
+    if (!existsSync(this.path)) return dirs
+
+    function walk(dir: string, push: (d: string) => void): void {
+      let dirents: ReturnType<typeof readdirSync>
+      try { dirents = readdirSync(dir, { withFileTypes: true }) } catch { return }
+      for (const d of dirents) {
+        if (!d.isDirectory() || d.name.startsWith('.')) continue
+        const sub = join(dir, d.name)
+        if (existsSync(join(sub, 'SKILL.md'))) {
+          push(sub)
+        } else {
+          walk(sub, push)
+        }
+      }
+    }
+
+    walk(this.path, (d) => dirs.push(d))
+    return dirs
+  }
+
   /** Enumerate cold-pool entries. Delegates classification to pure buildListPlan. */
   list(): string[] {
     if (!existsSync(this.path)) return []

package/src/index.ts

@@ -39,6 +39,9 @@ export { buildFetchPlan, executeFetchPlan } from './fetch-plan.js'
 
 export { getRepoHeadRef, getSkillBlobHash, getSkillTreeHash, hashSkillMd } from './git-hash.js'
 
+export type { PruneCandidate, PrunePlan, PruneResult, PruneIO } from './prune-plan.js'
+export { buildPrunePlan, executePrunePlan } from './prune-plan.js'
+
 export type {
   DesiredSkill,
   ReconcileDesiredState,

package/src/metadata-db.ts

@@ -7,10 +7,22 @@
  * Three tables:
  *   repos        — per-repo HEAD ref tracking
  *   skills       — per-skill content hash (git blob hash of SKILL.md)
- *   deck_refs    — cross-deck reference index
+ *   deck_refs    — cross-deck reference index with FSM state tracking
+ *
+ * deck_refs FSM (v3+):
+ *   state: 'added' | 'linked' | 'removed'
+ *   added ──link()──→ linked ──remove()──→ removed ──add()──→ added
+ *   added ──remove()──→ removed (never linked)
+ *   removed ──reconcile()──→ linked (reconciled back into active state)
+ *
+ * Prune uses state to distinguish "truly unreferenced" (all refs = removed)
+ * from "has active decks" (any ref = added/linked), preventing cross-deck
+ * accidental deletion.
  */
 
-import { SqliteDb } from './db-helpers.js'
+import { SqliteDb } from '@lythos/infra'
+
+export type DeckRefState = 'added' | 'linked' | 'removed'
 
 export interface RepoRef {
   host: string
@@ -34,9 +46,13 @@ export interface DeckReference {
   skillLocator: string
   deckPath: string
   declaredAlias: string | null
+  state: DeckRefState | null
+  mode: string | null
+  linkedAt: string | null
+  removedAt: string | null
 }
 
-const CURRENT_SCHEMA = 2
+const CURRENT_SCHEMA = 6
 
 export class MetadataDB extends SqliteDb {
   constructor(dbPath: string) {
@@ -74,12 +90,17 @@ export class MetadataDB extends SqliteDb {
         skill_locator TEXT NOT NULL,
         deck_path TEXT NOT NULL,
         declared_alias TEXT,
+        state TEXT NOT NULL DEFAULT 'linked',
+        mode TEXT DEFAULT 'symlink',
+        linked_at TEXT,
+        removed_at TEXT,
         PRIMARY KEY (skill_locator, deck_path)
       )
     `)
 
     this.exec(`CREATE INDEX IF NOT EXISTS idx_deck_refs_deck ON deck_refs(deck_path)`)
     this.exec(`CREATE INDEX IF NOT EXISTS idx_deck_refs_locator ON deck_refs(skill_locator)`)
+    this.exec(`CREATE INDEX IF NOT EXISTS idx_deck_refs_state ON deck_refs(state)`)
     this.exec(`CREATE INDEX IF NOT EXISTS idx_skills_repo ON skills(host, owner, repo)`)
 
     // Schema migrations
@@ -89,6 +110,22 @@ export class MetadataDB extends SqliteDb {
         version: 2,
         sql: `ALTER TABLE skills ADD COLUMN git_blob_hash TEXT`,
       },
+      {
+        version: 3,
+        sql: `ALTER TABLE deck_refs ADD COLUMN state TEXT NOT NULL DEFAULT 'linked'`,
+      },
+      {
+        version: 4,
+        sql: `ALTER TABLE deck_refs ADD COLUMN linked_at TEXT`,
+      },
+      {
+        version: 5,
+        sql: `ALTER TABLE deck_refs ADD COLUMN removed_at TEXT`,
+      },
+      {
+        version: 6,
+        sql: `ALTER TABLE deck_refs ADD COLUMN mode TEXT DEFAULT 'symlink'`,
+      },
     ])
   }
 
@@ -151,50 +188,174 @@ export class MetadataDB extends SqliteDb {
     return row?.content_sha256 ?? null
   }
 
-  // ── Deck References ──────────────────────────────────────────
+  // ── Deck References — FSM ───────────────────────────────────
 
+  /**
+   * Add a reference. Sets state='added' (declared but may not be linked).
+   * Can re-activate a previously-removed reference (state: removed → added).
+   */
   addReference(skillLocator: string, deckPath: string, declaredAlias: string | null): void {
     this.exec(
-      `INSERT OR REPLACE INTO deck_refs (skill_locator, deck_path, declared_alias)
-       VALUES ($locator, $deck, $alias)`,
+      `INSERT OR REPLACE INTO deck_refs (skill_locator, deck_path, declared_alias, state, linked_at, removed_at)
+       VALUES ($locator, $deck, $alias, 'added', NULL, NULL)`,
       { $locator: skillLocator, $deck: deckPath, $alias: declaredAlias },
     )
   }
 
+  /**
+   * Soft-remove: sets state='removed' instead of deleting the row.
+   * The historical record is preserved for cross-deck reference counting.
+   * Removes linked_at to indicate the skill is no longer active.
+   */
   removeReference(skillLocator: string, deckPath: string): void {
     this.exec(
-      `DELETE FROM deck_refs WHERE skill_locator = $locator AND deck_path = $deck`,
-      { $locator: skillLocator, $deck: deckPath },
+      `UPDATE deck_refs SET state = 'removed', removed_at = $now
+       WHERE skill_locator = $locator AND deck_path = $deck`,
+      { $locator: skillLocator, $deck: deckPath, $now: this.now() },
     )
   }
 
+  /**
+   * Soft-remove all refs for a deck (same as removeReference, bulk).
+   */
   removeAllReferencesForDeck(deckPath: string): void {
-    this.exec(`DELETE FROM deck_refs WHERE deck_path = $deck`, { $deck: deckPath })
+    this.exec(
+      `UPDATE deck_refs SET state = 'removed', removed_at = $now WHERE deck_path = $deck`,
+      { $deck: deckPath, $now: this.now() },
+    )
   }
 
-  getReferencingDecks(skillLocator: string): Array<{ deckPath: string; alias: string | null }> {
-    const rows = this.queryAll<{ deck_path: string; declared_alias: string | null }>(
-      `SELECT deck_path, declared_alias FROM deck_refs WHERE skill_locator = $locator`,
+  /**
+   * Get active (non-removed) referencing decks for a skill locator.
+   * Legacy rows with state=NULL are treated as active.
+   * Returns only active references — for full history use getAllRefsForLocator.
+   */
+  getReferencingDecks(
+    skillLocator: string,
+  ): Array<{ deckPath: string; alias: string | null; state: string | null }> {
+    const rows = this.queryAll<{ deck_path: string; declared_alias: string | null; state: string | null }>(
+      `SELECT deck_path, declared_alias, state FROM deck_refs
+       WHERE skill_locator = $locator AND (state IS NULL OR state != 'removed')`,
       { $locator: skillLocator },
     )
-    return rows.map((r) => ({ deckPath: r.deck_path, alias: r.declared_alias }))
+    return rows.map((r) => ({ deckPath: r.deck_path, alias: r.declared_alias, state: r.state }))
   }
 
-  // ── Reconcile ────────────────────────────────────────────────
+  /**
+   * Get ALL refs for a locator including removed (historical) ones.
+   * Used by prune to determine if a repo has NO active refs across any deck.
+   */
+  getAllRefsForLocator(skillLocator: string): DeckReference[] {
+    const rows = this.queryAll<{
+      skill_locator: string
+      deck_path: string
+      declared_alias: string | null
+      state: string | null
+      mode: string | null
+      linked_at: string | null
+      removed_at: string | null
+    }>(
+      `SELECT skill_locator, deck_path, declared_alias, state, mode, linked_at, removed_at
+       FROM deck_refs WHERE skill_locator = $locator`,
+      { $locator: skillLocator },
+    )
+    return rows.map((r) => ({
+      skillLocator: r.skill_locator,
+      deckPath: r.deck_path,
+      declaredAlias: r.declared_alias,
+      state: r.state as DeckRefState | null,
+      mode: r.mode,
+      linkedAt: r.linked_at,
+      removedAt: r.removed_at,
+    }))
+  }
 
+  /**
+   * Get all distinct skill locators that have at least one active ref
+   * (state = NULL/added/linked, not 'removed'). Used by prune to determine
+   * which repos must NOT be deleted.
+   */
+  getAllActiveLocators(): string[] {
+    const rows = this.queryAll<{ skill_locator: string }>(
+      `SELECT DISTINCT skill_locator FROM deck_refs
+       WHERE state IS NULL OR state IN ('added', 'linked')`,
+    )
+    return rows.map((r) => r.skill_locator)
+  }
+
+  /**
+   * Update the state of a single reference. Validates the transition:
+   *   added ↔ linked, added/linked → removed, removed → added
+   * Invalid transitions (e.g., linked → added, null → removed) are silently
+   * accepted to avoid hard failures from caller ordering issues.
+   */
+  updateRefState(skillLocator: string, deckPath: string, newState: DeckRefState): void {
+    const now = this.now()
+    switch (newState) {
+      case 'linked':
+        this.exec(
+          `UPDATE deck_refs SET state = 'linked', linked_at = $now
+           WHERE skill_locator = $locator AND deck_path = $deck`,
+          { $locator: skillLocator, $deck: deckPath, $now: now },
+        )
+        break
+      case 'removed':
+        this.removeReference(skillLocator, deckPath)
+        break
+      case 'added':
+        this.exec(
+          `UPDATE deck_refs SET state = 'added', removed_at = NULL
+           WHERE skill_locator = $locator AND deck_path = $deck`,
+          { $locator: skillLocator, $deck: deckPath },
+        )
+        break
+    }
+  }
+
+  /**
+   * Reconcile all deck references atomically.
+   *
+   * Compared to the old DELETE+INSERT approach, this uses state transitions:
+   * - Skills still declared → state='linked' (active, just linked)
+   * - Skills no longer declared → state='removed' (was active, now gone)
+   *
+   * The key semantic change: we NEVER hard-delete from deck_refs during normal
+   * operations. This enables cross-deck reference counting via getAllActiveLocators().
+   */
   reconcileDeckReferences(
     deckPath: string,
     declaredSkills: Array<{ locator: string; alias: string | null }>,
   ): void {
     this.db.transaction(() => {
-      this.exec(`DELETE FROM deck_refs WHERE deck_path = $deck`, { $deck: deckPath })
+      // Get current refs for this deck (any state)
+      const currentRefs = this.queryAll<{ skill_locator: string; state: string | null }>(
+        `SELECT skill_locator, state FROM deck_refs WHERE deck_path = $deck`,
+        { $deck: deckPath },
+      )
+
+      const declaredSet = new Map<string, string | null>()
+      for (const s of declaredSkills) {
+        declaredSet.set(s.locator, s.alias)
+      }
+
+      // Mark removed: skills in DB but no longer declared
+      for (const ref of currentRefs) {
+        if (!declaredSet.has(ref.skill_locator) && ref.state !== 'removed') {
+          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() },
+          )
+        }
+      }
 
+      // Upsert current declared skills as 'linked'
       const insert = this.db.query(`
-        INSERT INTO deck_refs (skill_locator, deck_path, declared_alias)
-        VALUES ($locator, $deck, $alias)
+        INSERT OR REPLACE INTO deck_refs (skill_locator, deck_path, declared_alias, state, linked_at, removed_at)
+        VALUES ($locator, $deck, $alias, 'linked', $now, NULL)
       `)
       for (const skill of declaredSkills) {
-        insert.run({ $locator: skill.locator, $deck: deckPath, $alias: skill.alias })
+        insert.run({ $locator: skill.locator, $deck: deckPath, $alias: skill.alias, $now: this.now() })
       }
       insert.finalize()
     })()

package/src/prune-plan.ts

@@ -0,0 +1,142 @@
+/**
+ * Prune plan — scan cold pool for repos with no active deck references.
+ *
+ * Uses the metadata DB's deck_refs FSM to determine whether a repo is
+ * actively referenced by any deck. A repo is prunable only if ALL its
+ * refs across ALL decks have state='removed' (or it has no refs at all).
+ *
+ * Unlike the previous deck-level prune implementation (which only checked
+ * ONE deck.toml), this version queries the cross-deck reference index,
+ * preventing accidental deletion of repos still needed by other decks.
+ *
+ * Scanning approach: instead of ColdPool.list() (which uses buildListPlan
+ * with strict canonical depth classification), this scans the cold pool
+ * filesystem directly at host/owner/repo depth, matching how deck add
+ * resolves locators. This correctly handles repos with arbitrary internal
+ * structure (subdirs, non-terminal repos, etc.).
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { ColdPool, DEFAULT_COLD_POOL_PATH } from './cold-pool.js'
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface PruneCandidate {
+  repoPath: string
+  /** Path relative to cold pool root, e.g. "github.com/owner/repo" */
+  repoRel: string
+  size: number
+}
+
+export interface PrunePlan {
+  coldPoolPath: string
+  candidates: PruneCandidate[]
+  totalSize: number
+}
+
+export interface PruneResult {
+  repoRel: string
+  deleted: boolean
+  error?: string
+}
+
+export interface PruneIO {
+  delete?: (path: string) => void
+  log?: (msg: string) => void
+  formatSize?: (bytes: number) => string
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function calculateDirSize(dir: string): number {
+  let total = 0
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        total += calculateDirSize(p)
+      } else if (entry.isFile()) {
+        total += statSync(p).size
+      }
+    }
+  } catch {}
+  return total
+}
+
+function defaultFormatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`
+}
+
+// ── Plan Builder ──────────────────────────────────────────────────────────
+
+/**
+ * Build a prune plan by comparing cold pool contents against the metadata DB.
+ *
+ * 1. Scans cold pool for all repo directories (SKILL.md-driven, like add/link).
+ * 2. Queries metadata DB for all active locators (state = added/linked/NULL).
+ * 3. A repo is prunable if no active locator references it.
+ */
+export function buildPrunePlan(coldPoolPath: string): PrunePlan {
+  const pool = new ColdPool(coldPoolPath)
+  const allRepos = pool.findSkillDirectories()
+  const activeLocators = pool.metadata.getAllActiveLocators()
+  pool.metadata.close()
+
+  const candidates: PruneCandidate[] = []
+  for (const repoPath of allRepos) {
+    const repoRel = repoPath.slice(coldPoolPath.length + 1)
+    // A repo matches if any active locator starts with its relative path
+    // (accounting for sub-skill locators like "host/owner/repo/subskill")
+    const isReferenced = activeLocators.some(
+      (loc) => loc === repoRel || loc.startsWith(repoRel + '/'),
+    )
+    if (!isReferenced) {
+      candidates.push({ repoPath, repoRel, size: calculateDirSize(repoPath) })
+    }
+  }
+
+  return {
+    coldPoolPath,
+    candidates,
+    totalSize: candidates.reduce((sum, c) => sum + c.size, 0),
+  }
+}
+
+// ── Execution (IO-injected) ───────────────────────────────────────────────
+
+/**
+ * Execute a prune plan. IO is injected for testability.
+ */
+export function executePrunePlan(plan: PrunePlan, io?: PruneIO): PruneResult[] {
+  const del = io?.delete ?? ((_p: string) => { throw new Error('delete not injected') })
+  const log = io?.log ?? (() => {})
+  const fmt = io?.formatSize ?? defaultFormatSize
+
+  log(`\n🧹 Prune candidates — ${plan.candidates.length} repo(s), ${fmt(plan.totalSize)} total:\n`)
+  for (const c of plan.candidates) {
+    log(`   ${c.repoRel} (${fmt(c.size)})`)
+  }
+
+  const results: PruneResult[] = []
+  let deleted = 0
+  let failed = 0
+
+  for (const c of plan.candidates) {
+    try {
+      del(c.repoPath)
+      log(`  🗑️  Deleted: ${c.repoRel}`)
+      results.push({ repoRel: c.repoRel, deleted: true })
+      deleted++
+    } catch (err: any) {
+      log(`  ❌ Failed to delete ${c.repoRel}: ${err.message}`)
+      results.push({ repoRel: c.repoRel, deleted: false, error: err.message })
+      failed++
+    }
+  }
+
+  log(`\n📦 Prune complete: ${deleted} deleted, ${failed} failed`)
+  return results
+}