PD Cockpit no Omarchy¶

Painel nativo para entender o que precisa de atenção, conversar com o Stamper e acompanhar sessões sem reconstruir contexto entre várias ferramentas.

Por que foi construído assim¶

O trabalho do PD Framework estava distribuído entre Linear, terminais, Herdr, GitHub e monitores. A dificuldade não era apenas abrir essas ferramentas, mas entender qual fato exigia uma decisão, o que estava acontecendo e qual ação era segura naquele momento.

O cockpit foi implementado como plugin nativo do Omarchy, usando a mesma linguagem visual dos demais widgets. Ele não virou uma segunda fonte de verdade: recebe uma projeção sanitizada do PD Framework e só oferece ações que essa projeção autoriza. Assim, dado ausente ou antigo aparece como desconhecido em vez de “saudável”.

O menu permite abrir diretamente o squad/persona escolhido; Stamper é a porta de coordenação quando selecionado, não substitui todos os agentes. Quando uma tarefa tem delegação autorizada, o core cria sessão e worktree isolados, atesta a topologia real do Herdr e devolve o resultado à conversa principal. A interface não injeta comandos livres no terminal.

Stack¶

Estado da validação¶

Instalação unificada e contratos — atualização de 11/09/2026¶

/home/felipe/Work/pd-framework é a única instalação diretamente em Work/, com origin direto para o GitHub. As antigas árvores -omarchy e -runtime foram movidas para Work/worktrees/pd-framework/retired-installations/ e são worktrees históricas ligadas ao .git canônico, não runtimes concorrentes.

A movimentação preservou 24 worktrees, arquivos, alterações pendentes, refs, índices, locks e owners, com backup privado verificado. Foram reconciliados 36 descriptors, 22 diretórios de estado, 30 journals e 1.118 links de skills. Não houve encerramento de agentes, merge de trabalho ou edição de conteúdo do LinkedIn. Os processos observados mantiveram seus cwd válidos.

33 descriptors autenticaram; três registros históricos continuam com cwd que já estavam ausentes. Não se criaram pastas fictícias nem se declarou recuperação dessas conversas. Isso não valida todos os squads, runtimes ou fluxos de Marketing/LinkedIn.

Contrato atual: ferramentas não exigem issue, label repo:*, plano, manifest ou dispensa. Desenvolvimento segue Dev Workflow; Issue Flow aplica-se à entrega vinculada quando Felipe pedir. Testes e revisão escolhida continuam fazendo parte da entrega, sem impedir diagnóstico ou correção na mesma sessão.

PreToolUse não cria reserva persistente por ferramenta; callbacks não exigem receipts antigas para permitir continuar. Stop/idle são checkpoints nos adapters atualizados, não autorização de commit, merge, push, encerramento ou cleanup. Fechamento explícito Omarchy usa handoff_only. Preservam-se credenciais, trabalho alheio, owner, proteção da main, permissões reais e autorização humana para publicação/destruição.

Manual, contrato de runtime e espelho CLAUDE.md → AGENTS.md precisam expressar essa mesma política. As seções datadas abaixo são checkpoints históricos e não reinstalam exigências retiradas nem pendências já resolvidas.

Recuperação canônica — 11 de setembro de 2026¶

A instalação escolhida é /home/felipe/Work/pd-framework, com origin direto para o GitHub do PD Framework. Worktrees continuam disponíveis para trabalho, mas não devem selecionar versões próprias do runtime ou das skills. O menu PD → Agentes é preservado: o squad selecionado determina a persona no Herdr. Não é necessário reconstruir a barra ou o cockpit para trabalhar.

Issue somente por pedido de Felipe. Desenvolvimento continua seguindo o Dev Workflow mesmo sem issue; havendo vínculo solicitado, seguir o Issue Flow. Copiar áudio, ler imagens, salvar documentos e corrigir código autorizado não dependem de issue/label/plano/manifest como permissão de ferramenta. Permanecem credenciais, preservação de trabalho, permissões reais, testes e autorização humana para publicação ou destruição. Falha de gate não impede diagnóstico e correção na conversa atual. A revisão qualitativa depende da escolha humana.

