@zaip-ai/cli 0.1.0 → 1.0.1

package/templates/.agents/skills/zaip-skill-move-spec/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: zaip-skill-move-spec
+description: Explicitly move, cancel, execute, or deliver a ZAIP SPEC while keeping descendant Tasks, Changes, and Executions lifecycle-consistent. Use only when a user asks to move a SPEC between dashboard columns, execute it, cancel or finalize it, or repair Tasks left behind by a SPEC status change.
+---
+
+# Mover SPEC com descendentes
+
+Use apenas comandos canônicos ZAIP. Não edite status diretamente no frontmatter nem mova arquivos de lifecycle manualmente.
+
+## Exigir autoridade explícita
+
+1. Criação, revisão, aprovação de conteúdo, refinamento, planejamento e `prepare` não autorizam movimento.
+2. Sem pedido explícito de movimento ou execução, mantenha SPEC `draft` em Planejamento e encerre o trabalho.
+3. Não trate “está pronta”, “aprovada” ou ausência de pendências como comando de promoção sem verbo de ação dirigido ao lifecycle.
+
+## Identificar o movimento
+
+1. Resolva a SPEC por ID e inspecione seu estado com `node .zaip-aios/bin/zaip.mjs spec show <SPEC-ID> --json`.
+2. Trate “finalizar”, “concluir” e “entregar” como `deliver`; trate “cancelar” e “abandonar” como `cancel`.
+3. Trate “mova/coloque em Pronto para Executar” como `spec ready`. Trate “execute/inicie a execução” como autorização para preparar, se necessário, e então usar `spec execute`.
+
+## Aplicar a política parental
+
+- `spec cancel <SPEC-ID>` cancela a SPEC e, pela lógica do framework, todas as Tasks, Changes e Executions descendentes ainda abertas.
+- Descendentes já `completed`, `failed` ou `cancelled` permanecem imutáveis.
+- `spec deliver <SPEC-ID>` só entrega após os gates provarem conclusão das Tasks, Changes, Executions, Runs, Acceptance Criteria e Evidences. Nunca marque Tasks incompletas como concluídas.
+- `spec prepare <SPEC-ID> --plan <plano>` valida e persiste o plano, mas preserva `draft` e a coluna Planejamento.
+- `spec ready <SPEC-ID>` exige PreparedPlan e move somente a SPEC para `ready`.
+- `spec execute <SPEC-ID>` materializa seu PreparedPlan; um pedido explícito de execução permite esse caminho a partir de `draft` preparado, e uma SPEC governada pelo plano global de um PRD não cria uma Execution duplicada.
+- Não altere o PRD pai ao mover apenas uma SPEC.
+
+## Verificar
+
+1. Leia novamente a SPEC após o comando.
+2. Após `prepare`, confirme que a SPEC continua `draft`; após `ready`, confirme que somente ela ficou `ready`.
+3. Confirme no resultado do cancelamento os arrays `cascade.tasks`, `cascade.changes` e `cascade.executions`.
+4. Verifique que SPECs irmãs e suas Tasks não mudaram.
+5. Se uma Task aberta permanecer fora da cascata, pare e reporte vínculo quebrado; não a associe por título.

package/templates/.agents/skills/zaip-skill-move-spec/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP Move SPEC"
+  short_description: "Promova SPECs somente com pedido explícito."
+  default_prompt: "Use $zaip-skill-move-spec para mover esta SPEC somente conforme minha solicitação explícita de lifecycle."

package/templates/.agents/skills/zaip-skill-navigate-work/SKILL.md

@@ -1,13 +1,16 @@
 ---
 name: zaip-skill-navigate-work
-description: Locate, filter, compare, inspect, and refine pending ZAIP PRDs, SPECs, Changes, Tasks, Executions, and Runs without accidentally starting execution.
+description: Navigate and refine pending ZAIP work without starting execution.
 ---
 
 # Navegar pelo trabalho
 
