Diagnóstico y rastro

Cuando un comando afirma algo que no te cuadra, el desacuerdo casi nunca es la regla: es qué carpeta o qué valor leyó. kbspec deja rastro en cuatro capas.

El caso típico, resuelto en orden

«kb listo dice que el 02 no está aprobado — ¡y yo lo veo aprobado!»

1. Mirá la ruta que resolvió. kb listo imprime siempre Expediente: <ruta completa> — y avisa si esa carpeta está fuera del repositorio de documentación en uso. La causa número uno es una sesión vieja apuntando a otro expediente (u otra ventana).

2. Pedí la evidencia. KB_DEBUG=1 kb listo muestra por stderr qué archivo y qué valor leyó cada chequeo:

   » listo · expediente=/…/REQ-4471-perfiles
   » listo · 02.aprobado_por=None · 00.sistemas=['APP-WEB']

   aprobado_por=None cierra la discusión en un segundo: el campo del frontmatter está vacío, aunque el texto del documento diga «aprobado».

3. Revisá el historial. Cada corrida queda en ~/.kb/log/kb.log.

4. Si fue desde el panel, abrí el canal (abajo).

El tablero o el Pull Request no responden

«Al iniciar leyó la tarea sin problema; a la hora del PR no puede actualizar las sub tareas ni crear el PR.»

No adivines —ni az login, ni el MCP, ni el navegador—. Tres comandos, en orden:

kb integracion probar          # ✓/✗/⚠ paso por paso, con la corrección al lado
kb integracion credenciales    # qué fuente de credencial hay y por qué no sirve
kb integracion log             # cada llamada: organización, ruta, estado, credencial, ms

probar recorre lo que el ciclo necesita: quién sos en cada organización, el proyecto, los tipos y estados, el permiso de escribir work items en el área, el work item de la sesión y en qué proyecto vive; y por cada repositorio: la credencial de git, el repositorio en el proyecto del código, los permisos efectivos de leer, push, crear ramas y crear Pull Requests —son permisos distintos, y es la razón habitual de «el push anda y el PR no»—, los revisores y el enlace work item ↔ PR. --escribir crea, modifica y borra una sub tarea de prueba. Lo habitual para arreglarlo: kb tablero login una vez (queda guardado y se renueva solo). La bitácora vive en ~/.kb/log/integraciones.jsonl y no guarda secretos.

Cuando el consumo sale en cero

El consumo pasa por cuatro manos —Copilot lo escribe, --registrar lo reclama, el ledger del expediente lo guarda, la tarifa lo cuesta— y cuando no aparece, el síntoma de las cuatro es el mismo: un cero. Y Copilot lo escribe en dos lugares: el chat de VS Code en agent-traces.db y la ventana de agentes en ~/.copilot/session-store.db; quien trabaja solo en la ventana de agentes no tiene nada en la primera, y el diagnóstico pregunta por las dos.

kb tokens --diagnostico

Recorre la cadena y dice dónde se cortó. Delata en particular dos cosas invisibles: un modelo con llamadas pero sin tokens (se ve idéntico a «no se usó ese modelo» y explica un panel vacío), y un span renombrado por una versión nueva de Copilot, que deja a kbspec sin ver nada y sin dar un solo error.

Las cuatro capas

Rastro	Dónde	Qué guarda
Log del framework	~/.kb/log/kb.log (rota a 1 MB)	Cada corrida: comando, cwd, KB_DOCS_ROOT, sesión resuelta, código de salida, duración
Evidencia en vivo	KB_DEBUG=1 kb <comando>	Qué archivo y qué valor leyó cada chequeo, por stderr, en el momento
Canal del panel	VS Code → Ver → Salida → kbspec	Toda llamada del panel que falla (comando, código, stderr). Con kbspec.rastro: true, también las exitosas con duración. El comando kbspec: diagnóstico vuelca además el entorno del proceso — que no es el de tu terminal
Bitácora del expediente	auditoria.jsonl · kb auditoria	Los hechos de negocio, encadenados por hash. Es el registro del trabajo, no un log de errores

Diseño

Los refrescos exitosos del panel no ensucian el log (corren cada pocos segundos); sus fallos sí quedan. Y el rastro jamás rompe un comando: si el disco falla, el diagnóstico se calla — nunca al revés.

El panel se queda «leyendo»

Desde 3.152.1 no puede quedarse así para siempre: cada proceso kb tiene tope de tiempo (120 s el panel, 60 s el resto) y, si se cuelga, el árbol dice qué comando no respondió; un error al pintar se muestra en vez de tragarse. Para ver qué parte es la lenta:

1. Ver → Salida → kbspec. Ahí queda · kb panel por partes: estado 120 ms · validar 900 ms · ramas 4000 ms … cuando algo pasa de 3 s, y cualquier kb que tarde más de 5 s. Con kbspec.rastro: true se anota todo, siempre.
2. En una terminal, con la carpeta del código abierta: kb panel --json (en PowerShell, Measure-Command { kb panel --json | Out-Null }). Si se cuelga, Ctrl+C imprime la pila de Python con la carpeta o el comando donde esperaba. kb check y kb tokens --diagnostico dicen qué rutas está leyendo.
3. Dónde vive el código. Sin code_root en ~/.kb/config ni KB_CODE_ROOT, kbspec sube por las carpetas buscando los proyectos del inventario; en una unidad de red o con OneDrive eso es lento. La búsqueda tiene tope (4.000 comprobaciones o 3 s) y kb apps --json dice raiz_acotada: true cuando lo alcanzó: fijala con kb instalar o con KB_CODE_ROOT.

Al activarse, la extensión lanza un proceso (kb panel): el contrato, el inventario y la sesión en vivo vienen en esa misma respuesta. El paquete npm lanza kb_main.py, que importa el módulo y usa el .pyc: python kb.py compilaba 38.000 líneas en cada llamada.