Os metadados Git das antigas raízes foram consolidados com preservação de refs, índices e alterações locais, sem mover diretórios usados por processos vivos. Launcher e hooks Codex instalados usam o entrypoint estável ~/Work/bin/pd-agent-launcher.py, que resolve a configuração canônica antes de um ambiente antigo. As pontes nas raízes antigas são compatibilidade transitória, não uma segunda política. Não remover essas pastas enquanto houver dependências.

Na validação nativa, o CS executou cópia com integridade, transcrição e ata no Vault. A sessão Vitor aberta pela ação do menu confirmou persona, apply_patch, cópia, redirecionamento e escrita em worktree anexada mantendo o cwd original. O runner de encerramento gravou os três destinos sem remover worktrees. Essas provas não validam todos os squads, o clique gráfico nem a retomada da sessão LinkedIn. Há uma dependência viva de runtime antigo a coordenar.

O candidato local ed0bbb6f passou 884 testes e 10 subtestes no host; a régua do repositório não encontrou novos achados bloqueantes de lint/duplicação. Complexidade continua report-only segundo a baseline vigente, sem dispensa inventada. Resultados locais não são CI remoto. Na redação desta atualização, a publicação e a retirada completa das dependências antigas ainda não ocorreram.

O complemento local 8510a482 centralizou também os adapters Claude/OpenCode e o encaminhamento de eventos Codex chamados de checkouts antigos. A regressão ampla passou com 889 testes e 10 subtests; após ajustar a equivalência das URLs GitHub com/sem .git, passaram 150 testes de conversação e destinos. Onze descriptors antigos tiveram a identidade da instalação migrada com preservação do original; três recusaram cwd inexistente e não foram recriados. A dependência viva do LinkedIn e a publicação ainda permanecem pendentes neste checkpoint.

Fonte operacional: pd-framework/docs/omarchy/instalacao-canonica.md e manual/14-gate-zero.md. O histórico abaixo descreve estados anteriores e não autoriza cleanup automático.

Publicação da correção — PR 189¶

A PR 189 do PD Framework foi integrada em 11/09/2026, merge f4d5935e7e6935aeacf98ec34f0b0c31b1804841. Inclui a entrega do Vitor DEV-2077 com autoria/histórico preservados e a retirada dos efeitos Git da entrada legada stop-session-branch.py. Fim de turno não faz auto-commit, merge ou sweep, inclusive sem marker Omarchy. Os helpers de encerramento explícito continuam disponíveis; sua existência não autoriza cleanup.

O candidato de código c17ad0e1 passou 933 testes e 10 subtestes no host, com um warning preexistente. Ruff baseline e JSCPD passaram; Radon permaneceu WARN em report-only. A autorrevisão foi escolhida por Felipe, sem modelo externo; relatório versionado em docs/omarchy/recuperacao-canonica-20260911-revisao.md no framework. A PR não reportou checks de CI remoto; não confundir isso com os testes locais.

O Stop instalado foi também executado diretamente no cwd real do Vitor: status, diretório e arquivo de QA permaneceram intactos. As fixtures de regressão agora usam repositórios Git mínimos: a versão anterior dos testes copiava todo o framework e esgotou quota temporária; a rodada afetada não foi contada como verde.

Naquele checkpoint, Felipe havia adiado a sessão LinkedIn e o handoff para Marketing; a retirada física ainda estava pendente. A atualização de instalação unificada acima registra a movimentação posterior. Nem a PR nem essa movimentação comprovam validação do perfil, do clique gráfico do menu ou de todos os squads.

Contrato operacional simplificado — DEV-2073 (10 de setembro de 2026)¶

O fluxo mantido é Linear → planejamento → execução → validações → publicação autorizada. Não há consulta obrigatória de roteamento Dell/CAIXA1, pré-requisito BMAD ou mise en place. Os workers exclusivos do ex-operador Luiz Sidião foram retirados das fontes executáveis e preservados como snapshots auditáveis; isso não atesta desativação de instalações remotas antigas.

