@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/src/commands/graph/build.js

@@ -7,12 +7,20 @@
  * @module graph-build
  */
 import chalk from 'chalk';
-import { spawnSync } from 'node:child_process';
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { GRAPHIFY_BIN, GRAPHIFY_VERSION, detectGraphifyVersion } from '../../lib/graph/graphify-runtime.js';
+import { GRAPHIFY_PACKAGE, GRAPHIFY_VERSION } from '../../lib/graph/graphify-runtime.js';
 import { getProjectTags } from '../../lib/stack-filter.js';
-import { writeGraphifyignore } from '../../lib/graph/graphifyignore.js';
+import {
+  buildGraphifyignore, writeGraphifyignore, describeOutdatedIgnore,
+} from '../../lib/graph/graphifyignore.js';
+import {
+  acquireRefreshLock, isPrimaryTree, readRefreshLock, releaseRefreshLock, resolveGraphify, runGraphify,
+} from '../../../framework/hooks/shared/graph-refresh.js';
+import { isSecondaryWorktree } from '../../../framework/hooks/shared/git-paths.js';
+import {
+  TEMP_IGNORE_MARKER, ignoreRulesHash, ignoreTextOf, isTemporaryIgnore, readHead, recordRefreshRun,
+} from '../../../framework/hooks/shared/graph-freshness.js';
 import { resolveGraphPath } from '../../lib/graph/graph-loader.js';
 
 function readProjectTags(projectPath) {
@@ -25,6 +33,44 @@ function readProjectTags(projectPath) {
   }
 }
 
+/**
+ * O `.graphifyignore` com que o graphify vai rodar.
+ *
+ * Na raiz: escrito ou migrado (writeGraphifyignore). Numa worktree o arquivo é
+ * do checkout e nunca é reescrito — seria uma mudança na branch da feature.
+ * Ausente ali (a raiz ainda não o versionou), as regras — as da raiz
+ * (`ignoreTextOf`), ou as geradas — entram só durante a rodada e saem depois
+ * (`cleanup`): um `?? .graphifyignore` deixado na worktree faz o `finish` e
+ * o `worktree remove --if-clean` recusarem com worktree-dirty (medido), e pôr
+ * o arquivo no exclude do common dir esconderia também o da raiz. O arquivo leva
+ * `TEMP_IGNORE_MARKER` na 1ª linha: se este processo morrer antes do
+ * `cleanup`, a sobra é reconhecida pelo conteúdo — a próxima rodada a reusa e o
+ * `finish` a apaga (`dropLeftoverIgnore`). O graphify não herda o da raiz: o
+ * ignore dele para na raiz de VCS mais próxima, que numa worktree é ela mesma
+ * (detect.py `_load_graphifyignore`).
+ *
+ * @param {string} projectPath
+ * @param {string[]} tags
+ * @returns {{written: boolean, migrated?: boolean, outdated?: object, temporary?: boolean, path: string, cleanup: () => void}}
+ */
+function prepareIgnore(projectPath, tags) {
+  const none = () => {};
+  if (!isSecondaryWorktree(projectPath)) return { ...writeGraphifyignore(projectPath, tags), cleanup: none };
+  const path = join(projectPath, '.graphifyignore');
+  if (existsSync(path) && !isTemporaryIgnore(readFileSync(path, 'utf-8'))) {
+    const preview = writeGraphifyignore(projectPath, tags, { fx: { writeFile: none } });
+    return { written: false, path, ...(preview.outdated ? { outdated: preview.outdated } : {}), cleanup: none };
+  }
+  const content = ignoreTextOf(projectPath) ?? buildGraphifyignore(tags);
+  writeFileSync(path, `${TEMP_IGNORE_MARKER}\n${content.replace(/^/, '')}`, 'utf-8');
+  return {
+    written: false,
+    temporary: true,
+    path,
+    cleanup: () => { try { unlinkSync(path); } catch { /* já saiu */ } },
+  };
+}
+
 /**
  * @param {{path?: string, json?: boolean, refresh?: boolean}} [options]
  */
