@cristobalbn/chaski 0.0.0-stage → 0.1.0

package/src/inject.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// Hook de inyección. Lo ejecutan los tres CLIs al arrancar una sesión.
+//
+// Lo que este script imprime por stdout entra al contexto del agent, así que
+// es la única parte de chaski que está en el camino crítico. Reglas:
+//   - Presupuesto duro de tamaño: por encima de 10.000 caracteres el CLI
+//     reemplaza el contenido por una ruta y el relevo no llega.
+//   - Si no hay relevo, no imprime nada. Un agent no debe recibir ruido.
+//   - Si la signature no valida, imprime igual pero rotulado: fallar en silencio
+//     dejaría al usuario creyendo que funciona.
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { relayPath, statePath, readJson, currentBranch, git, projectDir } from './lib/paths.mjs';
+import { preamble, CLOSING_MARK, isValidSignature, render, MAX_CHARS } from './lib/relay.mjs';
+import { createBudget, SESSION_START_BUDGET_MS } from './lib/budget.mjs';
+
+main();
+
+function main() {
+  // Mismo mecanismo que capture.mjs (ver lib/budget.mjs), aplicado aquí
+  // porque este es el único código de chaski en el camino crítico: lo que
+  // imprime entra al contexto antes de que el usuario pueda escribir. Las
+  // llamadas a git de detectDrift están medidas como baratas incluso en
+  // casos extremos (ver auditoría), pero el presupuesto de 4.000 ms por
+  // llamada tampoco se justificaba aquí solo, por la misma razón que en
+  // capture.mjs: ningún timeout por llamada protege si nadie lo deriva de
+  // cuánto queda.
+  const budget = createBudget(SESSION_START_BUDGET_MS);
+  try {
+    const cwd = projectDir(cwdFromPayload());
+    const ramaActual = currentBranch(cwd, budget);
+    const ruta = relayPath(cwd, ramaActual);
+    if (!existsSync(ruta)) return;
+
+    let md = readFileSync(ruta, 'utf8');
+    if (!md.trim()) return;
+
+    const estado = readJson(statePath(cwd, ramaActual), {}) ?? {};
+    let verificado = estado.signature ? isValidSignature(md, estado.signature) : false;
+
+    // El Markdown se renderiza al capturar, así que una narrative escrita
+    // después —con /relevo— no aparece hasta la captura siguiente. Si la
+    // sesión se corta justo ahí, se perdería lo más valioso del relevo. Si el
+    // estado trae una narrative que el Markdown no tiene, se re-renderiza.
+    if (estado.narrative && !md.includes(estado.narrative.trim().slice(0, 60))) {
+      md = render(estado);
+      // No asumir "verificado" porque viene del mismo estado.json: quien
+      // puede escribirlo ya podía inyectar texto editando relevo.md, y ahí
+      // el aviso de "no verificado" sí aparece. Si no se recalcula aquí, lo
+      // único que se gana es suprimir el rótulo justo cuando dos personas
+      // comparten .tambo/ con claves distintas — el caso para el que existe
+      // la firma.
+      verificado = estado.signature ? isValidSignature(md, estado.signature) : false;
+    }
+
+    const partes = [preamble(estado, verificado), '', md];
+
+    // Si el repo se movió desde que se escribió el relevo, hay que decirlo:
+    // un relevo desactualizado presentado como verdad es peor que nada.
+    const deriva = detectDrift(cwd, estado, budget, ramaActual);
+    if (deriva) partes.push('', deriva);
+
+    partes.push('', CLOSING_MARK);
+
+    let salida = partes.join('\n');
+    if (salida.length > MAX_CHARS + 1200) {
+      salida = salida.slice(0, MAX_CHARS + 1000) + '\n\n_[Recortado.]_\n' + CLOSING_MARK;
+    }
+    process.stdout.write(emitir(salida, process.argv[3]));
+  } catch (e) {
+    process.stderr.write(`chaski: no se pudo inyectar el relevo (${e?.message ?? e})\n`);
+  } finally {
+    process.exitCode = 0;
+  }
+}
+
+function cwdFromPayload() {
+  let ev = {};
+  try { ev = JSON.parse(readFileSync(0, 'utf8')) || {}; } catch {}
+  // Antigravity usa camelCase y manda un array de rutas de workspace en vez
+  // de un cwd. Documentado en su contrato de hooks.
+  const ws = Array.isArray(ev.workspacePaths) ? ev.workspacePaths[0] : null;
+  return ev.cwd ?? ws ?? ev.workspace ?? ev.project_dir ?? process.cwd();
+}
+
+/**
+ * Cada CLI espera un formato de salida distinto en el hook de inicio:
+ *
+ *   - Claude Code y Codex: texto plano, que se agrega al contexto.
+ *   - Antigravity: un objeto JSON con `injectSteps`. Si se le manda texto
+ *     plano no inyecta nada — falla en silencio, que es el peor caso.
+ */
+function emitir(texto, agent) {
+  if (/^agy$/i.test(agent ?? '')) {
+    return JSON.stringify({
+      injectSteps: [{ systemMessage: { systemMessage: texto } }],
+    }) + '\n';
+  }
+  return texto + '\n';
+}
+
+/** ¿Cambió el repo desde que se escribió el relevo? */
+function detectDrift(cwd, estado, budget = null, rama = undefined) {
+  const avisos = [];
+
+  const ramaActual = rama === undefined ? currentBranch(cwd, budget) : rama;
+  if (estado.facts?.branch && ramaActual && estado.facts.branch !== ramaActual) {
+    avisos.push(`- El relevo se escribió en \`${estado.facts.branch}\` y ahora estás en \`${ramaActual}\`.`);
+  }
+
+  const edadHoras = estado.writtenAt ? (Date.now() - new Date(estado.writtenAt).getTime()) / 3600000 : 0;
+  if (edadHoras > 24) {
+    avisos.push(`- Tiene ${Math.round(edadHoras / 24)} día(s) de antigüedad.`);
+  }
+
+  avisos.push(...changesSinceRelay(cwd, estado, budget));
+
+  if (!avisos.length) return null;
+  return [
+    '**ATENCIÓN: el repositorio cambió desde este relevo.**',
+    ...avisos,
+    '',
+    'Verifica contra el código antes de actuar sobre lo que dice este relevo.',
+  ].join('\n');
+}
+
+/**
+ * Qué pasó en el repositorio desde que se escribió el relevo.
+ *
+ * El caso que motiva esto: alguien se va una semana, su compañero sigue
+ * trabajando y hasta termina lo que había quedado a medias. El relevo sigue
+ * afirmando que falta, y el agent nuevo podría rehacerlo. Avisar "el
+ * repositorio cambió" no alcanza: hay que decir QUÉ cambió, QUIÉN lo hizo y,
+ * sobre todo, si toca los archivos que la narrative declara pendientes.
+ */
+function changesSinceRelay(cwd, estado, budget = null) {
+  const avisos = [];
+  const head = git(cwd, ['rev-parse', '--short', 'HEAD'], { budget });
+  if (!estado.head || !head || estado.head === head) return avisos;
+
+  // Si el commit del relevo ya no existe, la historia se reescribió
+  // (rebase, squash, fuerza). Nada de lo que sigue es comparable.
+  const existe = git(cwd, ['cat-file', '-e', `${estado.head}^{commit}`], { budget }) !== null;
+  if (!existe) {
+    avisos.push(`- El commit del relevo (\`${estado.head}\`) ya no existe: la historia se reescribió.`);
+    avisos.push('  Trata todo este relevo como una hipótesis y verifica cada punto.');
+    return avisos;
+  }
+
+  const rango = `${estado.head}..HEAD`;
+  const log = git(cwd, ['log', rango, '--format=%h|%an|%s'], { budget }) ?? '';
+  const commits = log.split('\n').filter(Boolean).map((l) => {
+    const [h, autor, ...resto] = l.split('|');
+    return { h, autor, asunto: resto.join('|') };
+  });
+
+  if (commits.length) {
+    const autores = [...new Set(commits.map((c) => c.autor))];
+    avisos.push(`- ${commits.length} commit(s) nuevo(s) desde entonces, de: ${autores.join(', ')}.`);
+    for (const c of commits.slice(0, 6)) {
+      avisos.push(`    \`${c.h}\` ${c.autor}: ${c.asunto.slice(0, 70)}`);
+    }
+    if (commits.length > 6) avisos.push(`    … y ${commits.length - 6} más`);
+  }
+
+  // Lo importante: ¿alguien tocó lo que la narrative dice que está pendiente?
+  // `--name-only` compara árboles, no contenido: a diferencia de `--numstat`
+  // en facts.mjs, no escala con el tamaño del diff. Medido con 10.000
+  // archivos cambiados en un commit: ~50 ms.
+  const tocados = new Set((git(cwd, ['diff', '--name-only', rango], { budget }) ?? '')
+    .split('\n').filter(Boolean));
+  const mencionados = mentionedPaths(estado.narrative);
+  const collisions = mencionados.filter((r) =>
+    [...tocados].some((t) => t === r || t.endsWith('/' + r) || r.endsWith('/' + t)));
+
+  if (collisions.length) {
+    avisos.push('');
+    avisos.push('- **Archivos que este relevo menciona y que ya cambiaron desde entonces:**');
+    for (const r of collisions.slice(0, 8)) avisos.push(`    \`${r}\``);
+    avisos.push('  Es posible que lo que el relevo declara pendiente ya esté resuelto.');
+    avisos.push('  Léelos antes de retomar: no rehagas trabajo ya hecho.');
+  }
+
+  return avisos;
+}
+
+/**
+ * Archivos que la narrative menciona.
+ *
+ * Reconoce `src/auth/refresh.ts`, `src/auth/refresh.ts:41` y también
+ * `refresh.ts` a secas, porque una narrative escrita a mano no siempre pone
+ * la ruta completa. Los falsos positivos no importan: el resultado se cruza
+ * contra los archivos que git dice que cambiaron, así que una palabra con
+ * punto que no sea un archivo no sobrevive al cruce.
+ */
+function mentionedPaths(narrative) {
+  if (!narrative) return [];
+  const re = /\b((?:[\w.@-]+\/)*[\w.-]+\.[a-zA-Z0-9]{1,8})(?::\d+)?\b/g;
+  return [...new Set([...String(narrative).matchAll(re)].map((m) => m[1]))].slice(0, 30);
+}