Na etapa de revisão, o agente pergunta em múltipla escolha: sem revisão, autorrevisão, modelos escolhidos via OpenCode ou outra instrução. Não existe trio automático. A escolha vincula-se à issue e ao SHA; dispensa de revisão não dispensa testes nem autoriza merge. O contrato e o seletor vivem em _core/REVIEW-CHOICE.md e _core/review_choice.py no PD Framework.

Uma entrega mantém uma branch coordenada. Isolamento de arquivos pode usar worktrees em detached HEAD, integradas pelo responsável pela branch. Git não deve ser forçado a manter a mesma branch em vários checkouts graváveis. Compartilhar um diretório exige escopos separados e operações Git serializadas; isso não concede um segundo owner de lifecycle. No Modo B, a coordenação operacional usa panes visíveis do Herdr.

O registro de execução da DEV-2073 distingue código validado, merge e ativação. Nenhum desses estados implica sozinho que sessões antigas foram recuperadas.

Recuperação operacional — DEV-2073 (9 de setembro de 2026)¶

O candidato inclui uma rota específica para notas operacionais do squad: _core/runtime/operational_context.py put/get. Ela mantém versões privadas fora do Git, compartilhadas pelas worktrees do framework, sem vincular a nota à issue do produto. Identidade, squad, credenciais e SHA anterior são validados; código e configuração continuam protegidos. A nova revisão aparece no contexto do próximo turno. O runtime foi ativado em 10 de setembro; isso não recupera nem altera automaticamente sessões que já estavam abertas.

A validação de setembro abaixo é histórica, não comprovação de que todas as sessões atuais estão saudáveis. A prioridade operacional definida por Felipe é o menu PD → Agentes: cada agente abre uma worktree e um workspace/pane próprios no Herdr. A escolha do menu também define a persona: Vitor usa times/dev/vitor/CLAUDE.md, Catarina usa seu squad e assim por diante. Stamper é somente a entrada Stamper; não é uma identidade aplicada a todos os agentes. Antes de planejar ou iniciar uma issue, o launcher pede a execução de /abrir-squad <squad> para carregar o panorama e as skills canônicas. Contexto inicial injetado não substitui essa skill. Os painéis da barra não são requisito para executar trabalho e não estão sendo removidos nesta recuperação.

Dois agentes reais (Stamper e Vitor) foram abertos pelo comando do launcher instalado, em worktrees distintas; ambos leram skills e executaram tools em dois turnos sem erro de hook visível. A correção posterior de persona foi coberta por testes dos itens atuais do menu, mas ainda requer validação visual de uma abertura nova pelo menu antes de ser declarada validada de ponta a ponta. Isso não valida o clique gráfico, todos os squads ou o ciclo completo de uma issue.

A correção em manutenção separa checkpoint de turno de encerramento, preserva worktrees com owner vivo/incerto e permite configurar a raiz do launcher sem depender do widget. Atualizar uma branch não instala essa correção nos hooks globais nem recupera automaticamente descritores com diretório desaparecido.

Não executar cleanup durante instalação com versões misturadas. Não recriar uma pasta vazia para satisfazer hooks, apagar locks ou trocar branches de projetos em andamento. O encerramento Omarchy usa handoff_only, sem merge/push/remoção automática da worktree do usuário. A limpeza de especialistas temporários citada no fluxo histórico abaixo não autoriza apagar sessões de trabalho abertas pelo menu.

Contrato e instruções canônicas: continuidade e recuperação. A publicação de documentação não substitui ativação nem validação visual: uma nova abertura pelo menu ainda é a prova necessária do comportamento do launcher.

Validação histórica do cockpit¶

Em 6 de setembro de 2026, o fluxo completo foi executado com Herdr e Codex reais em um workspace isolado: o Stamper abriu o especialista, enviou uma pergunta concreta, recebeu a resposta autenticada na conversa principal e o Cockpit removeu automaticamente a aba e o worktree temporários. A janela de QA foi fechada ao final sem mudar o workspace ativo do usuário.

