@lythos/cold-pool 0.9.24

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lythos-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# @lythos/cold-pool
+
+Cold pool service layer for the lythoskill ecosystem.
+
+> Status: scaffold (0.9.x). Public API will stabilize at 0.10.0.
+
+## What this is
+
+A dedicated resource-holder package for the cold pool — the local cache of
+skill repositories at `~/.agents/skill-repos/` (configurable). This package
+is the **only** layer in the ecosystem that holds git side-effects.
+deck / curator / arena consume it instead of running `git clone` themselves.
+
+## Architecture
+
+Three layers, sharing the project's `intent → plan → execute` pattern
+(`cortex/wiki/01-patterns/2026-05-04-intent-plan-execute-fractal-architecture-pattern.md`):
+
+- **Resource layer** — `ColdPool` class holds path, metadata index, reconcile
+  entry. Read-only accessors.
+- **Plan layer** — `buildFetchPlan(coldPool, locator) → FetchPlan`,
+  `buildValidationPlan(coldPool, locator) → ValidationReport`. Pure data,
+  no side effects, dry-run printable.
+- **Execute layer** — `executeFetchPlan(plan, io: FetchIO)`. IO is
+  injectable; defaults to real git operations. Tests swap mocks.
+
+## Locator
+
+Per `ADR-20260502012643244`, locators are FQ-only:
+
+- `host.tld/owner/repo[/skill]` — remote skill (monorepo, flat, or arbitrary subdir)
+- `localhost/<name>` — local-only skill, no remote origin
+
+Bare names and `owner/repo` shorthand are rejected — `parseLocator` returns null.
+
+## Granularity boundary
+
+`skill-deck.lock` is **working-set granularity** (per-skill in `.claude/skills/`).
+The cold pool reconciliation runs at **repo+ref granularity** (per cloned
+repository at a specific commit). The two are not conflated. See
+`ADR-20260507021957847`.
+
+## Package status
+
+This is internal monorepo infrastructure during the 0.9.x line. Public
+npm publish + stable API targeted for 0.10.0. See
+`EPIC-20260507020846020` for the rollout plan.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@lythos/cold-pool",
+  "version": "0.9.24",
+  "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",
+    "skill",
+    "claude-code",
+    "agent-skills",
+    "llm-tooling",
+    "lythoskill",
+    "cold-pool"
+  ],
+  "author": "lythos-labs",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lythos-labs/lythoskill.git",
+    "directory": "packages/lythoskill-cold-pool"
+  },
+  "bugs": {
+    "url": "https://github.com/lythos-labs/lythoskill/issues"
+  },
+  "homepage": "https://github.com/lythos-labs/lythoskill/tree/main/packages/lythoskill-cold-pool#readme",
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/cold-pool.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from 'bun:test'
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { ColdPool, DEFAULT_COLD_POOL_PATH } from './cold-pool'
+import { parseLocator } from './parse-locator'
+
+describe('ColdPool — constructor', () => {
+  test('default path when none given', () => {
+    const pool = new ColdPool()
+    expect(pool.path).toBe(DEFAULT_COLD_POOL_PATH)
+  })
+
+  test('custom path is stored verbatim', () => {
+    const pool = new ColdPool('/tmp/custom-pool')
+    expect(pool.path).toBe('/tmp/custom-pool')
+  })
+})
+
+describe('ColdPool.resolveDir — pure path computation', () => {
+  const pool = new ColdPool('/cold')
+
+  test('host/owner/repo', () => {
+    const loc = parseLocator('github.com/anthropics/skills')!
+    expect(pool.resolveDir(loc)).toBe('/cold/github.com/anthropics/skills')
+  })
+
+  test('host/owner/repo/skill — skill subpath does NOT extend the dir', () => {
+    // resolveDir returns repo dir, not skill dir. Skill subpath is for findSkillDir later.
+    const loc = parseLocator('github.com/anthropics/skills/skills/pdf')!
+    expect(pool.resolveDir(loc)).toBe('/cold/github.com/anthropics/skills')
+  })
+
+  test('localhost form — uniform <pool>/<host>/<owner>/<repo>, no special-case', () => {
+    const loc = parseLocator('localhost/me/my-skill')!
+    expect(pool.resolveDir(loc)).toBe('/cold/localhost/me/my-skill')
+  })
+})
+
+describe('ColdPool — fs-backed read accessors', () => {
+  // Build a small fake cold pool on disk per the uniform layout:
+  // `<pool>/<host>/<owner>/<repo>/SKILL.md` for ALL hosts including localhost.
+  // "Directory layers = FQ locator segments."
+  const root = mkdtempSync(join(tmpdir(), 'cold-pool-test-'))
+  mkdirSync(join(root, 'github.com/owner/repo-a'), { recursive: true })
+  mkdirSync(join(root, 'github.com/owner/repo-b'), { recursive: true })
+  mkdirSync(join(root, 'localhost/me/skill-x'), { recursive: true })
+  writeFileSync(join(root, 'localhost/me/skill-x/SKILL.md'), '# x')
+  // Hidden dir should be skipped
+  mkdirSync(join(root, '.git'), { recursive: true })
+
+  const pool = new ColdPool(root)
+
+  test('has() returns true for existing repo', () => {
+    const loc = parseLocator('github.com/owner/repo-a')!
+    expect(pool.has(loc)).toBe(true)
+  })
+
+  test('has() returns false for missing repo', () => {
+    const loc = parseLocator('github.com/owner/missing')!
+    expect(pool.has(loc)).toBe(false)
+  })
+
+  test('has() works for localhost form (uniform <host>/<owner>/<repo>)', () => {
+    const loc = parseLocator('localhost/me/skill-x')!
+    expect(pool.has(loc)).toBe(true)
+  })
+
+  test('list() enumerates uniform host/owner/repo across all hosts, skips hidden', () => {
+    const entries = pool.list().sort()
+    expect(entries).toEqual([
+      join(root, 'github.com/owner/repo-a'),
+      join(root, 'github.com/owner/repo-b'),
+      join(root, 'localhost/me/skill-x'),
+    ].sort())
+  })
+
+  test('list() includes legacy drift entries (depth-2 SKILL.md, missing repo level) for cleanup awareness', () => {
+    const driftRoot = mkdtempSync(join(tmpdir(), 'cold-pool-drift-'))
+    mkdirSync(join(driftRoot, 'github.com/o/r'), { recursive: true })
+    mkdirSync(join(driftRoot, 'localhost/me/canonical'), { recursive: true })
+    // Legacy drift A: top-level dir with SKILL.md (post-compaction agent invention,
+    // bare-name "skill-a" hack)
+    mkdirSync(join(driftRoot, 'legacy-toplevel'), { recursive: true })
+    writeFileSync(join(driftRoot, 'legacy-toplevel/SKILL.md'), '# legacy A')
+    // Legacy drift B: <localhost>/<name>/SKILL.md (depth-2 missing repo level,
+    // earlier `localhost/<name>` form before owner/repo became required)
+    mkdirSync(join(driftRoot, 'localhost/legacy-name'), { recursive: true })
+    writeFileSync(join(driftRoot, 'localhost/legacy-name/SKILL.md'), '# legacy B')
+
+    const driftPool = new ColdPool(driftRoot)
+    const entries = driftPool.list().sort()
+    expect(entries).toContain(join(driftRoot, 'legacy-toplevel'))
+    expect(entries).toContain(join(driftRoot, 'localhost/legacy-name'))
+  })
+
+  test('list() returns [] when path does not exist', () => {
+    const empty = new ColdPool('/no/such/path')
+    expect(empty.list()).toEqual([])
+  })
+})

