> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Detecção de Staleness de Arquivos

> Rastreamento de mtime e SHA-256 para detectar modificacoes externas entre read e write

O ChatCLI implementa um sistema de **detecção de staleness de arquivos** que rastreia o estado dos arquivos entre operações de leitura e escrita. Quando um arquivo e modificado externamente (pelo usuário, IDE, ou outro processo) após o agente te-lo lido, o sistema emite um aviso antes de sobrescrever -- prevenindo a perda silenciosa de alteracoes externas.

***

## Como Funciona

O tracker registra o estado de cada arquivo após leitura e verifica antes de escrita:

<Steps>
  <Step title="Leitura (RecordRead)">
    Após cada operação `read` bem-sucedida, o tracker registra:

    * **mtime**: timestamp de modificacao do arquivo
    * **SHA-256**: hash criptografico do conteúdo completo
    * **Size**: tamanho em bytes
    * **ReadAt**: timestamp de quando a leitura ocorreu
  </Step>

  <Step title="Verificação (CheckStaleness)">
    Antes de cada operação `write` ou `patch`, o tracker verifica se o arquivo mudou.
  </Step>

  <Step title="Aviso ou Prosseguimento">
    Se o arquivo mudou, um aviso e injetado no resultado da ferramenta para que o modelo decida como proceder. Se não mudou, a escrita prossegue normalmente.
  </Step>
</Steps>

***

## Verificação em 2 Etapas

A verificação usa uma estrategia otimizada de **fast path** seguida de **full hash**:

<Tabs>
  <Tab title="Etapa 1: mtime + size (rapida)">
    Primeiro, o tracker compara o `mtime` e `size` atuais com os registrados. Se ambos sao identicos, o arquivo **não esta stale** (retorno imediato, sem I/O adicional).

    ```text theme={"system"}
    mtime inalterado + size inalterado → não stale (fast path)
    ```

    <Tip>
      Essa otimização evita leitura e hash do arquivo na maioria dos casos, mantendo o overhead próximo de zero.
    </Tip>
  </Tab>

  <Tab title="Etapa 2: SHA-256 (completa)">
    Se o `mtime` ou `size` mudou, o tracker le o arquivo completo e calcula o SHA-256 para comparacao definitiva.

    ```text theme={"system"}
    mtime mudou + hash identico → não stale (ex: touch sem edicao)
    mtime mudou + hash diferente → STALE (modificacao real)
    ```

    <Note>
      Isso cobre o caso de `touch` em arquivo sem edicao (mtime muda mas conteúdo e igual) e o caso raro de modificacao que mantem o mesmo tamanho.
    </Note>
  </Tab>
</Tabs>

***

## Mensagem de Aviso

Quando um arquivo stale e detectado, o sistema gera um aviso formatado:

```text theme={"system"}
WARNING: File "/path/to/file.go" has been modified externally since you last read it.
Reason: file modified externally (mtime: 2026-04-10T10:30:00Z → 2026-04-10T10:35:22Z,
  size: 2048 → 2156)
You should re-read the file before making changes to avoid overwriting external edits.
If you proceed anyway, external changes will be lost.
```

O aviso instrui o modelo a:

1. **Re-ler** o arquivo antes de fazer alteracoes
2. Entender que continuar **sobrescrevera** as alteracoes externas

***

## Cenarios Cobertos

| Cenario                     | Resultado | Descricao                          |
| :-------------------------- | :-------- | :--------------------------------- |
| Arquivo não modificado      | Não stale | mtime e size identicos             |
| `touch` sem edicao          | Não stale | mtime muda mas SHA-256 identico    |
| Edicao real por usuário/IDE | **Stale** | mtime e hash diferentes            |
| Arquivo deletado            | **Stale** | Arquivo não existe mais            |
| Arquivo nunca lido          | Não stale | Sem registro para comparar         |
| Erro ao verificar           | Não stale | Assume não-stale para não bloquear |

***

## Normalizacao de Aspas

O ChatCLI também normaliza aspas Unicode em arquivos de código para prevenir erros de compilacao causados por aspas tipograficas geradas por LLMs:

| Caracter  | Descricao            | Substituicao |
| :-------- | :------------------- | :----------- |
| `'` `'`   | Aspas simples curvas | `'`          |
| `"` `"`   | Aspas duplas curvas  | `"`          |
| `'`       | Primo                | `'`          |
| `"`       | Duplo primo          | `"`          |
| `<<` `>>` | Aspas angulares      | `<<` `>>`    |

A normalizacao e aplicada automaticamente em **60+ tipos de arquivo de código** (`.go`, `.py`, `.js`, `.ts`, `.java`, `.rs`, `.sh`, `.sql`, `.json`, `.yaml`, etc.) e em nomes de arquivo especiais (`Makefile`, `Dockerfile`, `.gitignore`, etc.).

<Info>
  Arquivos de documentação (`.md`, `.txt`, `.rst`) **não** sao normalizados para preservar a tipografia intencional.
</Info>

***

## Ciclo de Vida do Tracking

```text theme={"system"}
1. @coder read main.go     → RecordRead(main.go): registra mtime + SHA-256
2. (usuário edita main.go no IDE)
3. @coder write main.go    → CheckStaleness(main.go): detecta mudanca
                            → WARNING injetado no resultado
                            → Modelo decide: re-ler ou prosseguir
4. @coder read main.go     → RecordRead(main.go): atualiza registro
5. @coder write main.go    → CheckStaleness(main.go): não stale
                            → Escrita normal
6. (após write bem-sucedido) → Clear(main.go): remove registro
```

***

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Plugin @coder" icon="hammer" href="/pt/features/coder-plugin">
    Referência completa das operações de read/write/patch.
  </Card>

  <Card title="Permissoes" icon="shield-halved" href="/pt/features/enhanced-permissions">
    Sistema de permissões que protege operações de escrita.
  </Card>

  <Card title="Recuperação de JSON" icon="screwdriver-wrench" href="/pt/features/json-recovery">
    Como argumentos de ferramenta sao corrigidos antes da execução.
  </Card>

  <Card title="Segurança do Coder" icon="lock" href="/pt/features/coder-security">
    Validação de caminhos e protecoes de segurança.
  </Card>
</CardGroup>