teqo-backup/docs/plans/worktree-launch-honra-flags.md

# Launch do worktree honra as flags do humano: o modelo pedido e o `--auto` chegam onde deveriam

Status: rascunho
Atualizado em: 2026-09-16
Issue: #1088
Priority: P2
Impeccable: A — N/A (CLI/shell, sem superfície de produto)
Design UI: N/A — sem UI
Appetite: ~1 dia eng; um outcome verificável — o que a pessoa digita na linha (`--zen`, `--go`, `--auto`) é o que a sessão e a mensagem inicial usam, ou a flag falha alto.
Responsável: —

## Intenção

Quem opera o `pnpm worktree` no terminal digita a intenção inteira na própria linha: o modelo (`--zen`, `--go`, …) e o modo autônomo (`--auto`). Hoje o launcher engole parte disso sem avisar. Dois relatos, dois sintomas do mesmo defeito:

- "Rodei `worktree plan --zen` e ele não abriu o opencode com o Muse Spark 1.3 Free do OpenCode Zen. Como esperava."
- "Rodei `worktree next --go --auto`, e a mensagem inicial não foi lançada com `--auto`, como esperado."

A raiz é a mesma: o `worktree` registra o modelo escolhido, mas em `plan`/`new` (driverless por OPS119) ele nunca é aplicado à sessão — o TUI anexado cai no pin global (`deepseek/deepseek-flash`). E `--auto` não existe no vocabulário do launcher: é parseado como booleano desconhecido e descartado em silêncio, então a skill começa supervisionada quando o humano pediu autonomia. A promessa implícita do terminal — "o que eu digitei é o que roda" — está quebrada.

## Persona e fluxo

- **Persona / contexto:** dev no terminal, começando um run do opencode; escolheu o modelo de propósito (custo/capacidade) e, às vezes, quer o run autônomo até o PR.
- **Job principal:** abrir a sessão do worktree já no modelo e no modo (`--auto`) que digitou — ou ser avisado de que aquela flag não será honrada.
- **Fluxo desejado:** digita `worktree plan --zen` → cai no worktree e no TUI da sessão já em Muse Spark; digita `worktree next --go --auto` → o driver auto-submete `/work-issue --issue <N> --auto` e a skill segue sem pausa.
- **Anti-goals de produto:** não virar um seletor de modelo/TUI de configuração; não reinterpretar `--auto` do humano como o `--auto` de permissões do `opencode run`; não mexer no preset nem no mapa de modelos.

## Objetivo e aceite

- **Modelo honrado em TODOS os purposes.** `pnpm worktree <next|plan|new|fix> --<modelo>` abre a sessão **a que a pessoa anexa** no modelo pedido, inclusive nos driverless (`plan` sem bag, `new`), onde não há driver para aplicar `--model`.
- **`--auto` do humano chega à mensagem inicial.** Com `--auto` na linha, o driver auto-submete exatamente `/work-issue --issue <N> --auto` (next), `/plan-issue --auto <bag>` (plan com bag) e `/bug-fix --auto <bag>` (fix); sem `--auto`, as formas atuais (supervisionadas) permanecem.
- **Flag não honrada falha alto.** Flag desconhecida ou que o launcher não sabe honrar morre com mensagem clara (e sugestão de vizinho, quando houver) — nunca é descartada em silêncio.
- **Guardrails:** preset default `deepseek/deepseek-flash` intocado; OPS119 mantido (`plan`/`new` sem driver não auto-submetem skill); ciclo de vida OPS110 (`serve`/`start`/`attach`/`stop`, marcador `TEQO_WORKTREE_TERMINAL`) e o contrato `purposeInvocation` preservados; nenhuma mudança de provider/auth.

## Dados (intenção)

- **Vou apresentar dados?** Não.
- **Decisões desbloqueadas:** N/A — é comportamento de CLI, não superfície de dado; o efeito é observável no estado da sessão e no log do driver.
- **Forma:** _adiada ao plano de implementação_.

## Dados da decisão (literais)

- Mapa de modelos (não alterar valores): `zen -> opencode/muse-spark-1.3-contributor-free`; `go -> opencode-go/deepseek-v4.1-flash`; preset sem flag `deepseek/deepseek-flash`.
- Formas exatas do comando auto-submetido: `/work-issue --issue <N> --auto`; `/plan-issue --auto <bag>`; `/bug-fix --auto <bag>`.
- O modelo pedido deve constar na **sessão** (`model` no estado em `~/.local/state/teqo/agent-sessions/<slug>.json` e na sessão do servidor), não só no argv do driver.
- API do servidor: `POST /session` aceita `model: { id, providerID, variant? }` na criação (e há rota de troca de modelo da sessão).

