agloop 0.6.0__py3-none-any.whl

core/privacy_audit.py

@@ -0,0 +1,87 @@
+"""
+AgLoop Privacy Audit (LGPD-04).
+
+Local-only diagnostic (`agloop audit --privacy`): checks `.gitignore` coverage
+for `.env`, lists git author e-mails (flagging which are isolated `@agloop.local`
+agent identities), and scans the War Room files for residual unmasked PII —
+reusing the same regexes `sanitize_prompt_pii` already uses in `core.agent`.
+"""
+
+import os
+import subprocess
+from typing import Dict, List
+
+from core.agent import _CPF_RE, _EMAIL_RE, _SECRET_TOKEN_RE
+
+ROOM_FILES = ("war_room.md", "HISTORICO.md")
+
+
+def _gitignore_protects(repo_root: str, pattern: str) -> bool:
+    gitignore = os.path.join(repo_root, ".gitignore")
+    if not os.path.isfile(gitignore):
+        return False
+    with open(gitignore, "r", encoding="utf-8") as f:
+        lines = [line.strip() for line in f if line.strip() and not line.strip().startswith("#")]
+    return any(pattern in line for line in lines)
+
+
+def _git_author_emails(repo_root: str) -> List[str]:
+    try:
+        res = subprocess.run(
+            ["git", "log", "--all", "--format=%ae"],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            timeout=15,
+            check=False,
+        )
+    except Exception:
+        return []
+    return sorted({e.strip() for e in res.stdout.splitlines() if e.strip()})
+
+
+def _scan_pii(repo_root: str) -> Dict[str, List[str]]:
+    findings: Dict[str, List[str]] = {}
+    for name in ROOM_FILES:
+        path = os.path.join(repo_root, name)
+        if not os.path.isfile(path):
+            continue
+        with open(path, "r", encoding="utf-8", errors="replace") as f:
+            text = f.read()
+
+        hits: List[str] = []
+        if _CPF_RE.search(text):
+            hits.append("CPF")
+        if _SECRET_TOKEN_RE.search(text):
+            hits.append("API_SECRET")
+        for m in _EMAIL_RE.finditer(text):
+            if m.group(1).lower() != "agloop.local":
+                hits.append(f"EXTERNAL_EMAIL:{m.group(0)}")
+        if hits:
+            findings[name] = hits
+    return findings
+
+
+def run_privacy_audit(repo_root: str = ".") -> str:
+    """Builds the LGPD-04 privacy diagnostic report as plain text."""
+    root = os.path.realpath(repo_root)
+    lines = ["AgLoop - Relatorio de Auditoria de Privacidade (LGPD-04)", "=" * 56, ""]
+
+    env_protected = _gitignore_protects(root, ".env")
+    lines.append(f"[.gitignore] .env protegido: {'OK' if env_protected else 'FALTANDO'}")
+
+    emails = _git_author_emails(root)
+    lines.append(f"\n[git log] e-mails de autoria encontrados ({len(emails)}):")
+    for email in emails:
+        tag = "isolado (agente)" if email.endswith("@agloop.local") else "ATENCAO: nao isolado"
+        lines.append(f"  - {email} [{tag}]")
+
+    findings = _scan_pii(root)
+    lines.append(f"\n[PII residual] arquivos verificados: {', '.join(ROOM_FILES)}")
+    if findings:
+        for name, hits in findings.items():
+            lines.append(f"  - {name}: {len(hits)} ocorrencia(s) -> {hits}")
+    else:
+        lines.append("  Nenhuma ocorrencia de CPF, chave de API ou e-mail externo nao mascarado encontrada.")
+
+    return "\n".join(lines)

core/runner.py