-1. Liste artefatos por tipo, estado, data, relação, risco e custo sem carregar o conteúdo completo.
-2. Mostre a cadeia de relações e um resumo macro antes de abrir detalhes.
-3. Diferencie claramente `draft`, `prepared`, `executing`, `blocked`, `verifying`, `completed` e `cancelled`.
-4. Permita refinar ou comparar PRDs/SPECs pendentes sem criar Tasks, Changes, Executions ou Runs.
-5. Ao selecionar trabalho, carregue apenas artefato ativo, Requirements/AC, Rules, código e testes diretamente relacionados.
+1. Comece por listagem compacta de metadados; nunca carregue corpos ou JSONL de todas as entidades.
+2. Filtre por `--status`, `--from`, `--to`, `--prd`, `--spec` ou `--task`; use `--limit` e continue com `--after <ID>`. Use `--all` apenas quando realmente necessário.
+3. O `index` retorna um `schema` e linhas compactas; `work_relations` contém até dois vínculos de lifecycle para navegação inicial. Abra `summary` para relações completas, preparação, custo, Requirements e ACs; use `show` depois de selecionar um ID.
+4. Diferencie lifecycle persistido de coluna: PRD `draft` fica em Definição, SPEC `draft` em Planejamento, Task avulsa `draft|planned` em Pronto para Executar, e `executing|verifying|completed|blocked|failed|cancelled` seguem suas colunas homônimas.
+5. Resolva a cadeia de relações e a visão macro antes de abrir detalhes.
+6. Ao selecionar um ID, carregue somente artefato ativo, Requirements/AC, Rules, decisões, código e testes relacionados.
+7. Permita comparar/refinar PRDs, SPECs e Tasks pendentes sem executar. Listar, mostrar ou revisar nunca implica `execute`.
 
+Exemplo: `zaip spec list --prd <PRD-ID> --status draft,ready --limit 25 --json`.

package/templates/.agents/skills/zaip-skill-navigate-work/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "ZAIP Work Navigator"
-  short_description: "Navigate and select pending work"
-  default_prompt: "Use $zaip-skill-navigate-work to locate and refine pending work without starting execution."
+  display_name: "Navigate ZAIP Work"
+  short_description: "Find and refine pending work without executing it."
+  default_prompt: "Use $zaip-skill-navigate-work to filter and inspect pending ZAIP work without starting execution."

package/templates/.agents/skills/zaip-skill-observability/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: zaip-skill-observability
+description: Inspect ZAIP Runs, tokens, costs, rework, coverage, and macro aggregates.
+---
+
+# Analisar uso e custo
+
+Escolha um modo: `record`, `analyze` ou `reconcile`.
+
+## Record
+
+1. Todo turno deve possuir Run, mas somente trabalho executável possui Task. Pergunta read-only ou classificação incerta usa `phase: conversation`, `entrypoint: conversation` e `task_id: null`; continuação/refinamento/rework reutiliza o alvo da mesma thread. Quando virar trabalho novo, feche essa Run e abra outra com o mesmo `CONV-*` e o novo escopo. Tentativa iniciada por `execute` usa `execution` e exige `EXEC-*`, mesmo sem diff.
+2. Preserve `new` ou `rework`, entrada (`task`, `spec`, `prd`) e somente IDs ancestrais conhecidos. Não invente PRD/SPEC para Task-first nem atribua Change/Execution antes da materialização.
+3. Registre segmentos com `zaip run usage <RUN-ID> --phase ... --activity ...`. O timestamp da fonte é automático; informe `--initial-pack-tokens`, `--tool-output-tokens`, `--files-opened` e `--snippets-opened` quando disponíveis. Ausência de token/preço permanece `null`.
+4. Finalize toda Run e Sub-Run com status técnico `--status completed|failed|cancelled`. A Run raiz de Task aguarda o Sub-Run finalizador e então aplica `--task-outcome completed|blocked|failed|cancelled`; o status técnico pode ser `completed` enquanto gates insuficientes deixam a Task `blocked`.
+5. Classifique pela hierarquia e propósito: Run raiz tem `parent_run_id: null` e `run_purpose: orchestration`; Sub-Run possui pai e usa `execution`, `review`, `audit` ou `finalization`. Cada chamada de agente fixa agente, modelo e effort até terminar. Calls e ferramentas são eventos internos; quando observáveis, suas quantidades, resultados, tokens e custos são agregados na Run/Sub-Run, sem `CallProjection` ou tela própria.
+
+## Analyze e reconcile
+
+1. Filtre primeiro com `zaip run list --prd|--spec|--task|--execution|--change ... --status ... --from ... --to ... --limit ...`; use `run show` apenas nas Runs selecionadas.
+2. Agregue sem dupla contagem com `zaip run aggregate` e o mesmo filtro de escopo. Task soma Runs atribuídas; SPEC e PRD somam descendentes identificados.
+3. Exponha conversa, planejamento, execução, total, `new/rework`, cobertura de tokens e cobertura de preço. Compare resultado, duração, tentativas, AC/evidência e assertividade junto do custo.
+4. Reconcilie a mesma semântica no dashboard/Kanban e Zaip Cost Monitor, incluindo abas e contagens separadas de Runs e Sub-Runs, finalizadores, identidade `zaip-agent-*`, modelo/effort planejados, configuração efetiva, Calls conhecidas, tokens por segmento e concentração top-10. Divergência é finding; não injete JSONL bruto nem crie índice de conteúdo persistente. As projeções lifecycle descartáveis em `.agents/projections/runtime` são autorizadas.
+5. Reconciliação de telemetria pode ser auditada separadamente; reconciliação global de lifecycle só roda pelo popup confirmado ou por comando humano explícito. Nunca adicione varredura por turno, intervalo ou abertura do dashboard.

