# Autoridade do agente depois do repouso e despertar do Mac

Um processo de agente aprovado não deve herdar autoridade apenas porque um Mac despertou com os mesmos processos ainda na memória. Repouso, apagamento da tela, bloqueio da tela, fechamento da tampa e despertar são eventos diferentes do sistema operacional, mas todos criam a mesma questão de segurança: a pessoa que aprovou essa execução continuou presente e capaz de intervir?

Trate essa questão como uma decisão de autorização, não como um detalhe de gerenciamento de energia. Se você permitir que um agente de programação mantenha autoridade sobre APIs ou SSH, uma aprovação antiga pode transformar uma pausa comum para tomar café, um deslocamento ou uma interrupção noturna em uso de credenciais sem supervisão. A solução não é criar um labirinto de regras. É usar um modelo de estados pequeno, uma política de expiração clara e testes que obriguem você a lidar com as transições incômodas que as pessoas costumam ignorar.

## O repouso não é um único evento

O macOS distingue o repouso do sistema do repouso da tela, e essa diferença importa porque uma tela escura não prova que o agente parou. A Apple expõe notificações NSWorkspace separadas para `willSleep`, `didWake`, `screensDidSleep` e `screensDidWake`. As notificações de repouso e despertar não carregam dados do usuário que informem ao aplicativo por que a transição ocorreu.

Um laptop pode reduzir o brilho ou desligar a tela enquanto uma compilação, uma transferência de rede ou um processo local continua. Um Mac de mesa pode funcionar sem uma tela ativa. Um notebook conectado à energia e a periféricos pode se comportar de forma diferente do mesmo notebook usando bateria. Não é possível tomar uma decisão sobre autoridade com base no fato de um pixel ter ficado preto.

Use quatro fatos separados no seu projeto:

- **Estado da tela** informa se a tela entrou em repouso ou despertou.
- **Estado de energia** informa se a máquina se preparou para dormir ou despertou.
- **Estado de presença do usuário** informa se a sessão está ativa, bloqueada, encerrada ou alternada.
- **Estado do cofre** informa se os segredos podem ser usados.

As equipes costumam juntar os três primeiros em um booleano chamado `isAwake`. Esse atalho deixa escapar autoridade. Um agente pode estar em execução enquanto a tela está em repouso. Uma máquina pode despertar na tela de bloqueio. O usuário pode bloquear a tela sem colocar o sistema em repouso. Cada caso precisa de seu próprio resultado esperado.

A regra padrão certa é rigorosa, mas fácil de explicar: uma ação protegida precisa de um cofre desbloqueado e de uma aprovação atual pertencente à época de autoridade atual. Um despertar, bloqueio, mudança de sessão do usuário, revogação manual ou bloqueio do cofre pode avançar essa época. Depois que ela avança, as chamadas da época antiga falham.

## O bloqueio da tela deve encerrar a autoridade interativa

O bloqueio da tela é o sinal mais claro de que a aprovação interativa deve parar. O Mac pode continuar funcionando, e um processo de terminal de longa duração pode ainda ter seus sockets e sua memória, mas o usuário que aprovou a ação deixou a sessão interativa. Continuar enviando solicitações de API ou comandos SSH com base em um clique anterior é difícil de justificar.

Isso não significa que todo agente precise morrer quando a tela é bloqueada. Encerrar o processamento local é uma decisão separada. Um modelo pode continuar lendo um repositório, compilando código ou preparando um patch se essas ações não exigirem um gateway com credenciais. A fronteira é a ação externa. Mantenha o trabalho e remova a autoridade.

Essa distinção é útil porque evita uma escolha tudo ou nada. Você não precisa escolher entre um agente congelado e um agente completamente aberto. Deixe o agente continuar com tarefas seguras no espaço de trabalho local e faça a próxima chamada protegida retornar uma negação clara:

```text
authorization_denied
reason: authority_epoch_changed
required: unlock_vault_and_approve_session
```

Uma negação útil informa ao agente o que aconteceu sem revelar um segredo nem fingir que a solicitação falhou por causa da rede. O agente pode pausar, registrar o bloqueio e esperar pelo usuário, em vez de repetir várias vezes o mesmo comando destrutivo.