@@ -0,0 +1,267 @@
+import logging
+import os
+import random
+import time
+from typing import Optional
+
+from core.git_lock import GitLock
+from core.war_room import WarRoom
+
+_logger = logging.getLogger("agloop.runner")
+
+
+def _mtime(path: str) -> float:
+    return os.path.getmtime(path) if os.path.exists(path) else 0.0
+
+
+def run_agent_loop(
+    agent,
+    war_room_file: str = "war_room.md",
+    sleep_time: Optional[float] = None,
+    local_poll: float = 3.0,
+    remote_poll: float = 30.0,
+    jitter: float = 2.0,
+    max_backoff: float = 60.0,
+    max_context_turns: int = 6,
+):
+    """
+    Hybrid Watcher (Vigília Híbrida). The LLM is only invoked when something changed:
+      * local_poll  -> os.path.getmtime() on the War Room (free, catches same-disk agents)
+      * remote_poll -> git fetch + "is origin ahead of me?" (network, catches other machines)
+    Idle iterations cost zero tokens and never parse the Markdown.
+
+    `sleep_time` is kept for backward compatibility and maps to `local_poll`.
+    """
+    if sleep_time is not None:
+        local_poll = float(sleep_time)
+
+    git_lock = GitLock(repo_path=".")
+    war_room = WarRoom(filepath=war_room_file)
+    room_paths = war_room.paths
+
+    _logger.info(
+        "starting agloop",
+        extra={
+            "event": "loop_start",
+            "agent": agent.name,
+            "model": agent.model,
+        },
+    )
+    print(f"Starting AgLoop for Agent: {agent.name}")
+    print(f"Model: {agent.model}")
+    print(f"War Room File: {war_room_file}")
+    print(f"Hybrid Watcher: local every ~{local_poll}s, remote every ~{remote_poll}s"
+          f"{'' if git_lock.origin else ' (no origin: local-only)'}")
+
+    # mtime observed at the END of our critical section (inside the lock). Reading it
+    # after releasing the lock could swallow a write made by another local agent.
+    observed = {"mtime": None}
+    # Set inside agent_action_callback when think_and_act() returns None (Issue #11):
+    # the outer loop must retry without having committed/pushed anything.
+    inference_failed = {"flag": False}
+    # Set inside agent_action_callback only when a real message was appended, so the
+    # outer loop's "turn_appended" log line isn't emitted for paused/no-op cycles.
+    turn_outcome = {"spoke": False}
+
+    def agent_action_callback():
+        inference_failed["flag"] = False
+        turn_outcome["spoke"] = False
+        try:
+            state = war_room.get_state()
+            if state in ("WAITING_HUMAN", "CONSENSUS"):
+                print(f"[{agent.name}] War Room state is {state}. Pausing inference until human/new turn.")
+                return
+
+            last_speaker = war_room.get_last_speaker()
+
+            # If I am the last speaker, I should wait for others.
+            if last_speaker == agent.name:
+                print(f"[{agent.name}] I was the last speaker. Waiting for others...")
+                return
+
+            # It's my turn (or no one has spoken)
+            print(f"[{agent.name}] My turn to speak!")
+            context = war_room.read_recent(max_turns=max_context_turns)
+            response = agent.think_and_act(context)
+            if response is None:
+                _logger.warning(
+                    "inference failed, skipping turn without writing to the War Room",
+                    extra={"event": "turn_failed", "agent": agent.name, "model": agent.model},
+                )
+                inference_failed["flag"] = True
+                return
+            war_room.append_message(agent.name, response)
+            turn_outcome["spoke"] = True
+            print(f"[{agent.name}] Appended response to War Room.")
+        finally:
+            observed["mtime"] = _mtime(war_room_file)
+
+    def nap(seconds: float):
+        time.sleep(seconds + random.uniform(0, jitter))
+
+    last_mod_time: Optional[float] = None  # None forces a first check on startup
+    next_remote_check = 0.0
+    pending_retry = False
+    failures = 0
+
+    while True:
+        try:
+            # ---- 1. Cheap trigger checks (no tokens, no Markdown parsing) ----
+            reason = None
+            current_mod_time = _mtime(war_room_file)
+            if pending_retry:
+                reason = "retry"
+            elif current_mod_time != last_mod_time:
+                reason = "local change"
+            elif git_lock.origin and time.monotonic() >= next_remote_check:
+                next_remote_check = time.monotonic() + remote_poll
+                if git_lock.has_remote_updates():
+                    reason = "remote update"
+
+            if reason is None:
+                nap(local_poll)
+                continue
+
+            # ---- 2. Something happened: take the lock and let the agent act ----
+            print(f"\n--- Loop Iteration for {agent.name} ({reason}) ---")
+            observed["mtime"] = None
+            success = git_lock.acquire_lock_and_push(
+                action_callback=agent_action_callback,
+                message=f"AgLoop: {agent.name} update in {war_room_file}",
+                paths=room_paths,
+                author_name=agent.name,
+            )
+
+            if success:
+                last_mod_time = observed["mtime"] if observed["mtime"] is not None else _mtime(war_room_file)
+
+                if inference_failed["flag"]:
+                    # Nothing was written/committed: back off like any other transient
+                    # failure and let the next iteration retry think_and_act cleanly.
+                    pending_retry = True
+                    failures += 1
+                    backoff = min(2 ** failures, max_backoff) + random.uniform(1, 5)
+                    print(f"[{agent.name}] Inference failed. Retrying in {backoff:.1f}s.")
+                    time.sleep(backoff)
+                    continue
+
+                pending_retry = False
+                failures = 0
+                if turn_outcome["spoke"]:
+                    try:
+                        commit_sha = git_lock.repo.head.commit.hexsha[:10]
+                    except Exception:
+                        commit_sha = None
+                    _logger.info(
+                        "turn cycle complete",
+                        extra={
+                            "event": "turn_appended",
+                            "agent": agent.name,
+                            "model": agent.model,
+                            "commit_sha": commit_sha,
+                        },
+                    )
+                nap(local_poll)
+                continue
+
+            # ---- 3. Failure: keep the trigger armed (no lost wake-ups) ----
+            pending_retry = True
+            status = git_lock.last_status
+            if status == "locked":
+                # Another local agent holds the lock: not an error, just wait a bit.
+                print(f"[{agent.name}] Local lock busy, another agent is acting. Retrying soon.")
+                nap(local_poll)
+                continue
+            if status == "lost_race":
+                # Someone pushed first: re-read immediately with fresh context.
+                print(f"[{agent.name}] Lost the race to another agent. Re-reading the War Room.")
+                failures = 0
+                nap(1.0)
+                continue
+
+            failures += 1
+            backoff = min(2 ** failures, max_backoff) + random.uniform(1, 5)
+            print(f"[{agent.name}] Sync failed ({status}). Backing off {backoff:.1f}s.")
+            time.sleep(backoff)
+
+        except KeyboardInterrupt:
+            print("\nExiting AgLoop.")
+            break
+        except Exception as e:
+            pending_retry = True
+            failures += 1
+            backoff = min(2 ** failures, max_backoff) + random.uniform(1, 5)
+            print(f"Unexpected error in loop: {e}. Backing off {backoff:.1f}s.")
+            time.sleep(backoff)
+
+
+def watch_war_room(
+    war_room_file: str = "war_room.md",
+    agent_name: str = "Gemini",
+    local_poll: float = 2.0,
+    remote_poll: float = 30.0,
+    once: bool = False,
+    repo_path: str = ".",
+    jitter: float = 2.0,
+    max_backoff: float = 60.0,
+) -> Optional[str]:
+    """
+    Passive Hybrid Watcher (SSOT shared with `scripts/vigia.py`).
+    Monitors `war_room_file` locally (`mtime`, zero cost) and remotely (`GitLock.sync_if_needed`).
+    When `once=True`, returns the new speaker's name as soon as the War Room changes and
+    the last speaker is not `agent_name` (allowing a background CLI task to exit 0 and wake the agent).
+
+    Any exception outside the `GitCommandError` cases already handled inside `GitLock`
+    (e.g. transient disk I/O, a file briefly missing mid-write) is caught per-iteration and
+    retried with exponential backoff, so the watcher never dies silently (Risco R04).
+    """
+    git_lock = GitLock(repo_path=repo_path)
+    room_path = os.path.join(repo_path, war_room_file) if not os.path.isabs(war_room_file) else war_room_file
+    war_room = WarRoom(filepath=room_path)
+
+    last_mtime = _mtime(room_path)
+    last_speaker = war_room.get_last_speaker()
+    print(
+        f"[Vigia] Monitorando '{war_room_file}' (Agente: {agent_name}, modo: {'once' if once else 'contínuo'}, "
+        f"último orador: '{last_speaker}')",
+        flush=True,
+    )
+
+    next_remote_check = time.monotonic() + remote_poll
+    failures = 0
+
+    while True:
+        try:
+            time.sleep(local_poll)
+
+            changed = False
+            current_mtime = _mtime(room_path)
+            if current_mtime != last_mtime:
+                last_mtime = current_mtime
+                changed = True
+                print(f"\n[VIGIA ALERTA] Modificação local detectada em {war_room_file}!", flush=True)
+            elif git_lock.origin and time.monotonic() >= next_remote_check:
+                next_remote_check = time.monotonic() + remote_poll
+                if git_lock.has_remote_updates():
+                    print("\n[VIGIA ALERTA] Novos commits detectados em origin!", flush=True)
+                    if git_lock.sync_if_needed(war_room.paths):
+                        last_mtime = _mtime(room_path)
+                        changed = True
+
+            if changed:
+                speaker = war_room.get_last_speaker()
+                print(f"[Vigia] Novo orador: '{speaker}'", flush=True)
+                if speaker and speaker != agent_name:
+                    print(f"[Vigia] >>> ATENÇÃO: {speaker} respondeu! Vez de {agent_name}.", flush=True)
+                    if once:
+                        return speaker
+                else:
+                    print(f"[Vigia] {agent_name} falou por último. Aguardando réplica...", flush=True)
+
+            failures = 0
+        except Exception as e:
+            failures += 1
+            backoff = min(2 ** failures, max_backoff) + random.uniform(0, jitter)
+            print(f"[Vigia] Erro inesperado no laço de monitoramento: {e}. Tentando novamente em {backoff:.1f}s.", flush=True)
+            time.sleep(backoff)
+

