Renomear internamente campos que identificam harnesses como agent

[4ndreello]

Problema

O código usa agent para identificar o harness que executa uma sessão, embora os valores sejam IDs de harness, como claude, codex, opencode e omp.

Isso aparece no modelo de sessão, na persistência SQLite, no protocolo IPC, na configuração, no cache de modelos e nos objetos JSON da CLI. O resultado é uma API inconsistente: alguns lugares usam agent, enquanto RoleBinding já usa harness.

A alteração não deve ser limitada ao cabeçalho visual de ps. O JSON atual é derivado diretamente de Session, portanto o campo também aparece em consumidores automatizados.

Evidência

Saída atual de codedeck ps --json --limit 1:

[
  {
    "id": "1984",
    "runId": "f11062a1-567b-4ddb-93af-d58c345246c5",
    "name": "setup-cli-contract",
    "agent": "codex",
    "nativeSessionId": "01a07d55-9767-7413-beb5-78aeaff58b70",
    "model": "gpt-5.6-luna",
    "status": "working",
    "repository": "/home/andreello/dev/codedeck",
    "cwd": "/home/andreello/.run-agent/worktrees/3189bd7a/1984",
    "worktree": "/home/andreello/.run-agent/worktrees/3189bd7a/1984",
    "branch": "ra/voce-e-um-worker-de-implementa-1984"
  }
]

A tabela SQLite atual também contém a coluna sessions.agent.

Escopo proposto

Recomendação

Fazer o rename canônico interno para harness, incluindo os objetos de sessão e catálogo de modelos, com uma camada explícita de leitura compatível para dados antigos.

O escopo deve cobrir:

• Session.agent para Session.harness.
• SessionRow.agent e o mapeamento de persistência.
• HarnessModels.agent para HarnessModels.harness.
• opções e variáveis internas de seleção de harness.
• campos e resultados IPC que identificam o harness.
• ps --json, show --json, wait --json e demais serializações de sessão.
• cache de modelos e consumidores em setup, open e launchers.
• testes de sessão, modelos, CLI, sandbox, recuperação e persistência.
• leitura de configurações e caches antigos conforme a política de compatibilidade escolhida.

Para reduzir risco com bancos existentes, a opção preferida é manter inicialmente a coluna física sessions.agent e convertê-la no limite do storage para Session.harness. Uma migração física pode ser feita depois, caso seja necessária.

Compatibilidade a definir

A implementação deve escolher explicitamente uma política para:

• aceitar agent como entrada IPC antiga;
• aceitar defaultAgent e chaves antigas de cache;
• decidir se novos JSONs emitem somente harness ou emitem temporariamente ambos os campos;
• preservar sessões em bancos já existentes;
• decidir se AgentId também será renomeado para HarnessId, ou se permanecerá temporariamente como nome de tipo compatível.

A recomendação é aceitar o formato antigo na leitura e escrever o formato canônico novo. Se consumidores de ps --json exigirem compatibilidade de saída, emitir ambos os campos durante um período de depreciação, documentando a remoção futura.

Fora de escopo

• Alteração de textos visíveis ao usuário, como o cabeçalho AGENT, descrições, ajuda e rótulos humanos. Isso já está sendo tratado em outro slice.
• Alteração do --agent específico de Claude.
• Alteração da chave agent pertencente ao schema do OpenCode.
• Alteração dos arquivos de roles e plugins em plugin/agents.
• Mudança de comportamento de worktree, branch, cwd, nativeSessionId ou IDs de sessão.
• Renomeação mecânica de config.agents, que representa roles e não uma lista de harnesses.
• Mudanças em códigos públicos de erro AGENT_*, salvo decisão explícita de compatibilidade.

OPEN QUESTIONS

• O JSON novo deve conter apenas harness ou deve conter agent e harness temporariamente?
• A coluna SQLite deve permanecer como agent com adapter, ou deve receber uma migração física?
• defaultAgent será renomeado para defaultHarness agora, com leitura compatível, ou permanecerá como chave de configuração por compatibilidade?
• AgentId, AgentDriver e AgentEvent.agent fazem parte deste rename? O último não apresentou produtores no levantamento.
• A opção pública --agent continuará como alias estável, mesmo que o campo interno passe a ser harness?

Checklist de aceitação

• O modelo interno de sessão usa harness para identificar o executor.
• O catálogo e o cache de modelos usam terminologia consistente.
• Todos os callers do daemon, registry, recovery, send, stop e resume usam o campo canônico.
• ps --json, show --json e wait --json seguem a política de compatibilidade escolhida.
• Sessões existentes em SQLite continuam carregando corretamente.
• Configurações e caches antigos são lidos sem perda silenciosa de dados.
• Sessões com worktree preservam cwd, worktree, branch e nativeSessionId.
• O fluxo de role binding continua usando RoleBinding.harness.
• O comportamento de seleção de modelo e sandbox permanece inalterado.
• Os campos agent específicos de vendors não são alterados.
• Testes focados cobrem persistência legada, JSON, IPC, modelos, configuração, roles, sandbox e recuperação.
• A verificação focada passa e o diff não contém mudanças fora do escopo.