O pacote agora instala a integração oficial herdr:codex, aponta os hooks de lifecycle para a versão instalada do framework e reconcilia aprovações sem duplicar tabelas no config.toml. O aceite visual final ainda deve ser feito pelo plugin instalado; os conectores de Entregas e Infraestrutura continuam em stories próprias.

Como funciona¶

flowchart TD
    classDef component fill:#D1FAE5,stroke:#10B981,color:#111
    classDef flow fill:#DBEAFE,stroke:#3B82F6,color:#111
    classDef decision fill:#EDE9FE,stroke:#8B5CF6,color:#111
    classDef core fill:#FEE2E2,stroke:#EF4444,color:#111
    classDef warning fill:#FEF9C3,stroke:#EAB308,color:#111

    subgraph SG_component["Componentes"]
        lane_components["FAIXA A — Componentes"]
        docs[("Projetos/PD Framework/Docs/pd-cockpit-omarchy.md")]
        plugin["Plugin QML"]
        view["View-model"]
        gateway["Gateway tipado"]
        orchestrator["Coordenador"]
        package["Pacote recuperável"]
        menu_launcher["Launcher do menu PD"]
    end
    class lane_components,docs,plugin,view,gateway,orchestrator,package,menu_launcher component

    subgraph SG_flow["Fluxo do processo"]
        lane_flow["FAIXA B — Fluxo"]
        publish["1. Fonte publica"]
        open["2. Pessoa abre"]
        choose["3. Pessoa escolhe"]
        direct["Foco/status: consulta a sessão sem iniciar trabalho."]
        reconcile["4. Painel reconcilia"]
        start["Start: abre ou reutiliza conversa principal do Stamper."]
        returned["RETURNED: payload autenticado contém resultado e pode conte…"]
        returned_delivered["Não: resultado chega ao Stamper e inicia cleanup automático."]
        closed["Sim: handoff persistido, owner liberado e pane fechado."]
        menu_open["Pessoa abre um agente pelo menu"]
        menu_isolated["Worktree e pane próprios"]
        menu_work["Agente trabalha"]
        menu_checkpoint["Stop de turno: checkpoint"]
        menu_handoff["Encerramento explícito: handoff"]
    end
    class lane_flow,publish,open,choose,direct,reconcile,start,returned,returned_delivered,closed,menu_open,menu_isolated,menu_work,menu_checkpoint,menu_handoff flow

    subgraph SG_decision["Decisões"]
        lane_decisions["FAIXA C — Decisões e falhas"]
        snapshot_ok["Snapshot utilizável?"]
        action_kind["Qual ação?"]
        attested["Delegação foi atestada?"]
        delegation_outcome["Especialista respondeu ou o transporte bloqueou?"]
        return_kind["O retorno contém block?"]
        close_confirmed["Close foi confirmado?"]
        c6_ok["C6 quando ativo e cleanup concluíram?"]
        route_terminal["A rota já está RETURNED?"]
        menu_valid["Diretório e identidade coerentes?"]
    end
    class lane_decisions,snapshot_ok,action_kind,attested,delegation_outcome,return_kind,close_confirmed,c6_ok,route_terminal,menu_valid decision

        title["PD Cockpit no Omarchy"]
    class title core

    subgraph SG_warning["Gotchas / Erros"]
        snapshot_error["Snapshot ausente, inválido ou vencido: leitura degradada e …"]
        attestation_error["Falha pré-bind: rota vira CANCELLED; recursos próprios e li…"]
        transport_block["Bloqueio de transporte: rota fica DISPATCHED; mesma sessão …"]
        business_block["Sim: motivo e próximo passo chegam ao Stamper; sessão perma…"]
        close_rejected["Não: rejeita sem efeito."]
        cleanup_preserved["Não: sessão, workspace e alterações ficam recuperáveis."]
        cancelled["Não: rota vira CANCELLED e o especialista é interrompido co…"]
        menu_blocked["Preservar e diagnosticar"]
    end
    class snapshot_error,attestation_error,transport_block,business_block,close_rejected,cleanup_preserved,cancelled,menu_blocked warning

    publish -->|"validar"| snapshot_ok
    snapshot_ok -->|"sim"| open
    snapshot_ok -->|"não"| snapshot_error
    open -->|"entender"| choose
    choose -->|"executar"| action_kind
    action_kind -->|"foco/status"| direct
    action_kind -->|"start"| start
    action_kind -->|"talk/delegate"| attested
    action_kind -->|"close"| close_confirmed
    direct -->|"consultado"| reconcile
    start -->|"ativo"| reconcile
    attested -->|"sim"| delegation_outcome
    attested -->|"não"| attestation_error
    attestation_error -->|"compensar"| cancelled
    delegation_outcome -->|"respondeu"| returned
    delegation_outcome -->|"transporte"| transport_block
    returned -->|"entregar"| return_kind
    return_kind -->|"sim"| business_block
    return_kind -->|"não"| returned_delivered
    returned_delivered -->|"automático"| c6_ok
    transport_block -->|"bloqueio"| reconcile
    business_block -->|"bloqueio"| reconcile
    close_confirmed -->|"sim"| route_terminal
    close_confirmed -->|"não"| close_rejected
    route_terminal -->|"sim"| c6_ok
    route_terminal -->|"não"| cancelled
    cancelled -->|"cleanup"| c6_ok
    c6_ok -->|"sim"| closed
    c6_ok -->|"não"| cleanup_preserved
    closed -->|"remover"| reconcile
    cleanup_preserved -->|"recuperável"| reconcile
    menu_open -->|"launcher"| menu_isolated
    menu_isolated -->|"ativar"| menu_valid
    menu_valid -->|"não"| menu_blocked
    menu_valid -->|"sim"| menu_work
    menu_work -->|"fim de turno"| menu_checkpoint
    menu_checkpoint -->|"próximo turno"| menu_work
    menu_work -->|"encerrar explicitamente"| menu_handoff