## Direção no codebase (hipótese)

- **Áreas prováveis:** `scripts/worktree.mjs` (parser e `printLaunchDirective`), `scripts/lib/worktree.mjs` (`opencodeLaunchDirective`, `resolveWorktreeModel`), `scripts/lib/agent-session.mjs` (`purposeInvocation`, `driverArgs`, criação de sessão no CLI `scripts/agent-session.mjs`), `.agents/shell/worktree.sh`.
- **Precedente a olhar:** `validateSessionFlags` + `nearestAcceptedFlag` (OPS110-F1, `scripts/lib/agent-session.mjs`) é o padrão pronto de "flag desconhecida falha alto" a espelhar no `parseArgs` do worktree; `attachArgs`/`driverArgs` mostram onde o modelo entra (e não entra).
- **Risco de acoplamento:** o `opencode attach` não tem `--model`; aplicar o modelo só faz sentido via sessão (criação/rota de troca) ou via driver — o executor deve escolher o ponto que cobre o anexo, sem duplicar estado.

## Dependências

- OPS110 (sessões persistentes attach/detach) — entregue.
- OPS119 (`plan` sem bag driverless) — entregue; comportamento a preservar.

## Fora de escopo

- Variantes de modelo (`--variant`): continuam na config global do opencode via Ctrl+T (OPS95).
- Alterar o mapa `WORKTREE_MODEL_MAP` ou o preset default.
- Provider/auth, servidor compartilhado, painel OPS109 e o caminho headless do auto-unblock (`opencode run --auto`) — não é este defeito.
- Redesenho da semântica de `--auto` das skills (`plan-issue`/`work-issue`/`bug-fix`) — o contrato documentado é a fonte; aqui só o transporte.

## Rabbit holes de produto

- **"Já que mexo no modelo, faço um seletor no TUI".** Explode para UX de configuração e interage com Ctrl+T. **Corte neste item:** só passar o modelo que veio na linha.
- **"`--auto` também poderia ligar permissões".** Misturar o `--auto` de skill com o `--auto` do `opencode run` cria dois significados incompatíveis. **Corte:** `--auto` do humano = opt-out do GATE da skill; permissões seguem como hoje.
- **"Valido todas as flags do opencode command também".** O caminho `/worktree` (sem `TEQO_WORKTREE_TERMINAL`) tem escopo próprio. **Corte:** fail-high no parser do script, sem estender a varredura além dele.

## Questões em aberto (produto)

- **Como aplicar o modelo no caminho driverless?** **Opções:** A) driver mínimo só para fixar o modelo; B) criar a sessão com `model` (`POST /session` já aceita; o TUI anexado herda); C) aplicar só quando há driver (deixa `plan`/`new` quebrados). **Recomendação:** B — sem processo fantasma, sem mensagem espúria e sem reintroduzir auto-submit que a OPS119 removeu; se o TUI não herdar, cair para a rota de troca de modelo da sessão. _(assumido — validar na implementação)_
- **Onde `--auto` é anexado?** **Opções:** A) em `purposeInvocation`, junto do `--issue N`/bag; B) na diretiva de launch. **Recomendação:** A — é lá que o comando auto-submetido nasce, um único dono.
- **Rejeitar flag desconhecida ou só avisar?** **Opções:** A) falhar alto (padrão OPS110-F1); B) avisar e seguir. **Recomendação:** A — o defeito nasceu justamente do descarte silencioso.

## Referências

- GitHub Issue #1088
- Design UI (gate): N/A — sem UI
- Arquivos: `scripts/worktree.mjs`, `scripts/lib/worktree.mjs`, `scripts/lib/agent-session.mjs`, `scripts/agent-session.mjs`, `.agents/shell/worktree.sh`
- Testes que pinam os contratos: `tests/unit/worktree.unit.spec.ts`, `tests/unit/agentSession.unit.spec.ts`
- Doc das flags de skill (contrato do `--auto`): `.opencode/commands/plan-issue.md`, `.opencode/commands/work-issue.md`, `.opencode/commands/worktree.md`, `.agents/skills/worktree-next-issue/SKILL.md`
- `docs/AGENT-OPS.md` — ciclo de vida das sessões (OPS110/OPS119)

## Self-score (shaping)

4/5 — (1) fatia = um outcome verificável (as duas flags têm o efeito pedido ou falham alto); (2) appetite ~1 dia para parser + transporte + modelo na sessão; (3) persona no terminal e aceite em linguagem de uso; (4) direção no codebase é hipótese (áreas e precedente como pista); (5) pontos de injeção são questões abertas com recomendação.