@gonrocca/zero-pi 0.1.56 → 0.1.58

package/README.md

@@ -74,8 +74,10 @@ into `/forge` for you.
 | Feature | What it does |
 | ------- | ------------ |
 | **Strict TDD** | The build phase drives RED → GREEN → TRIANGULATE → REFACTOR with a TDD Cycle Evidence table; veredicto audits it. On by default, runtime-gated on a test runner; `tdd.mode: "off"` disables it. |
-| **`/zero-models`** | Pick the model + provider + thinking level for each SDD phase — a boxed-window picker, or set one directly. |
+| **`/zero-models`** | Pick the model + provider + thinking level for each SDD phase — a boxed-window picker, or set one directly. Direct assignments are validated against pi's model registry when available. |
 | **Autotune** | Learns which model fits each phase from your run history and re-tunes itself. |
+| **`/zero-doctor`** | Preflight diagnostics for zero-pi: package install, Node version, pi-subagents, generated phase agents, model config, `.sdd/config`, run history, git, and `gh` auth. |
+| **`/zero-cost`** | Aggregates a run's sub-agent `meta.json` files into a per-phase token/cost/duration report — no schema change, reads what pi already writes. |
 | **`/zero-sync` / `/zero-archive`** | Folds each run's spec delta into a canonical, project-wide spec store and archives approved runs. |
 | **Git / PR / Issues** | `/zero-branch`, `/zero-git-validate`, `/zero-pr`, and `/zero-issue` keep branches and GitHub links audit-ready. |
 | **Run memory** | Every run recalls and saves traces to Cortex, so runs learn from each other. |
@@ -84,7 +86,7 @@ into `/forge` for you.
 | **Working-phrase ticker** | Swaps pi's `Working...` for a context-aware Spanish phrase + spinner. |
 | **Conversation resume** | Writes `.pi/zero-resume.md` on exit — the restore command + a conversation tail. |
 | **Windows tree-kill** | Aborting a turn kills the whole process tree — no orphaned `claude`. |
-| **Skill auto-learning** | Distills reusable skills from substantial tasks and surfaces them later. |
+| **SDD routing skill** | Natural-language requests that say "hacelo con sdd" route into `/forge` without remembering the slash command. |
 | **`zero-sdd` theme** | A dark, high-contrast pi theme tuned for SDD work. |
 | **`zero-sunset` theme** | A warm sunset variant — gold/coral/magenta accents over warm-dark panels, with one cool tone kept for syntax legibility. Activate with `/theme zero-sunset`. |
 
@@ -93,11 +95,13 @@ into `/forge` for you.
 | Command | Does |
 | ------- | ---- |
 | `/forge <feature>` | Run the SDD pipeline — `--continue [slug]` resumes. |
-| `/zero-models [<phase>=[<provider>/]<model> [thinking=<level>]]` | Show or set per-phase models, providers, and thinking — `thinking=<level>` (`off\|minimal\|low\|medium\|high\|xhigh`); `autotune=auto\|ask\|off`. |
+| `/zero-models [<phase>=[<provider>/]<model> [thinking=<level>]]` | Show or set per-phase models, providers, and thinking — `thinking=<level>` (`off\|minimal\|low\|medium\|high\|xhigh`); `autotune=auto\|ask\|off`. Direct assignments fail fast when pi's registry says the provider/model is unknown or ambiguous. |
+| `/zero-doctor` | Run zero-pi preflight diagnostics: package, Node, pi-subagents, generated agents/support modules, model config, `.sdd/config`, run history, git, and `gh`. |
 | `/zero-sync <slug>` | Fold a run's spec delta into the canonical spec store; a first all-`## ADDED` delta creates the store lazily. |
 | `/zero-archive <slug>` | Merge an approved run into `.sdd/specs/`, move it to `.sdd/archive/YYYY-MM-DD-<slug>/`, and persist `archivePath`. |
 | `/zero-validate <slug>` | Validate proposal/spec/design/tasks artifacts, including task schema and per-domain specs. |
 | `/zero-status` | Show each `.sdd/` run's artifact, sync, latest-verdict, and GitHub-link status. |
+| `/zero-cost [<slug>]` | Report tokens (in/out/cache), USD cost, duration, and tool-count per SDD phase for a run — `<slug>` for a specific run, no argument for the most recent. |
 | `/zero-branch <slug>` | Create/reuse the configured SDD Git branch and persist `branch`/`baseBranch`. |
 | `/zero-git-validate <slug>` | Check worktree, branch, remote, `gh auth`, and verdict gating before PR/archive. |
 | `/zero-pr <slug>` | Create an audit-ready GitHub PR from a run that already has verdict `pasa`. |