Não crie uma exceção porque o bloqueio veio de um temporizador de inatividade. Esse é justamente um dos casos em que o usuário pode ter esquecido que o agente ainda estava em execução. Um bloqueio explícito e um bloqueio automático refletem intenções humanas diferentes, mas nenhum dos dois prova que a pessoa continua disponível para aprovar uma alteração em produção.

Existe um caso restrito para manter a autoridade depois de um bloqueio: uma tarefa deliberadamente sem supervisão com uma capacidade concedida separadamente e cuidadosamente limitada. Esse deve ser um tipo de execução distinto, não uma exceção escondida à aprovação interativa. Se sua automação noturna se comporta exatamente como um agente diurno orientado por conversa, os riscos não foram separados.

## Um evento de despertar inicia uma nova época de autoridade

O despertar deve invalidar a aprovação interativa mesmo quando o processo aprovado sobrevive. Um processo pode pausar antes do repouso e continuar depois dele com o mesmo PID, as mesmas variáveis de ambiente e os mesmos descritores de arquivo abertos. Nada disso prova que a antiga decisão humana ainda se aplica.

Uma época de autoridade é um valor monotônico que marca um período contínuo em que uma concessão pode ser válida. Quando o sistema cruza uma fronteira relevante, incremente a época antes de atender outra ação. O processo não negocia isso. Ele descobre a mudança na próxima solicitação.

Um registro mínimo de autorização pode ser assim:

```json
{
  "session_nonce": "6a018d62-2e94-4d4a-9e79-1f4e4b5ca501",
  "process_id": 84172,
  "process_start_marker": "2026-07-22T14:03:18Z",
  "signing_authority": "approved-agent-binary",
  "authority_epoch": 27,
  "approved_at": "2026-07-22T14:04:01Z",
  "per_call_approval": false
}
```

O ID do processo é apenas um dos campos. O macOS pode reutilizar um PID depois que um processo termina, portanto um PID isolado se torna perigoso se o gateway esquecer um registro antigo e depois encontrar o mesmo número. Vincule a aprovação a um nonce novo e a uma instância de processo observada. Use a autoridade de assinatura do código como sinal de identidade do executável e, ainda assim, exija uma nova aprovação de sessão para cada nova execução do processo.

Quando o manipulador de eventos detectar `willSleep`, registre a intenção de revogar e pare imediatamente de aceitar novas chamadas protegidas. A Apple informa que um observador pode atrasar o tratamento do repouso por até 30 segundos, mas não use esse intervalo para concluir uma fila de ações pendentes. Negue-as ou marque-as como interrompidas. O usuário não autorizou uma última sequência de trabalho enquanto a tampa estava fechando.

Quando a máquina informar o despertar, avance a época novamente se necessário e mantenha o gateway do cofre fechado até que o usuário cumpra o requisito de desbloqueio. Isso lida com uma ordem imperfeita dos eventos. Os eventos de energia são confusos nas extremidades, e é melhor exigir uma aprovação extra, sem risco, do que deixar passar uma chamada que carregue um segredo durante uma transição.

## O fechamento da tampa merece um caso de teste próprio

Para uma pessoa, fechar a tampa de um notebook parece um comando de repouso, mas o software não deve presumir que o gesto físico corresponde exatamente a um único evento do sistema operacional. A fonte de energia, as telas externas, os acessórios de dock e as configurações podem alterar o comportamento da máquina. A única resposta honesta é testar o hardware e a configuração que sua equipe realmente usa.

A política de segurança ainda pode ser simples: o fechamento da tampa encerra a autoridade interativa assim que você observar uma fronteira relacionada e confiável. Em uma configuração portátil normal, `willSleep` oferece a primeira oportunidade de bloquear novas ações. Se uma configuração específica mantiver o sistema acordado depois do fechamento da tampa, use uma fronteira da sessão do usuário ou da tela como alternativa conservadora. Não espere por um rótulo semântico perfeito chamado `lidClosed`. O que você precisa impedir é o uso de credenciais sem supervisão.

Faça este teste com um agente que tenha uma capacidade protegida e inofensiva, como escrever um marcador em uma API de teste ou executar um comando seguro em um host SSH descartável:

1. Inicie um processo novo do agente e aprove a sessão.
2. Confirme que uma chamada protegida funciona e deixe o agente pronto para fazer outra.
3. Feche a tampa por tempo suficiente para acionar o comportamento de energia esperado e depois abra-a novamente.
4. Sem desbloquear nem aprovar novamente, permita que o agente tente outra vez a chamada protegida.
5. Confirme que o gateway nega a nova tentativa e registra a transição de autoridade antes da negação.