core/scan.py

@@ -0,0 +1,108 @@
+"""
+AgLoop Repository Scan (E07.3).
+
+`agloop scan` / MCP tool `scan_repository`: read-only inspection of a
+repository — directory structure (bounded depth, defensive caps) and known
+stack manifests — reusing the same confinement/PII primitives already
+enforced for `read_file`/`list_dir` in `core.agent`. Never triggered
+automatically (see the informational-only `SessionStart` hook); always an
+explicit, user-initiated action.
+"""
+
+import os
+import subprocess
+from typing import List, Optional
+
+from core.agent import _is_sensitive_path, _is_within_workspace, sanitize_prompt_pii
+
+MAX_DEPTH = 3
+MAX_LISTED_ITEMS = 30
+GITIGNORE_CHECK_TIMEOUT = 3
+
+_DEFAULT_IGNORED_DIRS = {
+    "node_modules", ".venv", "venv", "__pycache__", ".git", ".agloop.lock",
+    "target", "dist", "build", ".pytest_cache",
+}
+
+_STACK_MANIFESTS = (
+    "pyproject.toml", "requirements.txt", "package.json", "Cargo.toml",
+    "go.mod", "pom.xml", "Dockerfile",
+)
+
+
+def _is_gitignored(repo_root: str, rel_path: str) -> bool:
+    """`git check-ignore` with a short timeout; defensively returns False if not a git repo or on any error."""
+    try:
+        result = subprocess.run(
+            ["git", "check-ignore", "-q", rel_path],
+            cwd=repo_root,
+            capture_output=True,
+            timeout=GITIGNORE_CHECK_TIMEOUT,
+            check=False,
+        )
+    except Exception:
+        return False
+    return result.returncode == 0
+
+
+def _detect_stack(root: str) -> List[str]:
+    return [name for name in _STACK_MANIFESTS if os.path.isfile(os.path.join(root, name))]
+
+
+def _walk(root: str, current: str, depth: int, lines: List[str], counter: List[int]) -> None:
+    if depth > MAX_DEPTH or counter[0] >= MAX_LISTED_ITEMS:
+        return
+    try:
+        entries = sorted(os.listdir(current))
+    except OSError:
+        return
+
+    for entry in entries:
+        if counter[0] >= MAX_LISTED_ITEMS:
+            lines.append("  " * depth + "... e mais itens (limite do relatório atingido)")
+            return
+
+        full = os.path.join(current, entry)
+        rel = os.path.relpath(full, root).replace("\\", "/")
+
+        if entry in _DEFAULT_IGNORED_DIRS:
+            continue
+        if not _is_within_workspace(root, full) or _is_sensitive_path(root, full):
+            continue
+        if _is_gitignored(root, rel):
+            continue
+
+        is_dir = os.path.isdir(full)
+        lines.append("  " * depth + entry + ("/" if is_dir else ""))
+        counter[0] += 1
+
+        if is_dir:
+            _walk(root, full, depth + 1, lines, counter)
+
+
+def run_scan(repo_root: str = ".") -> str:
+    """Builds a read-only structure + stack report as plain text."""
+    root = os.path.realpath(repo_root)
+    lines = ["AgLoop - Relatorio de Varredura do Repositorio", "=" * 48, ""]
+
+    stack = _detect_stack(root)
+    lines.append(f"[stack detectada] {len(stack)} manifesto(s):")
+    if stack:
+        for name in stack:
+            lines.append(f"  - {name}")
+    else:
+        lines.append("  Nenhum manifesto de stack conhecido encontrado na raiz.")
+
+    has_war_room = os.path.isfile(os.path.join(root, "war_room.md"))
+    has_gestao = os.path.isdir(os.path.join(root, "docs", "gestao"))
+    lines.append(f"\n[governanca AgLoop] war_room.md: {'OK' if has_war_room else 'AUSENTE'}")
+    lines.append(f"[governanca AgLoop] docs/gestao/: {'OK' if has_gestao else 'AUSENTE'}")
+    if not has_war_room:
+        lines.append("  Dica: execute 'agloop init' para criar a governanca.")
+
+    lines.append(f"\n[estrutura de diretorios] profundidade maxima {MAX_DEPTH}, até {MAX_LISTED_ITEMS} itens:")
+    tree_lines: List[str] = []
+    _walk(root, root, 0, tree_lines, [0])
+    lines.extend(tree_lines if tree_lines else ["  (vazio)"])
+
+    return sanitize_prompt_pii("\n".join(lines))