package/extensions/format-tokens.ts

@@ -0,0 +1,14 @@
+// Pure helper: compact token count to a short human string.
+// 1234 → "1.2k", 4_695_040 → "4.7M", 999 → "999".
+//
+// Intentionally separate from `formatTokenCount` in zero-statusline.ts,
+// which uses a different contract; this helper requires lowercase `k`,
+// uppercase `M`, and uppercase `B` suffixes.
+
+export function formatTokens(n: number): string {
+  if (!Number.isFinite(n) || n < 0) return "0";
+  if (n < 1000) return `${Math.floor(n)}`;
+  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
+  if (n < 1_000_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  return `${(n / 1_000_000_000).toFixed(1)}B`;
+}

package/extensions/zero-cost-extension.ts

@@ -0,0 +1,59 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { parseMeta, selectRunMetas, aggregateRun, formatReport, type PhaseMeta } from "./zero-cost.ts";
+
+type NotifyType = "info" | "warning" | "error";
+interface PiCommandContext { ui: { notify(message: string, type?: NotifyType): void } }
+interface PiExtensionAPI { registerCommand(name: string, options: { description?: string; handler: (args: string, ctx: PiCommandContext) => void | Promise<void> }): void }
+
+/** Read every sub-agent `meta.json` across all pi session dirs and parse the
+ *  zero-<phase> ones. Scanning every session keeps us decoupled from pi's
+ *  cwd-encoding scheme; selection by slug/timestamp narrows to one run. */
+function readAllPhaseMetas(): PhaseMeta[] {
+  const root = join(homedir(), ".pi", "agent", "sessions");
+  if (!existsSync(root)) return [];
+  const out: PhaseMeta[] = [];
+  for (const session of readdirSync(root, { withFileTypes: true })) {
+    if (!session.isDirectory()) continue;
+    const artifacts = join(root, session.name, "subagent-artifacts");
+    if (!existsSync(artifacts)) continue;
+    for (const f of readdirSync(artifacts)) {
+      if (!f.endsWith("_meta.json")) continue;
+      try {
+        const meta = parseMeta(JSON.parse(readFileSync(join(artifacts, f), "utf8")));
+        if (meta) out.push(meta);
+      } catch { /* skip unreadable / malformed meta */ }
+    }
+  }
+  return out;
+}
+
+function runCost(args: string, ctx: PiCommandContext): void {
+  const notify = (m: string, t?: NotifyType) => { try { ctx.ui.notify(m, t); } catch {} };
+  const slug = args.trim() || null;
+  const metas = readAllPhaseMetas();
+  const selected = selectRunMetas(metas, slug);
+  if (selected.length === 0) {
+    notify(
+      slug
+        ? `zero-cost: no encontré datos de costo para "${slug}".`
+        : "zero-cost: no encontré runs con datos de costo todavía.",
+      "info",
+    );
+    return;
+  }
+  notify(formatReport(aggregateRun(selected, slug ?? selected[0]?.slug ?? null)), "info");
+}
+
+export default function register(pi?: PiExtensionAPI): void {
+  if (!pi || typeof pi.registerCommand !== "function") return;
+  pi.registerCommand("zero-cost", {
+    description: "Reporta tokens, costo y duración por fase de un run SDD (slug opcional; sin slug = el más reciente)",
+    handler: (args: string, ctx: PiCommandContext): void => {
+      try { if (ctx?.ui?.notify) runCost(args ?? "", ctx); }
+      catch (err) { try { ctx.ui.notify(`zero-cost: ${err instanceof Error ? err.message : String(err)}`, "error"); } catch {} }
+    },
+  });
+}

package/extensions/zero-cost.ts

@@ -0,0 +1,220 @@
+// zero-pi — per-run cost/usage report, pure-logic module.
+//
+// A `/forge` run delegates each phase to a sub-agent that writes a
+// `*_meta.json` under `~/.pi/agent/sessions/<session>/subagent-artifacts/`
+// carrying real `usage` (tokens + cost), `model`, `durationMs` and
+// `toolCount`. `~/.pi/zero-runs.jsonl` records the verdict/rounds/model but
+// never cost — so there is no aggregate view of what a run cost, by phase.
+//
+// This module turns those raw meta records into a per-phase + total report.
+// Every decision (phase mapping, slug extraction, selection, aggregation,
+// formatting) lives here as plain, dependency-free TypeScript so it is
+// testable in isolation. The pi wiring lives in `zero-cost-extension.ts`.
+
+import { formatTokens } from "./format-tokens.ts";
+
+/** The SDD phases a run is composed of, in pipeline order. */
+export const COST_PHASES = ["explore", "plan", "build", "veredicto"] as const;
+export type CostPhase = (typeof COST_PHASES)[number];
+
+/** Token + cost usage of a single sub-agent run. */
+export interface PhaseUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  turns: number;
+}
+
+/** One normalized sub-agent `meta.json` belonging to a phase. */
+export interface PhaseMeta {
+  runId: string;
+  phase: CostPhase;
+  /** Feature slug extracted from the sub-agent task, or `null`. */
+  slug: string | null;
+  model: string;
+  usage: PhaseUsage;
+  durationMs: number;
+  toolCount: number;
+  /** Epoch ms the meta was written (newest wins for selection/model). */
+  timestamp: number;
+}
+
+/** One phase row: summed usage of every sub-agent that ran that phase. */
+export interface PhaseAggregate extends PhaseUsage {
+  phase: CostPhase;
+  model: string;
+  subAgents: number;
+  durationMs: number;
+  toolCount: number;
+}
+
+/** The aggregated cost of a whole run. */
+export interface RunCost {
+  slug: string | null;
+  phases: PhaseAggregate[];
+  total: PhaseUsage & { durationMs: number; toolCount: number; subAgents: number };
+}
+
+const PHASE_INDEX: Record<CostPhase, number> = { explore: 0, plan: 1, build: 2, veredicto: 3 };
+
+/** Map a sub-agent name `zero-<phase>` to its phase, or `null`. */
+export function phaseFromAgent(agent: unknown): CostPhase | null {
+  if (typeof agent !== "string") return null;
+  const m = /^zero-(explore|plan|build|veredicto)$/.exec(agent);
+  return m ? (m[1] as CostPhase) : null;
+}
+
+/** Extract the feature slug from the first `.sdd/<slug>/` in a task string.
+ *  The internal `specs` and `archive` directories are never slugs. */
+export function extractSlug(task: unknown): string | null {
+  if (typeof task !== "string") return null;
+  const re = /\.sdd\/([A-Za-z0-9._-]+)\//g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(task)) !== null) {
+    const slug = m[1];
+    if (slug && slug !== "specs" && slug !== "archive") return slug;
+  }
+  return null;
+}
+
+function num(v: unknown): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+
+function asUsage(raw: unknown): PhaseUsage | null {
+  if (!raw || typeof raw !== "object") return null;
+  const u = raw as Record<string, unknown>;
+  // A usage object must carry at least the token fields as numbers.
+  if (typeof u.input !== "number" && typeof u.output !== "number") return null;
+  return {
+    input: num(u.input),
+    output: num(u.output),
+    cacheRead: num(u.cacheRead),
+    cacheWrite: num(u.cacheWrite),
+    cost: num(u.cost),
+    turns: num(u.turns),
+  };
+}
+
+/** Parse one raw `meta.json` object into a `PhaseMeta`, or `null` if it is not
+ *  a zero-<phase> sub-agent or lacks a usage object. */
+export function parseMeta(raw: unknown): PhaseMeta | null {
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw as Record<string, unknown>;
+  const phase = phaseFromAgent(r.agent);
+  if (!phase) return null;
+  const usage = asUsage(r.usage);
+  if (!usage) return null;
+  return {
+    runId: typeof r.runId === "string" ? r.runId : "",
+    phase,
+    slug: extractSlug(r.task),
+    model: typeof r.model === "string" ? r.model : "",
+    usage,
+    durationMs: num(r.durationMs),
+    toolCount: num(r.toolCount),
+    timestamp: num(r.timestamp),
+  };
+}
+
+/** Select the phase-metas for one run: the given slug, or — by default — the
+ *  slug whose newest meta has the greatest timestamp. Slug-less metas are
+ *  ignored for the default pick. */
+export function selectRunMetas(metas: readonly PhaseMeta[], slug?: string | null): PhaseMeta[] {
+  if (slug) return metas.filter((m) => m.slug === slug);
+  let bestSlug: string | null = null;
+  let bestTs = -Infinity;
+  for (const m of metas) {
+    if (m.slug && m.timestamp > bestTs) {
+      bestTs = m.timestamp;
+      bestSlug = m.slug;
+    }
+  }
+  if (bestSlug === null) return [];
+  return metas.filter((m) => m.slug === bestSlug);
+}
+
+/** Aggregate selected phase-metas into per-phase rows (pipeline order) plus a
+ *  run total. A phase that ran multiple sub-agents sums them; its model is the
+ *  newest meta's model. */
+export function aggregateRun(metas: readonly PhaseMeta[], slug: string | null): RunCost {
+  const byPhase = new Map<CostPhase, PhaseAggregate & { _modelTs: number }>();
+  for (const m of metas) {
+    let agg = byPhase.get(m.phase);
+    if (!agg) {
+      agg = {
+        phase: m.phase,
+        model: m.model,
+        subAgents: 0,
+        input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0,
+        durationMs: 0, toolCount: 0,
+        _modelTs: -Infinity,
+      };
+      byPhase.set(m.phase, agg);
+    }
+    agg.subAgents += 1;
+    agg.input += m.usage.input;
+    agg.output += m.usage.output;
+    agg.cacheRead += m.usage.cacheRead;
+    agg.cacheWrite += m.usage.cacheWrite;
+    agg.cost += m.usage.cost;
+    agg.turns += m.usage.turns;
+    agg.durationMs += m.durationMs;
+    agg.toolCount += m.toolCount;
+    if (m.timestamp >= agg._modelTs) {
+      agg._modelTs = m.timestamp;
+      agg.model = m.model;
+    }
+  }
+  const phases = [...byPhase.values()]
+    .sort((a, b) => PHASE_INDEX[a.phase] - PHASE_INDEX[b.phase])
+    .map(({ _modelTs, ...row }) => row);
+
+  const total = phases.reduce(
+    (t, p) => {
+      t.input += p.input; t.output += p.output; t.cacheRead += p.cacheRead;
+      t.cacheWrite += p.cacheWrite; t.cost += p.cost; t.turns += p.turns;
+      t.durationMs += p.durationMs; t.toolCount += p.toolCount; t.subAgents += p.subAgents;
+      return t;
+    },
+    { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0, durationMs: 0, toolCount: 0, subAgents: 0 },
+  );
+
+  return { slug, phases, total };
+}
+
+/** Human-readable duration: `12s`, `5m31s`. */
+export function formatDuration(ms: number): string {
+  const safe = Number.isFinite(ms) && ms > 0 ? ms : 0;
+  const totalSec = Math.round(safe / 1000);
+  const min = Math.floor(totalSec / 60);
+  const sec = totalSec % 60;
+  return min > 0 ? `${min}m${sec.toString().padStart(2, "0")}s` : `${sec}s`;
+}
+
+/** USD with two decimals: `$2.48`. */
+export function formatUsd(n: number): string {
+  const safe = Number.isFinite(n) ? n : 0;
+  return `$${safe.toFixed(2)}`;
+}
+
+/** Render an aligned per-phase + total report. */
+export function formatReport(run: RunCost): string {
+  if (run.phases.length === 0) return "zero-cost: no encontré datos de costo para ese run.";
+  const head = `zero-cost: ${run.slug ?? "(run reciente)"}`;
+  const cols = `fase       sub  in      out     cache    tools  dur     costo`;
+  const lines = [head, cols];
+  const row = (
+    label: string, subs: string, inn: number, out: number, cache: number,
+    tools: number, dur: number, cost: number,
+  ): string =>
+    `${label.padEnd(10)} ${subs.padStart(3)}  ${formatTokens(inn).padStart(6)}  ${formatTokens(out).padStart(6)}  ${formatTokens(cache).padStart(7)}  ${String(tools).padStart(5)}  ${formatDuration(dur).padStart(6)}  ${formatUsd(cost).padStart(7)}`;
+  for (const p of run.phases) {
+    lines.push(row(p.phase, String(p.subAgents), p.input, p.output, p.cacheRead, p.toolCount, p.durationMs, p.cost));
+  }
+  const t = run.total;
+  lines.push(row("TOTAL", String(t.subAgents), t.input, t.output, t.cacheRead, t.toolCount, t.durationMs, t.cost));
+  return lines.join("\n");
+}