Repita o mesmo teste conectado ao dock, usando bateria e com uma tela externa, se as pessoas utilizarem esses modos. Mantenha o endpoint de teste inofensivo. O objetivo é observar o comportamento da autoridade, não descobrir se uma implantação em produção pode ser interrompida no meio.

Uma falha aqui costuma parecer tranquilizadora: o registro de ações não mostra nenhuma chamada durante o repouso e, então, a primeira chamada depois do despertar funciona. Ainda assim, isso é uma falha se o usuário encontrou uma tela de bloqueio e nunca aprovou a execução retomada. O intervalo de tempo é justamente o ponto do teste.

## O repouso da tela é um gatilho de revogação ruim quando usado sozinho

Revogar apenas quando a tela entra em repouso é seguro, mas pode ser inconveniente em um Mac de mesa cuja tela repousa durante o trabalho normal. Manter a autoridade durante o repouso da tela é prático, mas também é fácil errar quando o tempo limite da tela funciona como sinal de que o usuário se ausentou.

Escolha uma regra e deixe o compromisso explícito. Para credenciais de alto impacto, revogue no bloqueio da tela e no repouso do sistema, não apenas no repouso da tela. Em uma máquina onde o repouso da tela ocorre de forma confiável pouco antes do bloqueio, você pode escolher revogar nesse momento como proteção adicional, aceitando mais solicitações de aprovação. O segredo é não chamar nenhuma das opções de «óbvia». A escolha depende da implantação e do que a credencial pode fazer.

As notificações separadas de tela e sistema da Apple são um lembrete útil de que elas não significam a mesma coisa. Monitore ambas, registre ambas e teste a política associada a cada uma.

Uma matriz prática evita que isso vire conhecimento informal:

| Transição | Trabalho local do agente | Aprovação da sessão existente | Ação baseada no cofre |\n| --- | --- | --- | --- |\n| A tela entra em repouso | Pode continuar | A política definida por você decide | Normalmente aguardar ou permitir apenas uso de baixo risco |\n| A tela é bloqueada | Pode continuar | Encerrar | Negar até uma nova aprovação |\n| O sistema começa a entrar em repouso | Pode pausar naturalmente | Encerrar imediatamente | Negar novas chamadas |\n| O sistema desperta na tela de bloqueio | Pode continuar localmente | Continua encerrada | Negar até o desbloqueio e uma aprovação |\n| O usuário desbloqueia | Pode continuar | Continua encerrada | Exigir uma nova aprovação de sessão |

O usuário desbloqueia o Mac para recuperar a área de trabalho. Essa ação não deve restaurar silenciosamente a autoridade anterior de um agente. Desbloquear um computador e aprovar uma ação externa são coisas relacionadas, mas respondem a perguntas diferentes.

## As execuções noturnas precisam de um contrato separado

Uma execução noturna de um agente não deve herdar as permissões de uma sessão interativa da tarde. As pessoas aprovam um trabalho interativo enquanto observam o diff, o terminal ou um cartão de solicitação. O trabalho noturno é uma decisão explícita de permitir que algo prossiga sem essa supervisão imediata.

Faça o contrato da tarefa ser restrito o suficiente para que você consiga explicá-lo em uma frase. «Executar testes e preparar um pull request» é compreensível. «Fazer o que for necessário para concluir a tarefa» não é um contrato. É um cheque em branco.

Para trabalhos sem supervisão, separe ações locais de ações externas. Permita as primeiras quando estiverem contidas: análise do repositório, edições em uma branch, execução de testes e geração de artefatos. Exija uma nova aprovação humana para efeitos externos sensíveis, incluindo uma alteração em uma API de produção, uma implantação, a publicação de um pacote, uma gravação em um banco de dados compartilhado ou o acesso SSH a uma máquina importante.

Há casos em que uma execução noturna precisa chamar um serviço externo. Nesses casos, use uma credencial dedicada ou um ambiente de teste cujo impacto potencial seja compatível com a tarefa. Não reutilize uma credencial de administrador só porque ela já existe no cofre. O argumento comum é que a pessoa aprovou o agente mais cedo naquela noite. Essa aprovação abrangia uma execução visível e interativa. Ela não abrange o que restar depois que a pessoa adormecer.