package/src/cold-pool.ts

@@ -0,0 +1,87 @@
+/**
+ * ColdPool — dedicated resource holder.
+ *
+ * Owns the cold-pool path, exposes read-only accessors. Operations
+ * (fetch, validate, reconcile) are external functions that take a
+ * ColdPool and return Plan-shaped data, per the intent/plan/execute
+ * pattern.
+ */
+import { existsSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { Locator } from './types.js'
+
+export const DEFAULT_COLD_POOL_PATH = process.env.LYTHOS_COLD_POOL
+  ?? join(homedir(), '.agents/skill-repos')
+
+export class ColdPool {
+  readonly path: string
+
+  constructor(coldPoolPath?: string) {
+    this.path = coldPoolPath ?? DEFAULT_COLD_POOL_PATH
+  }
+
+  /**
+   * Compute the cold-pool directory for a locator. No fs check.
+   *
+   * Layout invariant: `<pool>/<host>/<owner>/<repo>` for ALL locators
+   * including localhost. No special-case branching — "directory layers
+   * = FQ locator segments" (per user 2026-05-07). Skill subpath
+   * extends within the repo dir (resolveDir returns the repo dir).
+   */
+  resolveDir(locator: Locator): string {
+    return join(this.path, locator.host, locator.owner, locator.repo)
+  }
+
+  /** Whether a locator's repo directory exists in the pool. */
+  has(locator: Locator): boolean {
+    return existsSync(this.resolveDir(locator))
+  }
+
+  /**
+   * Enumerate cold-pool entries.
+   *
+   * Uniform layout: `<pool>/<host>/<owner>/<repo>`. localhost is just
+   * another host. No localhost special-case.
+   *
+   * Legacy drift: `<pool>/<x>/SKILL.md` (depth 2 with SKILL.md) or
+   * `<pool>/localhost/<name>/SKILL.md` (depth 3 with SKILL.md, missing
+   * owner/repo) are non-canonical state from older agents that bypassed
+   * FQ-only enforcement. Surface them so prune can offer cleanup.
+   */
+  list(): string[] {
+    if (!existsSync(this.path)) return []
+    const repos: string[] = []
+
+    for (const host of readdirSync(this.path, { withFileTypes: true })) {
+      if (!host.isDirectory() || host.name.startsWith('.')) continue
+      const hostPath = join(this.path, host.name)
+
+      // Legacy drift: top-level dir with SKILL.md (not canonical 3-segment)
+      if (existsSync(join(hostPath, 'SKILL.md'))) {
+        repos.push(hostPath)
+        continue
+      }
+
+      // Canonical: <host>/<owner>/<repo>
+      for (const owner of readdirSync(hostPath, { withFileTypes: true })) {
+        if (!owner.isDirectory() || owner.name.startsWith('.')) continue
+        const ownerPath = join(hostPath, owner.name)
+
+        // Legacy drift: <host>/<x>/SKILL.md (depth 2 missing repo level —
+        // typically `localhost/<name>/SKILL.md` from older agents)
+        if (existsSync(join(ownerPath, 'SKILL.md'))) {
+          repos.push(ownerPath)
+          continue
+        }
+
+        for (const repo of readdirSync(ownerPath, { withFileTypes: true })) {
+          if (!repo.isDirectory() || repo.name.startsWith('.')) continue
+          repos.push(join(ownerPath, repo.name))
+        }
+      }
+    }
+
+    return repos
+  }
+}

package/src/fetch-plan.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from 'bun:test'
+import { mkdtempSync, mkdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { ColdPool } from './cold-pool'
+import { parseLocator } from './parse-locator'
+import { buildFetchPlan, executeFetchPlan } from './fetch-plan'
+import type { FetchIO } from './types'
+
+describe('buildFetchPlan', () => {
+  test('builds targetDir + cloneUrl from locator', () => {
+    const pool = new ColdPool('/cold')
+    const loc = parseLocator('github.com/anthropics/skills/skills/pdf')!
+    const plan = buildFetchPlan(pool, loc)
+    expect(plan.targetDir).toBe('/cold/github.com/anthropics/skills')
+    expect(plan.cloneUrl).toBe('https://github.com/anthropics/skills.git')
+    expect(plan.alreadyExists).toBe(false)
+  })
+
+  test('alreadyExists reflects fs presence', () => {
+    const root = mkdtempSync(join(tmpdir(), 'fetch-plan-test-'))
+    mkdirSync(join(root, 'github.com/owner/repo'), { recursive: true })
+    const pool = new ColdPool(root)
+    const loc = parseLocator('github.com/owner/repo')!
+    const plan = buildFetchPlan(pool, loc)
+    expect(plan.alreadyExists).toBe(true)
+  })
+
+  test('localhost locator gets empty cloneUrl + uniform <host>/<owner>/<repo> path', () => {
+    const pool = new ColdPool('/cold')
+    const loc = parseLocator('localhost/me/my-skill')!
+    const plan = buildFetchPlan(pool, loc)
+    expect(plan.cloneUrl).toBe('')
+    expect(plan.targetDir).toBe('/cold/localhost/me/my-skill')
+  })
+
+  test('passes ref through', () => {
+    const pool = new ColdPool('/cold')
+    const loc = parseLocator('github.com/o/r')!
+    const plan = buildFetchPlan(pool, loc, { ref: 'v1.2.3' })
+    expect(plan.ref).toBe('v1.2.3')
+  })
+})
+
+describe('executeFetchPlan', () => {
+  test('alreadyExists path → already-present, no clone called', () => {
+    const pool = new ColdPool('/cold')
+    const loc = parseLocator('github.com/o/r')!
+    const plan = { ...buildFetchPlan(pool, loc), alreadyExists: true }
+    let cloneCalls = 0
+    const io: FetchIO = {
+      gitClone: () => { cloneCalls++ },
+      exists: () => true,
+    }
+    const result = executeFetchPlan(plan, io)
+    expect(result.status).toBe('already-present')
+    expect(cloneCalls).toBe(0)
+  })
+
+  test('clones when target absent', () => {
+    const pool = new ColdPool('/cold')
+    const loc = parseLocator('github.com/o/r')!
+    const plan = buildFetchPlan(pool, loc)
+    const cloneArgs: Array<{ url: string; dir: string; opts: unknown }> = []
+    const io: FetchIO = {
+      gitClone: (url, dir, opts) => { cloneArgs.push({ url, dir, opts }) },
+      exists: () => false,
+    }
+    const result = executeFetchPlan(plan, io)
+    expect(result.status).toBe('cloned')
+    expect(cloneArgs.length).toBe(1)
+    expect(cloneArgs[0].url).toBe('https://github.com/o/r.git')
+    expect(cloneArgs[0].dir).toBe('/cold/github.com/o/r')
+  })
+
+  test('clone error → failed result with message', () => {
+    const pool = new ColdPool('/cold')
+    const loc = parseLocator('github.com/o/r')!
+    const plan = buildFetchPlan(pool, loc)
+    const io: FetchIO = {
+      gitClone: () => { throw new Error('boom') },
+      exists: () => false,
+    }
+    const result = executeFetchPlan(plan, io)
+    expect(result.status).toBe('failed')
+    expect(result.message).toContain('boom')
+  })
+
+  test('localhost locator refuses to fetch', () => {
+    const pool = new ColdPool('/cold')
+    const loc = parseLocator('localhost/me/x')!
+    const plan = buildFetchPlan(pool, loc)
+    let cloneCalls = 0
+    const io: FetchIO = {
+      gitClone: () => { cloneCalls++ },
+      exists: () => false,
+    }
+    const result = executeFetchPlan(plan, io)
+    expect(result.status).toBe('failed')
+    expect(result.message).toContain('localhost')
+    expect(cloneCalls).toBe(0)
+  })
+
+  test('log IO is invoked', () => {
+    const pool = new ColdPool('/cold')
+    const loc = parseLocator('github.com/o/r')!
+    const plan = buildFetchPlan(pool, loc)
+    const lines: string[] = []
+    const io: FetchIO = {
+      gitClone: () => {},
+      exists: () => false,
+      log: (m) => lines.push(m),
+    }
+    executeFetchPlan(plan, io)
+    expect(lines.some((l) => l.includes('cloning'))).toBe(true)
+  })
+})

package/src/fetch-plan.ts

@@ -0,0 +1,72 @@
+/**
+ * FetchPlan + executor.
+ *
+ * Per-locator fetch primitive. `buildFetchPlan` is pure (computes
+ * targetDir + cloneUrl, peeks fs for `alreadyExists`). `executeFetchPlan`
+ * does the side-effecting `git clone` via injected IO.
+ *
+ * Localhost locators are not fetchable (no remote) — `buildFetchPlan`
+ * returns a plan with `alreadyExists: pool.has(locator)` but
+ * `executeFetchPlan` will refuse to clone (status: 'failed').
+ */
+import { existsSync } from 'node:fs'
+import type { ColdPool } from './cold-pool.js'
+import type { Locator, FetchPlan, FetchResult, FetchIO } from './types.js'
+import { gitClone } from './git-io.js'
+
+export function buildFetchPlan(
+  pool: ColdPool,
+  locator: Locator,
+  opts?: { ref?: string },
+): FetchPlan {
+  const targetDir = pool.resolveDir(locator)
+  const cloneUrl = locator.isLocalhost
+    ? ''
+    : `https://${locator.host}/${locator.owner}/${locator.repo}.git`
+
+  return {
+    locator,
+    cloneUrl,
+    targetDir,
+    ref: opts?.ref,
+    alreadyExists: existsSync(targetDir),
+  }
+}
+
+export function executeFetchPlan(plan: FetchPlan, io?: FetchIO): FetchResult {
+  const log = io?.log ?? (() => {})
+  const exists = io?.exists ?? existsSync
+  const cloneFn = io?.gitClone ?? gitClone
+
+  if (plan.locator.isLocalhost) {
+    return {
+      status: 'failed',
+      targetDir: plan.targetDir,
+      message: 'localhost locators have no remote; nothing to fetch',
+    }
+  }
+
+  if (exists(plan.targetDir)) {
+    log(`✓ already present: ${plan.targetDir}`)
+    return {
+      status: 'already-present',
+      targetDir: plan.targetDir,
+    }
+  }
+
+  log(`📦 cloning ${plan.cloneUrl} → ${plan.targetDir}`)
+  try {
+    cloneFn(plan.cloneUrl, plan.targetDir, { depth: 1, ref: plan.ref })
+    return {
+      status: 'cloned',
+      targetDir: plan.targetDir,
+    }
+  } catch (err: unknown) {
+    const e = err as { message?: string }
+    return {
+      status: 'failed',
+      targetDir: plan.targetDir,
+      message: e.message ?? 'git clone failed',
+    }
+  }
+}

package/src/git-io.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } 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'
+
+// 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.
+
+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
+  const orphanDir = join(root, 'pool/orphan')
+  mkdirSync(orphanDir, { recursive: true })
+
+  test('finds .git at the same dir', () => {
+    const r = detectGitRoot(repoDir)
+    expect(r.gitRoot).toBe(resolve(repoDir))
+  })
+
+  test('walks up to find .git', () => {
+    const r = detectGitRoot(subDir)
+    expect(r.gitRoot).toBe(resolve(repoDir))
+  })
+
+  test('returns not-found when no .git in walk', () => {
+    const r = detectGitRoot(orphanDir)
+    expect(r.gitRoot).toBeNull()
+    expect(r.reason).toBe('not-found')
+  })
+
+  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')
+    mkdirSync(inner, { recursive: true })
+    mkdirSync(coldPool, { recursive: true })
+    const r = detectGitRoot(inner, coldPool)
+    expect(r.gitRoot).toBeNull()
+    expect(r.reason).toBe('outside-cold-pool')
+  })
+
+  test('coldPool given, walking up within cold pool finds .git', () => {
+    const r = detectGitRoot(subDir, join(root, 'pool'))
+    expect(r.gitRoot).toBe(resolve(repoDir))
+  })
+})