Uma fonte autorizada publica um snapshot com fatos, datas e ações permitidas. O plugin o apresenta em três áreas: Trabalho, Entregas e Infraestrutura. Trabalho é a área funcional desta etapa; Entregas e Infraestrutura permanecem visíveis, mas dizem claramente que seus conectores ainda não foram ligados.

Ao clicar em uma ação, o gateway confere novamente o snapshot e o estado do Herdr. Conversar, Iniciar e Delegar preservam o Stamper como conversa principal. Uma delegação cria isolamento próprio e só é autorizada depois de confirmar workspace, tab, pane, cwd, branch e processo. Quando o Herdr publica metadados de worktree gerenciado, checkout e repositório também são conferidos.

Resultados, bloqueios e falhas voltam como dados limitados ao painel. Encerrar sessão exige confirmação, executa o fechamento semântico e preserva qualquer trabalho que ainda não possa ser limpo com segurança.

Decisões técnicas¶

• Snapshot em vez de consultas no QML. Mantém credenciais e regras de negócio fora da interface e permite falhar fechado.
• Ações allowlisted e tipadas. O rótulo visual nunca vira comando livre; ação, alvo e chave idempotente são revalidados no gateway.
• Stamper como front door. O especialista trabalha isolado, mas o usuário não precisa migrar de conversa para receber o resultado.
• RouteEnvelope como estado da delegação. Correlação, autorização, bind, retorno e cancelamento têm uma única fonte privada e recuperável.
• Pacote no escopo do usuário. Nada é alterado em /usr/share/omarchy; a atualização guarda backup, instala a integração Herdr/Codex e reinicia apenas o shell.
• Fatos desconhecidos continuam desconhecidos. O cockpit não transforma ausência de sinal em sucesso. Felipe é usuário/decisor, não agente monitorado.

Gotchas e armadilhas¶

