Detecção de Staleness de Arquivos

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:

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

Verificação (CheckStaleness)

Antes de cada operação write ou patch, o tracker verifica se o arquivo mudou.

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.

Verificação em 2 Etapas

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

Etapa 1: mtime + size (rapida)
Etapa 2: SHA-256 (completa)

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).

mtime inalterado + size inalterado → não stale (fast path)

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

Se o mtime ou size mudou, o tracker le o arquivo completo e calcula o SHA-256 para comparacao definitiva.

mtime mudou + hash identico → não stale (ex: touch sem edicao)
mtime mudou + hash diferente → STALE (modificacao real)

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.

Mensagem de Aviso

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

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:

Re-ler o arquivo antes de fazer alteracoes
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.).

Arquivos de documentação (.md, .txt, .rst) não sao normalizados para preservar a tipografia intencional.

Ciclo de Vida do Tracking

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

Plugin @coder

Referência completa das operações de read/write/patch.

Permissoes

Sistema de permissões que protege operações de escrita.

Recuperação de JSON

Como argumentos de ferramenta sao corrigidos antes da execução.

Segurança do Coder

Validação de caminhos e protecoes de segurança.

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

Detecção de Staleness de Arquivos

Como Funciona

Verificação em 2 Etapas

Mensagem de Aviso

Cenarios Cobertos

Normalizacao de Aspas

Ciclo de Vida do Tracking

Próximos Passos

Plugin @coder

Permissoes

Recuperação de JSON

Segurança do Coder

​Como Funciona

​Verificação em 2 Etapas

​Mensagem de Aviso

​Cenarios Cobertos

​Normalizacao de Aspas

​Ciclo de Vida do Tracking

​Próximos Passos

Plugin @coder

Permissoes

Recuperação de JSON

Segurança do Coder

Como Funciona

Verificação em 2 Etapas

Mensagem de Aviso

Cenarios Cobertos

Normalizacao de Aspas

Ciclo de Vida do Tracking

Próximos Passos