package/templates/.agents/skills/zaip-skill-observability/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP Observability"
+  short_description: "Analyze Runs, tokens, costs, rework, and coverage."
+  default_prompt: "Use $zaip-skill-observability to reconcile phase-aware usage and macro costs for Tasks, SPECs, and PRDs."

package/templates/.agents/skills/zaip-skill-openai-docs/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: zaip-skill-openai-docs
+description: Answer questions about OpenAI APIs, models, SDKs, Agents SDK, Responses API, Realtime API, Apps SDK, Codex, MCP, authentication, limits, or migrations using current official OpenAI documentation. Use whenever a user asks how an OpenAI product works, requests implementation guidance, compares current OpenAI capabilities, or needs exact API fields and citations.
+---
+
+# Consultar documentacao oficial OpenAI
+
+1. Para OpenAI API e produtos, use primeiro as tools do MCP `openaiDeveloperDocs`; nao responda apenas por memoria.
+2. Pesquise com consulta curta, selecione o resultado oficial mais relevante e leia a pagina antes de responder.
+3. Para campos, parametros e schemas, consulte tambem a referencia/OpenAPI oficial quando a tool estiver disponivel.
+4. Para Codex, configuração, MCP, skills, plugins ou comportamento das superficies, prefira o manual oficial do Codex; use o Docs MCP para lacunas especificas.
+5. Cite links oficiais usados e diferencie fato documentado, inferencia e comportamento observado localmente.
+6. Se o MCP estiver indisponivel, informe a limitacao e use somente fallback em `developers.openai.com` ou `platform.openai.com`.
+7. Nunca invente modelo, parametro, limite, preço, disponibilidade ou comportamento.
+8. Pedidos de implementacao podem exigir `OPENAI_API_KEY`, mas consultas de documentacao nao exigem chave. Nunca peça que a chave seja colada no chat.
+
+Leia `references/routing.md` apenas quando houver duvida sobre a fonte correta.

package/templates/.agents/skills/zaip-skill-openai-docs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP OpenAI Docs"
+  short_description: "Consulte documentação oficial OpenAI via MCP"
+  default_prompt: "Use $zaip-skill-openai-docs para responder esta pergunta com a documentação oficial da OpenAI."

package/templates/.agents/skills/zaip-skill-openai-docs/references/routing.md

