@ancleto/spec 0.6.27 → 0.6.29

package/README.md

@@ -26,6 +26,7 @@
 - [Guía de .gitignore](#guía-de-gitignore)
 - [Configuración y tiers de costo](#configuración-y-tiers-de-costo)
 - [Uso rápido](#uso-rápido)
+- [Proyectos con ancleto](#proyectos-con-ancleto)
 - [Referencia de comandos CLI](#referencia-de-comandos-cli)
 - [Motor de memoria persistente](#motor-de-memoria-persistente)
 - [Comandos del ciclo SDD en tu IDE](#comandos-del-ciclo-sdd-en-tu-ide)
@@ -120,6 +121,8 @@ Cómo bajarlo:
 - Evitá `--with-engram` salvo que uses esa memoria: es el que más pesa (9× la memoria propia).
 - Podés deshabilitar cualquier servidor en tu `opencode.json`: `"mcp": { "engram": { "enabled": false } }`.
 
+Para medir el consumo **real** por sesión (no estimado): `ancleto stats` lee la base de sesiones de opencode y reporta tokens de entrada/salida/razonamiento/cache, costo y subagentes por sesión. Con `--session <id>` desglosa por agente y con `--since YYYY-MM-DD` permite comparar antes/después de una optimización. Solo funciona con opencode.
+
 ---
 
 ## Guía de .gitignore
@@ -136,6 +139,36 @@ El framework **no gestiona tu `.gitignore`**: es una decisión del proyecto. Com
 
 ---
 
+## Proyectos con ancleto
+
+Cuando instalás ancleto **en un proyecto** (`install --project`, `init` o `update`), el CLI lo anota en un registro global (`~/.config/ancleto/projects.json`). Así podés ver de un vistazo todos los proyectos que lo usan, sin importar desde qué terminal estés:
+
+```bash
+ancleto projects            # lista (o `ancleto list --projects`)
+ancleto projects info       # estado del proyecto actual
+ancleto projects scan "D:/Repos D/Proyectos"   # descubre y registra los que ya existen
+ancleto projects prune      # saca del registro los borrados/movidos
+```
+
+La lista muestra versión instalada, origen (por proyecto vs agentes globales), tier y agente:
+
+```
+ancleto: proyectos (2 activos de 3 registrados · CLI v0.6.28)
+
+   PROYECTO        VERSIÓN   ORIGEN    TIER      AGENTE     RUTA
+  ● App Coffice    0.6.28    scoped    minimo    opencode   D:/Repos D/Proyectos/App Coffice
+  ● spec           0.6.28    scoped    normal    opencode   D:/Repos D/Proyectos/ancleto/spec
+  ✖ Volatile        —         muerto    —         —          D:/Repos D/tmp/volatile
+```
+
+- `●` verde: instalación por proyecto · `○` amarillo: usa agentes globales · `✖` rojo: ruta inexistente (candidata a `prune`).
+- Versión en rojo = desactualizada respecto del CLI instalado.
+- `--json` en todos para scripting.
+
+El registro es tuyo y local: no viaja con el repo ni se comparte. `ANCLETO_PROJECTS_FILE` permite apuntarlo a otro lado.
+
+---
+
 ## Configuración y tiers de costo
 
 En la primera ejecución, un **wizard interactivo** te guía por los pasos de configuración (agente/IDE y nivel de gasto). También podés pasarlos por flags:
@@ -204,6 +237,18 @@ ancleto check             # Verifica la integridad de la instalación (faltantes
 ancleto specs check [--change <nombre>] [--json]
                           # Valida keywords canónicos en aspec/specs y en los deltas de un change
 
+ancleto stats [--all] [--limit N] [--since YYYY-MM-DD] [--session <id>] [--json]
+                          # Tokens por sesión de opencode (rollup de subagentes; --session desglosa por agente)
+
+ancleto projects [list] [--json]
+                          # Lista los proyectos que usan ancleto (versión, tier, origen, ruta)
+ancleto projects scan <raíz> [--dry-run] [--json]
+                          # Descubre y registra proyectos ancleto bajo una raíz
+ancleto projects prune [--dry-run] [--json]
+                          # Quita del registro los proyectos borrados o movidos
+ancleto projects info [ruta] [--json]
+                          # Estado de un proyecto (versión, memoria, seed, changes activos)
+
 ancleto doctor            # Diagnostica el entorno (Node, node:sqlite, opencode.json)
 
 ancleto memory context [--scope <project|feature|task>] [--out <archivo>]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancleto/spec",
-  "version": "0.6.27",
+  "version": "0.6.29",
   "description": "Orquestador SDD liviano con subagentes optimizados para costo/tokens",
   "type": "module",
   "bin": {

package/src/cli/index.js

@@ -4,6 +4,7 @@ import { cp, mkdir, access, writeFile, readFile, readdir, rename } from 'node:fs
 import { spawnSync } from 'node:child_process'
 import { createHash } from 'node:crypto'
 import { createInterface } from 'node:readline'
+import { DatabaseSync } from 'node:sqlite'
 import { join, dirname, resolve, basename, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { homedir, tmpdir } from 'node:os'
@@ -43,6 +44,17 @@ Uso:
   ancleto specs check [--change <name>] [--json]
                                    Valida keywords canonicos (### Requirement:, WHEN, THEN)
                                    en aspec/specs y, con --change, en los deltas del change
+  ancleto stats [--all] [--limit N] [--since YYYY-MM-DD] [--session <id>] [--json]
+                                   Tokens por sesion de opencode (entrada/salida/razonamiento/cache),
+                                   con rollup de subagentes y desglose por agente con --session
+  ancleto projects [list] [--json] Lista los proyectos que usan ancleto (version, tier, origen, ruta)
+  ancleto projects scan <raiz> [--dry-run] [--json]
+                                   Descubre y registra proyectos ancleto bajo una raiz
+  ancleto projects prune [--dry-run] [--json]
+                                   Quita del registro los proyectos borrados o movidos
+  ancleto projects info [ruta] [--json]
+                                   Estado de un proyecto (version, memoria, seed, changes activos)
+  ancleto list --projects [--json]  Alias de "ancleto projects list"
   ancleto memory context [--scope X] [--out file]
                                    Imprime/escribe el bloque <ProjectMemoryRules> (reglas activas)
   ancleto memory list [--type X] [--scope X] [--all] [--json]
@@ -97,6 +109,301 @@ function globalConfigDir() {
     : join(homedir(), '.config', 'opencode')
 }
 
+// Registro global de proyectos que usan ancleto (no depende de opencode).
+function projectsRegistryPath() {
+  if (process.env.ANCLETO_PROJECTS_FILE) return process.env.ANCLETO_PROJECTS_FILE
+  const base = process.env.XDG_CONFIG_HOME ? join(process.env.XDG_CONFIG_HOME, 'ancleto') : join(homedir(), '.config', 'ancleto')
+  return join(base, 'projects.json')
+}
+
+function normKey(p) {
+  return normPath(resolve(p))
+}
+
+async function readProjectsRegistry() {
+  const file = projectsRegistryPath()
+  if (!(await exists(file))) return { schemaVersion: 1, projects: {} }
+  try {
+    const data = JSON.parse((await readFile(file, 'utf8')).replace(/^\uFEFF/, ''))
+    return { schemaVersion: 1, projects: data.projects || {} }
+  } catch (err) {
+    console.warn(`ancleto: registro de proyectos ilegible (${file}): ${err.message}`)
+    return { schemaVersion: 1, projects: {} }
+  }
+}
+
+async function writeProjectsRegistry(reg) {
+  const file = projectsRegistryPath()
+  await mkdir(dirname(file), { recursive: true })
+  await writeFile(file, JSON.stringify(reg, null, 2) + '\n')
+  return file
+}
+
+async function registerProject(projectDir, { agent, tier } = {}) {
+  const abs = resolve(projectDir)
+  const rc = await readAncletorc(abs)
+  const tierFile = join(abs, '.opencode', '.ancleto-tier')
+  const localTier = (await exists(tierFile)) ? (await readFile(tierFile, 'utf8')).trim() : null
+  const hasScopedAgents = await exists(join(abs, '.opencode', 'agents'))
+  const entry = {
+    path: abs.replace(/\\/g, '/'),
+    version: await packageVersion(),
+    agent: agent || rc?.agent || 'opencode',
+    tier: tier || localTier || null,
+    scoped: hasScopedAgents,
+    registeredAt: new Date().toISOString()
+  }
+  const reg = await readProjectsRegistry()
+  const key = normKey(abs)
+  entry.registeredAt = reg.projects[key]?.registeredAt || entry.registeredAt
+  entry.lastSeen = new Date().toISOString()
+  reg.projects[key] = entry
+  await writeProjectsRegistry(reg)
+}
+
+async function unregisterProject(projectDir) {
+  const reg = await readProjectsRegistry()
+  const key = normKey(projectDir)
+  if (!reg.projects[key]) return false
+  delete reg.projects[key]
+  await writeProjectsRegistry(reg)
+  return true
+}
+
+// Color helpers (respetan NO_COLOR y TTY).
+const useColor = () => process.stdout.isTTY && !process.env.NO_COLOR
+function paint(code, s) {
+  return useColor() ? `\x1b[${code}m${s}\x1b[0m` : String(s)
+}
+const c = {
+  dim: (s) => paint('2', s),
+  bold: (s) => paint('1', s),
+  green: (s) => paint('32', s),
+  yellow: (s) => paint('33', s),
+  red: (s) => paint('31', s),
+  cyan: (s) => paint('36', s)
+}
+const stripAnsi = (s) => String(s).replace(/\x1b\[[0-9;]*m/g, '')
+function padVisible(s, width) {
+  const len = stripAnsi(s).length
+  return s + ' '.repeat(Math.max(0, width - len))
+}
+
+// Descubre proyectos ancleto bajo una raiz (busca .ancletorc, con profundidad acotada).
+async function discoverProjectsUnder(root, maxDepth = 3) {
+  const found = []
+  const skip = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.next', 'vendor'])
+  async function walk(dir, depth) {
+    let entries
+    try {
+      entries = await readdir(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    if (entries.some((e) => e.isFile() && (e.name === '.ancletorc' || e.name === '.ancletorc'))) found.push(dir)
+    if (depth >= maxDepth) return
+    for (const e of entries) {
+      if (!e.isDirectory() || skip.has(e.name) || e.name.startsWith('.')) continue
+      await walk(join(dir, e.name), depth + 1)
+    }
+  }
+  await walk(resolve(root), 0)
+  return found
+}
+
+// Lee el estado real de un proyecto registrado (o descubre que ya no existe).
+async function projectStatus(entry) {
+  const abs = entry.path
+  if (!(await exists(abs))) return { ...entry, exists: false }
+  const rc = await readAncletorc(abs)
+  if (!rc) return { ...entry, exists: false, reason: 'sin .ancletorc' }
+  const tierFile = join(abs, '.opencode', '.ancleto-tier')
+  const tier = (await exists(tierFile)) ? (await readFile(tierFile, 'utf8')).trim() : null
+  const scoped = await exists(join(abs, '.opencode', 'agents'))
+  return {
+    ...entry,
+    exists: true,
+    path: abs.replace(/\\/g, '/'),
+    version: rc.version || entry.version || null,
+    agent: rc.agent || entry.agent || null,
+    tier,
+    scoped
+  }
+}
+
+async function projectsList(reg, { asJson, currentVersion }) {
+  const rows = await Promise.all(Object.values(reg.projects).map(projectStatus))
+  rows.sort((a, b) => String(a.path).localeCompare(String(b.path)))
+  if (asJson) {
+    console.log(JSON.stringify({ ok: true, cliVersion: currentVersion, registry: projectsRegistryPath(), count: rows.length, projects: rows }, null, 2))
+    return rows
+  }
+  if (rows.length === 0) {
+    console.log('ancleto: no hay proyectos registrados todavia')
+    console.log(c.dim('  registra uno con: ancleto install --project <ruta>  ·  o descubre con: ancleto projects scan <raiz>'))
+    return rows
+  }
+  const live = rows.filter((r) => r.exists)
+  console.log(`${c.bold('ancleto: proyectos')} ${c.dim(`(${live.length} activos de ${rows.length} registrados · CLI v${currentVersion})`)}`)
+  console.log('')
+  const header = ['', padVisible('PROYECTO', 22), padVisible('VERSIÓN', 10), padVisible('ORIGEN', 10), padVisible('TIER', 9), padVisible('AGENTE', 10), 'RUTA']
+  console.log(c.dim(`  ${header.join(' ')}`))
+  for (const r of rows) {
+    const name = r.path.split('/').filter(Boolean).pop() || r.path
+    if (!r.exists) {
+      console.log(`  ${c.red('✖')} ${padVisible(c.red(name.slice(0, 21)), 22)} ${padVisible(c.dim('—'), 10)} ${padVisible(c.red('muerto'), 10)} ${padVisible('—', 9)} ${padVisible('—', 10)} ${c.dim(r.path)}`)
+      continue
+    }
+    const outdated = r.version && currentVersion && r.version !== currentVersion
+    const marker = r.scoped ? c.green('●') : c.yellow('○')
+    const ver = outdated ? c.red(r.version) : c.green(r.version || '—')
+    const origin = r.scoped ? c.green('scoped') : c.yellow('global')
+    console.log(`  ${marker} ${padVisible(c.bold(name.slice(0, 21)), 22)} ${padVisible(ver, 10)} ${padVisible(origin, 10)} ${padVisible(r.tier || c.dim('—'), 9)} ${padVisible(r.agent || '—', 10)} ${r.path}`)
+  }
+  console.log('')
+  console.log(c.dim('  ● instalación por proyecto   ○ usa agentes globales   versión en rojo = desactualizada'))
+  return rows
+}
+
+async function projectsScan(root, { asJson, dryRun }) {
+  if (!root) {
+    console.error('ancleto: uso: ancleto projects scan <raiz> [--dry-run] [--json]')
+    process.exit(1)
+  }
+  if (!(await exists(root))) {
+    console.error(`ancleto: no existe la raiz "${root}"`)
+    process.exit(1)
+  }
+  const found = await discoverProjectsUnder(root)
+  const reg = await readProjectsRegistry()
+  const added = []
+  const known = []
+  for (const dir of found) {
+    const key = normKey(dir)
+    if (reg.projects[key]) {
+      known.push(dir)
+      continue
+    }
+    added.push(dir)
+    if (!dryRun) await registerProject(dir)
+  }
+  if (asJson) {
+    console.log(JSON.stringify({ ok: true, root: resolve(root), found: found.length, added: added.map((p) => p.replace(/\\/g, '/')), known: known.map((p) => p.replace(/\\/g, '/')), dryRun: !!dryRun }, null, 2))
+    return
+  }
+  console.log(`${c.bold('ancleto: scan')} ${c.dim(resolve(root).replace(/\\/g, '/'))}`)
+  console.log(`  ${c.dim('encontrados:')} ${found.length} proyectos con .ancletorc`)
+  for (const p of added) console.log(`  ${dryRun ? c.yellow('·') : c.green('+')} ${p.replace(/\\/g, '/')}`)
+  for (const p of known) console.log(`  ${c.dim('=')} ${c.dim(p.replace(/\\/g, '/'))}`)
+  if (dryRun) console.log(c.dim('\n  --dry-run: no se registro nada'))
+  else console.log(c.dim(`\n  registrados: ${added.length} nuevos`))
+}
+
+async function projectsPrune({ asJson, dryRun }) {
+  const reg = await readProjectsRegistry()
+  const removed = []
+  for (const [key, entry] of Object.entries(reg.projects)) {
+    const st = await projectStatus(entry)
+    if (!st.exists) {
+      removed.push({ key, path: entry.path, reason: st.reason || 'ruta inexistente' })
+      if (!dryRun) delete reg.projects[key]
+    }
+  }
+  if (!dryRun && removed.length) await writeProjectsRegistry(reg)
+  if (asJson) {
+    console.log(JSON.stringify({ ok: true, pruned: removed.length, removed, dryRun: !!dryRun }, null, 2))
+    return
+  }
+  if (removed.length === 0) {
+    console.log(c.dim('ancleto: no hay entradas muertas en el registro'))
+    return
+  }
+  console.log(`${c.bold('ancleto: prune')}${dryRun ? ` ${c.dim('(dry-run)')}` : ''}`)
+  for (const r of removed) console.log(`  ${dryRun ? c.yellow('·') : c.red('−')} ${r.path} ${c.dim(`(${r.reason})`)}`)
+  console.log(dryRun ? c.dim(`\n  --dry-run: se quitarian ${removed.length}`) : c.dim(`\n  removidos: ${removed.length}`))
+}
+
+async function projectsInfo(target, { asJson, currentVersion }) {
+  const abs = resolve(target || process.cwd())
+  const rc = await readAncletorc(abs)
+  if (!rc) {
+    console.error(`ancleto: "${abs}" no parece un proyecto ancleto (sin .ancletorc)`)
+    process.exit(1)
+  }
+  const st = await projectStatus({ path: abs, ...rc })
+  const hasMemory = await exists(join(abs, '.ancleto', 'memory.db'))
+  const hasSeedIndex = await exists(join(abs, rc.discovery?.outputDir || 'docs/technical-discovery', 'index.md'))
+  const hasWorkingContext = await exists(join(abs, '.ancleto', 'working-context.md'))
+  const activeChangesDir = join(abs, CHANGES_ROOT, 'changes')
+  let activeChanges = 0
+  if (await exists(activeChangesDir)) {
+    const entries = await readdir(activeChangesDir, { withFileTypes: true })
+    activeChanges = entries.filter((e) => e.isDirectory() && e.name !== 'archive').length
+  }
+  const info = {
+    path: abs.replace(/\\/g, '/'),
+    version: st.version,
+    outdated: st.version && currentVersion ? st.version !== currentVersion : false,
+    agent: st.agent,
+    tier: st.tier,
+    scoped: st.scoped,
+    azureEnabled: !!rc.azure?.enabled,
+    memoryDb: hasMemory,
+    technicalSeed: hasSeedIndex,
+    workingContext: hasWorkingContext,
+    activeChanges
+  }
+  if (asJson) {
+    console.log(JSON.stringify({ ok: true, cliVersion: currentVersion, ...info }, null, 2))
+    return
+  }
+  console.log(`${c.bold((abs.split(/[\\/]/).filter(Boolean).pop() || abs))} ${c.dim(info.path)}`)
+  console.log('')
+  console.log(`  versión      ${info.outdated ? c.red(`${info.version} → ${currentVersion} disponible`) : c.green(info.version || '—')}`)
+  console.log(`  instalación  ${info.scoped ? c.green('por proyecto (scoped)') : c.yellow('agentes globales')}`)
+  console.log(`  tier / agente ${info.tier || c.dim('—')} / ${info.agent || '—'}`)
+  console.log(`  Azure DevOps ${info.azureEnabled ? c.green('habilitado') : c.dim('deshabilitado')}`)
+  console.log(`  memoria      ${info.memoryDb ? c.green('sí (.ancleto/memory.db)') : c.dim('no')}`)
+  console.log(`  seed técnico ${info.technicalSeed ? c.green('generado') : c.dim('sin generar')}`)
+  console.log(`  changes      ${info.activeChanges > 0 ? c.cyan(`${info.activeChanges} activo(s)`) : c.dim('ninguno')}`)
+  if (info.outdated) console.log(c.dim(`\n  actualizá con: cd "${info.path}" && ancleto update`))
+}
+
+async function projectsCommand(args) {
+  const sub = args.find((a) => !a.startsWith('-')) || 'list'
+  const flags = args.filter((a) => a.startsWith('-'))
+  const asJson = flags.includes('--json')
+  const dryRun = flags.includes('--dry-run')
+  const currentVersion = await packageVersion()
+  switch (sub) {
+    case 'list': {
+      await projectsList(await readProjectsRegistry(), { asJson, currentVersion })
+      break
+    }
+    case 'scan': {
+      const idx = args.indexOf('scan')
+      const root = args[idx + 1] && !args[idx + 1].startsWith('-') ? args[idx + 1] : null
+      await projectsScan(root, { asJson, dryRun })
+      break
+    }
+    case 'prune': {
+      await projectsPrune({ asJson, dryRun })
+      break
+    }
+    case 'info': {
+      const idx = args.indexOf('info')
+      const target = args[idx + 1] && !args[idx + 1].startsWith('-') ? args[idx + 1] : null
+      await projectsInfo(target, { asJson, currentVersion })
+      break
+    }
+    default:
+      console.error(`ancleto: subcomando desconocido: projects ${sub}`)
+      console.error('ancleto: uso: ancleto projects [list|scan <raiz>|prune|info <ruta>] [--json] [--dry-run]')
+      process.exit(1)
+  }
+}
+
+
 function binName(base) {
   return process.platform === 'win32' ? `${base}.exe` : base
 }
@@ -490,6 +797,8 @@ async function install(args) {
   await applyTier(join(target, 'agents'), tier, models)
   await writeFile(tierStatePath(target), tier + '\n')
 
+  if (projectDir) await registerProject(projectDir, { agent, tier })
+
   let azureMcp = false
   if (projectDir && withMcp) {
     const rc = await readAncletorc(projectDir)
@@ -587,6 +896,7 @@ async function initProject(args) {
   await copyTemplates(projectDir)
   await scaffoldAspec(projectDir)
   await refreshWorkingContext(projectDir)
+  await registerProject(projectDir, { agent, tier: tier || null })
   if (azure.enabled) console.log(AZURE_MCP_NOTICE)
   console.log(`ancleto: .ancletorc actualizado en ${projectDir} (v${manifest.version})${azure.enabled ? ' (Azure habilitado)' : ' (Azure desactivado)'} (Agente: ${agent})${tier ? ` (Tier: ${tier})` : ''}`)
 }
@@ -1054,6 +1364,240 @@ async function specsCheckCommand(args) {
   process.exit(ok ? 0 : 1)
 }
 
+function opencodeDbPath() {
+  return process.env.ANCLETO_OPENCODE_DB || join(homedir(), '.local', 'share', 'opencode', 'opencode.db')
+}
+
+function fmtTokens(n) {
+  if (!n) return '0'
+  if (n >= 1e9) return `${(n / 1e9).toFixed(2)}B`
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`
+  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}k`
+  return String(n)
+}
+
+function fmtCost(c) {
+  return c && c < 0.01 ? `$${c.toFixed(4)}` : `$${(c || 0).toFixed(2)}`
+}
+
+function fmtDate(ms) {
+  const d = new Date(ms || 0)
+  const p = (x) => String(x).padStart(2, '0')
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`
+}
+
+const normPath = (p) => String(p || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase()
+
+function sessionModel(model) {
+  try {
+    const m = JSON.parse(model || '{}')
+    return m.id ? `${m.id}${m.providerID ? ` (${m.providerID})` : ''}` : ''
+  } catch {
+    return ''
+  }
+}
+
+function buildSessionTree(sessions) {
+  const byId = new Map(sessions.map((s) => [s.id, s]))
+  const children = new Map()
+  for (const s of sessions) {
+    if (!s.parent_id) continue
+    if (!children.has(s.parent_id)) children.set(s.parent_id, [])
+    children.get(s.parent_id).push(s)
+  }
+  const cache = new Map()
+  const totalsOf = (id) => {
+    if (cache.has(id)) return cache.get(id)
+    const own = byId.get(id)
+    const t = {
+      input: own?.tokens_input || 0,
+      output: own?.tokens_output || 0,
+      reasoning: own?.tokens_reasoning || 0,
+      cacheRead: own?.tokens_cache_read || 0,
+      cacheWrite: own?.tokens_cache_write || 0,
+      cost: own?.cost || 0,
+      sessions: own ? 1 : 0
+    }
+    for (const c of children.get(id) || []) {
+      const ct = totalsOf(c.id)
+      t.input += ct.input
+      t.output += ct.output
+      t.reasoning += ct.reasoning
+      t.cacheRead += ct.cacheRead
+      t.cacheWrite += ct.cacheWrite
+      t.cost += ct.cost
+      t.sessions += ct.sessions
+    }
+    cache.set(id, t)
+    return t
+  }
+  const subtreeIds = (id) => [id, ...(children.get(id) || []).flatMap((c) => subtreeIds(c.id))]
+  return { byId, totalsOf, subtreeIds }
+}
+
+function sessionInfo(s, totals) {
+  return {
+    id: s.id,
+    title: s.title || null,
+    agent: s.agent || null,
+    model: sessionModel(s.model) || null,
+    subagentSessions: Math.max(0, totals.sessions - 1),
+    timeCreated: s.time_created || null,
+    timeUpdated: s.time_updated || null,
+    cost: totals.cost,
+    tokens: {
+      input: totals.input,
+      output: totals.output,
+      reasoning: totals.reasoning,
+      cacheRead: totals.cacheRead,
+      cacheWrite: totals.cacheWrite
+    }
+  }
+}
+
+async function statsCommand(args) {
+  const asJson = args.includes('--json')
+  const all = args.includes('--all')
+  const si = args.indexOf('--session')
+  const sessionId = si >= 0 ? args[si + 1] : null
+  const li = args.indexOf('--limit')
+  const limit = li >= 0 ? Number.parseInt(args[li + 1], 10) : 10
+  if (li >= 0 && (!Number.isFinite(limit) || limit < 1)) {
+    console.error('ancleto: --limit requiere un entero >= 1')
+    process.exit(1)
+  }
+  const sinceIdx = args.indexOf('--since')
+  const sinceRaw = sinceIdx >= 0 ? args[sinceIdx + 1] : null
+  let since = null
+  if (sinceRaw) {
+    const t = Date.parse(`${sinceRaw}T00:00:00`)
+    if (Number.isNaN(t)) {
+      console.error('ancleto: --since requiere formato YYYY-MM-DD')
+      process.exit(1)
+    }
+    since = t
+  }
+
+  const dbPath = opencodeDbPath()
+  if (!(await exists(dbPath))) {
+    console.error(`ancleto: no se encontro la base de sesiones de opencode en ${dbPath}`)
+    console.error('ancleto: ancleto stats solo funciona con opencode (podes apuntar ANCLETO_OPENCODE_DB a la base)')
+    process.exit(1)
+  }
+  const db = new DatabaseSync(dbPath, { readOnly: true })
+  let allSessions
+  try {
+    allSessions = db.prepare('SELECT * FROM session').all()
+  } catch (err) {
+    console.error(`ancleto: no se pudo leer la base de sesiones: ${err.message}`)
+    process.exit(1)
+  }
+  const tree = buildSessionTree(allSessions)
+  const cwd = process.cwd()
+
+  if (sessionId) {
+    const root = tree.byId.get(sessionId)
+    if (!root) {
+      console.error(`ancleto: no existe la sesion "${sessionId}"`)
+      process.exit(1)
+    }
+    const ids = tree.subtreeIds(sessionId)
+    let messages = []
+    try {
+      messages = db.prepare(`SELECT data FROM message WHERE session_id IN (${ids.map(() => '?').join(',')})`).all(...ids)
+    } catch {
+      messages = []
+    }
+    const byAgent = new Map()
+    for (const row of messages) {
+      let d
+      try {
+        d = JSON.parse(row.data)
+      } catch {
+        continue
+      }
+      if (d.role !== 'assistant' || !d.tokens) continue
+      const key = d.agent || '(desconocido)'
+      const agg = byAgent.get(key) || { agent: key, messages: 0, input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0 }
+      agg.messages++
+      agg.input += d.tokens.input || 0
+      agg.output += d.tokens.output || 0
+      agg.reasoning += d.tokens.reasoning || 0
+      agg.cacheRead += d.tokens.cache?.read || 0
+      agg.cacheWrite += d.tokens.cache?.write || 0
+      byAgent.set(key, agg)
+    }
+    const agents = [...byAgent.values()].sort((a, b) => b.input - a.input)
+    const totals = tree.totalsOf(sessionId)
+    db.close()
+    if (asJson) {
+      console.log(JSON.stringify({ ok: true, scope: 'session', session: sessionInfo(root, totals), byAgent: agents, totals }, null, 2))
+      return
+    }
+    console.log(`ancleto: sesion ${root.id}`)
+    console.log(`  titulo: ${root.title || '(sin titulo)'}`)
+    console.log(`  agente: ${root.agent || '-'} · modelo: ${sessionModel(root.model) || '-'}`)
+    console.log(`  creada: ${fmtDate(root.time_created)} · ultima actividad: ${fmtDate(root.time_updated)}`)
+    console.log(`  sesiones incluidas: ${totals.sessions} (raiz + subagentes)`)
+    console.log('')
+    console.log('  agente        mensajes   entrada   salida    razon     cache-read')
+    for (const a of agents) {
+      console.log(`  ${String(a.agent).padEnd(13)} ${String(a.messages).padEnd(10)} ${fmtTokens(a.input).padEnd(9)} ${fmtTokens(a.output).padEnd(9)} ${fmtTokens(a.reasoning).padEnd(9)} ${fmtTokens(a.cacheRead)}`)
+    }
+    console.log('')
+    console.log(`  totales: entrada ${fmtTokens(totals.input)} · salida ${fmtTokens(totals.output)} · razon ${fmtTokens(totals.reasoning)} · cache ${fmtTokens(totals.cacheRead)} · costo ${fmtCost(totals.cost)}`)
+    return
+  }
+
+  let roots = allSessions.filter((s) => !s.parent_id)
+  let scope = 'all'
+  if (!all) {
+    scope = 'directory'
+    const cwdN = normPath(cwd)
+    const inDir = (d) => {
+      const dn = normPath(d)
+      return dn === cwdN || dn.startsWith(`${cwdN}/`) || cwdN.startsWith(`${dn}/`)
+    }
+    roots = roots.filter((s) => inDir(s.directory))
+  }
+  if (since !== null) roots = roots.filter((s) => (s.time_created || 0) >= since)
+  roots.sort((a, b) => (b.time_updated || 0) - (a.time_updated || 0))
+  const shown = roots.slice(0, limit)
+  const rows = shown.map((s) => ({ ...sessionInfo(s, tree.totalsOf(s.id)), directory: s.directory }))
+  const totals = rows.reduce(
+    (acc, r) => {
+      acc.input += r.tokens.input
+      acc.output += r.tokens.output
+      acc.reasoning += r.tokens.reasoning
+      acc.cacheRead += r.tokens.cacheRead
+      acc.cacheWrite += r.tokens.cacheWrite
+      acc.cost += r.cost
+      return acc
+    },
+    { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0, cost: 0 }
+  )
+  db.close()
+
+  if (asJson) {
+    console.log(JSON.stringify({ ok: true, scope, directory: scope === 'directory' ? cwd.replace(/\\/g, '/') : null, since: sinceRaw || null, sessions: rows, totals }, null, 2))
+    return
+  }
+  if (rows.length === 0) {
+    console.log(`ancleto: no hay sesiones${scope === 'directory' ? ' para este directorio' : ''}${sinceRaw ? ` desde ${sinceRaw}` : ''}`)
+    if (scope === 'directory') console.log('ancleto: proba --all para ver todas las sesiones de la maquina')
+    return
+  }
+  console.log(`ancleto: stats (opencode)${scope === 'directory' ? ` — ${cwd.replace(/\\/g, '/')}` : ' — todas las sesiones'}${sinceRaw ? ` — desde ${sinceRaw}` : ''}`)
+  console.log('')
+  console.log('  fecha              agente        entrada   salida    razon     cache     costo    titulo')
+  for (const r of rows) {
+    console.log(`  ${fmtDate(r.timeUpdated).padEnd(18)} ${String(r.agent || '-').padEnd(13)} ${fmtTokens(r.tokens.input).padEnd(9)} ${fmtTokens(r.tokens.output).padEnd(9)} ${fmtTokens(r.tokens.reasoning).padEnd(9)} ${fmtTokens(r.tokens.cacheRead).padEnd(9)} ${fmtCost(r.cost).padEnd(8)} ${String(r.title || '').slice(0, 42)}`)
+  }
+  console.log('')
+  const shownLabel = roots.length > rows.length ? `${rows.length} de ${roots.length} sesiones` : rows.length === 1 ? '1 sesion' : `${rows.length} sesiones`
+  console.log(`  totales (${shownLabel}): entrada ${fmtTokens(totals.input)} · salida ${fmtTokens(totals.output)} · razon ${fmtTokens(totals.reasoning)} · cache ${fmtTokens(totals.cacheRead)} · costo ${fmtCost(totals.cost)}`)
+}
+
 async function doctorCommand() {
   let fatal = false
 
@@ -1122,6 +1666,20 @@ switch (cmd) {
   case 'specs':
     await specsCheckCommand(rest)
     break
+  case 'stats':
+    await statsCommand(rest)
+    break
+  case 'projects':
+    await projectsCommand(rest)
+    break
+  case 'list':
+    // Alias conveniente: `ancleto list --projects`
+    if (rest.includes('--projects')) await projectsCommand(rest.filter((a) => a !== '--projects'))
+    else {
+      console.error('ancleto: uso: ancleto list --projects [--json]  (o ancleto projects)')
+      process.exit(1)
+    }
+    break
   case 'doctor':
     await doctorCommand()
     break