package/src/git-io.ts

@@ -0,0 +1,90 @@
+/**
+ * Git IO primitives — the only place in the lythoskill ecosystem that
+ * runs `git clone` / `git pull` directly. Consumers (deck/curator/arena)
+ * must go through these (or through `executeFetchPlan` which uses them).
+ *
+ * Per ADR-20260507021957847: cold-pool is the dedicated holder of git
+ * 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 { existsSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+
+export interface GitCloneOptions {
+  /** Default 1 (shallow). Set to 0 to disable depth (full history). */
+  depth?: number
+  /** Branch/tag/commit to checkout after clone. Implies a follow-up `git checkout` if not HEAD. */
+  ref?: string
+  /** stdio mode for the spawned git process. Default 'pipe' (capture). */
+  stdio?: 'pipe' | 'inherit' | 'ignore'
+}
+
+export function gitClone(url: string, dir: string, opts?: GitCloneOptions): void {
+  const args = ['clone']
+  const depth = opts?.depth ?? 1
+  if (depth > 0) {
+    args.push('--depth', String(depth))
+  }
+  args.push(url, dir)
+  execFileSync('git', args, { stdio: opts?.stdio ?? 'pipe' })
+
+  if (opts?.ref && opts.ref !== 'HEAD') {
+    execFileSync('git', ['checkout', opts.ref], { cwd: dir, stdio: opts?.stdio ?? 'pipe' })
+  }
+}
+
+export interface GitPullResult {
+  status: 'updated' | 'up-to-date' | 'failed'
+  message: string
+}
+
+export function gitPull(dir: string, timeoutMs: number = 30000): GitPullResult {
+  try {
+    const output = execSync('git pull', {
+      cwd: dir,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: timeoutMs,
+    }).trim()
+
+    if (output.includes('Already up to date') || output.includes('Already up-to-date')) {
+      return { status: 'up-to-date', message: output }
+    }
+    return { status: 'updated', message: output }
+  } catch (err: unknown) {
+    const e = err as { stderr?: { toString: () => string }; message?: string }
+    const stderr = e.stderr?.toString() || e.message || ''
+    return { status: 'failed', message: stderr.trim() }
+  }
+}
+
+/**
+ * Walk up from `dir` looking for a directory containing `.git/`. Stops
+ * walking when it crosses outside `coldPool` (if given) — keeps the
+ * search scoped to the cold-pool's own git roots.
+ */
+export interface GitRootResult {
+  gitRoot: string | null
+  reason?: 'not-found' | 'outside-cold-pool'
+}
+
+export function detectGitRoot(dir: string, coldPool?: string): GitRootResult {
+  const absDir = resolve(dir)
+  const absColdPool = coldPool ? resolve(coldPool) : null
+
+  let cur = absDir
+  while (true) {
+    if (absColdPool && !cur.startsWith(absColdPool)) {
+      return { gitRoot: null, reason: 'outside-cold-pool' }
+    }
+    if (existsSync(`${cur}/.git`)) {
+      return { gitRoot: cur }
+    }
+    const parent = dirname(cur)
+    if (parent === cur) {
+      return { gitRoot: null, reason: 'not-found' }
+    }
+    cur = parent
+  }
+}