5.3 KiB
OPS110-F1 — agent:session: flags desconhecidas fail-high, single-flight do start testado e polish de help/list
Status: rascunho
Atualizado em: 2026-09-15
Issue: (a registrar — OPS110-F1)
Intenção: entrega OPS110 (Issue #1019, docs/plans/ops110-attach-detach-runs-agent.md) — débitos do ciclo /simplify capturados após o merge
Appetite restante: ~1 dia eng (3 fases, fill-in)
Leitura da intenção
- Outcome: fechar as lacunas deixadas pelo ciclo OPS110 sem mudar o contrato de produto: (a) flags desconhecidas no CLI
agent:sessionpassam a falhar alto (hoje--prupose=nextcai silenciosamente no defaultnew, criando sessão sem driver); (b) o invariante "nunca dois runs no mesmo branch" (D5/R4 do impl plan) ganha pin automatizado do single-flight (acquireStartLock+ reuso dentro do lock); (c) help/listficam completos (flags--hostname/--porte obrigatoriedade do--modelno USAGE dostart;logPathvisível nolisthumano). - O que NÃO negociar: o contrato de
list --json(OPS109), o fail-closed de bind, a credencial só por env e o comportamento de attach/detach (fechar cliente não encerra;stopé explícito) ficam como estão. - O que reavaliar: nenhum achado de access/LGPD/schema.
Abordagem recomendada
Opções: A) 3 fases curtas no mesmo lote (flags → teste do lock → help/list) | B) só a fase de flags agora e o resto defer | C) unificar tudo num refactor do CLI.
Recomendação: A — as três são cheap_polish na mesma superfície (scripts/agent-session.mjs) e o lote cabe em ~1 dia; a fase 1 é a de maior risco (falha muda no caminho crítico), a 2 pin o invariante mais caro de reverter (dois runs no mesmo worktree), a 3 é cosmético.
Rejeitadas: B — deixa sem pin o único invariante de segurança de processo do item; C — sem ganho, o CLI já foi extraído na OPS110.
Fases verificáveis
- Flags estritas (F1).
scripts/agent-session.mjs: validador de flags aceitas por verbo (whitelist:servehostname/port;startpurpose/dir/model/issue/argument/new/hostname/port;attachsession/branch/issue;stopidem;listjson) — desconhecida →diecom sugestão da mais próxima (distância 1) ou listando o USAGE. Unit novo do validador (puro, emscripts/lib/agent-session.mjs) +pnpm gate:fast. ~2–3h. - Single-flight com seam testável (F2). Extrair de
cmdStarta decisão "reusar vs criar" para uma função com I/O injetável (ex.resolveStartDecision({ statePath, readFile, serverUrl, probeBusy, driverAlive, forceNew })) na lib pura; unit cobre: estado vivo → reuse; estado stale (driver morto e idle) → fresh;--new→ fresh; e o reclaim do lock com PID morto (hoje sóstartLockPathé pinado). Documentar no spec a lacuna que fica (corrida real de processos). ~3–4h. - Help/list (F3). USAGE do
startcom--hostname/--porte "--modelobrigatório quando há skill";listhumano ganha a coluna dologPath(mantendo o header). Spec deformatSessionListatualizado. ~1h.
Dados → forma (N/A — sem dados)
Rabbit holes / Não escopo (engenharia)
- Refactor do CLI em módulos por verbo (a CLI fina atual é intencional).
- Persistir credencial para
list/attachsem env (proibido pelo D9 da OPS110). - Validação semântica de todos os valores de flag (ex. e-mail de branch) — fora.
Adiado com gatilho (triage OPS110)
- Fronteira dupla da regra "issue só no
next" e da sanitização do bag (scripts/lib/worktree.mjsna diretiva ∥scripts/lib/agent-session.mjsnopurposeInvocation): unificar no dono do ciclo de vida quandoplan/newganharem argumento próprio ou surgir um 3º purpose com bag/issue. Hoje há comentário cruzado nos dois pontos e pins nos dois specs.
Explicitamente fora (skips e descartes da triage — não reabrir)
- Literal
/bug-fixem dois donos (OPS106 × OPS110): os dois specs pinam juntos num rename; unificar acoplaria o auto-unblock ao ciclo de sessão. - 404 no
aborttratado como "já encerrado": semanticamente correto (sessão inexistente não está rodando). stop/list/attachdependerem deOPENCODE_SERVER_PASSWORDno env quando o servidor exigiu senha: decisão D9 (credencial nunca persistida);stopdegrada para encerramento local e o hint é acionável.- Marcador
(line truncated to 2000 chars)commitado emAGENTS-infra.md:15: pré-existente emmain, fora do diff da OPS110. - knip não carregar
src/payload.config.ts: P3 já ledgered (docs/TECH-DEBT.md).
Riscos e mitigação
- Whitelist de flags divergir do parser
parseEqualsFlags(que aceita--flagsem valor): F1 deve rejeitar flag desconhecida, não mudar a forma=; teste cobre--json/--newbooleanos. - F2 extrair decisão sem mover I/O para a lib: manter a lib pura (filesystem/probe entram por parâmetro).
Aceite de engenharia
- Flag desconhecida em qualquer verbo falha com mensagem acionável (inclui
--prupose→--purpose). - Decisão de reuso + reclaim do lock pinados em unit puro; corrida real documentada como lacuna.
- USAGE do
startcompleto;listmostra o log. pnpm gate:fastverde; sem migration/UI/access.
Self-score decision-quality (gate ≥4): decisões A/B/C com rejeitadas (1,0); cabe no appetite ~1 dia (1,0); rabbit holes nomeados (1,0); reusa a lib/CLI existentes sem twin (1,0); contrato OPS110 preservado (1,0) → 5,0/5.