Use um orçamento limitado de ações se a tarefa tiver uma atividade externa recorrente legítima. Limite-o por destino, método e efeito, não por pontuações vagas de confiança. Por exemplo, uma tarefa de testes sem supervisão pode ter permissão para enviar uma solicitação fixa a um único endpoint de staging, mas não pode trocar de host, alterar os métodos HTTP nem usar SSH. Se precisar de mais, deve esperar.

A autorização por sessão do Sallyport dá a cada novo processo do agente seu próprio limite de aprovação. Mantenha o trabalho noturno em um processo recém-iniciado e submeta suas ações protegidas ao mesmo escrutínio de qualquer outra execução sem supervisão.

## Os registros precisam provar a negação, não apenas a atividade

Um registro que diz «o Mac despertou» não prova que a autoridade terminou. Você precisa de evidências dos dois lados da fronteira: o evento do sistema operacional que acionou a transição da política e a próxima ação protegida que o gateway recusou.

O macOS oferece um ponto de partida útil para investigar o lado da energia:

```sh
pmset -g log | grep -E 'Sleep|Wake|DarkWake|Display'
```

As linhas exatas variam conforme o hardware e a versão do macOS, mas a saída deve mostrar registros com horários e nomes de eventos como `Sleep`, `Wake`, `DarkWake` ou transições de tela. Salve a janela correspondente de cada teste. Não use esse registro como fonte de verdade para a autorização, porque ele não conhece seu cofre nem a identidade do seu agente.

Seu próprio diário deve responder a outro conjunto de perguntas:

```text
14:20:16.402 session_approved process=84172 epoch=27 authority=approved-agent-binary
14:22:04.118 power_will_sleep epoch=27
14:22:04.119 authority_revoked old_epoch=27 new_epoch=28 reason=system_sleep
14:25:38.771 power_did_wake epoch=28
14:25:44.025 action_denied process=84172 request=ssh.exec reason=authority_epoch_changed
```

A ordem importa. Se a ação aparecer antes do registro de revogação, você encontrou uma condição de corrida. Se nenhuma ação negada aparecer porque o agente de teste saiu silenciosamente, você não provou nada sobre um processo persistente. Organize o teste para que o mesmo processo de longa duração tente uma chamada protegida depois de cada transição.

Um registro de auditoria à prova de adulteração oferece um segundo benefício: permite verificar depois se a sequência de eventos e ações não foi editada para produzir uma história mais bonita. O Sallyport projeta seus diários de sessões e atividades a partir de um registro de auditoria criptografado, encadeado por hash e sem possibilidade de gravação. O comando `sp audit verify` verifica essa cadeia offline sobre o texto cifrado. Isso é útil neste teste porque uma verificação bem-sucedida informa que a sequência registrada não foi reescrita silenciosamente. Ela não compensa uma política de revogação fraca.

## As condições de corrida acontecem na fronteira

O bug perigoso costuma ser uma solicitação que já está em andamento quando o Mac começa a entrar em repouso ou o usuário bloqueia a tela. Um gateway que verifica a aprovação apenas ao aceitar uma conexão pode permitir que um trabalho enfileirado seja executado depois da transição de autoridade. Um gateway que verifica apenas depois de injetar uma credencial pode expor a credencial a um auxiliar antes de perceber a revogação.

Verifique a autoridade imediatamente antes da operação privilegiada. Isso significa antes de injetar a credencial, antes de abrir um auxiliar SSH com uma chave utilizável e antes de enviar a solicitação HTTP. Se uma operação tiver várias fases privilegiadas, verifique novamente em cada fase na qual o sistema poderia atravessar uma fronteira de autoridade.

Uma estrutura simples é assim:

```text
receber solicitação
identificar processo e nonce de sessão
ler a época de autoridade atual
comparar a época da concessão da solicitação com a época atual
verificar o bloqueio do cofre
verificar a aprovação por chamada quando necessário
injetar a credencial e executar a ação
acrescentar o resultado ao registro de auditoria
```

Mantenha a leitura da época e o compromisso com a execução privilegiada tão próximos quanto sua implementação permitir. Não é possível tornar perfeitamente reversível uma ação HTTP distribuída depois que os bytes saem do Mac. É possível impedir que uma concessão antiga a inicie.

