@andespindola/crow-skills 0.12.2 → 0.13.0

package/skills/crow-behaviour/scripts/lc_run.py

@@ -0,0 +1,731 @@
+#!/usr/bin/env python3
+"""lean-context: roda um comando e entrega ao agente uma visão enxuta e fiel da saída.
+
+Princípios (cada um corrige um gap observado em rtk, caveman ou context-mode):
+- Nunca resume, reescreve ou inventa: só seleciona linhas reais, com a numeração original.
+- Nunca esconde perda: todo corte é marcado e a saída completa fica num arquivo reabrível,
+  também quando o comando dá certo.
+- Preserva o exit code do comando (sinal -> 128+N, timeout -> 124), herda o stdin,
+  roda em grupo de processos próprio, tem timeout e mata o grupo inteiro ao estourar.
+- Mascara padrões comuns de segredo no que mostra e no que grava (melhor esforço, não garantia);
+  nada bruto vai para o disco; arquivos 0600 num diretório 0700, com retenção curta.
+- Métrica honesta: bytes medidos (brutos vs. exibidos), nunca tokens estimados.
+
+Uso:
+  lc_run.py [opções] -- comando arg1 arg2      # executa direto (sem shell)
+  lc_run.py [opções] -- 'cmd | outro && mais'   # um único argumento: roda em bash -c
+  lc_run.py --stats                             # totais medidos
+Só usa a biblioteca padrão do Python 3.8+. macOS e Linux.
+"""
+from __future__ import annotations
+
+import argparse
+import collections
+import json
+import os
+import re
+import shutil
+import signal
+import stat
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+TAG = "[lean-context]"
+PIECE = 65536  # linhas maiores são processadas em pedaços: custo linear, memória limitada
+
+# ---------------------------------------------------------------- redação (melhor esforço)
+_KW = r"(?:password|passwd|passphrase|pwd|secret|token|api[_-]?key|apikey|private[_-]?key|access[_-]?key|client[_-]?secret|credentials?)"
+_SECRET_PATTERNS = [
+    # PEM/PGP inteiro numa linha (ex.: JSON de service account com \n literal)
+    (re.compile(rb"(-----BEGIN [A-Z0-9 ]{0,40}PRIVATE KEY(?: BLOCK)?-----).{0,20000}?(-----END [A-Z0-9 ]{0,40}PRIVATE KEY(?: BLOCK)?-----)"), rb"\1<redigido:chave-privada>\2"),
+    (re.compile(rb"(?i)\b(authorization\s{0,5}[:=]\s{0,5}(?:bearer|basic|token|bot)\s{1,5})[A-Za-z0-9._~+/=-]{8,}"), rb"\1<redigido>"),
+    (re.compile(rb"(?i)\b(bearer\s{1,5})[A-Za-z0-9._~+/=-]{16,}"), rb"\1<redigido>"),
+    (re.compile(rb"(?i)\b(x-api-key\s{0,5}[:=]\s{0,5})\S{8,}"), rb"\1<redigido>"),
+    # VAR=valor / chave: valor / "chave": "valor", com prefixo (PGPASSWORD, AWS_SECRET_ACCESS_KEY, OPENAI_API_KEY);
+    # o valor só é mascarado se parecer segredo (ver _kv_repl): erros como token: expired_or_revoked ficam
+    (re.compile(rb"(?i)(" + _KW.encode() + rb"([A-Za-z0-9_]{0,20})[\"']?\s{0,5}[:=]\s{0,5}[\"']?)(?!<redigido)([^\s\"',;&]{4,})"), "kv"),
+    # flags: --password valor, --token=valor
+    (re.compile(rb"(?i)((?<![\w-])--?(?:password|passwd|pass|token|secret|api-key|apikey|auth-token)(?:=|\s{1,5}))(?![0-9]+\b)(?!<redigido)[^\s\"']{4,}"), rb"\1<redigido>"),
+    # curl -u usuario:senha, cookies, Azure, Grafana, Hugging Face
+    (re.compile(rb"((?<![\w-])(?:-u|--user)\s{1,5}[^\s:'\"]{1,64}:)[^\s'\"]{4,}"), rb"\1<redigido>"),
+    (re.compile(rb"(?i)\b((?:set-)?cookie:\s{0,5}[^=;\s]{1,64}=)[^;\s]{8,}"), rb"\1<redigido>"),
+    (re.compile(rb"(?i)\b(AccountKey=|SharedAccessSignature=|SharedAccessKey=|[?&]sig=)[A-Za-z0-9%+/=]{16,}"), rb"\1<redigido>"),
+    (re.compile(rb"\bglsa_[A-Za-z0-9_]{20,}"), b"<redigido:grafana>"),
+    (re.compile(rb"\bhf_[A-Za-z0-9]{30,}"), b"<redigido:huggingface>"),
+    (re.compile(rb"\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}"), b"<redigido:sk>"),
+    (re.compile(rb"\b(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{10,}"), b"<redigido:stripe>"),
+    (re.compile(rb"\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}"), b"<redigido:sendgrid>"),
+    (re.compile(rb"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{30,}"), b"<redigido:github>"),
+    (re.compile(rb"\bgithub_pat_[A-Za-z0-9_]{40,}"), b"<redigido:github>"),
+    (re.compile(rb"\bglpat-[A-Za-z0-9_-]{20,}"), b"<redigido:gitlab>"),
+    (re.compile(rb"\b(?:AKIA|ASIA)[0-9A-Z]{16}\b"), b"<redigido:aws>"),
+    (re.compile(rb"\bxox[abprs]-[A-Za-z0-9-]{10,}"), b"<redigido:slack>"),
+    (re.compile(rb"\bAIza[0-9A-Za-z_-]{35}\b"), b"<redigido:google>"),
+    (re.compile(rb"\bnpm_[A-Za-z0-9]{36}\b"), b"<redigido:npm>"),
+    (re.compile(rb"\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}"), b"<redigido:jwt>"),
+    # credencial em URL: esquema://usuario:senha@  (ancorado e limitado: linear)
+    (re.compile(rb"(?<![A-Za-z0-9+.-])([A-Za-z][A-Za-z0-9+.-]{0,20}://[^\s:/@]{1,200}:)[^\s@/]{3,200}@"), rb"\1<redigido>@"),
+]
+# pré-filtro: só roda as regex completas quando a linha tem algum gatilho
+_SECRET_TRIGGER = re.compile(rb"(?i)-----BEGIN|authoriz|bearer|api[_-]?key|pass|pwd|secret|token|private|access|credential|sk-|_live_|_test_|SG\.|gh[pousr]_|github_pat_|glpat-|AKIA|ASIA|xox|AIza|npm_|eyJ|://|cookie|accountkey|sharedaccess|sig=|glsa_|hf_|-u |--user")
+_KEY_SUFFIX_NOT_SECRET = re.compile(rb"(?i)^(izer|izers|ization|_?names?|_?types?|_?ids?|_?paths?|_?files?|_?urls?|_?counts?|_?limits?|_?len(gth)?|_?expir\w*|_?ttl|s_used|_?status|_?policy|_?format)$")
+
+
+def _secretish(val: bytes) -> bool:
+    if len(val) < 6 or val[:1] in (b"/", b"~", b".", b"$", b"<", b"{"):
+        return False
+    if re.fullmatch(rb"[a-z_.-]+", val) or re.fullmatch(rb"[0-9]+", val):
+        return False  # palavra comum (expired_or_revoked, invalid_grant) ou número (max_tokens=4096)
+    if val.lower() in (b"true", b"false", b"null", b"none", b"undefined", b"required", b"missing", b"invalid"):
+        return False
+    return True
+_PEM_BEGIN = re.compile(rb"-----BEGIN [A-Z0-9 ]{0,40}PRIVATE KEY(?: BLOCK)?-----")
+_PEM_END = re.compile(rb"-----END [A-Z0-9 ]{0,40}PRIVATE KEY(?: BLOCK)?-----")
+_PEM_BODY = re.compile(rb"^\s*(?:[A-Za-z0-9+/=]{1,}|[A-Za-z][A-Za-z-]{0,30}: .{0,200}|=[A-Za-z0-9+/]{1,10})?\s*$")
+PEM_MAX_LINES = 200
+
+
+class Redactor:
+    def __init__(self, enabled: bool):
+        self.enabled = enabled
+        self.pem_lines = -1  # -1 = fora de bloco PEM
+        self.count = 0
+
+    def _kv_repl(self, m) -> bytes:
+        if _KEY_SUFFIX_NOT_SECRET.match(m.group(2)) or not _secretish(m.group(3)):
+            return m.group(0)
+        self.count += 1
+        return m.group(1) + b"<redigido>"
+
+    def piece(self, raw: bytes, line_start: bool) -> bytes:
+        if not self.enabled:
+            return raw
+        if self.pem_lines >= 0 and line_start:
+            if _PEM_END.search(raw):
+                self.pem_lines = -1
+                return raw
+            # só o miolo base64 é mascarado; qualquer outra linha encerra o modo PEM
+            if _PEM_BODY.match(raw.rstrip(b"\r\n")) and self.pem_lines < PEM_MAX_LINES:
+                self.pem_lines += 1
+                self.count += 1
+                return b"<redigido:chave-privada>" + (b"\n" if raw.endswith(b"\n") else b"")
+            self.pem_lines = -1
+        if not _SECRET_TRIGGER.search(raw):
+            return raw
+        out = raw
+        for pat, rep in _SECRET_PATTERNS:
+            if rep == "kv":
+                out = pat.sub(self._kv_repl, out)
+            else:
+                out, n = pat.subn(rep, out)
+                self.count += n
+        if _PEM_BEGIN.search(out) and not _PEM_END.search(out):
+            self.pem_lines = 0
+        return out
+
+
+# ---------------------------------------------------------------- sinais (todas as regex limitadas: custo linear)
+_ERR = re.compile(
+    r"(?i)(\b(error|errors|erro|erros|fatal|panic|panicked|exception|traceback|failed|failure|failing|fail|"
+    r"falha|falhas|falhou|falharam|falhando|denied|negado|refused|recusad[oa]|timed out|timeout|"
+    r"segmentation fault|segfault|sigsegv|sigabrt|aborted|core dumped|critical|crit|"
+    r"cannot|can't|unable to|não foi possível|nao foi possivel|not found|não encontrad[oa]|no such file|"
+    r"undefined|unresolved|assertion|assert|caused by|killed|oom|oomkilled|out of memory|evicted|crashloopbackoff|imagepullbackoff|errimagepull)\b"
+    r"|(Error|Exception|Fault)\b|ERR!|^\s{0,8}ERR(OR)?\b|\b(BUILD|TEST) FAIL"
+    r"|^\s{0,8}(E|F)\s{2,}|^\s{0,12}[✗✘×✕✖●]\s"
+    r"|\bHTTP/\d(\.\d)?\s{1,5}[45]\d\d\b|\bstatus(code|_code)?[\"']?\s{0,3}[=:]\s{0,3}[\"']?5\d\d\b"
+    r"|\b(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b.{0,300}[\s\"]5\d\d\b"
+    r"|\blevel[\"']?\s{0,3}[=:]\s{0,3}[\"']?(crit|critical|error|err|fatal|panic|alert|emerg)\b"
+    r"|\bexit(ed)?( with)?( code| status)?[=: ]{1,3}[1-9]\d{0,2}\b)"
+)
+_FRAME = re.compile(r"^\s{1,40}(at\s\S|File \"[^\"\n]{0,500}\", line \d+|\.\.\. \d+ more|in <module>|#\d+\s+0x)"
+                    r"|^\s{4,40}\S[^()\n]{0,300}\([^()\n]{0,300}:\d+(:\d+)?\)\s*$")
+_WARN = re.compile(r"(?i)\b(warn|warning|warnings|deprecat\w{0,10}|aviso|avisos)\b")
+_ZERO = re.compile(r"(?i)\b(0|no|zero|sem|nenhum[a]?)\s{1,3}(failed|failures?|errors?|erros?|falhas?)\b|\b(failed|errors?|failures?|erros?|falhas?)[\"']?\s{0,3}[=:]\s{0,3}0\b")
+
+
+_FRAME_M = re.compile(_FRAME.pattern, re.M)
+_PYTEST_M = re.compile(r"(?m)^\s{0,8}[EF]\s\s")
+# palavras que qualquer linha de falha ou aviso contém (em minúsculas); bloco sem nenhuma vai pelo caminho rápido
+_SIG_KEYS = ("err", "fatal", "fail", "falh", "panic", "xception", "traceback", "denied", "negad", "refus", "recusad", "timed out",
+             "timeout", "fault", "sigsegv", "sigabrt", "abort", "core dump", "crit", "cannot", "can't", "unable",
+             "foi poss", "not found", "encontrad", "no such", "undefined", "unresolved", "assert", "caused by", "killed",
+             "oom", "out of memory", "evicted", "backoff", "warn", "deprecat", "aviso",
+             "✗", "✘", "×", "✕", "✖", "●")
+# formas específicas de falha que contêm palavras comuns (status=200, GET, level=info, exit 0 não disparam)
+_BLOCK_SIG = re.compile(r"status(code|_code)?[\"']?\s{0,3}[=:]\s{0,3}[\"']?5\d\d|\b(get|post|put|patch|delete|head|options)\b[^\n]{0,300}[\s\"]5\d\d\b"
+                        r"|level[\"']?\s{0,3}[=:]\s{0,3}[\"']?(crit|critical|error|err|fatal|panic|alert|emerg)\b"
+                        r"|\bexit(ed)?( with)?( code| status)?[=: ]{1,3}[1-9]|http/\d(\.\d)?\s{1,5}[45]\d\d")
+_SECRET_TRIGGER_L = re.compile(_SECRET_TRIGGER.pattern.replace(b"(?i)", b"").lower())
+_CTRL_B = re.compile(rb"[\x00-\x08\x0b\x0e-\x1f\x7f]")
+
+
+def match_err(text: str):
+    m = _FRAME.search(text)
+    if m:
+        return m
+    m = _ERR.search(text)
+    if m and _ZERO.search(text):
+        m = _ERR.search(_ZERO.sub(lambda z: " " * len(z.group(0)), text))
+    return m
+
+
+def classify(text: str) -> int:
+    if match_err(text):
+        return 1
+    if _WARN.search(text):
+        return 2
+    return 0
+
+
+_CTRL = re.compile(r"[\x00-\x08\x0b\x0e-\x1f\x7f]+|\ufffd+")
+
+
+def is_binary(b: bytes) -> bool:
+    if not b:
+        return False
+    if b"\x00" in b:
+        return True
+    ctrl = sum(1 for c in b[:4096] if c < 32 and c not in (9, 10, 12, 13, 27))
+    return ctrl / min(len(b), 4096) > 0.3
+
+
+# ---------------------------------------------------------------- linha lógica
+class Line:
+    """Visão de exibição de uma linha (possivelmente enorme, com \\r de barra de progresso)."""
+    __slots__ = ("n", "length", "kind", "text", "binary", "cr")
+
+    def __init__(self, n):
+        self.n, self.length, self.kind, self.text, self.binary, self.cr = n, 0, 0, None, False, False
+
+    def feed(self, red: bytes, width: int):
+        self.length += len(red)
+        txt = red.decode("utf-8", errors="replace").rstrip("\r\n")
+        if is_binary(red) or (len(txt) > 8 and txt.count("\ufffd") > 0.3 * len(txt)):
+            self.binary = True
+            txt = _CTRL.sub("", txt)
+            m = match_err(txt)
+            if m:
+                self.kind, self.text = 1, window(txt, m.start(), width)
+            return
+        segs = txt.split("\r") if "\r" in txt else [txt]
+        if len(segs) > 1:
+            self.cr = True
+        for seg in segs:
+            m = match_err(seg)
+            k = 1 if m else (2 if _WARN.search(seg) else 0)
+            if k and (self.kind == 0 or k < self.kind):
+                self.kind = k
+                self.text = window(seg, m.start() if m else 0, width)
+            elif self.kind == 0 and seg.strip():
+                self.text = window(seg, 0, width)  # último segmento visível de uma barra de progresso
+        if self.text is None:
+            self.text = ""
+
+    def show(self) -> str:
+        if self.binary and not self.text:
+            return f"<conteúdo binário, {self.length} bytes>"
+        extra = []
+        if self.cr:
+            extra.append("atualizações com \\r omitidas")
+        if self.length > len(self.text.encode("utf-8", errors="replace")) + 4 and not self.cr:
+            extra.append(f"linha com {self.length} bytes")
+        return self.text + (f"  …({'; '.join(extra)}; ver arquivo)" if extra else "")
+
+
+def window(s: str, pos: int, width: int) -> str:
+    if len(s) <= width:
+        return s
+    start = max(0, min(pos - width // 4, len(s) - width))
+    out = s[start:start + width]
+    return ("…" if start else "") + out + ("…" if start + width < len(s) else "")
+
+
+# ---------------------------------------------------------------- estado em disco
+def state_dir(arg: str | None) -> Path:
+    base = arg or os.environ.get("LEAN_CONTEXT_DIR")
+    if not base:
+        xdg = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+        base = os.path.join(xdg, "lean-context")
+    p = Path(base)
+    p.mkdir(parents=True, exist_ok=True, mode=0o700)
+    st = os.lstat(p)
+    if stat.S_ISLNK(st.st_mode) or not stat.S_ISDIR(st.st_mode):
+        raise SystemExit(f"{TAG} recusado: {p} não é um diretório comum")
+    if st.st_uid != os.getuid():
+        raise SystemExit(f"{TAG} recusado: {p} pertence a outro usuário")
+    if stat.S_IMODE(st.st_mode) & 0o077:
+        os.chmod(p, 0o700)
+        if stat.S_IMODE(os.lstat(p).st_mode) & 0o077:
+            raise SystemExit(f"{TAG} recusado: não consegui deixar {p} privado (0700)")
+    return p
+
+
+def purge_old(d: Path, keep_days: float) -> None:
+    limit = time.time() - keep_days * 86400
+    for pat in ("run-*.log", ".tmp-*"):
+        for f in d.glob(pat):
+            try:
+                if os.lstat(f).st_mtime < limit:
+                    f.unlink()
+            except OSError:
+                pass
+
+
+def private_open(path: Path, append=False):
+    flags = os.O_WRONLY | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0)
+    flags |= os.O_APPEND if append else os.O_EXCL
+    fd = os.open(path, flags, 0o600)
+    return os.fdopen(fd, "ab" if append else "wb")
+
+
+def human(n: float) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024 or unit == "GB":
+            return f"{int(n)} {unit}" if unit == "B" else f"{n:.1f} {unit}"
+        n /= 1024
+    return str(n)
+
+
+def emit(s: str = "") -> None:
+    try:
+        sys.stdout.write(s + "\n")
+    except (BrokenPipeError, OSError):
+        pass  # erro de escrita nunca troca o exit code do comando
+
+
+def safe_cut(data: bytes, limit: int) -> int:
+    """Ponto de corte de uma linha enorme: o último espaço antes do limite cujos 96 bytes anteriores não têm
+    gatilho de segredo, para que nem segredo nem palavra de erro fiquem partidos entre dois pedaços."""
+    lo = max(1, limit - 8192)
+    i = limit
+    while True:
+        i = max(data.rfind(b" ", lo, i), data.rfind(b"\t", lo, i))
+        if i < lo:
+            return limit  # sem espaço (ex.: minificado): corte fixo; risco residual documentado
+        if not _SECRET_TRIGGER_L.search(data[max(0, i - 96):i].lower()):
+            return i + 1
+
+
+# ---------------------------------------------------------------- coleta em streaming
+class Collector:
+    def __init__(self, args, redactor: Redactor, out):
+        self.a, self.red, self.out = args, redactor, out
+        self.lines = 0
+        self.bytes = 0
+        self.head: list[Line] = []
+        self.tail: collections.deque = collections.deque(maxlen=args.tail)
+        k = max(1, args.max_signals)
+        self.err_first: list[Line] = []
+        self.err_last: collections.deque = collections.deque(maxlen=k // 2 or 1)
+        self.err_total = 0
+        self.warn: list[Line] = []
+        self.warn_total = 0
+        self.ctx_after = 0
+        self.ctx_buf: collections.deque = collections.deque(maxlen=max(1, args.context))
+        self.pending_ctx: list = []
+        self.small_raw = bytearray()  # cópia redigida enquanto a saída ainda é pequena
+        self.small_ok = True
+        self.altered = False
+        self.binary_lines = 0
+        self.cur: Line | None = None
+        self.buf = bytearray()
+        self.sec_any = True
+        self.sig_any = True
+        self.must_keep = False
+
+    def write(self, chunk: bytes):
+        data = bytes(self.buf) + chunk if self.buf else chunk
+        # testes de bloco: um bloco sem nenhum gatilho dispensa as regex por linha
+        self.sec_any = self.red.enabled and (self.red.pem_lines >= 0 or bool(_SECRET_TRIGGER_L.search(data.lower())))
+        if _CTRL_B.search(data):
+            self.sig_any = True
+        else:
+            t = data.decode("utf-8", errors="replace")
+            low = t.lower()
+            self.sig_any = ("\ufffd" in t or "\r" in t or any(k in low for k in _SIG_KEYS)
+                            or bool(_BLOCK_SIG.search(low) or _FRAME_M.search(t) or _PYTEST_M.search(t)))
+        parts = data.split(b"\n")
+        rest = parts.pop()
+        for part in parts:
+            while len(part) >= PIECE:
+                cut = safe_cut(part, PIECE)
+                self._piece(part[:cut], end=False)
+                part = part[cut:]
+            self._piece(part + b"\n", end=True)
+        while len(rest) >= PIECE:
+            cut = safe_cut(rest, PIECE)
+            self._piece(rest[:cut], end=False)
+            rest = rest[cut:]
+        self.buf = bytearray(rest)
+
+    def close(self):
+        self.sec_any = self.sig_any = True
+        if self.buf:
+            self._piece(bytes(self.buf), end=True)
+            self.buf.clear()
+        elif self.cur is not None:
+            self._finish()
+
+    def _piece(self, raw: bytes, end: bool):
+        start = self.cur is None
+        if start:
+            self.cur = Line(self.lines + 1)
+        red = self.red.piece(raw, start) if self.sec_any else raw
+        if red != raw:
+            self.altered = True
+        self.out.write(red)
+        self.bytes += len(raw)
+        if self.small_ok:
+            if len(self.small_raw) + len(red) <= self.a.inline_max_bytes:
+                self.small_raw += red
+            else:
+                self.small_ok = False
+                self.small_raw = bytearray()
+        if not self.sig_any:
+            ln = self.cur
+            ln.length += len(red)
+            if ln.text is None or (ln.kind == 0 and len(ln.text) < self.a.width):
+                t = red[: self.a.width * 4].decode("utf-8", errors="replace").rstrip("\r\n")
+                ln.text = window(((ln.text or "") + t), 0, self.a.width) if ln.text else window(t, 0, self.a.width)
+        elif len(self.cur.text or "") < self.a.width or self.cur.kind == 0:
+            self.cur.feed(red, self.a.width)
+        else:
+            self.cur.length += len(red)
+        if end:
+            self._finish()
+
+    def _finish(self):
+        ln, self.cur = self.cur, None
+        self.lines += 1
+        if ln.binary:
+            self.binary_lines += 1
+        if len(self.head) < self.a.head:
+            self.head.append(ln)
+        self.tail.append(ln)
+        if ln.kind == 1:
+            self.err_total += 1
+            group = list(self.ctx_buf)[-1:] + [ln]  # uma linha antes (ex.: título do teste)
+            self._add_err(group)
+            self.ctx_after = self.a.context
+        elif self.ctx_after > 0:
+            self.ctx_after -= 1
+            self._add_err([ln], context=True)
+        elif ln.kind == 2:
+            self.warn_total += 1
+            if len(self.warn) < self.a.max_signals:
+                self.warn.append(ln)
+        self.ctx_buf.append(ln)
+
+    def _add_err(self, group, context=False):
+        k = max(1, self.a.max_signals)
+        if len(self.err_first) < k:
+            self.err_first.extend(group)
+        elif context:
+            if self.err_last:
+                self.err_last[-1].extend(group)
+        else:
+            self.err_last.append(list(group))
+
+
+# ---------------------------------------------------------------- execução
+def run(cmd: list[str], timeout: float, coll: Collector) -> tuple[int, float, list[str]]:
+    notes: list[str] = []
+    if len(cmd) == 1 and re.search(r"[\s|&;<>()$`*?~{}\[\]'\"\\]", cmd[0]):
+        sh = shutil.which("bash") or "/bin/sh"
+        argv = [sh, "-c", cmd[0]]
+    else:
+        argv = cmd
+    start = time.monotonic()
+    try:
+        # grupo de processos próprio na mesma sessão (o vigia precisa poder entrar nele)
+        proc = subprocess.Popen(argv, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, stdin=None,
+                                preexec_fn=lambda: os.setpgid(0, 0))
+    except FileNotFoundError:
+        coll.write(f"lean-context: comando não encontrado: {argv[0]}\n".encode())
+        coll.close()
+        return 127, 0.0, notes
+    except PermissionError:
+        coll.write(f"lean-context: sem permissão para executar: {argv[0]}\n".encode())
+        coll.close()
+        return 126, 0.0, notes
+    pgid = proc.pid
+    watchdog = start_watchdog(pgid)
+
+    def forward(signum, _frame):
+        try:
+            os.killpg(pgid, signum)
+        except (ProcessLookupError, PermissionError):
+            pass
+
+    old = {s: signal.signal(s, forward) for s in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP)}
+    lock = threading.Lock()
+
+    def pump():
+        assert proc.stdout is not None
+        for chunk in iter(lambda: proc.stdout.read1(65536), b""):
+            with lock:
+                coll.write(chunk)
+
+    reader = threading.Thread(target=pump, daemon=True)
+    reader.start()
+    timed_out = False
+    try:
+        proc.wait(timeout=timeout if timeout > 0 else None)
+    except subprocess.TimeoutExpired:
+        timed_out = True
+        kill_group(pgid, proc)
+        notes.append(f"timeout de {timeout:g}s atingido; SIGTERM e depois SIGKILL enviados ao grupo do comando "
+                     "(processos que criaram sessão própria com setsid ficam fora do alcance)")
+    reader.join(timeout=5)
+    if reader.is_alive():
+        if timed_out:
+            kill_group(pgid, proc)
+        notes.append("um processo filho em segundo plano manteve a saída aberta; a leitura parou sem matá-lo")
+    for s, h in old.items():
+        signal.signal(s, h)
+    if watchdog is not None:
+        try:
+            watchdog.kill()
+            watchdog.wait(timeout=2)
+        except Exception:
+            pass
+    with lock:
+        coll.close()
+    elapsed = time.monotonic() - start
+    rc = proc.returncode
+    if timed_out:
+        rc = 124
+    elif rc is None:
+        rc = 1
+    elif rc < 0:
+        rc = 128 + (-rc)
+    return rc, elapsed, notes
+
+
+_WATCHDOG = r"""
+import os, signal, sys, time
+parent, pgid = int(sys.argv[1]), int(sys.argv[2])
+while os.getppid() == parent:
+    time.sleep(0.5)
+for sig, wait in ((signal.SIGTERM, 2.0), (signal.SIGKILL, 0)):
+    try:
+        os.killpg(pgid, sig)
+    except ProcessLookupError:
+        break
+    time.sleep(wait)
+"""
+
+
+_REAP: list = []
+
+
+def start_watchdog(pgid: int):
+    """Processo vigia dentro do grupo do comando: se o lc_run for morto (ex.: SIGKILL pelo timeout do host),
+    o vigia percebe a orfandade e encerra o grupo, para não sobrar comando órfão."""
+    try:
+        w = subprocess.Popen([sys.executable, "-I", "-c", _WATCHDOG, str(os.getpid()), str(pgid)],
+                             stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                             preexec_fn=lambda: os.setpgid(0, pgid))
+        _REAP.append(w)
+        return w
+    except Exception:
+        return None
+
+
+def group_alive(pgid: int) -> bool:
+    try:
+        os.killpg(pgid, 0)
+        return True
+    except (ProcessLookupError, PermissionError):
+        return False  # macOS: EPERM quando só restam zombies no grupo
+
+
+def kill_group(pgid: int, proc) -> None:
+    for sig, grace in ((signal.SIGTERM, 3.0), (signal.SIGKILL, 2.0)):
+        try:
+            os.killpg(pgid, sig)
+        except (ProcessLookupError, PermissionError):
+            return
+        deadline = time.monotonic() + grace
+        while time.monotonic() < deadline:
+            proc.poll()
+            for w in _REAP:
+                w.poll()
+            if not group_alive(pgid):
+                return
+            time.sleep(0.05)
+
+
+# ---------------------------------------------------------------- relatório
+def render(rc, elapsed, c: Collector, path: Path, args, notes, shell_cmd: bool):
+    small = (c.small_ok and c.lines <= args.inline_max_lines and c.binary_lines == 0)
+    shown = 0
+
+    def out(s: str = ""):
+        nonlocal shown
+        shown += len(s.encode("utf-8", errors="replace")) + 1
+        emit(s)
+
+    status = f"exit={rc} · {c.lines} linhas · {human(c.bytes)} · {elapsed:.1f}s"
+    if c.bytes == 0:
+        out(f"{TAG} {status} · o comando não escreveu nada")
+    elif small:
+        text = bytes(c.small_raw).decode("utf-8", errors="replace")
+        for line in text.split("\n")[:-1] if text.endswith("\n") else text.split("\n"):
+            out(line)
+        note = "saída completa acima, sem cortes"
+        if c.altered or "\ufffd" in text or "\r" in text:
+            c.must_keep = True
+            note += f" (exibição pode diferir em bytes: \\r, UTF-8 inválido ou segredos; original redigido em {path})"
+        out(f"{TAG} {status} · {note}")
+    else:
+        red = " (padrões comuns de segredo mascarados; melhor esforço)" if c.red.enabled else ""
+        out(f"{TAG} {status}")
+        out(f"{TAG} saída completa{red}: {path}")
+        out(f"{TAG} abaixo só há linhas reais, com a numeração original; nada foi resumido nem reescrito")
+        seen: set[int] = set()
+
+        def block(title: str, items):
+            fresh = [l for l in items if l.n not in seen]
+            if not fresh:
+                return
+            out(f"--- {title} ---")
+            prev = None
+            run_start = None
+            for l in sorted(fresh, key=lambda x: x.n):
+                if l.n in seen:
+                    continue
+                if prev is not None and l.n > prev + 1:
+                    if run_start is not None:
+                        out(f"L{run_start}–L{prev}: <conteúdo binário>")
+                        run_start = None
+                    out(f"      … L{prev + 1}–L{l.n - 1} omitidas")
+                if l.binary and not l.text:
+                    if run_start is None:
+                        run_start = l.n
+                else:
+                    if run_start is not None:
+                        out(f"L{run_start}–L{prev}: <conteúdo binário>")
+                        run_start = None
+                    out(f"L{l.n}: {l.show()}")
+                seen.add(l.n)
+                prev = l.n
+            if run_start is not None:
+                out(f"L{run_start}–L{prev}: <conteúdo binário>")
+
+        if c.head:
+            block(f"início (L1–L{c.head[-1].n})", c.head)
+        errs = list(c.err_first) + [l for g in c.err_last for l in g]
+        if c.err_total:
+            shown_err = len({l.n for l in errs if l.kind == 1})
+            title = f"falhas e contexto ({c.err_total} linha(s) de falha"
+            if c.err_total > shown_err:
+                title += f"; exibidas as primeiras e as últimas, {c.err_total - shown_err} omitidas: use Grep no arquivo"
+            block(title + ")", errs)
+        budget = max(0, args.max_signals - len(errs))
+        if c.warn_total and budget:
+            ws = c.warn[:budget]
+            title = f"avisos ({c.warn_total} no total"
+            title += f"; {c.warn_total - len(ws)} não exibidos)" if c.warn_total > len(ws) else ")"
+            block(title, ws)
+        elif c.warn_total:
+            out(f"{TAG} {c.warn_total} linha(s) de aviso não exibidas (prioridade para falhas)")
+        if c.tail:
+            block(f"fim (L{c.tail[0].n}–L{c.tail[-1].n})", list(c.tail))
+        out(f"{TAG} {len(seen)} de {c.lines} linhas exibidas; {c.lines - len(seen)} omitidas. Para ver mais: Read no arquivo com offset/limit, ou Grep nele")
+    if rc != 0 and not c.err_total and c.bytes:
+        out(f"{TAG} atenção: exit={rc} sem linha de falha reconhecida; leia o fim do arquivo antes de concluir")
+    if rc == 0 and c.err_total:
+        hint = " (num pipeline vale o exit do último estágio; use set -o pipefail)" if shell_cmd else ""
+        out(f"{TAG} atenção: exit=0, mas há {c.err_total} linha(s) com cara de falha{hint}")
+    if c.red.count:
+        out(f"{TAG} {c.red.count} trecho(s) com cara de segredo mascarado(s)")
+    for n in notes:
+        out(f"{TAG} {n}")
+    return small, shown
+
+
+def record_stats(d: Path, raw_bytes: int, shown: int, rc: int, kept: bool) -> None:
+    try:
+        with private_open(d / "stats.jsonl", append=True) as f:
+            f.write((json.dumps({"ts": int(time.time()), "raw_bytes": raw_bytes, "shown_bytes": shown,
+                                 "exit": rc, "file_kept": kept}) + "\n").encode())
+    except OSError:
+        pass
+
+
+def print_stats(d: Path) -> int:
+    runs = raw = shown = 0
+    p = d / "stats.jsonl"
+    if p.exists() and not p.is_symlink():
+        for line in p.read_text(encoding="utf-8", errors="replace").splitlines():
+            try:
+                r = json.loads(line)
+            except ValueError:
+                continue
+            runs += 1
+            raw += r.get("raw_bytes", 0)
+            shown += r.get("shown_bytes", 0)
+    emit(f"{TAG} execuções: {runs}")
+    emit(f"{TAG} bytes produzidos pelos comandos: {human(raw)}")
+    emit(f"{TAG} bytes que entraram no contexto: {human(shown)}")
+    if raw:
+        emit(f"{TAG} redução medida em bytes: {100 * (1 - shown / raw):.1f}% (bytes, não tokens; não diz nada sobre a qualidade da tarefa)")
+    return 0
+
+
+def main(argv: list[str]) -> int:
+    if "--" in argv:
+        i = argv.index("--")
+        opts, cmd = argv[:i], argv[i + 1:]
+    else:
+        opts, cmd = argv, []
+    ap = argparse.ArgumentParser(prog="lc_run.py", description="Saída enxuta e fiel de comandos para agentes.")
+    ap.add_argument("--timeout", type=float, default=float(os.environ.get("LEAN_CONTEXT_TIMEOUT", 110)),
+                    help="segundos (padrão 110, abaixo do timeout padrão de 120 s do Bash do host)")
+    ap.add_argument("--inline-max-lines", type=int, default=150)
+    ap.add_argument("--inline-max-bytes", type=int, default=12000)
+    ap.add_argument("--head", type=int, default=30)
+    ap.add_argument("--tail", type=int, default=50)
+    ap.add_argument("--max-signals", type=int, default=40)
+    ap.add_argument("--context", type=int, default=3, help="linhas exibidas depois de cada falha")
+    ap.add_argument("--width", type=int, default=400, help="largura (marcada) de linhas muito longas")
+    ap.add_argument("--keep-days", type=float, default=3)
+    ap.add_argument("--dir", default=None)
+    ap.add_argument("--no-redact", action="store_true")
+    ap.add_argument("--stats", action="store_true")
+    args = ap.parse_args(opts)
+    d = state_dir(args.dir)
+    if args.stats:
+        return print_stats(d)
+    if not cmd:
+        ap.error("informe o comando depois de --")
+    purge_old(d, args.keep_days)
+    stamp = time.strftime("%Y%m%d-%H%M%S") + f"-{os.getpid()}"
+    final_path = d / f"run-{stamp}.log"
+    redactor = Redactor(not args.no_redact)
+    with private_open(final_path) as out:
+        coll = Collector(args, redactor, out)
+        rc, elapsed, notes = run(cmd, args.timeout, coll)
+    shell_cmd = len(cmd) == 1 and "|" in cmd[0]
+    small, shown = render(rc, elapsed, coll, final_path, args, notes, shell_cmd)
+    keep = coll.bytes > 0 and (not small or coll.altered or coll.must_keep)
+    if not keep:
+        try:
+            final_path.unlink()  # coube inteiro e intacto no contexto: não há o que recuperar
+        except OSError:
+            pass
+    record_stats(d, coll.bytes, shown, rc, keep)
+    try:
+        sys.stdout.flush()
+    except (BrokenPipeError, OSError):
+        pass
+    return rc
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))