@ingeniomaps/cauce 0.98.0 → 0.99.1

package/engine/core/migrations.js

@@ -0,0 +1,275 @@
+'use strict'
+
+// Qué es una migración para un proyecto, qué parte de ella aplica y qué cuenta como destruir. Lo preguntan
+// el guard `migrations`, que juzga cada escritura, y `check`, que mira si lo declarado alcanza a algún
+// archivo; la respuesta tiene que ser la misma en los dos, y por eso vive una sola vez acá.
+
+const path = require('node:path')
+const { spawnSync } = require('node:child_process')
+
+// Sin esto el guard sólo veía `.sql`, así que en TypeORM, Prisma, Django, Rails o Alembic no miraba nada:
+// ni frenaba el SQL destructivo, ni protegía una migración existente de ser reescrita. Y no lo decía —
+// aparecía cableado y en verde—. Medido en una instancia real: 64 migraciones `.sql` cubiertas y **409
+// TypeORM `.ts` invisibles** (caso 077).
+//
+// No se amplía el default a `.ts`/`.py`/`.rb` por su cuenta: eso reintroduciría el falso positivo del
+// caso 039 —un archivo de lenguaje que menciona `DROP TABLE` en un comentario o en un string— por otra
+// puerta. Declararlo es opt-in porque el que sabe si sus migraciones son de lenguaje es el proyecto, y
+// porque así el costo lo elige quien lo paga.
+const DEFAULT_EXTENSIONS = ['sql']
+
+// Las carpetas se declaran por lo mismo que las extensiones: ninguna lista del motor alcanza a Alembic,
+// cuya carpeta es el argumento de `alembic init` y puede moverse con `version_locations` (caso 196). El
+// default son los tres nombres que el motor usaba antes, así que quien no declara nada no ve diferencia.
+const DEFAULT_PATHS = ['migrations', 'migration', 'migrate']
+
+// Una carpeta relativa, de segmentos que no empiezan con punto: así no hay `..`, `.` ni ruta absoluta, y
+// lo que entra en la expresión regular no trae metacaracteres salvo el punto, que se escapa al usarla.
+const PATH_SHAPE = /^[A-Za-z0-9_-][A-Za-z0-9._-]*(?:\/[A-Za-z0-9_-][A-Za-z0-9._-]*)*$/
+const EXTENSION_SHAPE = /^[a-z0-9]+$/
+
+// Lo inválido no se descarta en silencio: descartarlo dejaría al proyecto creyendo que declaró una
+// cobertura que no tiene. Lo valida `validateOpsConfig`, y acá se ignora lo que no pasa ese filtro porque
+// el guard no es el lugar donde se enseña a escribir la configuración.
+function declared(config, key, shape, fallback) {
+  const value = ((config && config.migrations) || {})[key]
+  const usable = (Array.isArray(value) ? value : []).filter((one) => typeof one === 'string' && shape.test(one))
+  return usable.length ? usable : fallback
+}
+
+function pattern(config) {
+  const extensions = declared(config, 'extensions', EXTENSION_SHAPE, DEFAULT_EXTENSIONS)
+  const folders = declared(config, 'paths', PATH_SHAPE, DEFAULT_PATHS).map((one) => one.replace(/\./g, '\\.'))
+  return new RegExp(`(?:^|/)(?:${folders.join('|')})/.*\\.(?:${extensions.join('|')})$`, 'i')
+}
+
+// Dónde empieza la reversión, por formato. Cada marcador es el que su herramienta reconoce y no uno
+// parecido, porque partir donde la herramienta no parte deja sin juzgar algo que sí corre:
+//
+// - goose (`internal/sqlparser/parser.go` de pressly/goose, `main`): la línea empieza con `--` sin
+//   espacio antes, y la anotación se compara con `strings.EqualFold`, así que `--+goose down` vale.
+// - dbmate (`pkg/dbmate/migration.go` de amacneil/dbmate, `main`): `(?m)^--\s*migrate:down(\s*$|\s+\S+)`,
+//   sensible a mayúsculas.
+//
+// El `Up` también se reconoce porque devuelve al lado que aplica: lo que venga después de él se juzga.
+const SQL_MARKERS = [
+  { up: /^--\s*\+goose\s*up\s*$/i, down: /^--\s*\+goose\s*down\s*$/i, label: '-- +goose Down' },
+  { up: /^--\s*migrate:up(?:\s*$|\s+\S+)/, down: /^--\s*migrate:down(?:\s*$|\s+\S+)/, label: '-- migrate:down' },
+]
+
+// El método de reversión de cada herramienta de lenguaje: `downgrade()` de Alembic, `down` de Rails
+// (también el `self.down` de las versiones viejas), `down()` de TypeORM y `exports.down` o `export function
+// down` de Knex. Se lo reconoce al principio de la línea, así que una llamada a `this.down(...)` dentro de
+// `up` no cuenta.
+const LANGUAGE_HEADERS = [
+  { header: /^(\s*)(?:async\s+)?def\s+downgrade\s*\(/, label: 'downgrade()' },
+  { header: /^(\s*)def\s+(?:self\.)?down\b/, label: 'down' },
+  { header: /^(\s*)(?:(?:public|protected|private)\s+)?(?:async\s+)?down\s*\(/, label: 'down()' },
+  { header: /^(\s*)(?:module\.)?exports\.down\s*=/, label: 'exports.down' },
+  { header: /^(\s*)export\s+(?:async\s+)?function\s+down\s*\(|^(\s*)export\s+const\s+down\s*=/, label: 'down()' },
+]
+
+// Las herramientas golang-migrate y sqlx guardan la reversión en otro archivo, `{version}_{title}.down.{extension}`
+// (`MIGRATIONS.md` de golang-migrate/migrate), y ése es reversión entera.
+const DOWN_FILE = /\.down\.[^./]+$/i
+
+const indent = (line) => line.match(/^\s*/)[0].length
+
+// Qué líneas aplican: una lista de booleanos, uno por línea, y el marcador que parte. `null` si no hay nada
+// que partir, para que quien pregunta juzgue el texto entero: sin marcador reconocido se degrada al
+// comportamiento de antes en vez de fallar abierto. Los marcadores son comentarios y no aplican.
+function sqlMask(lines) {
+  const markers = SQL_MARKERS.filter((one) => lines.some((line) => one.up.test(line) || one.down.test(line)))
+  if (!markers.length) return null
+  let applies = true
+  const mask = lines.map((line) => {
+    if (markers.some((one) => one.up.test(line))) {
+      applies = true
+      return false
+    }
+    if (markers.some((one) => one.down.test(line))) {
+      applies = false
+      return false
+    }
+    return applies
+  })
+  return { mask, label: markers[0].label }
+}
+
+// En una migración de lenguaje el bloque termina donde la indentación vuelve a la del encabezado: la línea
+// que lo cierra —`}`, `end`, `};`— queda del lado que aplica, y da igual porque no destruye nada. Es la
+// forma en que las herramientas generan sus migraciones; lo que se aparta de ella acorta el bloque en vez de
+// alargarlo, así que un archivo con formato raro se juzga de más y no de menos. El borde que queda abierto
+// es escribir `up` en la misma línea que el encabezado de `down`, y eso no lo genera ninguna.
+function languageMask(lines) {
+  let label = ''
+  let depth = null
+  const mask = lines.map((line) => {
+    if (depth !== null) {
+      if (!line.trim() || indent(line) > depth) return false
+      depth = null
+    }
+    const found = LANGUAGE_HEADERS.find((one) => one.header.test(line))
+    if (!found) return true
+    label = found.label
+    depth = indent(line)
+    return false
+  })
+  return label ? { mask, label } : null
+}
+
+function applyMask(file, lines) {
+  if (DOWN_FILE.test(file)) return { mask: lines.map(() => false), label: path.basename(file) }
+  return /\.sql$/i.test(file) ? sqlMask(lines) : languageMask(lines)
+}
+
+// Lo que hay que juzgar de una escritura: el texto de las líneas que aplican y el marcador que partió, o
+// el texto entero sin marcador si no había nada que partir.
+//
+// En un `Edit` el guard no ve el archivo, sólo el fragmento. Se reconstruye el archivo como va a quedar
+// —`old` reemplazado en `disk`— y se juzga la parte del fragmento que cae del lado que aplica, así que un
+// fragmento que mueve un marcador se lee en su lugar y no suelto. Sin `disk` o sin `old` adentro se juzga
+// el fragmento entero, como antes.
+function judged(file, text, edit = {}) {
+  const { disk, old, all } = edit
+  let result = String(text)
+  let spans = [[0, result.length]]
+  if (old && typeof disk === 'string' && disk.includes(old)) {
+    const at = disk.indexOf(old)
+    const pieces = all ? disk.split(old) : [disk.slice(0, at), disk.slice(at + old.length)]
+    result = pieces[0]
+    spans = []
+    for (const piece of pieces.slice(1)) {
+      spans.push([result.length, result.length + String(text).length])
+      result += String(text) + piece
+    }
+  } else if (old) return { text: String(text), label: '' }
+  const lines = result.split('\n')
+  const split = applyMask(file, lines.map((line) => line.replace(/\r$/, '')))
+  if (!split && spans.length === 1 && spans[0][0] === 0 && spans[0][1] === result.length) {
+    return { text: result, label: '' }
+  }
+  const kept = []
+  let at = 0
+  lines.forEach((line, index) => {
+    const [from, to] = [at, at + line.length]
+    at = to + 1
+    if (split && !split.mask[index]) return
+    for (const [start, end] of spans) {
+      if (Math.max(start, from) <= Math.min(end, to)) {
+        kept.push(result.slice(Math.max(start, from), Math.min(end, to)))
+      }
+    }
+  })
+  return { text: kept.join('\n'), label: split ? split.label : '' }
+}
+
+// Las secciones de un `apply_patch`, por archivo: la línea `*** Add|Update|Delete File: <ruta>` y lo que
+// sigue hasta la cabecera del próximo archivo o `*** End Patch`. Cada línea conserva su prefijo —`+`
+// agregada, `-` quitada, ` ` contexto— porque de él depende qué se juzga. `@@`, `*** Move to:` y
+// `*** End of File` son del formato y no contenido, y no cortan la sección: cortarla ahí dejaba sin juzgar
+// lo que venía después, y pasaba lo que el guard viejo, que juzgaba el sobre entero, frenaba.
+function patchSections(patch) {
+  const sections = new Map()
+  let current = null
+  for (const line of String(patch).split('\n')) {
+    const header = line.match(/^\*\*\* (Add|Update|Delete) File:\s*(.+)$/)
+    if (header) {
+      current = { kind: header[1].toLowerCase(), lines: [] }
+      sections.set(header[2].trim(), current)
+    } else if (/^\*\*\* End Patch\s*$/.test(line)) current = null
+    else if (current && !line.startsWith('@@') && !line.startsWith('*** ')) {
+      current.lines.push({ op: line[0] || ' ', text: line.slice(1) })
+    }
+  }
+  return sections
+}
+
+// Lo que hay que juzgar de un archivo del parche, con el mismo contrato que `judged` (caso 199). Un archivo
+// nuevo es su contenido entero sin el prefijo, y se parte como un `Write`. Una modificación es el lado que va a
+// quedar —contexto y agregado—, partido con lo que el hunk trae, y de él se juzga sólo lo agregado: lo quitado
+// no destruye nada y el contexto ya estaba. Si el hunk no trae ningún marcador, no se sabe de qué lado cae y se
+// juzga todo lo agregado, como antes.
+function judgedPatch(file, section) {
+  if (section.kind === 'delete') return { text: '', label: '' }
+  if (section.kind === 'add') return judged(file, section.lines.map((line) => line.text).join('\n'))
+  const after = section.lines.filter((line) => line.op !== '-')
+  const split = applyMask(file, after.map((line) => line.text.replace(/\r$/, '')))
+  const kept = after.filter((line, index) => line.op === '+' && (!split || split.mask[index]))
+  return { text: kept.map((line) => line.text).join('\n'), label: split ? split.label : '' }
+}
+
+// Lo que destruye escrito en SQL. Cada rama cierra su propio límite. Cuando el `\b` estaba al final del
+// grupo se aplicaba a las tres, y la de `delete` termina a propósito en `;`: después de un punto y coma no
+// hay límite de palabra, así que `DELETE FROM pedidos;` —la forma que tiene en cualquier migración— pasaba
+// y sólo frenaba la variante sin punto y coma. `drop column` y `drop constraint` faltaban: pierden datos y
+// garantías igual que `drop table`.
+const DESTRUCTIVE_SQL = new RegExp(
+  String.raw`\bdrop\s+(?:table|database|schema|column|constraint)\b` +
+    String.raw`|\btruncate\b` +
+    String.raw`|\bdelete\s+from\s+\S+\s*(?:;|$)`,
+  'i',
+)
+
+// Lo que destruye escrito con la API de la herramienta (caso 193). Son los nombres que la documentación
+// pública de cada una define, comprobados el 2026-09-23 y no más: Alembic (`ops.html`), Rails
+// (`active_record_migrations.md`), TypeORM (`migrations/09-api.md`), Knex (`schema-builder.md`) y Django
+// (`ref/migration-operations`). La lista envejece nombrando: lo que no está sigue pasando, igual que antes.
+// Sensible a mayúsculas porque la API lo es, y así `DeleteModel` no se confunde con prosa.
+const DESTRUCTIVE_API = new RegExp(
+  String.raw`\b(?:drop_table|drop_column|remove_columns?|drop_join_table` +
+    String.raw`|dropTable|dropTableIfExists|dropColumns?|DeleteModel|RemoveField)\b`,
+)
+
+// Qué destruye en `text`, o vacío: el fragmento que lo delata y de qué clase es, para que el mensaje pueda
+// nombrar la sentencia y no sólo el archivo.
+function destructive(text) {
+  const sql = String(text).match(DESTRUCTIVE_SQL)
+  if (sql) return { kind: 'SQL destructivo', what: sql[0].replace(/\s+/g, ' ').toUpperCase() }
+  const api = String(text).match(DESTRUCTIVE_API)
+  return api ? { kind: 'un borrado destructivo', what: api[0] } : null
+}
+
+// Lo declarado en `migrations` que no alcanza a ningún archivo del producto: una extensión o una carpeta
+// que el guard promete mirar y no mira nada. Es lo que el 077 y el 196 tienen en común —cobertura
+// declarada que no cubre, en silencio—, y va en `check` y no en el guard porque recorre el repositorio y el
+// guard corre en cada escritura (R26).
+//
+// Sólo mira lo que el proyecto declaró: sin declarar, el default no promete nada que alguien haya elegido.
+// Lee `git ls-files` de cada repositorio de las raíces, que es barato y deja afuera lo generado; sin
+// repositorio no dice nada, como el resto de los avisos que preguntan a git.
+function coverageWarnings(repos, config) {
+  const migrations = (config && config.migrations) || {}
+  const askExtensions = Array.isArray(migrations.extensions)
+  const askPaths = Array.isArray(migrations.paths)
+  if (!askExtensions && !askPaths) return []
+  const files = repos.flatMap((repo) => {
+    const listed = spawnSync('git', ['ls-files', '-z'], { cwd: repo, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 })
+    return listed.status === 0 ? listed.stdout.split('\0').filter(Boolean) : []
+  })
+  if (!files.length) return []
+  const matcher = pattern(config)
+  const covered = files.filter((file) => matcher.test(file))
+  const warnings = []
+  if (askExtensions) {
+    for (const one of declared(config, 'extensions', EXTENSION_SHAPE, [])) {
+      if (covered.some((file) => file.toLowerCase().endsWith(`.${one}`))) continue
+      warnings.push(`ops.config.json: migrations.extensions "${one}" no alcanza a ningún archivo bajo `
+        + `${declared(config, 'paths', PATH_SHAPE, DEFAULT_PATHS).join(', ')}: el guard no mira ninguna `
+        + 'migración con esa extensión. Si viven en otra carpeta, declarala en migrations.paths')
+    }
+  }
+  if (askPaths) {
+    for (const one of declared(config, 'paths', PATH_SHAPE, [])) {
+      const only = pattern({ migrations: { ...migrations, paths: [one] } })
+      if (files.some((file) => only.test(file))) continue
+      warnings.push(`ops.config.json: migrations.paths "${one}" no alcanza a ningún archivo con las extensiones `
+        + `${declared(config, 'extensions', EXTENSION_SHAPE, DEFAULT_EXTENSIONS).join(', ')}`)
+    }
+  }
+  return warnings
+}
+
+module.exports = {
+  PATH_SHAPE, EXTENSION_SHAPE, pattern, judged, judgedPatch, patchSections, destructive, coverageWarnings,
+}

package/engine/core/repos.js

@@ -34,7 +34,7 @@ function reposFor(opsRoot, service) {
     .filter(Boolean)
     // Dos raíces del mismo repositorio son un solo repositorio: lo ambiguo es a cuál pertenece el
     // servicio, no cuántas rutas lo contienen.
-    .filter((repo, index, todos) => todos.indexOf(repo) === index)
+    .filter((repo, index, all) => all.indexOf(repo) === index)
 }
 
 // El repositorio del servicio cuando no hay duda. Sin ninguno o con varios devuelve vacío, y quien
@@ -84,7 +84,7 @@ function unrecordedCommits(repo, since, recorded) {
   // historial reescrito o un `commit --date` la cuenta daba cero sobre un repositorio lleno.
   const log = git(repo, 'log', '--no-merges', '--date=short', '--format=%h %ad %s')
   if (log.status !== 0) return []
-  const conocidos = new Set([...recorded].map((sha) => String(sha).slice(0, 7)))
+  const known = new Set([...recorded].map((sha) => String(sha).slice(0, 7)))
   // El hash y la fecha se leen partiendo por espacios y no por columna: `%h` mide 7 por default y git lo
   // sube solo cuando el repositorio crece —en éste mide 8—, así que una posición fija leía un espacio en
   // vez de la fecha y ningún commit pasaba el filtro. El aviso quedaba mudo sin decirlo, que es la peor
@@ -92,7 +92,7 @@ function unrecordedCommits(repo, since, recorded) {
   return log.stdout.split('\n').map((line) => line.trim()).filter(Boolean)
     .map((line) => ({ line, sha: line.split(/\s+/)[0], date: line.split(/\s+/)[1] }))
     .filter((one) => one.date >= since)
-    .filter((one) => !conocidos.has(one.sha.slice(0, 7)))
+    .filter((one) => !known.has(one.sha.slice(0, 7)))
     .map((one) => one.line)
 }
 
@@ -153,4 +153,18 @@ function unrecordedHumanActions(opsRoot, rows) {
     .map((row) => `HUMAN_ACTIONS.md: ${row.task} figura resuelta y ningún commit la registró`)
 }
 
-module.exports = { reposFor, repoOf, lastCommit, coverageWarnings, unrecordedHumanActions }
+// Qué archivos tocó un commit, buscado en todos los repositorios declarados: una entrada de DONE nombra
+// el sha y no el repositorio. Devuelve null si ninguno lo conoce, y quien pregunta decide qué significa.
+// `--root` es para que el primer commit de un repositorio también liste lo suyo.
+function commitFiles(opsRoot) {
+  const repos = reposFor(opsRoot, '.')
+  return (sha) => {
+    for (const repo of repos) {
+      const shown = git(repo, 'diff-tree', '--no-commit-id', '--name-only', '-r', '--root', sha)
+      if (shown.status === 0) return shown.stdout.split('\n').map((line) => line.trim()).filter(Boolean)
+    }
+    return null
+  }
+}
+
+module.exports = { reposFor, repoOf, lastCommit, coverageWarnings, unrecordedHumanActions, commitFiles }

package/engine/hooks/approval.js

@@ -15,8 +15,8 @@
 // **Se coteja, no se consume.** Borrar el archivo al leerlo daría el mismo alcance y traería dos cosas
 // que no queremos: hoy ningún guard escribe en el repositorio, y `governance` corre antes que `verify`,
 // así que un commit frenado por otra razón se habría llevado puesta la aprobación y habría que
-// rehacerla. Cotejando, la aprobación vale para el conjunto que nombra y para ningún otro: en cuanto
-// cambia lo que está en el índice deja de servir, que es «por operación» sin fecha ni contador.
+// rehacerla. Cotejando, la aprobación vale para las rutas que nombra y para ninguna otra: lo que se sume
+// al índice vuelve a frenar, que es «por operación» sin fecha ni contador.
 //
 // Queda a la vista porque `check` avisa mientras exista. Sin eso, un archivo olvidado sigue autorizando
 // esas mismas rutas la próxima vez que alguien las stagee, que es la puerta abierta que esto evitaba.
@@ -79,6 +79,17 @@ function where(input) {
   return relative && !relative.startsWith('..') && !path.isAbsolute(relative) ? relative : file
 }
 
+// Lo que el último mensaje de la persona negaba no quedó esperando su confirmación, así que un «dale» no
+// lo aprobaría: ofrecerlo sería mandarla a contestar para volver a frenar (caso 188). Lo que sí lo pasa es
+// pedirlo nombrándolo, que es una orden y no una confirmación.
+function REFUSED(items, input = {}) {
+  return `Lo último que dijo la persona niega o frena ${items.join(', ')}, así que no quedó esperando su `
+    + 'confirmación y un sí no lo aprobaría: no reintentes. '
+    + (input.agent_id
+      ? 'Devolvele el bloqueo a quien te lanzó. '
+      : 'Si lo quiere, que lo pida en el chat nombrándolo. ')
+}
+
 // Cómo se toma la salida angosta, dicho una vez porque lo dicen todos los bloqueos que la tienen. Lleva
 // las líneas exactas porque cada guard coteja la ruta en la forma que tiene a mano —absoluta la que llega
 // de un Write, relativa al repositorio la que sale del índice— y una línea en la otra forma no pega: sin
@@ -93,8 +104,10 @@ function where(input) {
 // `pasteable` es lo que se puede aprobar por archivo, y por defecto es todo: un guard lo angosta cuando lo
 // que tiene a mano no sirve para pegar —por qué, en `secrets-shell.js` (caso 118)—. Lo frenado se anota
 // igual, así que el «dale» sigue cubriendo todo.
-function HOW(variable, lines, input, pasteable = lines) {
-  const chat = CHAT.hold(input, lines)
+function HOW(variable, lines, input, pasteable = lines, { durable = false } = {}) {
+  const held = CHAT.hold(input, lines)
+  const dropped = held ? held.dropped : []
+  const chat = held && dropped.length < lines.length
   const stuck = lines.filter((one) => !pasteable.includes(one))
   // El alcance del «dale» va con la oferta y no después. La rama del pegado ya decía el suyo —«valen para
   // ese conjunto»— y la del chat no decía ninguno, siendo la que se ofrece primero. Las dos mitades que
@@ -103,18 +116,35 @@ function HOW(variable, lines, input, pasteable = lines) {
   // siguientes** es la dirección permisiva, la que nadie nota porque lo que no ocurre es un bloqueo.
   // `check` la muestra al final de la corrida —es lo que trajo el 117—, y al concederla no la decía nadie
   // (caso 170).
-  const ask = chat
-    ? 'Decile a la persona qué se frenó y por qué, y pedile que lo confirme con sus palabras: un «dale» '
+  // Un subagente no puede esperar la respuesta —su turno termina antes—, así que lo que le toca es
+  // devolver el bloqueo: preguntar lo hace quien lo lanzó, y el reintento pasa aunque vuelva a ser delegado
+  // (caso 186).
+  const lead = input.agent_id
+    ? 'Sos un subagente y no podés esperar la respuesta: devolvele a quien te lanzó qué se frenó y por qué, '
+      + 'para que se lo pregunte a la persona. Si ella lo confirma, el mismo cambio pasa aunque lo reintente '
+      + 'un subagente. '
+    : 'Decile a la persona qué se frenó y por qué, y pedile que lo confirme con sus palabras: un «dale» '
       + 'alcanza, pero no hace falta esa palabra. Si lo que contesta es un sí, reintentá el mismo cambio y '
       + 'pasa; si duda, pregunta o dice que no, no reintentes. Juzgarlo te toca a vos: el guard sólo frena la '
-      + 'respuesta que niega, frena o pregunta. Esa confirmación cubre lo que se frenó y nada más —algo nuevo '
-      + 'vuelve a frenar— y sigue valiendo en los mensajes siguientes hasta que ella lo niegue. '
+      + 'respuesta que niega, frena o pregunta. '
+  const ask = chat
+    ? lead + 'Esa confirmación cubre lo que se frenó y nada más —algo nuevo vuelve a frenar— y sigue valiendo '
+      + 'en los mensajes siguientes hasta que ella lo niegue. '
     : ''
+  const refused = dropped.length ? REFUSED(dropped, input) : ''
+  const keep = chat && durable ? KEEP(input, pasteable.filter((one) => !dropped.includes(one))) : ''
+  // Sin chat la salida es la misma, y también se dice como cosa de ella: el imperativo que el párrafo de
+  // arriba sacó de la rama con chat seguía acá, y es lo único que ve quien no tiene a nadie en el chat
+  // (caso 194). A quien corre el guard le toca otra cosa, y se le dice cuál. Vale también cuando hay persona
+  // pero no se le ofrece contestar, porque su último mensaje negaba todo lo frenado.
   const paste = pasteable.length
-    ? (chat ? 'Si prefiere aprobarlo a mano, que pegue ella tal cual en' : 'Aprobalo pegando tal cual en')
+    ? (chat ? 'Si prefiere aprobarlo a mano, que pegue ella' : 'Esto lo aprueba una persona: que pegue ella')
+      + ' tal cual en'
       + ` ${where(input)} estas líneas:\n`
       + pasteable.map((line) => `  ${line}\n`).join('')
-      + 'Valen para ese conjunto y dejan de valer en cuanto cambie. '
+      + 'Cada línea vale hasta que alguien la borre, y lo que no esté ahí vuelve a frenar. '
+      + (chat ? '' : 'Vos no lo escribas —un guard lo frena—: decí qué se frenó y dónde, y reintentá cuando '
+        + 'esté; si sos un subagente, devolvele el bloqueo a quien te lanzó. ')
     : ''
   const unresolved = stuck.length
     ? `Por archivo no hay línea que pegar para ${stuck.join(', ')}: la ruta llegó con una expansión del shell `
@@ -128,7 +158,28 @@ function HOW(variable, lines, input, pasteable = lines) {
     ? `La variable ${variable}=1 sigue existiendo y apaga el guard para toda la sesión, que es por lo que no `
       + 'es la vía recomendada.'
     : ''
-  return ask + paste + unresolved + off
+  return ask + keep + refused + paste + unresolved + off
+}
+
+// La lectura que un proyecto necesita siempre —el token con que su regla manda autenticar— se preguntaba en
+// cada sesión, porque el «dale» dura la sesión y la línea del archivo la tenía que pegar la persona a mano:
+// «pon esa línea» o «acepto que leas» no le alcanzaban al agente para escribírsela (caso 202).
+//
+// La pregunta va entera al agente, y no se le pide a la persona ninguna frase: cuál de las dos cosas quiso la
+// juzga él, igual que el «dale» (caso 184). Lo que hace el guard es dejar anotados, además de lo frenado, el
+// archivo de aprobación, así que la misma confirmación que habilita leer habilita escribir **esas líneas y
+// ninguna otra** —cuáles, lo compara `self-approval`—. Sólo lo ofrece un guard de lectura: una lectura
+// frena siempre la misma ruta, y ahí una línea permanente es lo que la persona está pidiendo; para un
+// commit, lo frenado cambia con el índice y dejarlo escrito no le ahorra nada a nadie.
+function KEEP(input, lines) {
+  const root = opsRoot(input)
+  if (!root || !lines.length) return ''
+  const held = CHAT.hold(input, [path.join(root, 'planning', APPROVAL)])
+  if (!held || held.dropped.length) return ''
+  return 'Preguntale también si quiere dejarlo aprobado para siempre, para no volver a preguntarlo en otra '
+    + `sesión. Si esa es su intención, agregá a ${where(input)} las líneas de abajo, con un comentario arriba que `
+    + 'diga quién lo aprobó, cuándo y para qué: la misma confirmación te deja escribirlas. Si sólo quiso que '
+    + 'leas ahora, no las escribas y vale para esta sesión. '
 }
 
 // Las dos exenciones que sobreviven a un bloqueo, para que `check` las muestre juntas: la lista que una
@@ -139,11 +190,23 @@ function HOW(variable, lines, input, pasteable = lines) {
 // repetir la autorización en cada mensaje —y eso está bien—, pero quedó del lado que nadie audita: vive en
 // el temporal del sistema, mientras que por una sola línea del archivo `check` sí avisaba. Una exención que
 // no se ve es un límite que ya no existe (caso 117).
+//
+// Una credencial aprobada se nombra aparte, y no como algo «sin borrar». Está ahí a propósito —la dejó
+// escrita la persona para no volver a autorizar la misma lectura en cada sesión (caso 202)—, y contada
+// junto a lo que quedó de un commit se leía como un olvido que había que limpiar. Sigue saliendo en cada
+// corrida, igual que `writableOutsideRoots`: una exención deliberada también se ve.
 function warnings(root) {
   const out = []
+  const { credential } = require('./files')
   const approved = read(root)
-  if (approved.length) {
-    out.push(`planning/${APPROVAL}: ${approved.length} ruta(s) aprobadas y sin borrar; `
+  const secret = approved.filter((line) => credential({ cwd: root }, line))
+  const rest = approved.filter((line) => !secret.includes(line))
+  if (secret.length) {
+    out.push(`planning/${APPROVAL}: ${secret.length} credencial(es) aprobadas hasta que se borre su línea: `
+      + secret.join(', '))
+  }
+  if (rest.length) {
+    out.push(`planning/${APPROVAL}: ${rest.length} ruta(s) aprobadas y sin borrar; `
       + 'el archivo sigue autorizándolas')
   }
   const granted = CHAT.grantedIn(root)
@@ -153,4 +216,4 @@ function warnings(root) {
   return out
 }
 
-module.exports = { APPROVAL, lines, read, pending, pendingNow, where, HOW, warnings }
+module.exports = { APPROVAL, lines, read, pending, pendingNow, where, HOW, REFUSED, warnings }