package/src/leer.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Puente de compatibilidad. Este archivo se llamaba así antes de que el código
+// se homologara al inglés, y `leer.mjs` pasó a ser `inject.mjs`.
+//
+// El motivo completo está en `capturar.mjs`, el otro puente. En resumen: los
+// hooks guardan la ruta absoluta del script en una configuración que vive
+// fuera del repositorio, así que quien actualiza chaski sin volver a correr
+// `chaski init` sigue invocando este nombre.
+//
+// Este sí avisa, porque corre una vez por sesión y no una vez por turno. El
+// aviso va por stderr y NUNCA por stdout: lo que este script imprime por
+// stdout entra al contexto del agent, y una línea de más ahí es ruido que el
+// agent trata como dato.
+process.stderr.write(
+  'chaski: tus hooks apuntan a un nombre de archivo antiguo (leer.mjs). '
+  + 'Funciona igual, pero ejecuta `chaski init` para actualizarlos.\n',
+);
+
+await import('./inject.mjs');

package/src/lib/ask.mjs

@@ -0,0 +1,194 @@
+// Cuándo pedirle al agent que escriba la narrativa, y cómo pedírselo.
+//
+// El modo manual tiene un defecto estructural, no de disciplina del usuario:
+// la narrativa la escribe el agent, así que **necesita cuota**. Quien espera a
+// estar al límite descubre que el momento en que más la necesita es justo
+// aquel en que ya no se puede generar. Y el corte por cuota es abrupto: deja
+// una tarea a medias y un relevo que solo tiene hechos, sin el porqué ni el
+// siguiente paso, que es lo único que no se deriva de git.
+//
+// La solución no es recordárselo mejor al usuario: es pedirla **temprano y
+// repartida**, cuando todavía hay cuota de sobra. Así nunca depende del final.
+//
+// Cómo: el hook `Stop` de Claude Code acepta `{decision:"block", reason}`, que
+// mantiene al agent trabajando con una instrucción más. No se invoca ningún
+// modelo por fuera —los términos de los tres proveedores lo prohíben para
+// suscripciones de consumidor, ver el invariante 5— sino que se le pide al
+// agent que YA está en sesión. Es uso interactivo, y además es técnicamente
+// mejor que una llamada externa: ese agent tiene la conversación en contexto y
+// en caché, así que sabe lo que ningún proceso aparte podría reconstruir.
+//
+// El costo es real y hay que respetarlo: cada disparo agrega un turno a la
+// conversación del usuario. Un hook que bloqueara en cada `Stop` duplicaría
+// sus turnos y sería insufrible, así que el debounce no es un ajuste fino sino
+// una condición de usabilidad.
+
+/** Minutos mínimos entre dos peticiones, para no agregar un turno cada rato. */
+export const DEBOUNCE_MIN = 12;
+
+/** Turnos de trabajo mínimos desde la última narrativa antes de volver a pedir. */
+export const TURNOS_MIN = 8;
+
+/**
+ * Minutos que una narrativa se considera fresca. Mientras lo sea, no se vuelve
+ * a pedir ni aunque haya commits nuevos.
+ *
+ * Sin esto, una sesión que mergea tres PR seguidos recibía una petición por
+ * merge: cada uno mueve el HEAD, y "hay commits nuevos" disparaba aunque la
+ * narrativa fuera de hace un minuto y siguiera siendo exacta. El usuario lo
+ * vio como un mensaje después de cada prompt, que es justo el modo de fallo
+ * que el debounce existe para evitar.
+ */
+export const NARRATIVA_FRESCA_MIN = 20;
+
+/**
+ * ¿Hay que pedir la narrativa en este `Stop`?
+ *
+ * Devuelve `null` si no, o el motivo (string corto) si sí. El motivo entra en
+ * el texto que lee el agent, así que explica POR QUÉ se le pide ahora.
+ *
+ * @param ev      payload del hook
+ * @param estado  el estado que se acaba de calcular para este turno
+ * @param previo  el estado del turno anterior
+ * @param config  configuración mezclada del proyecto
+ * @param ahora   Date.now() inyectable, para poder probar sin esperar
+ */
+export function shouldAsk(ev, estado, previo, config, ahora = Date.now()) {
+  // Apagable. Quien no quiera un turno extra nunca, pone `askNarrative: false`.
+  if (config?.askNarrative === false) return null;
+
+  // Los tres soportan mantener al agent un turno más, pero NO con el mismo
+  // contrato (ver `askPayload`). Un CLI desconocido no se intenta.
+  if (!askPayload(estado.agent, '')) return null;
+
+  // Protección contra bucles. Sin esto, un hook que bloquea vuelve a
+  // bloquear en el turno que él mismo provocó, y no termina nunca.
+  //
+  // Claude Code y Codex traen `stop_hook_active` justamente para esto.
+  // Antigravity no documenta nada equivalente: trae `executionNum`, que
+  // cuenta las vueltas del bucle del agent, y un tope propio de
+  // continuaciones forzadas cuyo valor no está documentado. Así que ahí la
+  // protección la pone chaski: solo se pide en la primera vuelta.
+  if (ev.stop_hook_active) return null;
+  if (Number(ev.executionNum ?? 1) > 1) return null;
+
+  // Un `Stop` sin trabajo detrás no necesita narrativa: no hay nada que
+  // contar y el turno extra sería puro ruido.
+  const hechos = estado.facts ?? {};
+  const sucios = Array.isArray(hechos.dirty) ? hechos.dirty.length : 0;
+  const commitsNuevos = previo?.head && estado.head && previo.head !== estado.head;
+  if (!sucios && !commitsNuevos && !estado.commands?.length) return null;
+
+  // Debounce. Se guarda en el estado, así que sobrevive al reinicio del
+  // proceso: el hook corre de cero en cada turno y no tiene memoria propia.
+  const ultima = previo?.askedAt ? Date.parse(previo.askedAt) : 0;
+  if (ultima && (ahora - ultima) / 60000 < DEBOUNCE_MIN) return null;
+
+  // Sin narrativa todavía: es el caso que más duele, porque un corte deja el
+  // relevo con hechos y sin intención.
+  if (!estado.narrative) return 'el relevo todavía no tiene narrativa';
+
+  // Una narrativa recién escrita no se vuelve a pedir, pase lo que pase. Es
+  // el corte más fuerte y va primero: lo que hace insufrible a esta función no
+  // es pedirla de más en una sesión larga, es pedirla dos veces seguidas.
+  const edadNarrativa = estado.narrativeWrittenAt
+    ? (ahora - Date.parse(estado.narrativeWrittenAt)) / 60000 : Infinity;
+  if (edadNarrativa < NARRATIVA_FRESCA_MIN) return null;
+
+  // Narrativa que quedó atrás. Se mide en turnos de trabajo y en commits, no
+  // en tiempo: una sesión larga sin cambios no necesita reescribirla.
+  // Si cambió la sesión o el contador previo quedó por encima del actual tras
+  // un reinicio de sesión, la cuenta parte desde cero en la sesión nueva.
+  const mismaSesion = !previo?.session || !estado?.session || previo.session === estado.session;
+  const baseTurns = mismaSesion && (previo?.turnsAtNarrative ?? 0) <= (estado.turns ?? 0)
+    ? (previo?.turnsAtNarrative ?? 0) : 0;
+  const turnosDesde = (estado.turns ?? 0) - baseTurns;
+  if (commitsNuevos) return 'hay commits nuevos desde la última narrativa';
+  if (turnosDesde >= TURNOS_MIN) return `van ${turnosDesde} turnos desde la última narrativa`;
+
+  return null;
+}
+
+/**
+ * El texto de la petición.
+ *
+ * Tiene DOS lectores con necesidades opuestas, y ahí estaba el problema: el
+ * agent necesita saber cómo escribir la narrativa, y el usuario —que lo ve en
+ * pantalla, porque el CLI lo muestra— solo necesita saber qué está pasando.
+ * Mezclarlo le dejaba al usuario nombres de campo y rutas de archivo que no le
+ * sirven de nada. Sus palabras: «queda como raro, muy técnico para el
+ * usuario».
+ *
+ * Así que el cómo se delega a la skill, que es del agent y no se ve en
+ * pantalla. El mensaje visible queda en una línea legible.
+ *
+ * La parte técnica solo aparece cuando el agent no tiene la skill disponible
+ * en su sesión, porque ahí es la única forma de que la petición sea accionable.
+ * Es el caso raro pagando su propio costo, en vez de que lo pague el normal.
+ *
+ * Nada de marcos tipo «orden del sistema»: la documentación de los hooks avisa
+ * que un texto así puede activar las defensas contra inyección de prompts del
+ * propio modelo.
+ */
+export function askText(motivo, haySkill = true) {
+  const linea = `chaski: antes de cerrar, guarda el relevo de este trabajo — ${motivo}.`;
+  if (haySkill) return `${linea} Usa la skill \`relevo\`.`;
+  return [
+    linea,
+    'Anota qué quedó a medias y dónde, qué descartaste y el siguiente paso, en',
+    'los campos `narrative`, `narrativeAuthor` y `narrativeWrittenAt` de',
+    '`.tambo/branches/<rama>/estado.json` en la raíz del repositorio. No edites `relevo.md`.',
+  ].join('\n');
+}
+
+/**
+ * El objeto que hay que imprimir por stdout para que el agent siga un turno
+ * más, en el contrato de SU CLI. Devuelve `null` para un CLI desconocido.
+ *
+ * Los tres lo soportan, y ninguno igual. La diferencia que más importa es la
+ * de Antigravity: su clave es `"continue"`, y su documentación dice que
+ * **cualquier otro valor permite parar**. Así que imprimirle el `"block"` de
+ * Claude Code no da error — simplemente no hace nada, en silencio, que es el
+ * peor modo de fallo posible para esta herramienta. Por eso la salida se arma
+ * por CLI y no se comparte.
+ *
+ * Verificado contra la documentación de cada uno, no en vivo: la primera
+ * sesión real de cada CLI es la verificación de verdad. El riesgo de
+ * equivocarse es bajo y asimétrico: si el contrato estuviera mal, el agent
+ * termina el turno como siempre y se pierde la petición, no el relevo.
+ */
+export function askPayload(agent, reason) {
+  const a = String(agent ?? '').toLowerCase();
+
+  // Claude Code: `additionalContext` y NO `decision: "block"`.
+  //
+  // Los dos mantienen al agent un turno más y los dos respetan
+  // `stop_hook_active` y el tope de continuaciones. La diferencia es cómo se
+  // presenta: con `block`, la interfaz rotula la respuesta como **«Stop hook
+  // error»** —la misma palabra que usa para un hook que de verdad falló— y el
+  // usuario ve un error en cada petición. Con `additionalContext` el rótulo es
+  // «Stop hook feedback». La documentación lo llama literalmente «non-error
+  // feedback for Claude».
+  //
+  // El usuario lo reportó dos veces: «la palabra error no es bonita verla en
+  // ninguno caso y menos para un usuario». Y tenía razón más allá de la
+  // estética: en una herramienta publicada, un error aparente en cada turno
+  // dice que está rota.
+  //
+  // No se combinan los dos campos: la documentación no dice qué rótulo saldría.
+  if (/^claude/.test(a)) {
+    return { hookSpecificOutput: { hookEventName: 'Stop', additionalContext: reason } };
+  }
+
+  // Codex: `decision: "block"`, y el `reason` se convierte en el prompt de
+  // continuación. Su documentación no describe un equivalente de
+  // `additionalContext` para `Stop`, así que aquí el formato se queda.
+  if (a === 'codex') return { decision: 'block', reason };
+
+  // Antigravity: `continue` bloquea el stop y reentra al bucle; el `reason` se
+  // inyecta como mensaje de sistema. Su documentación dice que **cualquier otro
+  // valor permite parar**, así que mandarle el `"block"` de Claude Code no
+  // daría error: no haría nada, en silencio, el peor modo de fallo posible.
+  if (a === 'agy' || a === 'antigravity') return { decision: 'continue', reason };
+  return null;
+}