@@ -0,0 +1,11 @@
+# Roteamento de fontes
+
+| Pergunta | Fonte primaria |
+|---|---|
+| Responses, Realtime, Agents ou Apps SDK | OpenAI Developer Docs MCP |
+| Campo ou parametro exato | OpenAPI/referencia oficial via MCP |
+| Modelo atual ou migracao | Guia oficial de modelos e migracao |
+| Codex, config.toml, MCP, skills ou plugins | Manual oficial do Codex |
+| Falha do MCP | developers.openai.com; depois platform.openai.com |
+
+Nao use blogs, snippets ou memoria como fonte autoritativa quando a documentacao oficial estiver disponivel.

package/templates/.agents/skills/zaip-skill-prd/SKILL.md

@@ -1,13 +1,44 @@
 ---
 name: zaip-skill-prd
-description: Create, compare, refine, prepare, execute, and analyze optional ZAIP PRDs that translate business outcomes into one or more delivery SPECs and task DAGs.
+description: Create, refine, prepare, and analyze ZAIP PRDs that map business outcomes to SPECs and Task DAGs while preserving draft status until the user explicitly requests ready or execution.
 ---
 
 # Trabalhar com PRDs
 
-1. Explore objetivos, usuários, valor, métricas, restrições, hipóteses e riscos sem executar nada.
-2. Permita múltiplos PRDs pendentes; refine somente os escolhidos e marque descarte/adiamento sem materializar Tasks.
-3. Decomponha o PRD selecionado em uma ou mais SPECs técnicas, Requirements/AC e uma DAG global.
-4. Use `prepare` para validar e persistir o plano; só use `execute` após autorização explícita.
-5. Mostre visão macro por PRD: SPECs, Tasks, Executions, Runs, assertividade, retrabalho, tokens, custo e cobertura por fase.
+PRD é opcional e permanece em Definição com `status: draft` durante criação, revisão, refinamento e `prepare`. Ter SPECs ou PreparedPlan válido não autoriza promoção.
 
+## Limite de autoridade
+
+1. Não invoque `prd ready`, `prd execute` ou `prd activate` por inferência, conveniência ou conclusão do conteúdo.
+2. Pedido para criar, revisar, aprovar conteúdo, refinar, planejar ou preparar preserva `draft`.
+3. Somente pedido explícito para mover a “Pronto para Executar” delega a promoção para `$zaip-skill-move-prd`.
+4. Somente pedido explícito para executar delega preparação necessária e execução para `$zaip-skill-execution`.
+
+## Create e refine
+
+1. Registre problema, usuários, valor, outcomes mensuráveis, restrições, hipóteses, riscos e não objetivos sem executar nada.
+2. Mantenha o PRD agnóstico de linguagem, framework, banco, infraestrutura e fornecedor. Uma tecnologia só aparece quando for restrição externa real de negócio, regulação ou compatibilidade contratual; registre-a como restrição, não como desenho da solução.
+3. Permita múltiplos PRDs pendentes; compare por valor, risco, custo e evidência, e refine somente os escolhidos.
+4. Crie uma ou mais SPECs técnicas ligadas ao PRD quando solicitado. PRD e SPECs novas continuam em `draft`; cada Change planejada deve pertencer exatamente a uma dessas SPECs.
+5. Não crie Tasks, Changes, Executions ou Runs de execução durante conversa/refinamento; telemetria de conversation/planning pode registrar o uso sem torná-lo executável.
+6. Para refine Git-native, edite somente o arquivo canônico retornado pelo create enquanto `status: draft`; preserve ID/`created_at`, incremente `revision`, atualize `updated_at` e valide com `zaip prd show <ID>`. Não use `prepare` como encerramento automático da criação. Depois de `ready`, não faça patch manual: gere nova revisão do plano antes da execução ou rework após materialização.
+
+Durante essa etapa, a Execution universal `interaction` e sua Run raiz continuam obrigatórias para telemetria e rastreabilidade; a proibição acima refere-se somente a Execution `delivery` e a Runs de execução.
+
+## Prepare
+
+1. Bloqueie PRD sem SPEC, SPEC de outro PRD, referência quebrada, AC vago, DAG cíclica ou write scopes concorrentes.
+2. Construa uma DAG global que pode atravessar SPECs e inclua integração/gates como dependências explícitas.
+3. Gere e valide o PreparedPlan conforme [o contrato compacto](../zaip-skill-execution/references/prepared-plan.md), persista-o e pré-aloque IDs sem materializar trabalho executável nem mudar `draft` para `ready`.
+4. Após `prepare`, mostre que o PRD continua em Definição e pare; não encadeie `prd ready` ou `prd execute` sem a solicitação explícita correspondente.
+
+## Handoff e analyze
+
+1. Pare em Definição após `prepare`. Somente após pedido explícito de promoção, use `$zaip-skill-move-prd`; somente após pedido explícito de execução, delegue materialização, ativação e orquestração para `$zaip-skill-execution`.
+2. Na análise, mostre visão macro por PRD: SPECs, Tasks, Executions, Runs, outcomes, AC/evidência, retrabalho, tokens e custo por fase/total.
+
+## Assurance de outcomes
+
+1. Antes de entregar um PRD, construa a matriz parental completa de ACs e outcomes e produza pelo menos três validações e três Evidences próprias.
+2. As modalidades mínimas são cross-SPEC E2E, spec review e quality review por autor/Run independente, todas no commit final esperado.
+3. Cada outcome possui Evidence explícita. SPECs e Tasks aprovadas são pré-condições, não substitutos para a prova de integração e de resultado no nível do PRD.