core/templates/HISTORICO.md

@@ -0,0 +1,3 @@
+# Histórico
+
+Turnos encerrados são arquivados aqui automaticamente pelo `GitLock` ao atingir `<!--FIM_TURNO-->`.

core/templates/gestao/backlog-produto.md

@@ -0,0 +1,3 @@
+# Backlog de Produto
+
+<!-- Registre aqui os Épicos do projeto, um por seção, com Issue vinculada, status e entregas. -->

core/templates/gestao/matriz-riscos.md

@@ -0,0 +1,5 @@
+# Matriz de Riscos
+
+| ID | Risco | Probabilidade / Impacto | Status |
+| :---: | :--- | :---: | :---: |
+| R01 | | | Aberto |

core/templates/gestao/roadmap.md

@@ -0,0 +1,5 @@
+# Roadmap
+
+| Marco | Nome | Escopo Principal | Issues Vinculadas | Status |
+| :---: | :--- | :--- | :---: | :---: |
+| **M1** | | | | Planejado |

core/templates/war_room.md

@@ -0,0 +1,3 @@
+# War Room
+
+This is the IPC communication channel for agents.

core/war_room.py

@@ -0,0 +1,196 @@
+import os
+import re
+from typing import List, Optional
+
+CLOSE_MARKERS = (
+    "<!--FIM_TURNO-->",
+    "<!-- AGLOOP_STATE: CONSENSUS -->",
+    "STATUS: CONSENSUS",
+)
+
+WAITING_HUMAN_MARKERS = (
+    "<!-- AGLOOP_STATE: WAITING_HUMAN -->",
+    "STATUS: WAITING_HUMAN",
+)
+
+
+class WarRoom:
+    def __init__(
+        self,
+        filepath: str = "war_room.md",
+        archive_filepath: Optional[str] = None,
+        keep_recent_turns: int = 1,
+    ):
+        self.filepath = filepath
+        if archive_filepath is not None:
+            self.archive_filepath = archive_filepath
+        else:
+            directory = os.path.dirname(self.filepath)
+            self.archive_filepath = os.path.join(directory, "HISTORICO.md") if directory else "HISTORICO.md"
+        self.keep_recent_turns = keep_recent_turns
+
+        if not os.path.exists(self.filepath):
+            with open(self.filepath, "w", encoding="utf-8") as f:
+                f.write("# AgLoop War Room\n\nThis is the IPC communication channel for agents.\n\n")
+
+    @property
+    def paths(self) -> List[str]:
+        """Paths managed by this WarRoom (main room + archive file for atomic commits)."""
+        return [self.filepath, self.archive_filepath]
+
+    @staticmethod
+    def has_close_marker(text: str) -> bool:
+        """Returns True if `text` contains a turn-closing or consensus marker."""
+        return any(marker in text for marker in CLOSE_MARKERS)
+
+    @staticmethod
+    def has_waiting_human_marker(text: str) -> bool:
+        """Returns True if `text` contains a waiting-for-human marker."""
+        return any(marker in text for marker in WAITING_HUMAN_MARKERS)
+
+    def read_all(self) -> str:
+        """Reads the entire war room content."""
+        with open(self.filepath, "r", encoding="utf-8") as f:
+            return f.read()
+
+    def read_recent(self, max_turns: int = 6) -> str:
+        """
+        Reads the War Room header plus at most the last `max_turns` speaker messages
+        (sliding context window — E03.1 / Risco R07).
+        """
+        content = self.read_all()
+        if max_turns <= 0:
+            parts = re.split(r"(?=^##\s+(?!Turno\b))", content, flags=re.MULTILINE)
+            return (parts[0].rstrip() + "\n") if parts else ""
+
+        parts = re.split(r"(?=^##\s+(?!Turno\b))", content, flags=re.MULTILINE)
+        header = parts[0] if parts else ""
+        speaker_blocks = [p for p in parts[1:] if p.strip()]
+        if len(speaker_blocks) <= max_turns:
+            return content
+
+        kept = speaker_blocks[-max_turns:]
+        return header.rstrip() + "\n\n" + "\n\n".join(b.strip() for b in kept) + "\n"
+
+    def get_state(self) -> str:
+        """
+        Inspects the latest speaker block (after any trailing `<!--INICIANDO_TURNO-->`)
+        and returns one of:
+          * `"WAITING_HUMAN"` — if a human-intervention marker is present
+          * `"CONSENSUS"`     — if a consensus / turn-closed marker is present
+          * `"ACTIVE"`        — otherwise
+        """
+        content = self.read_all()
+        parts = re.split(r"(?=^##\s+(?!Turno\b))", content, flags=re.MULTILINE)
+        speaker_blocks = [p for p in parts[1:] if p.strip()]
+        if not speaker_blocks:
+            return "ACTIVE"
+
+        last_segment = speaker_blocks[-1].split("<!--INICIANDO_TURNO-->")[-1]
+        if self.has_waiting_human_marker(last_segment):
+            return "WAITING_HUMAN"
+        if self.has_close_marker(last_segment):
+            return "CONSENSUS"
+        return "ACTIVE"
+
+    def append_message(self, agent_name: str, message: str):
+        """
+        Appends a message to the war room. If the message carries a close/consensus
+        marker (`<!--FIM_TURNO-->` or `CONSENSUS`), older turns are automatically
+        archived into `self.archive_filepath` (`HISTORICO.md`) in the same disk operation.
+        """
+        with open(self.filepath, "a", encoding="utf-8") as f:
+            f.write(f"\n## {agent_name}\n\n{message}\n")
+        if self.has_close_marker(message):
+            self.archive_old_turns(keep_recent=self.keep_recent_turns)
+
+    def _split_header_and_blocks(self, content: str):
+        """
+        Splits the War Room into (preamble_header, blocks).
+        If formal `<!--INICIANDO_TURNO-->` markers exist, splits by turn blocks
+        (treating any pre-turn speaker sections as a block before the first formal turn);
+        otherwise splits by `## <Speaker>` sections.
+        """
+        if "<!--INICIANDO_TURNO-->" in content:
+            parts = re.split(r"(?=^(?:---\s*\n+)?<!--INICIANDO_TURNO-->)", content, flags=re.MULTILINE)
+            first_part = parts[0]
+            turn_blocks = [p for p in parts[1:] if p.strip()]
+            # Separate the top `# ...` header from any legacy `## Speaker` messages in first_part
+            m = re.search(r"^##\s+", first_part, flags=re.MULTILINE)
+            if m:
+                header = first_part[: m.start()]
+                legacy_block = first_part[m.start() :]
+                blocks = ([legacy_block] if legacy_block.strip() else []) + turn_blocks
+            else:
+                header = first_part
+                blocks = turn_blocks
+            return header, blocks
+
+        parts = re.split(r"(?=^##\s+)", content, flags=re.MULTILINE)
+        header = parts[0] if parts else ""
+        blocks = [p for p in parts[1:] if p.strip()]
+        return header, blocks
+
+    def archive_old_turns(self, keep_recent: Optional[int] = None) -> bool:
+        """
+        Moves older blocks/turns to `self.archive_filepath` (`HISTORICO.md`),
+        keeping the `keep_recent` most recent block(s) in `self.filepath`.
+        Returns True if any block was archived.
+        """
+        keep = self.keep_recent_turns if keep_recent is None else max(1, int(keep_recent))
+        content = self.read_all()
+        header, blocks = self._split_header_and_blocks(content)
+        if len(blocks) <= keep:
+            return False
+
+        to_archive = blocks[:-keep]
+        to_keep = blocks[-keep:]
+
+        if not os.path.exists(self.archive_filepath):
+            with open(self.archive_filepath, "w", encoding="utf-8") as af:
+                af.write("# AgLoop — Histórico da Sala de Guerra\n\n")
+
+        with open(self.archive_filepath, "a", encoding="utf-8") as af:
+            for block in to_archive:
+                af.write(block.rstrip() + "\n\n")
+
+        new_room = header.rstrip() + "\n\n" + "\n\n".join(b.strip() for b in to_keep) + "\n"
+        with open(self.filepath, "w", encoding="utf-8") as rf:
+            rf.write(new_room)
+        return True
+
+    def close_turn_and_archive(
+        self,
+        agent_name: Optional[str] = None,
+        closing_message: str = "<!--FIM_TURNO-->",
+        keep_recent: Optional[int] = None,
+    ) -> List[str]:
+        """
+        Appends a closing message (ensuring a close marker is present) and archives
+        older turns into `HISTORICO.md` in one step so `GitLock` can commit both
+        files atomically in a single commit.
+        """
+        if not self.has_close_marker(closing_message):
+            closing_message = f"{closing_message.rstrip()}\n\n<!--FIM_TURNO-->"
+
+        if agent_name:
+            with open(self.filepath, "a", encoding="utf-8") as f:
+                f.write(f"\n## {agent_name}\n\n{closing_message}\n")
+        else:
+            with open(self.filepath, "a", encoding="utf-8") as f:
+                f.write(f"\n{closing_message}\n")
+
+        self.archive_old_turns(keep_recent=keep_recent)
+        return self.paths
+
+    def get_last_speaker(self) -> Optional[str]:
+        """
+        Parses the file to find who spoke last.
+        Looks for the last '## AgentName' header.
+        """
+        content = self.read_all()
+        matches = re.findall(r"^##\s+(.+)$", content, flags=re.MULTILINE)
+        if matches:
+            return matches[-1].strip()
+        return None
+