shilo-cli 0.6.0 → 0.8.0

package/src/commands/push.js

@@ -21,7 +21,14 @@ const {
 const { ShiloClient } = require('../ShiloClient');
 
 const DEFAULT_BASE_URL = 'https://www.shilo.city';
-const COMMIT_BATCH = 100; // máximo de archivos por commit (límite del backend)
+const COMMIT_BATCH = 100; // máximo de archivos por commit (límite del backend, camino anterior)
+
+// Techos de una propuesta (los del endpoint /api/projects/proposals). Un texto
+// más grande que PROPOSAL_INLINE_MAX no va inline: se inventaría por URL
+// firmada, como un binario, y entra por su oid.
+const PROPOSAL_MAX_CHANGES = 500;
+const PROPOSAL_INLINE_MAX = 1024 * 1024;
+const PROPOSAL_MAX_BYTES = 4 * 1024 * 1024; // el server corta en 5 MB; margen
 
 // Cuánto se lee de cada archivo en el preflight: alcanza para decidir binario
 // (looksBinary mira 8000 bytes) y para escanear secretos, sin cargar el repo
@@ -29,6 +36,11 @@ const COMMIT_BATCH = 100; // máximo de archivos por commit (límite del backend
 const HEAD_BYTES = 8192;
 
 // Cuántos ejemplos se muestran por cada motivo de salteo.
+// Techo por campo del bloque `agent` y del prompt (Etapa 4, puntos 1 y 2). El
+// del prompt es el mismo que aplica el servidor: avisar acá ahorra el viaje.
+const AGENT_FIELD_MAX = 200;
+const PROMPT_MAX_BYTES = 64 * 1024;
+
 const SKIP_EXAMPLES = 5;
 // A partir de cuántos salteos en una misma carpeta de primer nivel sugerimos
 // ignorarla entera.
@@ -142,6 +154,61 @@ function preflight(dir) {
   return { uploads, skipped: skips, ignored, gitDirs, findings };
 }
 
+/**
+ * Aplica los selectores de `--only` sobre los archivos que dejó el preflight.
+ *
+ * Cada selector se normaliza con `sync.toRepoPath`, que ya blinda contra salir
+ * de la carpeta, y matchea por igualdad exacta o como prefijo de carpeta
+ * (`Documentacion/` alcanza todo lo de adentro).
+ *
+ * Un selector que no matchea nada es ERROR, no un push silencioso de todo:
+ * confundir "no subí nada de lo que pedí" con "subí el repo entero" es
+ * exactamente el fallo que arruinaría la confianza en el flag.
+ *
+ * Devuelve `{ uploads, leftOut }` o `{ error }`.
+ */
+function selectUploads(dir, allUploads, only) {
+  const selectors = (Array.isArray(only) ? only : only ? [only] : [])
+    .map((s) => String(s).trim())
+    .filter(Boolean);
+
+  if (selectors.length === 0) return { uploads: allUploads, leftOut: [] };
+
+  const normalized = [];
+  for (const raw of selectors) {
+    const repoPath = sync.toRepoPath(dir, raw);
+    if (!repoPath) return { error: `--only "${raw}" queda fuera de la carpeta del push.` };
+    normalized.push({ raw, repoPath });
+  }
+
+  const matched = new Set();
+  const uploads = [];
+  const leftOut = [];
+
+  for (const u of allUploads) {
+    const hit = normalized.find(
+      (s) => u.relPath === s.repoPath || u.relPath.startsWith(`${s.repoPath}/`)
+    );
+    if (hit) {
+      matched.add(hit.repoPath);
+      uploads.push(u);
+    } else {
+      leftOut.push(u);
+    }
+  }
+
+  const misses = normalized.filter((s) => !matched.has(s.repoPath));
+  if (misses.length > 0) {
+    return {
+      error:
+        `--only no encontró nada para: ${misses.map((s) => `"${s.raw}"`).join(', ')}. ` +
+        `Puede estar ignorado, salteado, o escrito distinto; nada se subió.`,
+    };
+  }
+
+  return { uploads, leftOut };
+}
+
 /**
  * Reporte agrupado de salteos. Un repo con un `venv/` adentro generaba miles de
  * líneas "saltado …" que tapaban todo lo demás; acá se resume por motivo, con
@@ -237,9 +304,11 @@ function neededFolders(relPaths) {
  * shilo push [carpeta] [--project <uuid>] [-m <msg>] [--dry-run] [--yes]
  *            [--allow-secrets] [--concurrency <n>] [--no-index] [--verbose]
  *
- * Replica una carpeta local a un repo de Shilo: crea archivos nuevos, actualiza
- * los que cambiaron, salta binarios/oversize/nombres inválidos, y registra todo
- * en uno o más commits.
+ * Replica una carpeta local a un repo de Shilo: crea archivos nuevos y actualiza
+ * los que cambiaron. Desde la Etapa 3 lo hace como PROPUESTA: el servidor la
+ * aplica si combina limpio con la versión actual, y si otra persona cambió
+ * alguno de los mismos archivos la deja abierta sin pisar nada. Con un servidor
+ * anterior cae al camino viejo (escribir + commit), que sí puede pisar.
  */
 async function push(args) {
   const dir = path.resolve(args._[0] || '.');
@@ -283,8 +352,26 @@ async function push(args) {
     return 1;
   }
 
+  // Procedencia (Etapa 4, punto 1). Sin --agent no se manda bloque alguno y el
+  // guardado queda como escrito por una persona, que es la verdad.
+  const agent = buildAgent(args);
+  if (agent && agent.error) {
+    ui.error(agent.error);
+    return 1;
+  }
+
+  const promptRead = readPrompt(args, agent);
+  if (promptRead.error) {
+    ui.error(promptRead.error);
+    return 1;
+  }
+  for (const w of promptRead.warnings) ui.warn(w);
+  const promptText = promptRead.prompt;
+
   // 3) PREFLIGHT: todo offline. Recién después de esto se toca la red.
-  const { uploads, skipped, ignored, gitDirs, findings } = preflight(dir);
+  //    `allUploads` es la carpeta entera; `--only` recorta DESPUÉS (ver 3b),
+  //    para que los ignores y el escáner de secretos corran igual siempre.
+  const { uploads: allUploads, skipped, ignored, gitDirs, findings } = preflight(dir);
 
   if (gitDirs.length > 0) {
     ui.warn(
@@ -311,12 +398,23 @@ async function push(args) {
     );
   }
 
-  if (uploads.length === 0) {
+  if (allUploads.length === 0) {
     ui.info('No hay archivos para subir.');
     ui.info(ui.c.dim(`(${ignored} ignorados, ${skipped.length} salteados)`));
     return 0;
   }
 
+  // 3b) `--only`: recorta QUÉ se sube, no qué se mira. El push nunca borra
+  //     archivos remotos (su plan es added/modified/unchanged/failed), así que
+  //     subir un subconjunto es seguro por construcción: no hay semántica nueva.
+  const selection = selectUploads(dir, allUploads, args.only);
+  if (selection.error) {
+    ui.error(selection.error);
+    return 1;
+  }
+  const uploads = selection.uploads;
+  const leftOut = selection.leftOut;
+
   // 4) Cliente + control de ritmo. `onThrottle` baja la concurrencia sola si el
   //    servidor empieza a responder 429, en vez de insistir hasta que corte.
   const limit = sync.resolveConcurrency(args);
@@ -504,30 +602,9 @@ async function push(args) {
 
   config.persistCredsIfChanged(cfg, mgr.current);
 
-  // 5d) Atribución: para los archivos que vamos a pisar, quién los tocó último.
-  //     Es lo que distingue "esto lo subí yo antes" de "esto lo va a perder un
-  //     compañero". Best-effort: si el historial no se puede leer, seguimos.
-  let attribution = { index: new Map() };
+  // Con token de acceso personal no sabemos el id del usuario; sólo importa
+  // para reconocer propuestas propias que este push reemplaza.
   const myId = cfg.credentials && cfg.credentials.user ? cfg.credentials.user.id : null;
-  if (plan.modified.length > 0) {
-    attribution = await sync.buildAuthorIndex(client, projectId, mgr, { commits: 50 });
-    config.persistCredsIfChanged(cfg, mgr.current);
-  }
-
-  /** Etiqueta " — última edición de X, fecha" para un archivo del plan. */
-  const authorNote = (u) => {
-    const meta = u.remote && attribution.index.get(u.remote.id);
-    if (!meta) return '';
-    const mine = myId && meta.authorId && meta.authorId === myId;
-    const who = mine ? ui.c.dim('vos') : ui.c.bold(meta.author);
-    return ui.c.dim(' — última edición de ') + who + ui.c.dim(`, ${sync.formatDate(meta.date)}`);
-  };
-
-  /** ¿El último que tocó este archivo fue otra persona? */
-  const touchedByOthers = plan.modified.filter((u) => {
-    const meta = u.remote && attribution.index.get(u.remote.id);
-    return meta && meta.authorId && myId && meta.authorId !== myId;
-  });
 
   // 6) Reporte del plan.
   ui.info('');
@@ -545,45 +622,25 @@ async function push(args) {
       for (const f of plan.failed) ui.error(`${f.relPath} — ${f.reason}`);
       return 1;
     }
-    if (useIndex && !dryRun) saveIndex(dir, index, plan, uploads);
+    if (useIndex && !dryRun) saveIndex(dir, index, plan, allUploads);
     ui.success('Todo al día. Nada para subir.');
+    reportLeftOut(leftOut, remoteByPath);
     return 0;
   }
 
   if (dryRun) {
     for (const u of plan.added) ui.info(`  ${ui.c.green('+')} ${u.relPath}`);
-    for (const u of plan.modified) ui.info(`  ${ui.c.yellow('~')} ${u.relPath}${authorNote(u)}`);
+    for (const u of plan.modified) ui.info(`  ${ui.c.yellow('~')} ${u.relPath}`);
     for (const f of plan.failed) ui.info(`  ${ui.c.red('!')} ${f.relPath} — ${f.reason}`);
     ui.info('');
-    if (!myId && plan.modified.length > 0 && attribution.index.size > 0) {
-      ui.info(
-        ui.c.dim(
-          '(con token de acceso personal no sabemos tu id de usuario: ' +
-            'el autor se muestra, pero no se marca cuál sos vos)'
-        )
-      );
-      ui.info('');
-    }
-    if (touchedByOthers.length > 0) {
-      ui.warn(
-        `${touchedByOthers.length} de esos archivos los editó otra persona: ` +
-          `este push pisaría su versión.`
-      );
-      ui.info(ui.c.dim('Revisalos con "shilo diff <archivo>" o traelos con "shilo pull".'));
-      ui.info('');
-    }
+    reportLeftOut(leftOut, remoteByPath);
     ui.info(ui.c.dim('(--dry-run: no se subió nada)'));
     return plan.failed.length ? 1 : 0;
   }
 
-  // 7) Confirmar (salvo --yes). Si vamos a pisar trabajo ajeno, lo decimos
-  //    antes de preguntar: es el caso que motivó todo este flujo.
-  if (touchedByOthers.length > 0) {
-    ui.warn(`Vas a pisar ${touchedByOthers.length} archivo(s) editado(s) por otra persona:`);
-    for (const u of touchedByOthers) ui.info(`  ${ui.c.red('!')} ${u.relPath}${authorNote(u)}`);
-    ui.info('');
-  }
-
+  // 7) Confirmar (salvo --yes). Ya no hace falta advertir "vas a pisar trabajo
+  //    ajeno": desde la Etapa 3 el servidor no deja pisar nada. Si alguien más
+  //    cambió el mismo archivo, la propuesta queda abierta y se informa abajo.
   if (!args.yes) {
     const ok = await prompt.confirm(`¿Subir ${toWrite} archivo(s) al proyecto?`, true);
     if (!ok) {
@@ -592,13 +649,7 @@ async function push(args) {
     }
   }
 
-  // 8) Ejecutar subidas. Cada lote se commitea apenas termina (ver paso 9): si
-  //    el push se corta a la mitad, lo ya escrito queda en el historial en vez
-  //    de quedar en storage sin ningún commit que lo referencie.
-  const failedWrites = [];
   const pushedAt = Date.now();
-  let committed = 0;
-  let commitCount = 0;
 
   /** Log por archivo: en TTY lo tapa la barra de progreso, así que va sólo con --verbose. */
   const logFile = (prog, msg) => {
@@ -614,422 +665,697 @@ async function push(args) {
     ui.error(msg);
   };
 
-  // 8a) Carpetas faltantes, por nivel. El árbol remoto ya nos dice cuáles
-  //     existen, así que no hace falta listar antes de crear cada una; y crear
-  //     nivel por nivel (paralelo dentro del nivel, serie entre niveles)
-  //     garantiza que el padre exista sin depender del 409 del backend, que no
-  //     es confiable ante dos creaciones simultáneas de la misma carpeta.
+  // 8) Proponer. Todo lo que cambió va al servidor como UNA propuesta (o varias
+  //    si no entra en una: ver PROPOSAL_MAX_*) que parte de la versión que esta
+  //    carpeta vio por última vez (`.shilo.json` → `base`). El servidor la
+  //    aplica solo si combina limpio con la versión actual; si otra persona
+  //    cambió alguno de los mismos archivos, la deja abierta y NO pisa nada.
   //
-  //     Se ejecuta a demanda: el endpoint de lote hace mkdir -p por su cuenta,
-  //     así que estos requests sólo hacen falta en el camino archivo-por-archivo.
-  const failedFolders = [];
-  let foldersEnsured = false;
-
-  async function ensureFolders() {
-    if (foldersEnsured) return;
-    foldersEnsured = true;
-    if (plan.added.length === 0) return;
-
-    if (treeComplete) {
-      const missing = [...neededFolders(plan.added.map((u) => u.relPath))].filter(
-        (f) => !tree.folders.has(f)
+  //    El texto viaja inline; los binarios (y el texto que no entra en el JSON)
+  //    se inventarian primero por URL firmada y entran por su oid.
+  //
+  //    Devuelve null si el servidor no conoce las propuestas todavía: entonces
+  //    se usa el camino anterior, que sí puede pisar.
+  async function pushViaProposals() {
+    let listed;
+    try {
+      listed = await client.listProposals(projectId, await mgr.valid(), { state: 'abierta' });
+    } catch (e) {
+      if (e.notSupported) return null;
+      throw e;
+    }
+    config.persistCredsIfChanged(cfg, mgr.current);
+
+    const knownBase = savedRemote && savedRemote.base ? savedRemote.base : null;
+    let base = knownBase || listed.main;
+    if (!knownBase && listed.main) {
+      ui.info(
+        ui.c.dim(
+          'Esta carpeta no tenía anotada de qué versión partió: se toma la actual. ' +
+            'Desde ahora el push sabrá si alguien cambió lo mismo que vos.'
+        )
       );
-      const byDepth = new Map();
-      for (const f of missing) {
-        const d = f.split('/').length;
-        if (!byDepth.has(d)) byDepth.set(d, []);
-        byDepth.get(d).push(f);
-      }
+    }
 
-      for (const depth of [...byDepth.keys()].sort((a, b) => a - b)) {
-        const level = byDepth.get(depth);
-        const results = await sync.runPool(level, throttle, async (folderPath) => {
-          const parts = folderPath.split('/');
-          const name = parts.pop();
-          const creds = await mgr.valid();
-          await client.createFolder(projectId, name, parts.join('/'), creds);
-          return folderPath;
-        });
-        for (const r of results) {
-          if (r && r.__error) {
-            failedFolders.push({ folderPath: r.item, reason: r.__error });
-            ui.error(`carpeta ${r.item} — ${r.__error}`);
-          }
-        }
-      }
-    } else {
-      // Árbol incompleto: no sabemos qué existe. Volvemos al camino conservador.
-      const ensuredCache = new Set();
-      for (const u of plan.added) {
-        try {
-          const creds = await mgr.valid();
-          await client.ensurePath(projectId, u.relPath, creds, ensuredCache);
-        } catch (e) {
-          failedFolders.push({ folderPath: path.posix.dirname(u.relPath), reason: e.message });
-          ui.error(`${u.relPath} — ${e.message}`);
-        }
+    // 8a) Propuestas propias que siguen abiertas: este push las reemplaza, porque
+    //     la carpeta local es lo que la persona quiere que quede. Si se dejaran,
+    //     bloquearían a la nueva por tocar los mismos archivos.
+    const mine = myId ? listed.proposals.filter((pr) => pr.author_id === myId) : [];
+    for (const pr of mine) {
+      try {
+        await client.resolveProposal(projectId, pr.id, 'discard', await mgr.valid());
+        ui.info(ui.c.dim(`Se descartó tu propuesta anterior "${pr.title || pr.id.slice(0, 8)}": este push la reemplaza.`));
+      } catch (e) {
+        ui.warn(`No se pudo descartar tu propuesta anterior ${pr.id.slice(0, 8)}: ${e.message}`);
       }
     }
-    config.persistCredsIfChanged(cfg, mgr.current);
-  }
 
-  const blocked = (relPath) =>
-    failedFolders.some((f) => f.folderPath && relPath.startsWith(`${f.folderPath}/`));
-
-  // 8b) Subidas. El costo dominante no es el trabajo del servidor sino la
-  //     latencia de cada round-trip, así que van agrupadas: el endpoint de lote
-  //     escribe hasta 100 archivos por request y crea las carpetas que falten.
-  //     El contenido se lee lote por lote, no todo de una: un repo grande no
-  //     tiene por qué entrar entero en memoria.
-  const BATCH_MAX_FILES = COMMIT_BATCH; // 100: mismo techo que el commit
-  const BATCH_MAX_BYTES = 4 * 1024 * 1024; // el server corta en 5 MB; margen
-
-  const toUpload = [
-    ...plan.added.map((u) => ({ u, isNew: true })),
-    ...plan.modified.map((u) => ({ u, isNew: false })),
-  ];
-
-  // Empaquetado por cantidad Y por tamaño. Un archivo más grande que el
-  // presupuesto termina solo en su lote, y ahí se sube por el endpoint
-  // individual.
-  //
-  // Los lotes son HOMOGÉNEOS: o todo texto, o todo binario. Los dos grupos se
-  // escriben por caminos distintos —lote JSON contra URL firmada— y un lote
-  // mezclado obligaría a partirlo en el momento de escribir, justo donde después
-  // hay que volver a juntar los cambios para un solo commit. Separarlos acá
-  // deja esa parte sin ramas.
-  //
-  // El presupuesto de bytes no se le aplica a los binarios: su contenido nunca
-  // entra en el payload de un request, así que un lote de diez PDF de 30 MB son
-  // diez subidas directas y ningún JSON grande.
-  const batches = [];
-  for (const group of [toUpload.filter((e) => !e.u.binary), toUpload.filter((e) => e.u.binary)]) {
+    // 8b) Lotes: hasta PROPOSAL_MAX_CHANGES cambios y PROPOSAL_MAX_BYTES de
+    //     texto inline por propuesta. Los binarios no suman bytes: van por oid.
+    const toSend = [...plan.added, ...plan.modified];
+    const batches = [];
     let current = [];
     let currentBytes = 0;
-    for (const e of group) {
-      const bytes = e.u.binary ? 0 : typeof e.u.size === 'number' ? e.u.size : 0;
+    for (const u of toSend) {
+      const bytes = u.binary || u.size > PROPOSAL_INLINE_MAX ? 0 : u.size;
       const full =
-        current.length >= BATCH_MAX_FILES || currentBytes + bytes > BATCH_MAX_BYTES;
+        current.length >= PROPOSAL_MAX_CHANGES || currentBytes + bytes > PROPOSAL_MAX_BYTES;
       if (current.length > 0 && full) {
         batches.push(current);
         current = [];
         currentBytes = 0;
       }
-      current.push(e);
+      current.push(u);
       currentBytes += bytes;
     }
     if (current.length > 0) batches.push(current);
-  }
 
-  const upProg = ui.progress(toUpload.length, 'subiendo');
-  let upDone = 0;
-  const tickUp = (n = 1) => {
-    upDone += n;
-    upProg.update(upDone);
-  };
+    const failedWrites = [];
+    const uploaded = [];
+    const open = [];
+    let applied = 0;
+    let appliedCount = 0;
+    let stale = 0;
+    let main = listed.main;
 
-  const uploaded = []; // { relPath, size, mtimeMs, hash } para el índice
-  let batchSupported = true; // se descubre en el primer lote
-
-  /** Escribe un lote entero en un request. Devuelve un resultado por archivo. */
-  async function writeViaBatch(entries) {
-    const payload = entries.map((e) => ({
-      path: e.u.relPath,
-      content: e.content,
-      mimeType: e.u.mimeType,
-    }));
-    const creds = await mgr.valid();
-    const { results } = await client.writeBatch(projectId, payload, creds);
-
-    return entries.map((e, i) => {
-      const r = results[i];
-      if (!r || !r.ok) {
-        return { ok: false, reason: (r && r.error) || 'el servidor no devolvió resultado' };
-      }
-      const f = r.file || {};
-      const action = r.action === 'created' ? 'added' : 'modified';
-      const change = { file_id: f.id, action, new_storage_path: f.storage_path };
-      if (action === 'modified') {
-        // El backend devuelve el storage_path que acaba de reemplazar; sólo si
-        // faltara caemos a lo que sabíamos del árbol remoto.
-        change.previous_storage_path =
-          f.previous_storage_path || (e.u.remote && e.u.remote.storage_path) || f.storage_path;
-        // El hash del contenido que estamos reemplazando lo sabe únicamente el
-        // cliente: cuando el commit llega al servidor, `files.content_hash` ya
-        // fue pisado con el contenido nuevo. Puede ser null en archivos
-        // anteriores a la migración 010.
-        if (e.u.remote && e.u.remote.content_hash) {
-          change.previous_content_hash = e.u.remote.content_hash;
+    const upProg = ui.progress(toSend.length, 'subiendo');
+    let upDone = 0;
+
+    for (let bi = 0; bi < batches.length; bi += 1) {
+      const entries = batches[bi];
+
+      // Contenido completo, con reclasificación (ver loadContent).
+      const loaded = [];
+      for (const u of entries) {
+        try {
+          await loadContent(u);
+          loaded.push(u);
+        } catch (err) {
+          failedWrites.push({ relPath: u.relPath, reason: err.message });
+          logError(upProg, `${u.relPath} — ${err.message}`);
+          upDone += 1;
+          upProg.update(upDone);
         }
       }
-      return { ok: true, change, symbol: action === 'added' ? '+' : '~' };
-    });
-  }
+      if (loaded.length === 0) continue;
 
-  /**
-   * Camino de los binarios: URL firmada, un archivo a la vez y en paralelo.
-   *
-   * No se agrupan en un request como el texto porque no hay nada que agrupar:
-   * cada byte va directo a Storage. Lo que sí se comparte es el control de
-   * ritmo, que es el que evita que veinte subidas de 30 MB salgan juntas.
-   *
-   * El endpoint crea las carpetas intermedias por su cuenta, igual que el lote,
-   * así que acá no hace falta `ensureFolders()`.
-   */
-  async function writeViaDirect(entries) {
-    const results = await sync.runPool(entries, throttle, async (e) => {
-      const creds = await mgr.valid();
-      const { result } = await client.uploadBinary(
-        projectId,
-        {
-          path: e.u.relPath,
-          buffer: e.content,
-          contentHash: pushindex.hashContent(e.content),
-          mimeType: e.u.mimeType,
-        },
-        creds
+      // Lo que no puede ir inline se inventaría antes, en paralelo y con el
+      // mismo control de ritmo que cualquier subida.
+      const byOid = loaded.filter(
+        (u) => u.binary || Buffer.byteLength(u.content, 'utf8') > PROPOSAL_INLINE_MAX
       );
+      const registered = new Map();
+      if (byOid.length > 0) {
+        const results = await sync.runPool(byOid, throttle, async (u) => {
+          const buffer = Buffer.isBuffer(u.content) ? u.content : Buffer.from(u.content, 'utf8');
+          const creds = await mgr.valid();
+          const { oid } = await client.registerBlob(
+            projectId,
+            { path: u.relPath, buffer, contentHash: pushindex.hashContent(buffer), mimeType: u.mimeType },
+            creds
+          );
+          return oid;
+        });
+        results.forEach((r, i) => {
+          if (r && r.__error) {
+            failedWrites.push({ relPath: byOid[i].relPath, reason: r.__error });
+            logError(upProg, `${byOid[i].relPath} — ${r.__error}`);
+          } else {
+            registered.set(byOid[i], r);
+          }
+        });
+        config.persistCredsIfChanged(cfg, mgr.current);
+      }
 
-      const f = (result && result.file) || {};
-      const action = result && result.action === 'created' ? 'added' : 'modified';
-      const change = { file_id: f.id, action, new_storage_path: f.storage_path };
-
-      if (action === 'modified') {
-        change.previous_storage_path =
-          f.previous_storage_path || (e.u.remote && e.u.remote.storage_path) || f.storage_path;
-        // El hash de lo que estamos reemplazando: el servidor lo lee antes de
-        // pisar la fila, que es el único momento en que existe. Si no vino, lo
-        // sabemos por el árbol remoto.
-        const previous =
-          f.previous_content_hash || (e.u.remote && e.u.remote.content_hash) || null;
-        if (previous) change.previous_content_hash = previous;
+      const sent = [];
+      const changes = [];
+      for (const u of loaded) {
+        if (byOid.includes(u)) {
+          if (!registered.has(u)) continue;
+          changes.push({ path: u.relPath, oid: registered.get(u) });
+        } else {
+          changes.push({ path: u.relPath, content: u.content, mime_type: u.mimeType });
+        }
+        sent.push(u);
       }
+      upDone += loaded.length;
+      upProg.update(upDone);
+      if (changes.length === 0) continue;
 
-      return { ok: true, change, symbol: action === 'added' ? '+' : '~' };
-    });
+      const title = buildMessage(message, changes.length, toSend.length, bi + 1, batches.length, card);
+      let result;
+      try {
+        result = await client.propose(
+          projectId,
+          { base, title, summary: '', changes, agent, prompt: promptText, card },
+          await mgr.valid()
+        );
+        for (const w of result.warnings || []) ui.warn(w);
+        config.persistCredsIfChanged(cfg, mgr.current);
+      } catch (e) {
+        // Una base que el servidor no conoce (proyecto recreado, historial
+        // podado) no es motivo para no guardar: se reintenta desde la actual.
+        if (e.status === 404 && base && base !== main && e.body && /punto de guardado/i.test(e.body.error || '')) {
+          ui.warn('El servidor no reconoce la versión de partida anotada: se parte de la actual.');
+          base = main;
+          bi -= 1;
+          for (const u of loaded) u.content = null;
+          continue;
+        }
+        for (const u of sent) failedWrites.push({ relPath: u.relPath, reason: e.message });
+        logError(upProg, `Lote ${bi + 1}/${batches.length} — ${e.message}`);
+        for (const u of loaded) u.content = null;
+        continue;
+      }
+
+      if (result.main) main = result.main;
+      for (const u of sent) uploaded.push({ ...u, hash: pushindex.hashContent(u.content) });
 
-    return results.map((r) => (r && r.__error ? { ok: false, reason: r.__error } : r));
+      if (result.empty) {
+        stale += sent.length;
+      } else if (result.applied) {
+        applied += sent.length;
+        appliedCount += 1;
+        for (const u of sent) {
+          logFile(upProg, `${u.remote ? ui.c.yellow('~') : ui.c.green('+')} ${u.relPath}`);
+        }
+      } else {
+        open.push({ ...result, paths: sent.map((u) => u.relPath) });
+      }
+
+      for (const u of loaded) u.content = null;
+    }
+    upProg.clear();
+
+    return { failedWrites, committed: applied, commitCount: appliedCount, uploaded, open, stale, main, base };
   }
 
-  /** Camino archivo-por-archivo: server sin /batch, o archivo demasiado grande. */
-  async function writeViaSingle(entries) {
-    await ensureFolders();
+  /**
+   * El camino anterior a la Etapa 3: escribe archivo por archivo (o por lote) y
+   * después registra el commit. Puede pisar cambios ajenos, porque el servidor
+   * viejo no tiene con qué compararlos. Queda hasta que ningún servidor lo
+   * necesite.
+   */
+  async function pushLegacy() {
+    const failedWrites = [];
+    let committed = 0;
+    let commitCount = 0;
+
+    // 8a) Carpetas faltantes, por nivel. El árbol remoto ya nos dice cuáles
+    //     existen, así que no hace falta listar antes de crear cada una; y crear
+    //     nivel por nivel (paralelo dentro del nivel, serie entre niveles)
+    //     garantiza que el padre exista sin depender del 409 del backend, que no
+    //     es confiable ante dos creaciones simultáneas de la misma carpeta.
+    //
+    //     Se ejecuta a demanda: el endpoint de lote hace mkdir -p por su cuenta,
+    //     así que estos requests sólo hacen falta en el camino archivo-por-archivo.
+    const failedFolders = [];
+    let foldersEnsured = false;
+
+    async function ensureFolders() {
+      if (foldersEnsured) return;
+      foldersEnsured = true;
+      if (plan.added.length === 0) return;
+
+      if (treeComplete) {
+        const missing = [...neededFolders(plan.added.map((u) => u.relPath))].filter(
+          (f) => !tree.folders.has(f)
+        );
+        const byDepth = new Map();
+        for (const f of missing) {
+          const d = f.split('/').length;
+          if (!byDepth.has(d)) byDepth.set(d, []);
+          byDepth.get(d).push(f);
+        }
 
-    const outcomes = new Array(entries.length);
-    const queue = [];
-    entries.forEach((e, i) => {
-      if (e.isNew && blocked(e.u.relPath)) {
-        outcomes[i] = { ok: false, reason: 'no se pudo crear su carpeta' };
+        for (const depth of [...byDepth.keys()].sort((a, b) => a - b)) {
+          const level = byDepth.get(depth);
+          const results = await sync.runPool(level, throttle, async (folderPath) => {
+            const parts = folderPath.split('/');
+            const name = parts.pop();
+            const creds = await mgr.valid();
+            await client.createFolder(projectId, name, parts.join('/'), creds);
+            return folderPath;
+          });
+          for (const r of results) {
+            if (r && r.__error) {
+              failedFolders.push({ folderPath: r.item, reason: r.__error });
+              ui.error(`carpeta ${r.item} — ${r.__error}`);
+            }
+          }
+        }
       } else {
-        queue.push({ e, i });
+        // Árbol incompleto: no sabemos qué existe. Volvemos al camino conservador.
+        const ensuredCache = new Set();
+        for (const u of plan.added) {
+          try {
+            const creds = await mgr.valid();
+            await client.ensurePath(projectId, u.relPath, creds, ensuredCache);
+          } catch (e) {
+            failedFolders.push({ folderPath: path.posix.dirname(u.relPath), reason: e.message });
+            ui.error(`${u.relPath} — ${e.message}`);
+          }
+        }
       }
-    });
+      config.persistCredsIfChanged(cfg, mgr.current);
+    }
+
+    const blocked = (relPath) =>
+      failedFolders.some((f) => f.folderPath && relPath.startsWith(`${f.folderPath}/`));
+
+    // 8b) Subidas. El costo dominante no es el trabajo del servidor sino la
+    //     latencia de cada round-trip, así que van agrupadas: el endpoint de lote
+    //     escribe hasta 100 archivos por request y crea las carpetas que falten.
+    //     El contenido se lee lote por lote, no todo de una: un repo grande no
+    //     tiene por qué entrar entero en memoria.
+    const BATCH_MAX_FILES = COMMIT_BATCH; // 100: mismo techo que el commit
+    const BATCH_MAX_BYTES = 4 * 1024 * 1024; // el server corta en 5 MB; margen
+
+    const toUpload = [
+      ...plan.added.map((u) => ({ u, isNew: true })),
+      ...plan.modified.map((u) => ({ u, isNew: false })),
+    ];
+
+    // Empaquetado por cantidad Y por tamaño. Un archivo más grande que el
+    // presupuesto termina solo en su lote, y ahí se sube por el endpoint
+    // individual.
+    //
+    // Los lotes son HOMOGÉNEOS: o todo texto, o todo binario. Los dos grupos se
+    // escriben por caminos distintos —lote JSON contra URL firmada— y un lote
+    // mezclado obligaría a partirlo en el momento de escribir, justo donde después
+    // hay que volver a juntar los cambios para un solo commit. Separarlos acá
+    // deja esa parte sin ramas.
+    //
+    // El presupuesto de bytes no se le aplica a los binarios: su contenido nunca
+    // entra en el payload de un request, así que un lote de diez PDF de 30 MB son
+    // diez subidas directas y ningún JSON grande.
+    const batches = [];
+    for (const group of [toUpload.filter((e) => !e.u.binary), toUpload.filter((e) => e.u.binary)]) {
+      let current = [];
+      let currentBytes = 0;
+      for (const e of group) {
+        const bytes = e.u.binary ? 0 : typeof e.u.size === 'number' ? e.u.size : 0;
+        const full =
+          current.length >= BATCH_MAX_FILES || currentBytes + bytes > BATCH_MAX_BYTES;
+        if (current.length > 0 && full) {
+          batches.push(current);
+          current = [];
+          currentBytes = 0;
+        }
+        current.push(e);
+        currentBytes += bytes;
+      }
+      if (current.length > 0) batches.push(current);
+    }
+
+    const upProg = ui.progress(toUpload.length, 'subiendo');
+    let upDone = 0;
+    const tickUp = (n = 1) => {
+      upDone += n;
+      upProg.update(upDone);
+    };
+
+    const uploaded = []; // { relPath, size, mtimeMs, hash } para el índice
+    let batchSupported = true; // se descubre en el primer lote
+
+    /** Escribe un lote entero en un request. Devuelve un resultado por archivo. */
+    async function writeViaBatch(entries) {
+      const payload = entries.map((e) => ({
+        path: e.u.relPath,
+        content: e.content,
+        mimeType: e.u.mimeType,
+      }));
+      const creds = await mgr.valid();
+      const { results } = await client.writeBatch(projectId, payload, creds);
+
+      return entries.map((e, i) => {
+        const r = results[i];
+        if (!r || !r.ok) {
+          return { ok: false, reason: (r && r.error) || 'el servidor no devolvió resultado' };
+        }
+        const f = r.file || {};
+        const action = r.action === 'created' ? 'added' : 'modified';
+        const change = { file_id: f.id, action, new_storage_path: f.storage_path };
+        if (action === 'modified') {
+          // El backend devuelve el storage_path que acaba de reemplazar; sólo si
+          // faltara caemos a lo que sabíamos del árbol remoto.
+          change.previous_storage_path =
+            f.previous_storage_path || (e.u.remote && e.u.remote.storage_path) || f.storage_path;
+          // El hash del contenido que estamos reemplazando lo sabe únicamente el
+          // cliente: cuando el commit llega al servidor, `files.content_hash` ya
+          // fue pisado con el contenido nuevo. Puede ser null en archivos
+          // anteriores a la migración 010.
+          if (e.u.remote && e.u.remote.content_hash) {
+            change.previous_content_hash = e.u.remote.content_hash;
+          }
+        }
+        return { ok: true, change, symbol: action === 'added' ? '+' : '~' };
+      });
+    }
 
-    const results = await sync.runPool(queue, throttle, async ({ e }) => {
-      const u = e.u;
-      if (e.isNew) {
+    /**
+     * Camino de los binarios: URL firmada, un archivo a la vez y en paralelo.
+     *
+     * No se agrupan en un request como el texto porque no hay nada que agrupar:
+     * cada byte va directo a Storage. Lo que sí se comparte es el control de
+     * ritmo, que es el que evita que veinte subidas de 30 MB salgan juntas.
+     *
+     * El endpoint crea las carpetas intermedias por su cuenta, igual que el lote,
+     * así que acá no hace falta `ensureFolders()`.
+     */
+    async function writeViaDirect(entries) {
+      const results = await sync.runPool(entries, throttle, async (e) => {
         const creds = await mgr.valid();
-        const created = await client.createFile(projectId, u.relPath, e.content, u.mimeType, creds);
-        if (created.created && created.file) {
+        const { result } = await client.uploadBinary(
+          projectId,
+          {
+            path: e.u.relPath,
+            buffer: e.content,
+            contentHash: pushindex.hashContent(e.content),
+            mimeType: e.u.mimeType,
+          },
+          creds
+        );
+
+        const f = (result && result.file) || {};
+        const action = result && result.action === 'created' ? 'added' : 'modified';
+        const change = { file_id: f.id, action, new_storage_path: f.storage_path };
+
+        if (action === 'modified') {
+          change.previous_storage_path =
+            f.previous_storage_path || (e.u.remote && e.u.remote.storage_path) || f.storage_path;
+          // El hash de lo que estamos reemplazando: el servidor lo lee antes de
+          // pisar la fila, que es el único momento en que existe. Si no vino, lo
+          // sabemos por el árbol remoto.
+          const previous =
+            f.previous_content_hash || (e.u.remote && e.u.remote.content_hash) || null;
+          if (previous) change.previous_content_hash = previous;
+        }
+
+        return { ok: true, change, symbol: action === 'added' ? '+' : '~' };
+      });
+
+      return results.map((r) => (r && r.__error ? { ok: false, reason: r.__error } : r));
+    }
+
+    /** Camino archivo-por-archivo: server sin /batch, o archivo demasiado grande. */
+    async function writeViaSingle(entries) {
+      await ensureFolders();
+
+      const outcomes = new Array(entries.length);
+      const queue = [];
+      entries.forEach((e, i) => {
+        if (e.isNew && blocked(e.u.relPath)) {
+          outcomes[i] = { ok: false, reason: 'no se pudo crear su carpeta' };
+        } else {
+          queue.push({ e, i });
+        }
+      });
+
+      const results = await sync.runPool(queue, throttle, async ({ e }) => {
+        const u = e.u;
+        if (e.isNew) {
+          const creds = await mgr.valid();
+          const created = await client.createFile(projectId, u.relPath, e.content, u.mimeType, creds);
+          if (created.created && created.file) {
+            return {
+              ok: true,
+              symbol: '+',
+              change: {
+                file_id: created.file.id,
+                action: 'added',
+                new_storage_path: created.file.storage_path,
+              },
+            };
+          }
+          // 409: apareció entremedio; caemos a update.
+          const writeCreds = await mgr.valid();
+          const upd = await client.writeFile(projectId, u.relPath, e.content, u.mimeType, writeCreds);
           return {
             ok: true,
-            symbol: '+',
+            symbol: '~',
             change: {
-              file_id: created.file.id,
-              action: 'added',
-              new_storage_path: created.file.storage_path,
+              file_id: upd.file.id,
+              action: 'modified',
+              previous_storage_path:
+                (created.file && created.file.storage_path) || upd.file.storage_path,
+              new_storage_path: upd.file.storage_path,
             },
           };
         }
-        // 409: apareció entremedio; caemos a update.
-        const writeCreds = await mgr.valid();
-        const upd = await client.writeFile(projectId, u.relPath, e.content, u.mimeType, writeCreds);
+
+        const creds = await mgr.valid();
+        const upd = await client.writeFile(projectId, u.relPath, e.content, u.mimeType, creds);
         return {
           ok: true,
           symbol: '~',
           change: {
             file_id: upd.file.id,
             action: 'modified',
-            previous_storage_path:
-              (created.file && created.file.storage_path) || upd.file.storage_path,
+            previous_storage_path: u.remote ? u.remote.storage_path : upd.file.storage_path,
             new_storage_path: upd.file.storage_path,
+            // Ver la nota en writeViaBatch: el hash previo sólo existe acá.
+            ...(u.remote && u.remote.content_hash
+              ? { previous_content_hash: u.remote.content_hash }
+              : {}),
           },
         };
-      }
-
-      const creds = await mgr.valid();
-      const upd = await client.writeFile(projectId, u.relPath, e.content, u.mimeType, creds);
-      return {
-        ok: true,
-        symbol: '~',
-        change: {
-          file_id: upd.file.id,
-          action: 'modified',
-          previous_storage_path: u.remote ? u.remote.storage_path : upd.file.storage_path,
-          new_storage_path: upd.file.storage_path,
-          // Ver la nota en writeViaBatch: el hash previo sólo existe acá.
-          ...(u.remote && u.remote.content_hash
-            ? { previous_content_hash: u.remote.content_hash }
-            : {}),
-        },
-      };
-    });
-
-    // `runPool` devuelve los resultados alineados con la entrada, así que el
-    // índice de `queue` alcanza para volver a la posición original.
-    for (let k = 0; k < results.length; k += 1) {
-      const r = results[k];
-      outcomes[queue[k].i] = r && r.__error ? { ok: false, reason: r.__error } : r;
-    }
-    return outcomes;
-  }
-
-  for (let bi = 0; bi < batches.length; bi += 1) {
-    const entries = batches[bi];
+      });
 
-    // Un fallo de lectura (dejó de ser texto, permisos) saca a ese archivo del
-    // lote pero no arrastra a los demás.
-    const loaded = [];
-    for (const e of entries) {
-      try {
-        e.content = await loadContent(e.u);
-        loaded.push(e);
-      } catch (err) {
-        failedWrites.push({ relPath: e.u.relPath, reason: err.message });
-        logError(upProg, `${e.u.relPath} — ${err.message}`);
-        tickUp();
+      // `runPool` devuelve los resultados alineados con la entrada, así que el
+      // índice de `queue` alcanza para volver a la posición original.
+      for (let k = 0; k < results.length; k += 1) {
+        const r = results[k];
+        outcomes[queue[k].i] = r && r.__error ? { ok: false, reason: r.__error } : r;
       }
-    }
-    if (loaded.length === 0) continue;
-
-    // El lote se armó con lo que dijo el preflight, que sólo miró los primeros
-    // 8 KB. `loadContent` acaba de leer el archivo entero y pudo reclasificarlo,
-    // así que la partición se rehace ACÁ, sobre el contenido de verdad. Mandar
-    // un Buffer por el lote JSON lo convertiría en `{"type":"Buffer",...}`, que
-    // es la corrupción silenciosa que toda esta etapa existe para evitar.
-    const binaries = loaded.filter((e) => e.u.binary);
-    const texts = loaded.filter((e) => !e.u.binary);
-
-    const outcomeByEntry = new Map();
-
-    if (binaries.length > 0) {
-      // Un fallo acá es por archivo, no del lote: `writeViaDirect` devuelve un
-      // resultado por entrada y los errores ya vienen adentro.
-      const res = await writeViaDirect(binaries);
-      binaries.forEach((e, i) => outcomeByEntry.set(e, res[i]));
+      return outcomes;
     }
 
-    if (texts.length > 0) {
-      const oversize =
-        texts.length === 1 && Buffer.byteLength(texts[0].content, 'utf8') > BATCH_MAX_BYTES;
-      let res = null;
+    for (let bi = 0; bi < batches.length; bi += 1) {
+      const entries = batches[bi];
 
-      if (batchSupported && !oversize) {
+      // Un fallo de lectura (dejó de ser texto, permisos) saca a ese archivo del
+      // lote pero no arrastra a los demás.
+      const loaded = [];
+      for (const e of entries) {
         try {
-          res = await writeViaBatch(texts);
+          e.content = await loadContent(e.u);
+          loaded.push(e);
         } catch (err) {
-          if (err.notSupported) {
-            batchSupported = false;
-            upProg.clear();
-            ui.warn('El servidor no acepta escritura por lotes; se sube archivo por archivo.');
-          } else {
-            // Falla del request entero (red, 5xx, permisos): ningún archivo de
-            // texto del lote se escribió. Los binarios ya se resolvieron aparte
-            // y no los arrastra.
-            res = texts.map(() => ({ ok: false, reason: err.message }));
-          }
+          failedWrites.push({ relPath: e.u.relPath, reason: err.message });
+          logError(upProg, `${e.u.relPath} — ${err.message}`);
+          tickUp();
         }
       }
+      if (loaded.length === 0) continue;
+
+      // El lote se armó con lo que dijo el preflight, que sólo miró los primeros
+      // 8 KB. `loadContent` acaba de leer el archivo entero y pudo reclasificarlo,
+      // así que la partición se rehace ACÁ, sobre el contenido de verdad. Mandar
+      // un Buffer por el lote JSON lo convertiría en `{"type":"Buffer",...}`, que
+      // es la corrupción silenciosa que toda esta etapa existe para evitar.
+      const binaries = loaded.filter((e) => e.u.binary);
+      const texts = loaded.filter((e) => !e.u.binary);
+
+      const outcomeByEntry = new Map();
+
+      if (binaries.length > 0) {
+        // Un fallo acá es por archivo, no del lote: `writeViaDirect` devuelve un
+        // resultado por entrada y los errores ya vienen adentro.
+        const res = await writeViaDirect(binaries);
+        binaries.forEach((e, i) => outcomeByEntry.set(e, res[i]));
+      }
 
-      if (!res) res = await writeViaSingle(texts);
-      texts.forEach((e, i) => outcomeByEntry.set(e, res[i]));
-    }
+      if (texts.length > 0) {
+        const oversize =
+          texts.length === 1 && Buffer.byteLength(texts[0].content, 'utf8') > BATCH_MAX_BYTES;
+        let res = null;
+
+        if (batchSupported && !oversize) {
+          try {
+            res = await writeViaBatch(texts);
+          } catch (err) {
+            if (err.notSupported) {
+              batchSupported = false;
+              upProg.clear();
+              ui.warn('El servidor no acepta escritura por lotes; se sube archivo por archivo.');
+            } else {
+              // Falla del request entero (red, 5xx, permisos): ningún archivo de
+              // texto del lote se escribió. Los binarios ya se resolvieron aparte
+              // y no los arrastra.
+              res = texts.map(() => ({ ok: false, reason: err.message }));
+            }
+          }
+        }
 
-    const outcomes = loaded.map((e) => outcomeByEntry.get(e));
-    config.persistCredsIfChanged(cfg, mgr.current);
+        if (!res) res = await writeViaSingle(texts);
+        texts.forEach((e, i) => outcomeByEntry.set(e, res[i]));
+      }
 
-    const batchChanges = [];
-    for (let i = 0; i < loaded.length; i += 1) {
-      const e = loaded[i];
-      const o = outcomes[i];
-      if (!o || !o.ok) {
-        const reason = (o && o.reason) || 'error desconocido';
-        failedWrites.push({ relPath: e.u.relPath, reason });
-        logError(upProg, `${e.u.relPath} — ${reason}`);
-        continue;
+      const outcomes = loaded.map((e) => outcomeByEntry.get(e));
+      config.persistCredsIfChanged(cfg, mgr.current);
+
+      const batchChanges = [];
+      for (let i = 0; i < loaded.length; i += 1) {
+        const e = loaded[i];
+        const o = outcomes[i];
+        if (!o || !o.ok) {
+          const reason = (o && o.reason) || 'error desconocido';
+          failedWrites.push({ relPath: e.u.relPath, reason });
+          logError(upProg, `${e.u.relPath} — ${reason}`);
+          continue;
+        }
+        batchChanges.push(o.change);
+        uploaded.push({ ...e.u, hash: pushindex.hashContent(e.content) });
+        logFile(upProg, `${ui.c[o.symbol === '+' ? 'green' : 'yellow'](o.symbol)} ${e.u.relPath}`);
       }
-      batchChanges.push(o.change);
-      uploaded.push({ ...e.u, hash: pushindex.hashContent(e.content) });
-      logFile(upProg, `${ui.c[o.symbol === '+' ? 'green' : 'yellow'](o.symbol)} ${e.u.relPath}`);
-    }
-    tickUp(loaded.length);
-
-    // 9) Commit del lote, apenas termina de escribirse. Juntar todos los cambios
-    //    para un commit final ahorraba requests, pero dejaba una ventana larga
-    //    en la que los archivos ya estaban escritos y ningún commit los
-    //    mencionaba; si el push moría ahí, el historial quedaba mintiendo.
-    if (batchChanges.length > 0) {
-      const partNo = bi + 1;
-      const msg = buildMessage(
-        message,
-        batchChanges.length,
-        toUpload.length,
-        partNo,
-        batches.length,
-        card
-      );
-      try {
-        const creds = await mgr.valid();
-        await client.createCommit(projectId, msg, batchChanges, creds);
-        committed += batchChanges.length;
-        commitCount += 1;
-        config.persistCredsIfChanged(cfg, mgr.current);
-      } catch (e) {
-        ui.error(`Fallo al crear el commit (lote ${partNo}/${batches.length}): ${e.message}`);
-        failedWrites.push({ relPath: `<commit lote ${partNo}>`, reason: e.message });
+      tickUp(loaded.length);
+
+      // 9) Commit del lote, apenas termina de escribirse. Juntar todos los cambios
+      //    para un commit final ahorraba requests, pero dejaba una ventana larga
+      //    en la que los archivos ya estaban escritos y ningún commit los
+      //    mencionaba; si el push moría ahí, el historial quedaba mintiendo.
+      if (batchChanges.length > 0) {
+        const partNo = bi + 1;
+        const msg = buildMessage(
+          message,
+          batchChanges.length,
+          toUpload.length,
+          partNo,
+          batches.length,
+          card
+        );
+        try {
+          const creds = await mgr.valid();
+          await client.createCommit(projectId, msg, batchChanges, creds, { card });
+          committed += batchChanges.length;
+          commitCount += 1;
+          config.persistCredsIfChanged(cfg, mgr.current);
+        } catch (e) {
+          ui.error(`Fallo al crear el commit (lote ${partNo}/${batches.length}): ${e.message}`);
+          failedWrites.push({ relPath: `<commit lote ${partNo}>`, reason: e.message });
+        }
       }
-    }
 
-    // El contenido ya se hasheó y se subió: soltarlo mantiene el pico de memoria
-    // atado al tamaño del lote y no al del repo.
-    for (const e of loaded) {
-      e.content = null;
-      e.u.content = null;
+      // El contenido ya se hasheó y se subió: soltarlo mantiene el pico de memoria
+      // atado al tamaño del lote y no al del repo.
+      for (const e of loaded) {
+        e.content = null;
+        e.u.content = null;
+      }
     }
+    upProg.clear();
+
+    config.persistCredsIfChanged(cfg, mgr.current);
+    return { failedWrites, committed, commitCount, uploaded, open: [], stale: 0, main: null, base: null };
   }
-  upProg.clear();
+
+  let outcome = await pushViaProposals();
+  const legacy = outcome === null;
+  if (legacy) {
+    ui.warn(
+      'Este servidor todavía no recibe propuestas: se sube por el camino anterior, ' +
+        'que puede pisar cambios de otras personas.'
+    );
+    outcome = await pushLegacy();
+  }
+  const { failedWrites, committed, commitCount, uploaded, open, stale, main } = outcome;
 
   config.persistCredsIfChanged(cfg, mgr.current);
 
   // 10) Índice local: lo que subimos bien y lo que ya estaba igual. El próximo
-  //     push arranca sabiendo qué no hace falta ni leer.
+  //     push arranca sabiendo qué no hace falta ni leer. Lo que quedó en una
+  //     propuesta abierta también se anota: su hash no coincide con el de la
+  //     versión actual, así que el push siguiente lo vuelve a mirar igual.
   if (useIndex) {
     for (const u of uploaded) {
       pushindex.record(index, u, pushedAt);
     }
-    saveIndex(dir, index, plan, uploads, pushedAt);
+    saveIndex(dir, index, plan, allUploads, pushedAt);
   }
 
-  // 11) Anotar la sincronización: `status` la usa después para saber qué del
-  //     remoto es posterior a lo último que subimos. Sólo si TODO salió bien:
-  //     con archivos fallados, marcar "sincronizado" haría que status mienta.
-  if (failedWrites.length === 0 && plan.failed.length === 0) {
-    remote.touchSync(dir, { projectId, baseURL });
+  // 11) Anotar la sincronización y la base nueva. Sólo si TODO quedó en la
+  //     versión actual: con archivos fallados o propuestas abiertas, la carpeta
+  //     no está alineada, y mover la base haría que el push siguiente proponga
+  //     esos mismos archivos como si nadie más los hubiera tocado.
+  const clean = failedWrites.length === 0 && plan.failed.length === 0 && open.length === 0;
+  if (clean) {
+    remote.touchSync(dir, { projectId, baseURL, base: legacy ? null : main });
   }
 
   // 12) Resumen final.
   ui.info('');
-  if (failedWrites.length === 0 && plan.failed.length === 0) {
-    ui.success(`Push completo: ${committed} archivo(s) en ${commitCount} commit(s).`);
+  reportLeftOut(leftOut, remoteByPath);
+  for (const o of open) reportOpen(o);
+  if (stale > 0) {
+    ui.warn(
+      `${stale} archivo(s) ya no cambian nada: la versión actual avanzó y lo que tenés ` +
+        'es lo de antes. Traé lo nuevo con "shilo pull" antes de volver a subir.'
+    );
+  }
+  if (clean) {
+    if (committed === 0 && stale === 0) {
+      ui.success('Todo al día. Nada para subir.');
+    } else if (legacy) {
+      ui.success(`Push completo: ${committed} archivo(s) en ${commitCount} commit(s).`);
+    } else {
+      ui.success(`Push completo: ${committed} archivo(s) ya son parte de la versión actual.`);
+    }
     return 0;
   }
   for (const f of plan.failed) ui.error(`${f.relPath} — ${f.reason}`);
-  ui.warn(
-    `Push con problemas: ${failedWrites.length + plan.failed.length} archivo(s)/commit(s) fallaron.`
-  );
+  if (failedWrites.length + plan.failed.length > 0) {
+    ui.warn(`Push con problemas: ${failedWrites.length + plan.failed.length} archivo(s) fallaron.`);
+  } else {
+    ui.warn(
+      `${committed} archivo(s) subieron; ${open.reduce((n, o) => n + o.paths.length, 0)} quedaron en ` +
+        `${open.length} propuesta(s) abierta(s).`
+    );
+  }
   return 1;
 }
 
+/**
+ * Cuenta por qué una propuesta quedó abierta, en el vocabulario del glosario:
+ * nunca "merge" ni "conflicto de rama", siempre qué archivo y quién.
+ */
+function reportOpen(o) {
+  const id = o.proposal ? o.proposal.id.slice(0, 8) : '?';
+  if (o.conflicts.length > 0) {
+    ui.warn(
+      `${o.conflicts.length} archivo(s) los cambió otra persona desde tu última sincronización, ` +
+        'y vos también:'
+    );
+    for (const c of o.conflicts) {
+      const why =
+        c.kind === 'archivo-y-carpeta'
+          ? 'es archivo de un lado y carpeta del otro'
+          : c.ours === null
+            ? 'vos lo borraste y en la versión actual cambió'
+            : c.theirs === null
+              ? 'lo borraron en la versión actual y vos lo cambiaste'
+              : 'las dos versiones son distintas';
+      ui.info(`  ${ui.c.red('!')} ${c.path} ${ui.c.dim(`— ${why}`)}`);
+    }
+  } else if (o.blockedBy.length > 0) {
+    ui.warn('Otra propuesta abierta toca los mismos archivos:');
+    for (const b of o.blockedBy) {
+      ui.info(`  ${ui.c.yellow('·')} "${b.title || b.id.slice(0, 8)}" ${ui.c.dim(`— ${b.paths.join(', ')}`)}`);
+    }
+  } else {
+    ui.warn(o.message || 'La propuesta quedó abierta.');
+  }
+  ui.info(
+    `  Tus ${o.paths.length} archivo(s) no se perdieron: quedaron como propuesta ${ui.c.bold(id)}, ` +
+      'abierta para que el dueño del proyecto decida.'
+  );
+  ui.info(
+    ui.c.dim('  Para resolverlo vos: "shilo pull" trae la versión actual (no pisa lo tuyo sin --force), ') +
+      ui.c.dim('ajustá y volvé a "shilo push".')
+  );
+  ui.info('');
+}
+
 /**
  * Lee el contenido completo de un archivo, cacheado en la propia entrada.
  *
@@ -1062,26 +1388,154 @@ async function loadContent(u) {
   return u.content;
 }
 
+/**
+ * Lo que `--only` dejó afuera. "Una pieza = una tarjeta" sólo funciona si la
+ * CLI te recuerda lo que quedó atrás.
+ *
+ * "Cambiado" se decide contra el ÁRBOL REMOTO —falta allá, o está con otro
+ * tamaño—, que es el mismo criterio de `shilo status` y no cuesta un request
+ * extra: el árbol ya se recorrió para planificar. El índice local no sirve acá:
+ * `pull` no lo escribe, así que en una carpeta que se bajó de nuevo queda viejo
+ * y daría por cambiado medio repo.
+ *
+ * Misma concesión que `status`: dos archivos del mismo tamaño se dan por
+ * iguales aunque difieran byte a byte.
+ */
+function reportLeftOut(leftOut, remoteByPath) {
+  if (!leftOut || leftOut.length === 0) return;
+
+  const changed = leftOut.filter((u) => {
+    const r = remoteByPath.get(u.relPath);
+    if (!r) return true; // nunca subido
+    return typeof r.size === 'number' && r.size !== u.size;
+  });
+  if (changed.length === 0) {
+    ui.info(
+      ui.c.dim(
+        `${leftOut.length} archivo(s) quedaron fuera de este push (--only); ninguno tiene cambios sin subir.`
+      )
+    );
+    return;
+  }
+
+  ui.warn(`${changed.length} archivo(s) con cambios locales quedaron fuera de este push (--only):`);
+  for (const u of changed.slice(0, SKIP_EXAMPLES)) ui.info(`      ${ui.c.dim(u.relPath)}`);
+  if (changed.length > SKIP_EXAMPLES) {
+    ui.info(ui.c.dim(`      … y ${changed.length - SKIP_EXAMPLES} más`));
+  }
+}
+
 /**
  * Registra en el índice los archivos que ya estaban idénticos (para no volver a
  * compararlos), saca los que ya no existen y lo escribe.
+ *
+ * `presentUploads` es lo que EXISTE en la carpeta, no lo que se subió en esta
+ * corrida: con `--only` son cosas distintas. Podar con la selección borraría del
+ * índice las entradas del resto del repo, y el push completo siguiente tendría
+ * que recompararlo todo — lento, no incorrecto, pero evitable. Las entradas
+ * nuevas se fusionan sobre el índice ya leído de disco, no lo reemplazan.
  */
-function saveIndex(dir, index, plan, uploads, pushedAt = Date.now()) {
+function saveIndex(dir, index, plan, presentUploads, pushedAt = Date.now()) {
   for (const u of plan.unchanged) {
     if (u.content != null) {
       pushindex.record(index, { ...u, hash: pushindex.hashContent(u.content) }, pushedAt);
     }
   }
-  pushindex.prune(index, new Set(uploads.map((u) => u.relPath)));
+  pushindex.prune(index, new Set(presentUploads.map((u) => u.relPath)));
   pushindex.write(dir, index);
 }
 
+/**
+ * El bloque `agent` que se declara al proponer, o null si nadie lo declaró.
+ *
+ * `--model` y `--session` sin `--agent` son un error y no un descuido que se
+ * pueda completar solo: decir qué modelo escribió algo sin decir qué
+ * herramienta lo corrió deja una procedencia que no se puede rastrear hasta
+ * ningún lado.
+ */
+function buildAgent(args) {
+  const name = typeof args.agent === 'string' && args.agent.trim() ? args.agent.trim() : null;
+  const model = typeof args.model === 'string' && args.model.trim() ? args.model.trim() : null;
+  const session = typeof args.session === 'string' && args.session.trim() ? args.session.trim() : null;
+
+  if (!name) {
+    if (model || session) {
+      return { error: 'Para declarar procedencia hace falta --agent <nombre>; --model y --session solos no alcanzan.' };
+    }
+    return null;
+  }
+
+  return {
+    name: name.slice(0, AGENT_FIELD_MAX),
+    ...(model ? { model: model.slice(0, AGENT_FIELD_MAX) } : {}),
+    ...(session ? { session_id: session.slice(0, AGENT_FIELD_MAX) } : {}),
+    tool: 'push',
+  };
+}
+
+/**
+ * El prompt que se sube, si quien llama lo pidió explícitamente.
+ *
+ * No se infiere del entorno ni se lee de ningún archivo por convención: un
+ * prompt puede llevar adentro cualquier cosa que alguien haya pegado en su
+ * terminal, y subir eso sin que nadie lo haya decidido es lo mismo que
+ * filtrarlo.
+ *
+ * Un prompt más largo que el techo se descarta con aviso, no se trunca: medio
+ * prompt es peor que ninguno porque parece completo.
+ */
+function readPrompt(args, agent) {
+  const file = typeof args['prompt-file'] === 'string' ? args['prompt-file'].trim() : '';
+  const inline = typeof args.prompt === 'string' ? args.prompt : '';
+
+  if (!file && !inline) return { prompt: null, warnings: [] };
+  if (file && inline) {
+    return { error: 'Elegí uno: --prompt o --prompt-file, no los dos.' };
+  }
+  if (!agent || agent.error) {
+    return { error: 'El prompt se guarda dentro de la procedencia del agente: agregá --agent <nombre>.' };
+  }
+
+  let text = inline;
+  if (file) {
+    const resolved = path.resolve(file);
+    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
+      return { error: `No encontramos el archivo del prompt: ${resolved}` };
+    }
+    try {
+      text = fs.readFileSync(resolved, 'utf8');
+    } catch (e) {
+      return { error: `No se pudo leer el prompt: ${e.message}` };
+    }
+  }
+
+  if (!text.trim()) return { prompt: null, warnings: [] };
+
+  const bytes = Buffer.byteLength(text, 'utf8');
+  if (bytes > PROMPT_MAX_BYTES) {
+    return {
+      prompt: null,
+      warnings: [
+        `El prompt pesa ${Math.round(bytes / 1024)} KB y el techo es ` +
+          `${PROMPT_MAX_BYTES / 1024} KB: se guarda el cambio sin él.`,
+      ],
+    };
+  }
+
+  return { prompt: text, warnings: [] };
+}
+
 /**
  * Arma el mensaje del commit. Si vino `--card`, se agrega como trailer
  * `[card: <id>]` al final: queda visible en el historial y es fácil de grepear
  * para cruzar un cambio con la tarjeta que lo pidió (Metrónomo u otro tablero).
  * El backend corta en 500 caracteres, así que recortamos el mensaje del usuario
  * antes que el trailer.
+ *
+ * Desde la Etapa 4 la tarjeta viaja ADEMÁS aparte, en `provenance.card`, que es
+ * lo que se puede consultar (`GET /api/commits/<id>?card=…`). El trailer no se
+ * saca ni se va a sacar: es el formato de todo lo ya guardado, y la procedencia
+ * entra en el oid del commit, así que lo viejo no se puede completar.
  */
 function buildMessage(userMsg, batchCount, total, partNo, nBatches, card) {
   let base = userMsg || `shilo push: ${total} archivo(s)`;