package/templates/.agents/skills/zaip-skill-prd/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "ZAIP PRD"
-  short_description: "Plan and refine optional ZAIP PRDs"
-  default_prompt: "Use $zaip-skill-prd to create, refine, or prepare an optional PRD without starting execution."
+  short_description: "Crie PRDs sem promover antes da autorização."
+  default_prompt: "Use $zaip-skill-prd para criar ou preparar um PRD e mantê-lo em draft até eu pedir promoção ou execução."

package/templates/.agents/skills/zaip-skill-preview/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: zaip-skill-preview
+description: Discover, start, inspect, and stop local frontend or dashboard previews safely.
+---
+
+# Abrir preview local
+
+1. Identifique a superfície pedida: produto em `apps/frontend`, site público em `apps/site` ou dashboard em `.agents/dashboard`.
+2. Descubra package manager, workspace, script e variáveis pelo repositório; não assuma path pessoal, porta fixa ou comando legado.
+3. Reuse servidor saudável somente após confirmar processo, workspace e superfície. Caso contrário, escolha loopback e porta livre, inicie o processo oculto e registre PID/comando.
+4. Aguarde por health polling com timeout curto; não use sleep cego.
+5. Abra a URL com o browser disponível e verifique renderização, console, rede e acessibilidade relevantes ao pedido.
+6. Mantenha frontend, site e dashboard isolados; o site não importa dashboard e o dashboard continua local/read-only.
+7. Se o usuário pediu para abrir, mantenha o servidor disponível. Encerre somente em falha, preview efêmero ou pedido `stop`, e apenas pelo PID iniciado por esta execução.
+
+Preview não autoriza deploy nem mudanças de código. Se a inspeção revelar defeito, proponha uma Task ou execute somente com pedido explícito.