@@ -32,8 +78,10 @@ export async function graphBuildCommand(options = {}) {
   const projectPath = options.path || process.cwd();
   const refresh = options.refresh === true;
 
-  if (!detectGraphifyVersion()) {
-    const hint = `graphify não está no PATH. Instale com: uv tool install ${'graphifyy'}==${GRAPHIFY_VERSION}`;
+  // O mesmo resolvedor do refresh em background: no win32 um shim `.cmd` só
+  // é achado pelo shell, e os dois caminhos precisam ver o mesmo binário.
+  if (!resolveGraphify(process.env)) {
+    const hint = `graphify não está no PATH. Instale com: uv tool install ${GRAPHIFY_PACKAGE}==${GRAPHIFY_VERSION}`;
     const payload = { ok: false, reason: 'graphify-unavailable', hint };
     if (options.json) {
       console.log(JSON.stringify(payload, null, 2));
@@ -47,7 +95,33 @@ export async function graphBuildCommand(options = {}) {
 
   // O ignore precisa existir ANTES da extração, senão o grafo nasce com o
   // ruído que a ADR-004 existe para tirar.
-  writeGraphifyignore(projectPath, readProjectTags(projectPath));
+  const ignore = prepareIgnore(projectPath, readProjectTags(projectPath));
+  if (ignore.outdated && !options.json) {
+    console.error(chalk.yellow(`\n⚠ ${describeOutdatedIgnore(ignore.outdated)}`));
+  }
+
+  // Na árvore principal o refresh em background (framework/hooks/shared/
+  // graph-refresh.js) escreve o mesmo graph.json: dois graphify ao mesmo tempo
+  // disputam o arquivo e todos os núcleos. Numa worktree ninguém mais escreve
+  // o graph.json dela — o background só toca a raiz —, e esperar o lock da
+  // raiz ali prometeria "o grafo chega ao HEAD" sobre um refresh que nunca a
+  // alcança. Sem git não há lock, e o comando segue sozinho.
+  const primary = isPrimaryTree(projectPath);
+  const lock = primary ? acquireRefreshLock(projectPath) : null;
+  const running = primary && !lock ? readRefreshLock(projectPath) : null;
+  if (running?.live) {
+    ignore.cleanup();
+    const since = new Date(running.since).toLocaleTimeString();
+    if (options.json) {
+      console.log(JSON.stringify({
+        ok: true, running: true, since: running.since, pid: running.pid, mode: refresh ? 'refresh' : 'build',
+      }, null, 2));
+    } else {
+      console.log(chalk.yellow(`\n⟳ Refresh em background já em andamento desde ${since} (pid ${running.pid}).`));
+      console.log(chalk.gray('   O grafo chega ao HEAD quando ele terminar — confira com: morph-spec graph status\n'));
+    }
+    return;
+  }
 
   const args = refresh
     ? ['update', projectPath]
@@ -56,19 +130,33 @@ export async function graphBuildCommand(options = {}) {
   // Capturamos o output em vez de herdar o terminal porque precisamos
   // inspecioná-lo: o graphify sai 1 tanto quando quebra quanto quando não há
   // código para indexar, e essas duas coisas não podem virar a mesma mensagem.
-  const run = spawnSync(GRAPHIFY_BIN, args, {
-    cwd: projectPath,
-    encoding: 'utf-8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
+  // HEAD e regras lidos ANTES: são o que o graphify leu.
+  const head = readHead(projectPath);
+  const ignoreHash = ignoreRulesHash(projectPath);
+  let run;
+  let empty = false;
+  try {
+    run = runGraphify(projectPath, args, { timeout: null });
+    // Projeto sem código é o estado normal logo depois de um `init`, não uma
+    // falha: o graphify diz "found 0 code" / "graph is empty", sai 1 e não
+    // escreve graph.json. Tratar isso como erro faria todo init greenfield
+    // terminar em vermelho.
+    empty = run.status !== 0 && (/found 0 code/i.test(run.output) || /graph is empty/i.test(run.output));
+    // O registro é o que torna "untouched" em dia: sem ele, um refresh que não
+    // mudou a topologia deixa o carimbo no commit antigo e o grafo parece
+    // velho para sempre (framework/hooks/shared/graph-freshness.js).
+    if (!empty) {
+      recordRefreshRun(projectPath, {
+        head, exit: run.status ?? null, ignoreHash, unavailable: Boolean(run.unavailable),
+      });
+    }
+  } finally {
+    releaseRefreshLock(lock);
+    ignore.cleanup();
+  }
 
-  const output = `${run.stdout ?? ''}${run.stderr ?? ''}`;
+  const { output } = run;
   const ok = run.status === 0;
-  // Projeto sem código é o estado normal logo depois de um `init`, não uma
-  // falha: o graphify diz "found 0 code" / "graph is empty", sai 1 e não
-  // escreve graph.json. Tratar isso como erro faria todo init greenfield
-  // terminar em vermelho.
-  const empty = !ok && (/found 0 code/i.test(output) || /graph is empty/i.test(output));
 
   if (options.json) {
     console.log(JSON.stringify({
@@ -77,6 +165,9 @@ export async function graphBuildCommand(options = {}) {
       mode: refresh ? 'refresh' : 'build',
       path: resolveGraphPath(projectPath),
       exitCode: run.status,
+      ...(ignore.migrated ? { ignoreMigrated: true } : {}),
+      ...(ignore.outdated ? { ignoreOutdated: ignore.outdated } : {}),
+      ...(ignore.temporary ? { ignoreTemporary: true } : {}),
     }, null, 2));
   } else {
     if (!empty && output.trim()) process.stdout.write(`${output.trimEnd()}\n`);

package/src/commands/graph/explain.js

@@ -11,8 +11,8 @@
  * @module graph-explain
  */
 import chalk from 'chalk';
-import { loadGraph, getFreshness } from '../../lib/graph/graph-loader.js';
-import { buildIndex, resolveLabel, neighborhood } from '../../lib/graph/sanitize.js';
+import { loadGraph, getFreshness, describeStale } from '../../lib/graph/graph-loader.js';
+import { buildIndex, resolveLabel, neighborhood, isTestPath } from '../../lib/graph/sanitize.js';
 
 const FALLBACK_HINT = 'Sem resposta do grafo, caia para grep/Glob.';
 
@@ -62,6 +62,7 @@ export async function graphExplainCommand(symbol, options = {}) {
       label: node.label,
       source_file: node.source_file,
       source_location: node.source_location ?? '',
+      test: isTestPath(node.source_file),
     },
     incoming,
     outgoing,
@@ -74,16 +75,18 @@ export async function graphExplainCommand(symbol, options = {}) {
   }
 
   const nodeLoc = node.source_location ? `:${node.source_location}` : '';
-  console.log(chalk.green(`\n${node.label}`) + chalk.gray(`  ${node.source_file}${nodeLoc}`));
+  const testTag = payload.node.test ? chalk.gray('  [teste]') : '';
+  console.log(chalk.green(`\n${node.label}`) + chalk.gray(`  ${node.source_file}${nodeLoc}`) + testTag);
   if (freshness.state === 'stale') {
-    console.log(chalk.yellow('  ⚠ grafo stale — o rebuild do hook é assíncrono'));
+    console.log(chalk.yellow(`  ⚠ grafo stale — ${describeStale(projectPath, freshness)}`));
   }
 
   console.log(chalk.bold('\n  quem depende dele:'));
   for (const e of incoming) {
     const loc = e.source_location ? `:${e.source_location}` : '';
     const via = e.via === 'direct' ? '' : chalk.gray(` [${e.via}]`);
-    console.log(`   ${chalk.cyan(e.relation.padEnd(14))} ${e.source_file}${loc}${via}`);
+    const test = e.test ? chalk.gray(' [teste]') : '';
+    console.log(`   ${chalk.cyan(e.relation.padEnd(14))} ${e.source_file}${loc}${via}${test}`);
   }
   if (incoming.length === 0) console.log(chalk.gray('   (nenhum)'));
 

package/src/commands/graph/status.js

@@ -8,8 +8,10 @@
  * @module graph-status
  */
 import chalk from 'chalk';
-import { loadGraph, getFreshness } from '../../lib/graph/graph-loader.js';
-import { buildIndex, classifyLabel } from '../../lib/graph/sanitize.js';
+import {
+  loadGraph, getFreshness, describeStale, refreshState, staleCause,
+} from '../../lib/graph/graph-loader.js';
+import { buildIndex, classifyLabel, isTestPath } from '../../lib/graph/sanitize.js';
 import { GRAPHIFY_VERSION, detectGraphifyVersion } from '../../lib/graph/graphify-runtime.js';
 
 function summarizeSanitize(index) {
@@ -52,13 +54,16 @@ export async function graphStatusCommand(options = {}) {
 
   const { graph } = loaded;
   const freshness = getFreshness(projectPath, graph);
-  const sanitize = summarizeSanitize(buildIndex(graph));
+  const index = buildIndex(graph);
+  const sanitize = { ...summarizeSanitize(index), recoveredDispatch: index.recovered.length };
   const payload = {
     available: true,
     path: loaded.path,
     nodes: graph.nodes.length,
+    testNodes: graph.nodes.filter((n) => isTestPath(n.source_file)).length,
     links: graph.links.length,
     freshness,
+    refresh: refreshState(projectPath),
     version,
     sanitize,
   };
@@ -72,10 +77,8 @@ export async function graphStatusCommand(options = {}) {
   console.log(chalk.gray(`   ${loaded.path}`));
 
   if (freshness.state === 'stale') {
-    // O hook post-commit rebuilda em BACKGROUND: logo após um commit o grafo
-    // ainda é o do commit anterior.
-    console.log(chalk.yellow(`   ⚠ stale — construído em ${freshness.builtAtCommit.slice(0, 8)}, HEAD é ${freshness.headCommit.slice(0, 8)}`));
-    console.log(chalk.gray('     Atualize com: morph-spec graph refresh'));
+    console.log(chalk.yellow(`   ⚠ stale — ${staleCause(freshness)}`));
+    console.log(chalk.gray(`     ${describeStale(projectPath, freshness)}`));
   } else if (freshness.state === 'fresh') {
     console.log(chalk.gray(`   fresco (${freshness.headCommit.slice(0, 8)})`));
   } else {
@@ -88,6 +91,9 @@ export async function graphStatusCommand(options = {}) {
     console.log(chalk.yellow(`   ⚠ graphify ${installed} instalado; ${GRAPHIFY_VERSION} é a versão pinada e medida`));
   }
 
-  console.log(chalk.gray(`   saneamento: ${sanitize.coalescible} coalescível · ${sanitize.external} externo · ${sanitize.ambiguous} ambíguo`));
+  console.log(chalk.gray(`   saneamento: ${sanitize.coalescible} coalescível · ${sanitize.external} externo · ${sanitize.ambiguous} ambíguo · ${sanitize.recoveredDispatch} dispatch recuperado`));
+  if (payload.testNodes) {
+    console.log(chalk.gray(`   ${payload.testNodes} nós de teste (dublês, fixtures, helpers) — achados pelo explain, fora dos god nodes`));
+  }
   console.log('');
 }

package/src/commands/mcp/mcp-setup.js

@@ -64,21 +64,49 @@ export async function detectStack(targetPath) {
   }
 }
 
+/**
+ * Detect the project's integrations (`neon`, `stripe`...), same sources and
+ * order as detectStack. The detectors never fold them into the stack string, so
+ * without this an MCP scoped to an integration (neon, asaas) is never offered.
+ *
+ * @param {string} targetPath
+ * @returns {Promise<string[]>}
+ */
+export async function detectIntegrations(targetPath) {
+  try {
+    const configPath = join(targetPath, '.morph', 'config', 'config.json');
+    if (existsSync(configPath)) {
+      const integrations = JSON.parse(readFileSync(configPath, 'utf-8')).project?.integrations;
+      if (Array.isArray(integrations)) return integrations;
+    }
+  } catch {
+    // Fall through to filesystem detection
+  }
+
+  try {
+    const results = await detectProject(targetPath, { conversation: false, generateStandards: false });
+    return results.structure?.integrations ?? [];
+  } catch {
+    return [];
+  }
+}
+
 export async function mcpSetupCommand(name, options) {
   const targetPath = process.cwd();
 
   try {
     // Detect current environment
     const stack = await detectStack(targetPath);
+    const integrations = await detectIntegrations(targetPath);
     const claudeConfig = await detectClaudeConfig(targetPath);
     const existingMcps = claudeConfig.mcpServers || [];
 
     if (options.list) {
-      return showStatusList(targetPath, stack, existingMcps);
+      return showStatusList(targetPath, stack, existingMcps, integrations);
     }
 
     if (options.auto) {
-      return autoInstall(targetPath, stack, existingMcps);
+      return autoInstall(targetPath, stack, existingMcps, integrations);
     }
 
     if (name) {
@@ -86,7 +114,7 @@ export async function mcpSetupCommand(name, options) {
     }
 
     // Interactive wizard
-    return interactiveWizard(targetPath, stack, existingMcps);
+    return interactiveWizard(targetPath, stack, existingMcps, integrations);
   } catch (err) {
     console.error(chalk.red(`Error: ${err.message}`));
     process.exit(1);
@@ -96,8 +124,8 @@ export async function mcpSetupCommand(name, options) {
 /**
  * Show MCP status list (--list)
  */
-async function showStatusList(targetPath, stack, existingMcps) {
-  const orchestration = orchestrateMcpSetup(targetPath, stack, existingMcps);
+async function showStatusList(targetPath, stack, existingMcps, integrations) {
+  const orchestration = orchestrateMcpSetup(targetPath, stack, existingMcps, { integrations });
   const statusRows = formatMcpStatusTable(orchestration, {});
 
   console.log(chalk.cyan('\n  MCP Server Status\n'));
@@ -130,8 +158,8 @@ async function showStatusList(targetPath, stack, existingMcps) {
 /**
  * Auto-install credential-free MCPs (--auto)
  */
-async function autoInstall(targetPath, stack, existingMcps) {
-  const orchestration = orchestrateMcpSetup(targetPath, stack, existingMcps, { autoOnly: true });
+async function autoInstall(targetPath, stack, existingMcps, integrations) {
+  const orchestration = orchestrateMcpSetup(targetPath, stack, existingMcps, { autoOnly: true, integrations });
   const autoNames = Object.keys(orchestration.autoInstallable);
 
   if (autoNames.length === 0) {
@@ -391,8 +419,8 @@ async function setupSpecificMcp(targetPath, name, stack, existingMcps) {
 /**
  * Interactive wizard showing all MCPs
  */
-async function interactiveWizard(targetPath, stack, existingMcps) {
-  const orchestration = orchestrateMcpSetup(targetPath, stack, existingMcps);
+async function interactiveWizard(targetPath, stack, existingMcps, integrations) {
+  const orchestration = orchestrateMcpSetup(targetPath, stack, existingMcps, { integrations });
 
   console.log(chalk.cyan('\n  MCP Setup Wizard'));
   console.log(chalk.gray(`  Stack: ${stack}`));

package/src/commands/observability/cost.js

@@ -1,5 +1,5 @@
 /**
- * `morph-spec cost [feature] [--by task|phase] [--all-trees] [--json]`
+ * `morph-spec cost [feature] [--by task|phase] [--all-trees] [--metrics [--top n]] [--json]`
  *
  * A cost-facing view over the same harness event stream `telemetry` reads
  * (.morph/logs/events.jsonl): how much wall-clock time was spent inside
@@ -16,11 +16,14 @@
  * `sessionUsage` (when present) is the exception: real tokens, observed
  * directly, not a proxy — see aggregateCost's docstring for the contract.
  *
- * `--all-trees` (Furo 3) widens the source from "just the current tree" to
- * every git worktree that has its own events.jsonl — a fleet running N
- * features in N worktrees otherwise only ever sees whichever tree `cost` was
- * run from. Reuses the same worktree enumeration `doctor --worktrees`/`fleet`
- * use (see loadTelemetryAllTrees in telemetry-reader.js).
+ * `--all-trees` widens the source from "just the current tree" to every git
+ * worktree that has its own events.jsonl plus the logs `finish` saved before
+ * removing a worktree, deduplicated by eventId.
+ *
+ * `--metrics` measures the loop instead: turns, tool calls by orchestrator and
+ * sub-agent, time per command class, identical reruns and why, rereads, how
+ * many feature-scope verifies each feature ran, git calls per task and whether
+ * the reuse validator ran in root and worktree (see lib/telemetry/metrics.js).
  *
  * Read-only, always exits 0 on a normal (even empty) run — fail-open, an
  * empty stream is an answer, not an error. Only `--by` with an unknown value
@@ -28,7 +31,8 @@
  */
 
 import chalk from 'chalk';
-import { loadTelemetry, loadTelemetryAllTrees, aggregateCost } from '../../lib/telemetry/telemetry-reader.js';
+import { loadTelemetry, loadTelemetryAllTrees, aggregateCost, dedupeEvents } from '../../lib/telemetry/telemetry-reader.js';
+import { computeMetrics } from '../../lib/telemetry/metrics.js';
 
 const BYTES_CAVEAT =
   'Bytes re-ingeridos são um PROXY determinístico de custo (o que as ferramentas leram do disco) — NÃO são tokens reais. Hooks não enxergam o uso real de tokens do modelo.';
@@ -87,17 +91,30 @@ function printPhases(phases) {
   }
 }
 
+function tokenLine(u) {
+  return `  input=${u.inputTokens}  output=${u.outputTokens}  `
+    + `cacheRead=${u.cacheReadTokens}  cacheCreation=${u.cacheCreationTokens}`;
+}
+
 /**
- * Real (hook-observed) token counts, when the stream has `SessionUsage`
- * events — the non-proxy sibling of the bytes-re-ingested numbers above.
- * No-op when absent (aggregateCost returns `null`, never a zeroed object).
+ * Real (hook-observed) token counts — the non-proxy sibling of the bytes
+ * above: the main sessions and, separately, the sub-agents.
  */
-function printSessionUsage(sessionUsage) {
-  if (!sessionUsage) return;
-  console.log('\n' + chalk.white.bold('Tokens reais (sessões observadas)')
-    + chalk.gray(` · ${sessionUsage.sessions} SessionUsage`));
-  console.log(`  input=${sessionUsage.inputTokens}  output=${sessionUsage.outputTokens}  `
-    + `cacheRead=${sessionUsage.cacheReadTokens}  cacheCreation=${sessionUsage.cacheCreationTokens}`);
+function printSessionUsage(summary) {
+  const { sessionUsage, agentUsage, sessionUsageLegacySamples } = summary;
+  if (sessionUsage) {
+    console.log('\n' + chalk.white.bold('Tokens reais (sessões observadas)')
+      + chalk.gray(` · ${sessionUsage.sessions} sessão(ões), ${sessionUsage.samples} amostra(s)`));
+    console.log(tokenLine(sessionUsage));
+  }
+  if (agentUsage) {
+    console.log('\n' + chalk.white.bold('Tokens reais (sub-agents)')
+      + chalk.gray(` · ${agentUsage.agents} agente(s), ${agentUsage.samples} amostra(s)`));
+    console.log(tokenLine(agentUsage));
+  }
+  if (sessionUsageLegacySamples > 0) {
+    console.log(chalk.gray(`  ${sessionUsageLegacySamples} amostra(s) SessionUsage antigas (sem delta) fora da soma: eram o total acumulado, repetido a cada Stop.`));
+  }
 }
 
 function printSummary(summary) {
@@ -112,7 +129,115 @@ function printSummary(summary) {
     for (const t of summary.tools) console.log(`  ${t.name.padEnd(16)} ${t.count}`);
   }
 
-  printSessionUsage(summary.sessionUsage);
+  printSessionUsage(summary);
+}
+
+function pct(r) {
+  return r === null || r === undefined ? '-' : `${Math.round(r * 1000) / 10}%`;
+}
+
+function split(counts) {
+  return `${counts.total} (orq ${counts.orchestrator} · sub ${counts.subagent}${counts.unknown ? ` · sem agente ${counts.unknown}` : ''})`;
+}
+
+function printMetricsBody(m, { by }) {
+  const legacyShare = m.window.events ? m.coverage.legacy / m.window.events : 0;
+  console.log(chalk.gray(`janela: ${m.window.from ?? '-'} → ${m.window.to ?? '-'} · ${m.window.events} eventos`
+    + ` · ${pct(1 - legacyShare)} no esquema v2`));
+  if (m.coverage.legacy) {
+    console.log(chalk.gray('  eventos v1 não têm agente, exit code, duração nem janela de Read: entram como "sem agente" e rerun "unknown-*".'));
+  }
+
+  console.log('\n' + chalk.white.bold('Turnos e chamadas'));
+  console.log(`  turnos: ${m.turns ? split(m.turns) : 'desconhecido (nenhum PostToolBatch na janela)'}`
+    + (m.turnsPerTaskMedian !== null ? chalk.gray(` · mediana por task ${m.turnsPerTaskMedian}`) : ''));
+  console.log(`  chamadas de ferramenta: ${split(m.toolCalls)}`);
+  const perTask = m.perTaskByFeature;
+  if (perTask.toolCalls !== null) {
+    console.log(`  por task (total da feature ÷ tasks dela, mediana): ${perTask.toolCalls} chamadas`
+      + (perTask.turns !== null ? ` · ${perTask.turns} turnos` : '') + ` · ${perTask.git} git status+diff`
+      + chalk.gray(` · as janelas TaskStart→TaskEnd têm ${pct(m.taskWindowCoverage)} das chamadas`));
+  }
+
+  console.log('\n' + chalk.white.bold('Tempo por classe de comando'));
+  for (const [klass, t] of Object.entries(m.timeByClass).sort((a, b) => b[1].measuredMs - a[1].measuredMs)) {
+    const unmeasured = t.unmeasured ? chalk.gray(` (${t.unmeasured} sem duração)`) : '';
+    console.log(`  ${klass.padEnd(12)} ${fmtDuration(t.measuredMs / 1000).padStart(8)}  ${t.runs} execução(ões)${unmeasured}`);
+  }
+
+  console.log('\n' + chalk.white.bold('Rerun do mesmo comando em ≤10 min (mesma feature; o filtro de saída não conta)'));
+  console.log(`  total: ${pct(m.reruns.rate)} repetidas (${m.reruns.reruns}/${m.reruns.runs}) · ${pct(m.reruns.burstRate)} em rajada — testes, builds e verifies`);
+  for (const [kind, r] of Object.entries(m.rerunsByKind).sort((a, b) => b[1].runs - a[1].runs)) {
+    console.log(`  ${kind.padEnd(22)} ${pct(r.rate).padStart(6)} repetidas  ${pct(r.burstRate).padStart(6)} em rajada  (${r.runs} execuções)`);
+  }
+  const classes = Object.entries(m.rerunClasses);
+  if (classes.length) console.log(chalk.gray(`  por quê: ${classes.map(([k, n]) => `${k} ${n}`).join(' · ')}`));
+
+  console.log('\n' + chalk.white.bold('Releitura de arquivo (mesma janela, mesma feature)'));
+  console.log(`  ${pct(m.rereads.rate)} dos bytes lidos (${fmtBytes(m.rereads.redundantBytes)} de ${fmtBytes(m.rereads.bytes)}, ${m.rereads.reads} leituras)`);
+  if (m.rereads.windowed < m.rereads.reads) {
+    console.log(chalk.gray(`  ${m.rereads.reads - m.rereads.windowed} leitura(s) sem janela gravada (v1) contam o arquivo inteiro: a taxa é um teto`));
+  }
+  for (const f of m.topRereads) {
+    console.log(`  ${fmtBytes(f.redundantBytes).padStart(9)}  ${f.reads}×  ${f.file}${chalk.gray(` [${f.feature ?? '-'}]`)}`);
+  }
+
+  console.log('\n' + chalk.white.bold('verify, git e reuso'));
+  const perFeature = Object.entries(m.verify.byFeature).sort((a, b) => b[1].feature - a[1].feature);
+  console.log(`  verify de feature por feature: mediana ${m.verify.featureScopeMedian ?? '-'}`
+    + (perFeature.length ? chalk.gray(` (${perFeature.slice(0, 5).map(([f, v]) => `${f} ${v.feature}`).join(', ')})`) : ''));
+  const repeats = Object.entries(m.verify.unchangedRepeats);
+  if (repeats.length) {
+    console.log(`  verify de feature sobre a mesma árvore do anterior: ${repeats.reduce((n, [, v]) => n + v, 0)}`
+      + chalk.gray(` (${repeats.map(([f, n]) => `${f} ${n}`).join(', ')})`));
+  }
+  if (m.dotnetFullSuite.runs) {
+    const phases = Object.entries(m.dotnetFullSuite.byPhase).map(([p, v]) => `${p} ${v.withBuild}/${v.runs}`).join(' · ');
+    console.log(`  suíte .NET inteira que recompila (sem --no-build): ${m.dotnetFullSuite.withBuild}/${m.dotnetFullSuite.runs}`
+      + chalk.gray(` (${phases})`));
+  }
+  console.log(`  git status / diff por task: mediana ${m.gitPerTaskMedian.status ?? '-'} / ${m.gitPerTaskMedian.diff ?? '-'}`
+    + chalk.gray(` · total ${m.git.status} / ${m.git.diff}`));
+  const trees = Object.entries(m.reuse.byTree);
+  console.log(`  reuse-validator: ${trees.length
+    ? trees.map(([tree, s]) => `${tree} rodou ${s.ran}, pulou ${s.skipped}`).join(' · ')
+    : 'nenhum evento Verify na janela'}`);
+  for (const [reason, n] of Object.entries(m.reuse.skipReasons)) console.log(chalk.gray(`    pulou ${n}×: ${reason}`));
+
+  if (by === 'task') {
+    for (const t of m.tasks) {
+      const status = t.open ? chalk.yellow('[em aberto]') : (t.status || '-');
+      console.log('\n' + chalk.white.bold(`Task ${t.task}`) + chalk.gray(` · ${t.feature ?? '(sem feature)'}`) + ` · ${status}`);
+      console.log(`  turnos ${t.turns ? split(t.turns) : '-'} · chamadas ${split(t.toolCalls)}`);
+      const time = Object.entries(t.timeByClass).map(([k, v]) => `${k} ${fmtDuration(v.measuredMs / 1000)}`).join(' · ');
+      if (time) console.log(`  tempo: ${time}`);
+      console.log(`  rerun ${pct(t.reruns.rate)} (${t.reruns.reruns}/${t.reruns.runs}) · releitura ${pct(t.rereads.rate)} · git status/diff ${t.git.status}/${t.git.diff}`);
+    }
+  }
+}
+
+/**
+ * `--metrics`: the loop measurements over the current tree (and, with
+ * `--all-trees`, every tree plus the finish backups, deduplicated).
+ */
+function printMetrics(feature, options, cwd) {
+  const events = options.allTrees
+    ? dedupeEvents(loadTelemetryAllTrees(cwd).flatMap((t) => t.events))
+    : loadTelemetry(cwd);
+  const metrics = computeMetrics(events, { feature, top: options.top });
+
+  if (options.json) {
+    console.log(JSON.stringify(metrics));
+    return;
+  }
+  if (metrics.window.events === 0) {
+    const scope = feature ? ` para a feature "${feature}"` : '';
+    console.log(chalk.gray(`Telemetria vazia${scope} — nada a medir.`));
+    return;
+  }
+  const scope = feature ? chalk.cyan(` · feature ${feature}`) : '';
+  console.log(chalk.white.bold(`Medições do loop${options.allTrees ? ' — todas as árvores + finish-backup' : ''}`) + scope);
+  printMetricsBody(metrics, options);
 }
 
 /**
@@ -132,7 +257,7 @@ function printAllTrees(feature, options, cwd) {
     path,
     ...aggregateCost(events, { feature }),
   }));
-  const combined = aggregateCost(treesData.flatMap((t) => t.events), { feature });
+  const combined = aggregateCost(dedupeEvents(treesData.flatMap((t) => t.events)), { feature });
 
   if (options.json) {
     console.log(JSON.stringify({ allTrees: true, trees: perTree, combined }));
@@ -183,6 +308,11 @@ export function costCommand(feature, options = {}) {
 
   const cwd = options.cwd || process.cwd();
 
+  if (options.metrics) {
+    printMetrics(feature, options, cwd);
+    return;
+  }
+
   if (options.allTrees) {
     // Same fail-open + Windows-flush discipline as the single-tree path
     // below — no forced process.exit(), --json included.