• DEV-2073 ainda em manutenção. O aceite histórico do cockpit não comprova recuperação global: o smoke de dois launchers passou em leitura, mas a sessão antiga de Multicontas ainda falhou no Stop. Instalação do candidato e aceite completo continuam pendentes.
• O menu não é a barra. PD → Agentes abre trabalho isolado no Herdr; widgets de acompanhamento não são pré-requisito conceitual. O wrapper corrigido aceita raiz própria em launcher.json, mas precisa ser instalado para isso valer.
• Encerrar não é apagar. Sessões Omarchy usam handoff e preservação; Stop Codex de turno é checkpoint. Não aplicar cleanup de especialistas temporários às worktrees de trabalho nem executar limpeza em rollout misto.
• “Recarregar” não sincroniza fontes. A tecla r relê o último snapshot. Se o publisher não atualizou o arquivo, o conteúdo não muda. A própria interface agora informa essa limitação, em vez de sugerir atualização real.
• O contador representa pendências, não botões. Ele agrega decisões, bloqueios e exceções que pedem atenção. Itens sem ação ficam recolhidos em Acompanhamento para não disputar espaço com prioridades.
• Sessões dependem da publicação reconciliada. A lista pode combinar sessões do Zed e do Herdr, mas não deve inferi-las no QML nem chamar uma fotografia manual de sincronização contínua.
• Herdr online não basta. A sessão precisa estar atestada e vinculada à rota antes de a delegação produzir efeitos.
• JavaScript do QML pode ficar em cache. Use o instalador para atualizar; ele reinicia o shell depois de validar o pacote.
• Pause ainda não existe. O contrato atual oferece foco, status e encerramento seguro. Não há botão cenográfico para uma capacidade ausente no Herdr 0.8.2.
• PRs são empilhadas. A base visual integra antes do roteamento e da delegação; promover fora de ordem invalida gates e evidências.
• Snapshot de demonstração não prova integração. Linear, deploy e Infra só contam como conectados quando seus publishers reais existirem.

Como operar¶

# Estado da instalação
python3 omarchy/cockpit_package.py status

# Atualizar com backup e rollback automático
python3 omarchy/cockpit_package.py update

# Voltar à última versão instalada
python3 omarchy/cockpit_package.py rollback

# Testes de view, ações, fluxo e pacote
python3 -m pytest -q \
  _core/runtime/test_cockpit_view.py \
  _core/runtime/test_cockpit_action.py \
  _core/runtime/test_cockpit_delegation.py \
  _core/runtime/test_cockpit_plugin.py \
  _core/runtime/test_cockpit_package.py \
  adapters/codex/test_bootstrap_paths.py

O E2E final deve usar uma sessão Herdr descartável em outro workspace e o plugin instalado. Não se deve focar, controlar nem fechar uma sessão de trabalho existente para testar o cockpit.

FAQ¶

O que faço quando um item exige atenção?¶

Abra o cartão para ver objetivo, impacto, risco e próximo passo. Quando a fonte autorizar, use “Conversar com o Stamper” ou a ação operacional indicada. Um item sem explicação e sem próximo passo é dado incompleto, não tarefa para o usuário adivinhar.

Qual a diferença entre as três áreas?¶

Trabalho trata de decisões, bloqueios e sessões. Entregas tratará de PRs, deploys e saúde pós-deploy. Infraestrutura tratará de incidentes, serviços e automações. As duas últimas aguardam seus conectores próprios.

Por que meu nome apareceu como “saudável”?¶

Um snapshot de validação confundiu o usuário com um líder operacional. O dado foi corrigido e a regra agora é explícita: Felipe não recebe estado de agente. Sem sinal real, a pessoa operacional aparece como estado desconhecido.

Posso pausar sem perder a sessão?¶

Ainda não existe comando Pause no contrato atual. É possível focar, consultar status ou encerrar com handoff. Pause só deve aparecer quando runtime e Herdr suportarem essa transição de forma recuperável.

O que significa “snapshot não publicado”?¶

O plugin não encontrou uma projeção válida no caminho esperado. Verifique o publisher; clicar em recarregar não cria a projeção.

Referências¶

• Issues: DEV-2007, DEV-2008, DEV-2009, DEV-2010, DEV-2011, DEV-1965, DEV-1967 e DEV-1999.
• RFC-009 — interface nativa
• Contrato do view-model
• Bootstrap do runtime
• Instalação e recuperação