package/templates/.agents/skills/zaip-skill-preview/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP Preview"
+  short_description: "Discover and preview frontend, site, or dashboard locally."
+  default_prompt: "Use $zaip-skill-preview to discover, start, health-check, and inspect a local frontend, site, or dashboard."

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: zaip-skill-reconcile-telemetry
+description: Auditar e reparar telemetria ausente de Runs e tarefas ZAIP usando sessões locais do Codex, sem inventar tokens ou duplicar segmentos. Usar quando o dashboard mostrar dados indisponíveis, após falha de coleta, migração, projeção inconsistente ou solicitação de backfill retroativo.
+---
+
+# Reconciliar telemetria local
+
+1. Ler `.agents/config/project.yaml`, a Rule core e a skill de observabilidade.
+2. Executar o diagnóstico, sem mutação:
+   `node .agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-local-telemetry.mjs`
+3. Revisar `eligible`, `ambiguous`, `unmatched` e `already_measured`. Nunca aplicar correspondências ambíguas.
+4. Para novos Runs Codex, exigir correspondência exata por `client_turn_id` com `task_started.payload.turn_id` do arquivo local. Usar ID da Run, ID da Task, Conversation ID, contenção temporal ou vizinhança temporal mútua de até dois minutos somente para Runs legados sem `client_turn_id`:
+   `node .agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-local-telemetry.mjs --apply`
+   O mesmo comando pode encerrar uma Run ainda marcada como `running` somente quando existir um único segmento local concluído com o mesmo `client_turn_id`; usar o `finished_at` desse segmento como fim real, nunca o relógio atual.
+5. Reconstruir projeções com `node packages/cli/dist/index.js projection rebuild --confirm-full-scan --json`.
+6. Reexecutar o diagnóstico. Exigir `eligible: 0` e confirmar que a cobertura aumentou ou permaneceu igual.
+7. Para corrigir segmentos exatamente duplicados entre Runs sem aplicar o backfill geral, diagnosticar e revisar `duplicate_segment_groups` e `duplicate_segment_assignments`:
+   `node .agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-local-telemetry.mjs --deduplicate`
+   Aplicar somente após confirmação humana explícita com `--apply --deduplicate`. O modo preserva o evento original, insere uma supersessão indisponível antes de `run.finished` e protege o Run corrigido contra o backfill geral posterior.
+8. Quando ainda houver lacunas, executar `python .agents/skills/zaip-skill-reconcile-telemetry/scripts/inspect-local-sqlite.py`. Usar SQLite apenas como índice de threads e fonte de investigação; `threads.tokens_used` e `total_usage_tokens` de logs são acumulados e não substituem input/output por Run.
+9. Somente com autorização humana explícita para aproximação, executar primeiro o diagnóstico `node .agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-local-telemetry.mjs --approximate`. O score combina distância entre data/hora/minuto/segundo de criação e 35% da diferença de duração. Aplicar com `--apply --approximate`; persistir esses vínculos como `legacy_inferred`.
+
+## Normalizar identidade de agentes
+
+Quando o dashboard exibir agentes fora de `.agents/config/agents/catalog.yaml`, execute primeiro o diagnóstico:
+
+`node .agents/skills/zaip-skill-reconcile-telemetry/scripts/normalize-run-agents.mjs`
+
+Com autorização explícita para o backfill, aplique com `--apply` e reconstrua as projeções. O script preserva `codex` e agentes válidos do catálogo; identidades históricas desconhecidas são normalizadas para `codex` sem alterar tokens, custos, vínculos ou timestamps.
+
+## Garantias
+
+- Tratar cache como subconjunto de entrada e reasoning como subconjunto de saída.
+- Calcular `total = input + output`.
+- Reutilizar preços locais editáveis em `.zaip-aios/pricing/models.json` e câmbio local quando presentes.
+- Preservar eventos históricos e inserir o evento corretivo, com `supersedes_event_id`, imediatamente antes de `run.finished`, conforme a ordem canônica do Run V2.
+- Usar cada segmento local no máximo uma vez.
+- Persistir `client_thread_id` e `client_turn_id` em todo novo `run.started` criado dentro do Codex; o ID do turn é a chave canônica de reconciliação.
+- Manter indisponível quando não houver uma correspondência local exclusiva e comprovável.

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Reconciliar telemetria ZAIP"
+  short_description: "Recupera uso local ausente em Runs passadas"
+  default_prompt: "Use $zaip-skill-reconcile-telemetry para auditar e reparar telemetria local ausente com segurança."

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/inspect-local-sqlite.py

