# Loop

Extensão do Pi que mantém supervisão contínua dentro de uma conversa, acordando o agente para reavaliar uma tarefa até que uma condição de parada seja atingida.

## Language

**Objetivo do loop**:
A tarefa fixa definida ao iniciar o loop e reavaliada em todas as iterações. Permanece estável mesmo quando o histórico da conversa cresce.
_Avoid_: prompt recorrente, tarefa atual, próximo prompt

**Iteração**:
Uma nova execução do agente, disparada pelo loop, que recebe o objetivo do loop, uma instrução de continuidade e metadados da rodada, além do histórico atualizado da conversa.
_Avoid_: turno, tick, execução

**Decisão da iteração**:
O comando estruturado pelo qual o agente encerra cada iteração como `continue`, `complete`, `fail` ou `block`. Quando decide continuar em auto-ritmo, também informa quando a próxima iteração deve ocorrer; se omitir ou invalidar a decisão, recebe uma única cobrança imediata antes de o loop pausar.
_Avoid_: status, marcador textual, resultado do turno

**Ritmo fixo**:
Política em que todas as continuações usam o intervalo definido no início, salvo alteração explícita do usuário.
_Avoid_: intervalo manual

**Auto-ritmo**:
Política em que o agente escolhe um atraso concreto em cada decisão de continuação, recalibrando a próxima iteração conforme o estado que ainda está esperando mudar.
_Avoid_: intervalo automático, heurística da extensão

**Limites de execução**:
O prazo de calendário contado continuamente desde o `start`, inclusive durante pausas, e o número máximo absoluto de iterações permitidas. Ambos recebem defaults seguros e, quando atingidos, pausam a supervisão; apenas o orçamento de iterações é preservado por uma pausa. Um `update` pode ampliar limites sem zerar iterações já consumidas.
_Avoid_: tempo ativo, orçamento reiniciado

**Loop ativo**:
O único loop que pode estar supervisionando uma sessão, seja esperando, pausado ou executando uma iteração. Um novo loop não substitui implicitamente o existente; admitir vários loops exigiria identidade explícita em todos os comandos que hoje operam implicitamente sobre o único loop da sessão.
_Avoid_: job, watcher, monitor

**Pausa**:
Estado retomável que preserva objetivo e contadores, mas não agenda iterações nem suspende o prazo de calendário. Pode resultar de comando humano, limite atingido, bifurcação da conversa, fechamento da sessão ou bloqueio reportado pelo agente; reabrir a sessão nunca o retoma automaticamente, e retomar após o prazo produz `duration_limit`.
_Avoid_: cancelamento, encerramento

**Bloqueio**:
Pausa causada quando a supervisão não consegue prosseguir sem intervenção humana, embora o estado real do objetivo permaneça desconhecido. Exige resumo e evidência da obstrução e pode ser retomada quando a causa for removida.
_Avoid_: falha do objetivo, retry automático

**Falha observada**:
Encerramento definitivo porque o agente observou um resultado externo negativo para o objetivo, sustentado por resumo e evidência.
_Avoid_: bloqueio, erro de observação

**Encerramento**:
Término definitivo do loop por conclusão, falha observada ou comando `stop`. Um loop encerrado só permanece como histórico e não pode ser retomado.
_Avoid_: pausa, shutdown

**Evidência**:
Descrição separada e auditável que sustenta um evento que requer atenção, acompanhada de sua origem: `agent` para estado, comando ou referência reportados pelo agente, e `extension` para limites e erros de protocolo observados mecanicamente. Evidência do agente não é verificada pela extensão.
_Avoid_: resumo, prova verificada, justificativa

**Evento de atenção**:
Mudança involuntária para um estado sem supervisão ativa: `completed`, `failed`, `blocked`, `duration_limit`, `iteration_limit` ou `protocol_error`. Usa um único envelope versionado com status, resumo, evidência, objetivo, contadores e sessão.
_Avoid_: evento terminal, reason

**Aviso de atenção**:
Registro visível na conversa e na TUI para todo evento de atenção, rotulado com a origem da evidência. Pode também acionar um hook simples enquanto a sessão permanece aberta; pausa ou encerramento solicitado pelo usuário não gera esse aviso.
_Avoid_: notificação verificada, callback