Não tente resolver todas as situações de fronteira atrasando o repouso. A notificação `willSleep` permite um pequeno atraso para tratamento, mas impedir que um laptop durma para concluir ações do agente inverte a prioridade. A máquina está saindo de um estado interativo. Revogue o acesso, registre a interrupção e deixe o usuário decidir o que será retomado.

A aprovação por chamada é a resposta adequada para chaves que podem causar efeitos caros ou irreversíveis. Ela torna o repouso e o despertar menos relevantes porque cada uso já solicita a aprovação do usuário no momento da ação. Isso não é motivo para ignorar a revogação da sessão. É uma segunda barreira para um conjunto menor de credenciais.

## Teste as transições que as pessoas realmente fazem

Um bom plano de testes não começa com testes unitários de um manipulador de notificações. Esses testes ajudam, mas as falhas aparecem em transições reais de energia, telas de bloqueio reais e processos de agentes que sobrevivem a uma janela de terminal.

Crie um agente de teste que possa esperar, receber um sinal e então solicitar uma ação protegida inofensiva. Dê a cada teste um identificador de execução novo. Registre uma expectativa por escrito antes de executar o teste, porque, caso contrário, um resultado surpreendente vira «provavelmente está tudo bem» depois do fato.

Teste pelo menos estes casos em cada configuração de Mac compatível:

- Bloqueie a tela enquanto o agente estiver ocioso e tente novamente uma ação aprovada antes e depois do desbloqueio.
- Coloque o sistema em repouso pelo menu da Apple, desperte-o na tela de bloqueio e tente novamente com o processo original.
- Deixe a tela entrar em repouso enquanto o sistema permanece acordado e verifique se o comportamento corresponde à política de tela escolhida.
- Feche e reabra a tampa de um notebook, tanto usando bateria quanto na configuração de mesa utilizada pelas pessoas.
- Deixe uma execução de agente deliberadamente longa durante a noite e depois examine o registro de energia, o diário de ações e a primeira chamada protegida após o retorno.

Use uma pequena ficha de resultados para cada execução: época esperada, eventos de energia observados, sobrevivência ou não do processo original, estado do cofre e resultado da primeira chamada protegida. Essa ficha identifica um erro frequente: as equipes testam se o aplicativo viu o evento, mas nunca testam se a camada de ações rejeitou uma chamada depois dele.

Teste também os momentos difíceis. Inicie uma ação protegida, bloqueie a tela enquanto ela espera uma resposta da rede e examine se uma nova tentativa ou ação seguinte é executada com a concessão antiga. Inicie uma ação uma fração de segundo antes do repouso. Desconecte e reconecte um dock. Reinicie o processo do agente depois do despertar e confirme que ele não consegue reutilizar o registro de aprovação do processo antigo.

Você não precisa de um mecanismo de políticas enorme para fazer esses testes passarem. Precisa de um bloqueio rigoroso do cofre, um registro de aprovação por processo, uma época revogável e um caminho de ações que os verifique imediatamente antes de usar uma credencial.

## Escreva a política em termos de resultados e depois aplique-a

Uma boa política de autoridade cabe em uma página porque descreve resultados observáveis, não uma coleção de suposições sobre os rótulos do sistema operacional. Declare o que acontece com ações protegidas depois do bloqueio, repouso, despertar, fechamento da tampa, logout e revogação manual. Declare se o trabalho local pode continuar. Declare o que o usuário precisa fazer para retomar a execução.

Para a maioria dos agentes interativos de programação com IA, a política deve ser assim:

> Uma ação protegida exige um cofre desbloqueado e uma aprovação para o processo atual na época de autoridade atual. Bloqueio, repouso, perda da sessão do usuário, bloqueio do cofre e revogação manual encerram essa aprovação. O despertar e o desbloqueio não a restauram. O agente precisa solicitar uma nova aprovação antes de outra ação protegida.

Essa regra tem um custo: as pessoas precisam aprovar novamente depois de voltar ao Mac. Aceite esse custo. A alternativa exige que o usuário se lembre de cada processo de agente que estava ativo antes de fechar uma tampa e depois confie que ele se comportará de forma sensata quando a máquina despertar horas mais tarde.

Execute os testes antes de considerar uma configuração de agente segura para trabalhos sem supervisão. Se uma solicitação funcionar depois de um bloqueio ou despertar sem uma nova decisão do usuário, você encontrou uma autoridade que sobreviveu ao momento em que foi concedida.