@@ -0,0 +1,52 @@
+import json
+import os
+import sqlite3
+
+
+def inspect(path: str) -> dict:
+    if not os.path.exists(path):
+        return {"path": path, "exists": False, "tables": []}
+    connection = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+    tables = []
+    for name, sql in connection.execute(
+        "select name, sql from sqlite_master where type = 'table' order by name"
+    ):
+        columns = [row[1] for row in connection.execute(f'pragma table_info("{name}")')]
+        relevant = [
+            column
+            for column in columns
+            if any(term in column.lower() for term in ("token", "cost", "usage", "thread", "session"))
+        ]
+        tables.append({"name": name, "columns": columns, "telemetry_columns": relevant, "sql": sql})
+    diagnostics = {}
+    if any(table[0] == "logs" for table in connection.execute("select name from sqlite_master where type = 'table'")):
+        diagnostics["token_log_rows"] = connection.execute(
+            "select count(*) from logs where feedback_log_body like '%token_count%' or feedback_log_body like '%tokens_used%'"
+        ).fetchone()[0]
+        diagnostics["token_log_samples"] = connection.execute(
+            "select thread_id, substr(feedback_log_body, 1, 500) from logs where feedback_log_body like '%token_count%' limit 3"
+        ).fetchall()
+    if any(table[0] == "threads" for table in connection.execute("select name from sqlite_master where type = 'table'")):
+        diagnostics["workspace_threads"] = connection.execute(
+            "select count(*) from threads where lower(replace(cwd, '\\', '/')) = lower(replace(?, '\\', '/'))",
+            (os.getcwd(),),
+        ).fetchone()[0]
+        diagnostics["workspace_thread_tokens"] = connection.execute(
+            "select coalesce(sum(tokens_used), 0) from threads where lower(replace(cwd, '\\', '/')) = lower(replace(?, '\\', '/'))",
+            (os.getcwd(),),
+        ).fetchone()[0]
+        diagnostics["zaip_thread_samples"] = connection.execute(
+            "select id, cwd, tokens_used, rollout_path from threads where lower(cwd) like '%zaip-aios%' order by updated_at desc limit 5"
+        ).fetchall()
+    connection.close()
+    return {"path": path, "exists": True, "tables": tables, "diagnostics": diagnostics}
+
+
+root = os.path.expanduser("~/.codex")
+print(
+    json.dumps(
+        [inspect(os.path.join(root, name)) for name in ("logs_2.sqlite", "state_5.sqlite")],
+        ensure_ascii=False,
+        indent=2,
+    )
+)

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/normalize-run-agents.mjs

@@ -0,0 +1,63 @@
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const apply = process.argv.includes("--apply");
+const runsRoot = join(process.cwd(), ".agents", "records", "runs");
+const catalogPath = join(process.cwd(), ".agents", "config", "agents", "catalog.yaml");
+const catalog = await readFile(catalogPath, "utf8");
+const agentsSection = catalog.split(/^squads:\s*$/m, 1)[0];
+const allowed = new Set([
+  "codex",
+  ...[...agentsSection.matchAll(/^\s*-\s+id:\s*([^\s#]+)\s*$/gm)].map((match) => match[1]),
+]);
+const files = await jsonlFiles(runsRoot);
+const replacements = new Map();
+let changedFiles = 0;
+let changedEvents = 0;
+
+for (const file of files) {
+  const source = await readFile(file, "utf8");
+  const trailingNewline = source.endsWith("\n");
+  const lines = source.split(/\r?\n/).filter((line) => line.length > 0);
+  let changed = false;
+  const normalized = lines.map((line) => {
+    const event = JSON.parse(line);
+    if (typeof event.agent !== "string" || allowed.has(event.agent)) return line;
+    replacements.set(event.agent, (replacements.get(event.agent) ?? 0) + 1);
+    event.agent = "codex";
+    changed = true;
+    changedEvents += 1;
+    return JSON.stringify(event);
+  });
+  if (!changed) continue;
+  changedFiles += 1;
+  if (apply)
+    await writeFile(file, `${normalized.join("\n")}${trailingNewline ? "\n" : ""}`, "utf8");
+}
+
+console.log(
+  JSON.stringify(
+    {
+      mode: apply ? "apply" : "diagnostic",
+      scanned_files: files.length,
+      changed_files: changedFiles,
+      changed_events: changedEvents,
+      replacements: Object.fromEntries(
+        [...replacements.entries()].sort(([a], [b]) => a.localeCompare(b)),
+      ),
+      allowed_agents: [...allowed].sort(),
+    },
+    null,
+    2,
+  ),
+);
+
+async function jsonlFiles(root) {
+  const found = [];
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) found.push(...(await jsonlFiles(path)));
+    else if (entry.isFile() && entry.name.endsWith(".jsonl")) found.push(path);
+  }
+  return found;
+}