package/extensions/zero-doctor-extension.ts

@@ -0,0 +1,42 @@
+import { createDefaultDoctorHost, formatDoctorReport, runDoctor } from "./zero-doctor.ts";
+import type { PiModel } from "./zero-models.ts";
+
+type NotifyType = "info" | "warning" | "error";
+
+interface PiCommandContext {
+  ui: { notify(message: string, type?: NotifyType): void };
+  modelRegistry?: { getAll(): PiModel[] };
+}
+
+interface PiExtensionAPI {
+  registerCommand(
+    name: string,
+    options: { description?: string; handler: (args: string, ctx: PiCommandContext) => void | Promise<void> },
+  ): void;
+}
+
+function registryModels(ctx: PiCommandContext): PiModel[] | undefined {
+  try {
+    const models = ctx.modelRegistry?.getAll?.();
+    return Array.isArray(models) ? models : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export default function register(pi?: PiExtensionAPI): void {
+  if (!pi || typeof pi.registerCommand !== "function") return;
+  pi.registerCommand("zero-doctor", {
+    description: "Diagnostica instalación, modelos, sub-agentes, git/gh y estado SDD de zero-pi",
+    handler: (_args: string, ctx: PiCommandContext): void => {
+      try {
+        const report = runDoctor(createDefaultDoctorHost(registryModels(ctx)));
+        ctx.ui.notify(formatDoctorReport(report), report.ok ? "info" : "error");
+      } catch (err) {
+        try {
+          ctx.ui.notify(`zero-doctor: ${err instanceof Error ? err.message : String(err)}`, "error");
+        } catch {}
+      }
+    },
+  });
+}

package/extensions/zero-doctor.ts

@@ -0,0 +1,291 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  groupByProvider,
+  PHASES,
+  readModels,
+  readProviders,
+  validateAssignment,
+  type PiModel,
+} from "./zero-models.ts";
+
+export type DoctorLevel = "ok" | "warn" | "fail";
+
+export interface DoctorCheck {
+  name: string;
+  level: DoctorLevel;
+  message: string;
+  hint?: string;
+}
+
+export interface DoctorReport {
+  ok: boolean;
+  checks: DoctorCheck[];
+}
+
+export interface CommandResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  error?: string;
+}
+
+export interface DoctorHost {
+  cwd: string;
+  home: string;
+  nodeVersion: string;
+  models?: readonly PiModel[];
+  exists(path: string): boolean;
+  readText(path: string): string | null;
+  listDir(path: string): string[];
+  run(command: string, args: readonly string[], cwd: string): CommandResult;
+}
+
+function currentPackageDir(): string {
+  return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+
+function readText(path: string): string | null {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function defaultRun(command: string, args: readonly string[], cwd: string): CommandResult {
+  try {
+    const out = spawnSync(command, [...args], {
+      cwd,
+      encoding: "utf8",
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+      status: out.status,
+      stdout: typeof out.stdout === "string" ? out.stdout : "",
+      stderr: typeof out.stderr === "string" ? out.stderr : "",
+      error: out.error?.message,
+    };
+  } catch (err) {
+    return { status: null, stdout: "", stderr: "", error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+export function createDefaultDoctorHost(models?: readonly PiModel[]): DoctorHost {
+  return {
+    cwd: process.cwd(),
+    home: homedir(),
+    nodeVersion: process.version,
+    models,
+    exists: existsSync,
+    readText,
+    listDir(path: string): string[] {
+      try {
+        return readdirSync(path);
+      } catch {
+        return [];
+      }
+    },
+    run: defaultRun,
+  };
+}
+
+function check(name: string, level: DoctorLevel, message: string, hint?: string): DoctorCheck {
+  return hint ? { name, level, message, hint } : { name, level, message };
+}
+
+function parseVersion(version: string): number[] {
+  return version.replace(/^v/, "").split(".").map((p) => Number.parseInt(p, 10)).map((n) => (Number.isFinite(n) ? n : 0));
+}
+
+export function versionAtLeast(version: string, minimum: string): boolean {
+  const a = parseVersion(version);
+  const b = parseVersion(minimum);
+  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    if (av > bv) return true;
+    if (av < bv) return false;
+  }
+  return true;
+}
+
+function parseJson(text: string | null): { ok: true; value: Record<string, unknown> } | { ok: false; error: string } | null {
+  if (text === null) return null;
+  try {
+    const value = JSON.parse(text);
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+      ? { ok: true, value: value as Record<string, unknown> }
+      : { ok: false, error: "JSON root is not an object" };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+function settingsPackages(settings: Record<string, unknown>): string[] {
+  const raw = settings.packages;
+  if (!Array.isArray(raw)) return [];
+  const out: string[] = [];
+  for (const entry of raw) {
+    if (typeof entry === "string") out.push(entry);
+    else if (entry && typeof entry === "object" && typeof (entry as { source?: unknown }).source === "string") out.push((entry as { source: string }).source);
+  }
+  return out;
+}
+
+function packageSourceName(source: string): string {
+  return source.replace(/^npm:/, "").replace(/@[^/@]+$/, "");
+}
+
+function hasPackageSource(packages: readonly string[], name: string): boolean {
+  return packages.some((p) => packageSourceName(p) === name || packageSourceName(p).endsWith(`/${name}`));
+}
+
+function checkNode(host: DoctorHost): DoctorCheck {
+  return versionAtLeast(host.nodeVersion, "20.6.0")
+    ? check("node", "ok", `${host.nodeVersion} (>=20.6.0)`)
+    : check("node", "fail", `${host.nodeVersion} es viejo`, "zero-pi requiere Node >=20.6.0");
+}
+
+function checkPiSubagents(host: DoctorHost, settings: Record<string, unknown> | null): DoctorCheck {
+  const installed = host.exists(join(host.home, ".pi", "agent", "npm", "node_modules", "pi-subagents", "package.json"));
+  const configured = settings ? hasPackageSource(settingsPackages(settings), "pi-subagents") : false;
+  if (installed || configured) return check("pi-subagents", "ok", installed ? "package instalado" : "declarado en settings");
+  return check(
+    "pi-subagents",
+    "fail",
+    "no lo encontré instalado ni declarado",
+    "corré: pi install npm:pi-subagents",
+  );
+}
+
+function checkZeroJson(host: DoctorHost): { check: DoctorCheck; data: Record<string, unknown> | null } {
+  const path = join(host.home, ".pi", "zero.json");
+  const parsed = parseJson(host.readText(path));
+  if (parsed === null) return { check: check("zero.json", "warn", "~/.pi/zero.json no existe", "se crea al usar /zero-models"), data: null };
+  if (!parsed.ok) return { check: check("zero.json", "fail", `JSON inválido: ${parsed.error}`), data: null };
+
+  const groups = groupByProvider(host.models ?? []);
+  const models = readModels(parsed.value);
+  const providers = readProviders(parsed.value);
+  const failures: string[] = [];
+  if (groups.size > 0) {
+    for (const phase of PHASES) {
+      const assignment = { phase, model: models[phase], provider: providers[phase] || undefined };
+      const validation = validateAssignment(assignment, groups);
+      if (!validation.ok) failures.push(`${phase}: ${validation.message}`);
+    }
+  }
+  if (failures.length > 0) return { check: check("zero.json", "fail", failures.join(" · ")), data: parsed.value };
+  return { check: check("zero.json", "ok", groups.size > 0 ? "parseable y modelos válidos" : "parseable (sin registry para validar modelos)"), data: parsed.value };
+}
+
+function checkSettings(host: DoctorHost): { check: DoctorCheck; data: Record<string, unknown> | null } {
+  const path = join(host.home, ".pi", "agent", "settings.json");
+  const parsed = parseJson(host.readText(path));
+  if (parsed === null) return { check: check("settings", "warn", "~/.pi/agent/settings.json no existe"), data: null };
+  if (!parsed.ok) return { check: check("settings", "fail", `JSON inválido: ${parsed.error}`), data: null };
+  return { check: check("settings", "ok", "parseable"), data: parsed.value };
+}
+
+function checkGeneratedAgents(host: DoctorHost): DoctorCheck {
+  const dir = join(host.home, ".pi", "agent", "agents", "zero");
+  const missing = PHASES.map((p) => `zero-${p}.md`).filter((file) => !host.exists(join(dir, file)));
+  if (missing.length === 0) return check("agents", "ok", "sub-agentes zero generados");
+  return check("agents", "warn", `faltan ${missing.join(", ")}`, "reiniciá pi para que zero-pi regenere ~/.pi/agent/agents/zero/");
+}
+
+function checkSupportModules(host: DoctorHost): DoctorCheck {
+  const dir = join(host.home, ".pi", "agent", "agents", "zero", "support");
+  const required = ["strict-tdd.md", "strict-tdd-verify.md"];
+  const missing = required.filter((file) => !host.exists(join(dir, file)));
+  if (missing.length === 0) return check("support", "ok", "Strict TDD support modules presentes");
+  return check("support", "warn", `faltan ${missing.join(", ")}`, "reiniciá pi o reinstalá zero-pi");
+}
+
+function checkSddConfig(host: DoctorHost): DoctorCheck {
+  const path = join(host.cwd, ".sdd", "config.json");
+  const parsed = parseJson(host.readText(path));
+  if (parsed === null) return check(".sdd/config", "ok", "no existe (opcional)");
+  if (!parsed.ok) return check(".sdd/config", "fail", `JSON inválido: ${parsed.error}`);
+  return check(".sdd/config", "ok", "parseable");
+}
+
+function checkZeroRuns(host: DoctorHost): DoctorCheck {
+  const path = join(host.home, ".pi", "zero-runs.jsonl");
+  const text = host.readText(path);
+  if (text === null) return check("zero-runs", "warn", "~/.pi/zero-runs.jsonl no existe todavía", "se crea después de runs /forge");
+  let lines = 0;
+  let bad = 0;
+  for (const line of text.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    lines += 1;
+    try { JSON.parse(line); } catch { bad += 1; }
+  }
+  if (bad > 0) return check("zero-runs", "warn", `${bad}/${lines} líneas no parsean como JSONL`);
+  return check("zero-runs", "ok", `${lines} records parseables`);
+}
+
+function checkGit(host: DoctorHost): DoctorCheck {
+  const root = host.run("git", ["rev-parse", "--show-toplevel"], host.cwd);
+  if (root.status !== 0) return check("git", "warn", "este cwd no parece estar dentro de un repo git", root.stderr.trim() || root.error);
+  const repoRoot = root.stdout.trim() || host.cwd;
+  const remote = host.run("git", ["remote", "get-url", "origin"], repoRoot);
+  if (remote.status === 0) return check("git", "ok", `origin: ${remote.stdout.trim()}`);
+  return check("git", "warn", "repo git sin remote origin", remote.stderr.trim() || remote.error);
+}
+
+function checkGh(host: DoctorHost): DoctorCheck {
+  const gh = host.run("gh", ["auth", "status"], host.cwd);
+  if (gh.status === 0) return check("gh", "ok", "GitHub CLI autenticado");
+  const reason = (gh.stderr || gh.stdout || gh.error || "gh auth status falló").trim().split("\n")[0];
+  return check("gh", "warn", reason || "gh auth status falló", "necesario para /zero-pr y /zero-issue");
+}
+
+function checkPackageManifest(host: DoctorHost): DoctorCheck {
+  const pkg = parseJson(host.readText(join(currentPackageDir(), "package.json")));
+  if (!pkg || !pkg.ok) return check("zero-pi package", "warn", "no pude leer package.json del paquete");
+  const version = typeof pkg.value.version === "string" ? pkg.value.version : "unknown";
+  return check("zero-pi package", "ok", `@gonrocca/zero-pi v${version}`);
+}
+
+export function runDoctor(host: DoctorHost = createDefaultDoctorHost()): DoctorReport {
+  const checks: DoctorCheck[] = [];
+  checks.push(checkPackageManifest(host));
+  checks.push(checkNode(host));
+  const settings = checkSettings(host);
+  checks.push(settings.check);
+  checks.push(checkPiSubagents(host, settings.data));
+  const zero = checkZeroJson(host);
+  checks.push(zero.check);
+  checks.push(checkGeneratedAgents(host));
+  checks.push(checkSupportModules(host));
+  checks.push(checkSddConfig(host));
+  checks.push(checkZeroRuns(host));
+  checks.push(checkGit(host));
+  checks.push(checkGh(host));
+  return { ok: checks.every((c) => c.level !== "fail"), checks };
+}
+
+function icon(level: DoctorLevel): string {
+  if (level === "ok") return "✅";
+  if (level === "warn") return "⚠️";
+  return "❌";
+}
+
+export function formatDoctorReport(report: DoctorReport): string {
+  const ok = report.checks.filter((c) => c.level === "ok").length;
+  const warn = report.checks.filter((c) => c.level === "warn").length;
+  const fail = report.checks.filter((c) => c.level === "fail").length;
+  const lines = [`zero-doctor: ${report.ok ? "ok" : "falló"} · ${ok} ok · ${warn} warn · ${fail} fail`];
+  for (const c of report.checks) {
+    lines.push(`${icon(c.level)} ${c.name}: ${c.message}`);
+    if (c.hint) lines.push(`   ↳ ${c.hint}`);
+  }
+  return lines.join("\n");
+}

package/extensions/zero-models.ts

@@ -328,6 +328,85 @@ export function groupByProvider(models: readonly PiModel[]): Map<string, string[
   return map;
 }
 
+/** Result of validating a direct `/zero-models <phase>=...` assignment
+ *  against pi's model registry. */
+export type AssignmentValidation =
+  | { ok: true; provider?: string }
+  | { ok: false; message: string };
+
+function containsModel(list: readonly string[] | undefined, model: string): boolean {
+  return Boolean(list?.includes(model));
+}
+
+function modelProviders(groups: Map<string, string[]>, model: string): string[] {
+  const providers: string[] = [];
+  for (const [provider, models] of groups) if (models.includes(model)) providers.push(provider);
+  return providers.sort();
+}
+
+function suggestModels(groups: Map<string, string[]>, model: string): string[] {
+  const needle = model.toLowerCase();
+  const scored: string[] = [];
+  for (const [provider, models] of groups) {
+    for (const id of models) {
+      const hay = id.toLowerCase();
+      if (hay.includes(needle) || needle.includes(hay)) scored.push(`${provider}/${id}`);
+    }
+  }
+  return scored.slice(0, 5);
+}
+
+/**
+ * Validate a direct assignment against pi's model registry.
+ *
+ * Empty registry = permissive fallback (old behaviour), because tests and some
+ * headless contexts may not expose `ctx.modelRegistry`. When the registry is
+ * present, the command writes only provider/model pairs pi can actually
+ * resolve. Bare ambiguous model ids are rejected with a provider-qualified hint.
+ */
+export function validateAssignment(
+  assignment: Assignment,
+  groups: Map<string, string[]>,
+): AssignmentValidation {
+  if (groups.size === 0) return { ok: true, provider: assignment.provider };
+
+  if (assignment.provider) {
+    const providerModels = groups.get(assignment.provider);
+    if (!providerModels) {
+      return {
+        ok: false,
+        message: `provider desconocido: ${assignment.provider}. Usá uno de: ${[...groups.keys()].sort().join(", ")}`,
+      };
+    }
+    if (!containsModel(providerModels, assignment.model)) {
+      const suggestions = suggestModels(groups, assignment.model);
+      return {
+        ok: false,
+        message:
+          `modelo desconocido para ${assignment.provider}: ${assignment.model}` +
+          (suggestions.length > 0 ? `. Quizás: ${suggestions.join(", ")}` : ""),
+      };
+    }
+    return { ok: true, provider: assignment.provider };
+  }
+
+  const providers = modelProviders(groups, assignment.model);
+  if (providers.length === 1) return { ok: true, provider: providers[0] };
+  if (providers.length > 1) {
+    return {
+      ok: false,
+      message: `modelo ambiguo: ${assignment.model}. Usá provider/model: ${providers.map((p) => `${p}/${assignment.model}`).join(", ")}`,
+    };
+  }
+  const suggestions = suggestModels(groups, assignment.model);
+  return {
+    ok: false,
+    message:
+      `modelo desconocido: ${assignment.model}` +
+      (suggestions.length > 0 ? `. Quizás: ${suggestions.join(", ")}` : ""),
+  };
+}
+
 /** The pi-TUI host handed to a `ctx.ui.custom()` factory — only the one
  *  method the picker shell uses. */
 interface PiTui {
@@ -706,8 +785,15 @@ export default function register(pi?: PiExtensionAPI): void {
             );
             return;
           }
+          const validation = validateAssignment(assignment, groups);
+          if (!validation.ok) {
+            ctx.ui.notify(`zero-models: ${validation.message}`, "warning");
+            return;
+          }
+
           models[assignment.phase] = assignment.model;
           providers[assignment.phase] =
+            validation.provider ??
             assignment.provider ??
             resolveProvider(ctx.modelRegistry, assignment.model) ??
             providers[assignment.phase];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonrocca/zero-pi",
-  "version": "0.1.56",
+  "version": "0.1.58",
   "description": "zero-pi — an installable layer for pi (pi.dev): the zero spec-driven development workflow (explore → plan → build → veredicto) with per-phase model autotune and token-efficient batched builds. Adds capability to pi without modifying pi.",
   "type": "module",
   "keywords": [
@@ -35,6 +35,8 @@
       "./extensions/spec-merge-extension.ts",
       "./extensions/zero-validate-extension.ts",
       "./extensions/zero-status-extension.ts",
+      "./extensions/zero-doctor-extension.ts",
+      "./extensions/zero-cost-extension.ts",
       "./extensions/zero-pr-extension.ts",
       "./extensions/zero-branch-extension.ts",
       "./extensions/zero-git-validate-extension.ts",
@@ -66,6 +68,11 @@
     "extensions/zero-validate-extension.ts",
     "extensions/zero-status.ts",
     "extensions/zero-status-extension.ts",
+    "extensions/zero-doctor.ts",
+    "extensions/zero-doctor-extension.ts",
+    "extensions/zero-cost.ts",
+    "extensions/zero-cost-extension.ts",
+    "extensions/format-tokens.ts",
     "extensions/pr-body.ts",
     "extensions/sdd-links.ts",
     "extensions/sdd-config.ts",