package/src/lib/budget.mjs

@@ -0,0 +1,64 @@
+// Presupuesto de tiempo del hook.
+//
+// El hook `Stop` de Claude Code comparte 1,5 s con los demás hooks del mismo
+// evento, que no controlamos. Antes de este módulo no existía ningún reloj:
+// el único timeout era el de cada llamada a `git()` (4.000 ms), mayor que el
+// presupuesto entero, así que no protegía nada — una sola llamada cara (un
+// `diff --numstat` sobre miles de archivos) podía agotar el hook completo sin
+// que nada se lo impidiera, y el relevo del turno se perdía entero.
+//
+// La solución es doble a propósito, y las dos mitades son necesarias:
+//   - Un reloj GLOBAL desde el arranque del hook, contra el que cada paso
+//     consulta cuánto queda ANTES de lanzar un subproceso. Esto es lo que
+//     permite decidir qué omitir cuando no cabe todo (ver gitFacts en
+//     facts.mjs), y es barato: un Date.now(), nada de spawnear nada.
+//   - Un timeout por llamada DERIVADO de lo que queda del reloj global. Es
+//     la red de seguridad para cuando la estimación de costo de un paso
+//     resultó optimista (disco lento, antivirus, OneDrive bloqueando el
+//     archivo): ninguna llamada individual puede ya exceder el presupuesto
+//     completo, porque su timeout nunca es mayor que lo que queda.
+export const STOP_HOOK_BUDGET_MS = 1100; // de 1.500 ms compartidos, deja ~400 ms (27%) para los demás hooks del evento
+
+// inject.mjs no tiene un presupuesto compartido documentado como el de Stop,
+// pero es "el único código en el camino crítico" (ver inject.mjs): el usuario
+// espera a que termine antes de poder escribir. Medido: sus llamadas a git
+// son baratas por construcción (usan `--name-only`, nunca `--numstat`, así
+// que no escalan con el tamaño del diff) incluso con 3.000 commits o 10.000
+// archivos cambiados en un rango. Este presupuesto es la misma red de
+// seguridad por si el día de mañana aparece un caso que sí escale mal -- no
+// es una resta de un límite externo conocido, como sí lo es el de Stop.
+export const SESSION_START_BUDGET_MS = 800;
+
+// Una llamada a la que le queda menos que esto no vale la pena intentarla:
+// el costo fijo de spawnear git (medido: 20-40 ms en Windows) ya se la come.
+export const MIN_GIT_CALL_MS = 60;
+
+/** Reloj de un solo uso para un presupuesto de `ms` desde este instante. */
+export function createBudget(ms) {
+  const inicio = Date.now();
+  const limite = inicio + ms;
+  return {
+    remaining() { return limite - Date.now(); },
+    expired() { return Date.now() >= limite; },
+    elapsed() { return Date.now() - inicio; },
+  };
+}
+
+/** ¿Queda tiempo suficiente para intentar un paso de costo mínimo `piso`? */
+export function hasTime(budget, piso = MIN_GIT_CALL_MS) {
+  return !budget || budget.remaining() > piso;
+}
+
+/**
+ * El timeout que de verdad debe usar una llamada: nunca más que lo que queda
+ * del presupuesto global, aunque quien llama haya pedido más.
+ *
+ * Separado de `git()` a propósito, para poder probarlo sin spawnear nada: la
+ * alternativa (reintroducir el bug a mano para verificar el test) necesitaría
+ * un comando real lo bastante lento como para notar la diferencia, lo que
+ * vuelve el test lento y frágil entre máquinas. Esta función aislada se
+ * prueba con un presupuesto falso, sin spawnear ni esperar nada.
+ */
+export function effectiveTimeout(timeout, budget) {
+  return budget ? Math.min(timeout, budget.remaining()) : timeout;
+}