@zaip-ai/cli 4.2.0 → 4.3.0

package/templates/.agents/runtime/checksums.sha256

@@ -1,11 +1,11 @@
 b146bd0c7c60b1ab43c4f71e0b1d2262c6df6da6f7053a0425f834ccb77a6b48  LICENSE
 bc02cba77e8d51e5c580f43668863dc868eda66f1ff663bfaa49fcf3ca16320e  THIRD_PARTY_NOTICES.md
-8fb33dadbe981cf5847df269c10c2a3fe107f2b269d5ccb6db37d1f61ffc3bba  VERSION
-5b35f337672915d9a318be9f266c8e7b2ba429da6d10cd5383fc686bd4104572  bin/zaip.mjs
-64049ea6b7d3e262e804542de3f5569279be70787b2971b92aa439e869f4099d  manifest.json
+1e5302003691b6fdc7bddc0736eef7ce3adc870e97afdfcfb497dde2a78ed545  VERSION
+126208e70b62a20446cc2d7a5000fddf05af2b334e8d9f8f9f137d0a81670ddf  bin/zaip.mjs
+fd8b01d5a381387bc5fe3d878ea92f4b1f1697968f2ce37bcba29078ac19e5d3  manifest.json
 7f89219d7c567c82a51679ad136d84364bded7ac659492537e125d33b1d58a7a  migrations/001-layout-v1.json
 5f8c48b286d0b44d8fbb57a9a5d009a8a500439aa3148d750b8f193f72995c9f  migrations/002-layout-v2.json
 33c98d5dc506bba4b8b3ca612706d9eb05ef13d9e03c33a4f9e65ca7804be9d1  pnpm-lock.sha256
-2a619ec324e3ff4ec40c5dffa457d1e06c3b39414e01fbdff638f10b171de200  provenance.json
-442d77c7f41b8879c40d46ddb669bbe3c9d0a090aafd746d95e7383649d301cd  sbom.cdx.json
+dbcb7ca019229dc08426369c68efdba41c554536bd30ff61d517abf3440db4b7  provenance.json
+f152c56a6020fa33a47e6d40c550b8f941e49ab7c6e9b6e86856eb9efa16eff0  sbom.cdx.json
 b3ffedf9e146be802a15b4009f33e031dec3071ca1525e12c67606fd964a3067  schemas/contracts.schema.json

package/templates/.agents/runtime/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "name": "zaip-aios",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "node": ">=22",
   "files": [
     "LICENSE",

package/templates/.agents/runtime/provenance.json

@@ -2,10 +2,10 @@
   "schema_version": 1,
   "statement_type": "self_reported_build_integrity",
   "authenticity": "unverified",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "source_origin": "zaip-aios:local-build",
   "lockfile_sha256": "03d08e5bbb198d74014ea4a806fcdeb350db23ec2bf0c2886a2265066555d418",
-  "sbom_sha256": "442d77c7f41b8879c40d46ddb669bbe3c9d0a090aafd746d95e7383649d301cd",
-  "runtime_sha256": "71d9b329e2234c6883c8d7c0fb5a1470ab7898babb814b3f963fb4324d5458ed",
-  "statement_sha256": "c566542083242f672e9b71655516ff72da3508008f08b822f631476972ebed44"
+  "sbom_sha256": "f152c56a6020fa33a47e6d40c550b8f941e49ab7c6e9b6e86856eb9efa16eff0",
+  "runtime_sha256": "7bab388a60fee8ac611ef8af05629402a4cf896085302631b8aa0373b330aaa5",
+  "statement_sha256": "3ebd6dc2a728991c9fc822b324607fe1787cdfa9a2a20f6bace1303dd41ab314"
 }

package/templates/.agents/runtime/sbom.cdx.json

@@ -6,7 +6,7 @@
     "component": {
       "type": "application",
       "name": "zaip-aios",
-      "version": "4.2.0"
+      "version": "4.3.0"
     }
   },
   "components": [

package/templates/.agents/skills/zaip-skill-execution/SKILL.md

@@ -18,7 +18,7 @@ Use esta skill somente quando o usuário pedir execução. `prepare` não autori
 - Não encerre após criar/validar plano, sucessor, DAG ou Execution ativa. Não peça “continue execução” nem outra confirmação só porque a preparação consumiu tempo ou contexto; faça checkpoint/refresh e prossiga.
 - `spec execute`/`prd execute` ativam o macro e retornam `continuation.required`; isso é handoff obrigatório, não prova de implementação. Em runtime gerenciado, acione `execution run EXEC`; na colaboração nativa Codex, siga a seção de DAG nativa abaixo. Use somente um caminho de dispatch, com a mesma Execution e atribuição válida.
 - Depois de cada Task, execute as próximas elegíveis; ao terminar a DAG, realize os gates parentais e Gui. Só encerre com resultado observado ou impedimento concreto após recuperação permitida. Ramos independentes continuam somente quando a política de falha da DAG permitir.
-- Comandos longos permanecem em primeiro plano ou em sessão durável acompanhada até saída terminal. Antes de dizer que um processo “ainda está em execução”, consulte novamente seu PID/sessão e registre a saída mais recente; processo encerrado com falha exige diagnóstico e continuação autorizada, nunca uma resposta final baseada no estado antigo. O primeiro Stop de uma Task própria em `executing` ou `verifying` deve ser bloqueado mesmo quando seu registro pertence a outro worktree Git registrado.
+- Comandos longos permanecem em primeiro plano ou em sessão durável acompanhada até saída terminal. Antes de dizer que um processo “ainda está em execução”, consulte novamente seu PID/sessão e registre a saída mais recente; processo encerrado com falha exige diagnóstico e continuação autorizada, nunca uma resposta final baseada no estado antigo. Feche o resultado canônico pela CLI antes da resposta. O hook Stop registra pendências, inclusive de worktree registrada, mas nunca solicita continuação automática nem substitui a resposta; pendência não equivale a sucesso.
 - Falta real de autoridade, informação essencial, capacidade do host ou gates continua sendo bloqueio. Informe a causa e a condição de retomada; não invente sucesso, nova autorização, identidade ou ancestralidade para continuar.
 
 Antes de encerrar com trabalho pendente ou responder a uma falha, aplique [continuidade automática e parada justificada](references/autonomous-continuation.md). O perfil congelado e seu ledger decidem recuperação; reparação elegível usa a autorização existente, sem pedir outro turno.

package/templates/.agents/skills/zaip-skill-execution/references/correction-cycle.md

@@ -5,3 +5,29 @@ Carregue esta referência somente antes de uma nova correção. Falha operaciona
 Registre nos findings, Change ou Run existentes somente resultados observáveis: falha, tentativa e resultado, aprendizado ou hipótese nova, e próxima ação e teste discriminante; não registre raciocínio privado. Se a mesma falha reaparecer após uma correção, revise a hipótese antes de editar novamente. Evidência pode refutá-la mesmo quando o teste não passa. Diff, ID cosmético ou mera ausência de erro não demonstram avanço.
 
 Preserve escopo e critérios de aceite; evite melhorias opcionais e valide primeiro a hipótese específica, repetindo validação ampla somente por mudança relevante ou gate exigido. Respeite os limites e contadores existentes, sem criar paralelos; um replanejamento não os reinicia nem cria identidades novas para ganhar tentativas. Esgotada a recuperação, use `failed` somente para impedimento técnico comprovado; falta de acesso, prova, autoridade ou conclusão segura usa `blocked`, com a condição objetiva de retomada. Não peça “continue execução” para repetir uma tentativa vedada. Antes de uma parada, aplique [o contrato de continuidade](autonomous-continuation.md). Astra só é usado onde a política atual permite; Task avulsa preserva modelo e effort selecionados pelo host.
+
+## Falha durante verificação, antes de Gui
+
+Uma Task `verifying` com gate comprovadamente falhado pode voltar a `executing` por
+`task repair-verification TASK --run RUN --validation TEST-ID --commit SHA --expected-revision N --reason MOTIVO`.
+O comando exige a mesma Task/Change/Execution, a Run raiz ativa exata, ausência de filhos ativos e de decisão Gui,
+e uma Validation `failed` pertencente à raiz ou a seus descendentes, vinculada ao SHA observado.
+Não reescreva status manualmente nem reutilize aprovação de outro commit.
+
+A operação reserva recuperação no ledger congelado da Task; não apaga histórico nem reinicia a tentativa física.
+Se houver replan obrigatório, forneça `--replan-summary RESUMO` somente após o plano efetivamente realizado,
+com modelo/effort observados compatíveis com sua posição Sol/high, Sol/high, Astra/high.
+Use `--replan-run RUN` para um planejador filho já concluído da mesma raiz; na ausência dele,
+a seleção observada da própria raiz deve satisfazer a política. Não altere o modelo imutável da raiz.
+Uma seleção indisponível ou incompatível bloqueia a operação; não se registra replan fictício.
+Após executar e registrar nova Validation, use
+`task settle-repair TASK --run RUN --repair CHAVE --validation TEST-ID --rerun-of FAILED-TEST-ID --commit SHA`.
+A CHAVE é o sufixo retornado em `recovery_attempt_id`. Settlement requer resultado posterior à reserva,
+do mesmo trabalho e raiz, identificando o gate falhado e cobrindo seus ACs; uma reserva pendente não autoriza novo dispatch. Falha de escrita permite repetir
+o comando idêntico para roll-forward sem consumir duas vezes. Estes comandos não dispensam `task verify`,
+revisão independente, Evidence ou o último filho Gui.
+
+`task workspace TASK --run RUN` reaproveita a checkout registrada ao retomar a mesma Task/Execution,
+transferindo somente o claim de uma raiz já terminal para o único orquestrador ativo. Preserva base, branch,
+arquivos pendentes e recibo recuperável. Dono ativo, filhos pendentes, branch divergente ou claim incompatível
+exigem diagnóstico; nunca crie uma checkout substituta silenciosamente.

package/templates/.agents/skills/zaip-skill-execution/references/runtime-governance.md

@@ -7,8 +7,10 @@ Carregue antes de executar uma entrega ou delegar. Este contrato detalha o kerne
 - Para delegação Codex, Sub-Run ZAIP é somente subagente nativo de colaboração (`spawn_agent`). `create_thread` e `fork_thread` criam chats independentes e exigem pedido explícito do usuário; nunca são Sub-Run, fallback, retry ou prova de delegação. Se delegação nativa estiver indisponível, relate a limitação em vez de criar chat independente. Nome de catálogo, `task_name`, título ou prompt não prova ancestralidade nativa. Antes de repetir a mesma delegação limitada, aguarde ou reutilize seu filho pendente e capture somente ancestralidade/metadados observados em resultados nativos de spawn/terminal do host ou eventos SubagentStart/SubagentStop.
 - Cada `client_turn_id` observável tem uma Execution idempotente/claim atômico; sem ele use identidade local sem prometer idempotência. `interaction` read-only sem descendentes é conversa sem Task artificial e termina após a resposta entregue, sem executor ou finalizador; interaction com trabalho delegado e `delivery` exigem executor/finalizador. `delivery` é trabalho materializado e reuso exige kind/origem compatíveis. A raiz é `zaip-agent-orchestrator`; quando a barreira é exigida escolha executor por capacidade, permita reviewer/auditor/integrator e termine com `zaip-agent-finalizer` em `finalization`, após descendentes, bloqueando novas chamadas.
 - Hooks são best-effort: após cada spawn/terminal, o host autorizado a serviço do orquestrador executa `zaip subagent capture` idempotente com metadados reais. Na captura rica, preserve session/turn observados, `agent-id` com a identidade nativa retornada e `parent-agent-id`/`parent-run-id` do pai imediato exato; cada invocação preserva seu turn. Quando um evento terminal observado expõe somente agent_path, status, identidade catalogada e pai exato, `capture-terminal` aceita apenas `zaip-agent-finalizer` ou executor elegível para delivery com capacidade `task-delivery`; exige também `parent-run-id` igual ao `run_id` da raiz ativa exata, pois um client thread pode conter raízes concorrentes. O último segmento do agent_path deve ser seu `codex_task_name` canônico. O propósito deriva da identidade validada e session/turn/model/provider/usage permanecem indisponíveis; o fallback nunca substitui captura rica nem inventa modelo, effort, tokens ou custo.
+- Antes da primeira edição do executor nativo, capture seu início observado. O PreToolUse pode receber a sessão do pai junto com o turno do filho: a CLI grava correlações locais exatas para esse formato e para a sessão nativa do filho, somente após verificar ancestralidade, modelo/effort, Task e Execution ativos. A autorização de patch fica limitada aos write scopes da Task; reviewers, identidades desconhecidas, outro turno e Runs terminais não recebem essa capacidade. Não copie nem fabrique recibos. Ao reutilizar um subagente, capture seu novo turno ativo; o recibo anterior não autoriza a retomada.
 - Em `autonomy-v1`, carregue `RULE-AUTONOMY-DECISION`. Conversation sem entrega responde diretamente; Task avulsa no padrão `codex_native` usa executor e Gui nativos. O principal preserva a seleção manual do host; cada filho segue a seleção ZAIP por papel/risco/fase, registrada conforme o modelo/esforço efetivamente observados. Capacidade ausente bloqueia a tentativa, nunca é substituída por prompt. Sem `autonomy`, preserve o contrato legado de `automatic_sources` (`spec`,`prd`).
 - Escaladas seguem o perfil congelado: Essencial nunca Astra automático; Equilibrado Sol/high, Sol/high, Astra/high, com execução Astra/high elegível no terceiro bloco; Persistente sem quota total. `RULE-ASTRA-DIAGNOSTIC` descreve também compatibilidade legada. Não use título/volume como prova nem alegue mudança de modelo apenas pelo prompt.
+- Perfis nativos de orquestração e entrega não devem transformar preferências do catálogo em travas TOML de modelo/esforço. O host seleciona explicitamente a configuração da invocação conforme a política congelada, valida capacidade e reserva antes do despacho; ausência de trava não autoriza herança silenciosa, Astra antecipado ou ampliação de permissões. Revisores e finalizador conservam seus contratos próprios. Depois de regenerar os perfis, confira o schema efetivamente carregado pelo Codex: editar o arquivo não comprova recarga nem uma invocação Astra. Se o schema ainda fixa Sol, preserve o bloqueio e solicite recarga da sessão, nunca use `default` ou prompt como substituto.
 - Todo PreparedPlan PRD/SPEC traz `model_signals` por Task; o framework persiste `model_profile`, `task-risk-v1` e motivos, usando `runtime_defaults`, `runtime`, política/defaults sem `standard` silencioso. Não infira fase/complexidade/transversalidade/ambiguidade/rework/custo/capacidade por contagem de arquivos; use sinais, fase/agente e capacidades. Cabeçalho e `model.selection.recorded` repetem a seleção enviada.
 - Plano visível: `DEFINE:`, `PLAN:`, `EXECUTE:` ou `VERIFY:`, 3–4 passos (máximo 5); omita fase sem ação e combine trivialidades.
 

package/templates/.agents/skills/zaip-skill-release-qualification/references/local-preparation.md

@@ -3,6 +3,35 @@
 Preparation does not authorize publication. Use guarded delivery only for an explicit deployment request.
 Store keys, trust stores, receipts and artifacts outside the repository. Commit and synchronize first;
 every gate is bound to the resulting clean SHA. Repair changes require a new candidate.
+Qualification uses an independent local Git clone at that exact SHA, with copied
+objects and complete commit history, not a worktree sharing the caller's registry.
+This prevents dashboard source discovery from importing the main checkout or other
+Codex worktrees into candidate evidence; normal product worktree reconciliation is
+unchanged. Cleanup retries transient Windows locks and preserves the original gate
+error if cleanup also fails. A cleanup failure never produces a success receipt.
+
+When the ZAIP Codex PreToolUse hook is enabled, run release preparation, verification and
+guarded delivery as separate literal commands. Its external-path exception is limited to
+the reviewed release helpers, the declared SHA and version, the matching candidate
+directory under `~/.codex/release-candidates/zaip-aios/`, and key material under
+`~/.codex/release-keys/zaip-aios/<key-id>/`. It does not permit arbitrary home
+directory access, repository-local signing keys, or chained Git commands. A blocked
+unrelated path or compound command is an intentional safety decision, not a failed
+release gate. Persistent repository edits additionally require a current Task Run with
+the exact Codex thread and turn correlation.
+
+For native `exec_command`, the hook validates both the chat's `cwd` and the command's
+explicit absolute `workdir`. A registered worktree may be the execution root even
+when the chat remains in the primary checkout. Unregistered roots, links, relative
+overrides and missing exact worktree Run authority remain blocked; a primary
+checkout's Task is never a global fallback for mutations in another checkout.
+
+Some hosts present these commands as `Bash` without exposing a workdir override.
+In that case, invoke the literal reviewed helper from the chat checkout and pass
+the registered worktree in `--repository`. Only the helper may target that explicit
+root, after physical-root, Git registration and common-directory verification;
+its own preflight checks the exact clean SHA before any gate. This is not an
+exception for arbitrary commands or filesystem access.
 
 The signing key ID is the trusted identity, not a filename. Resolve it with
 `gh variable get ZAIP_LOCAL_RELEASE_TRUSTED_KEY_ID --repo zaip-ai/zaip-aios`.
@@ -71,7 +100,8 @@ build/type integrity, package/SBOM/TGZ binding, dependency audit and one clean i
 doctor/SQLite/API smoke. It does not run browser navigation across every dashboard tab or XLSX
 exports. `--profile full` explicitly selects `full-v2`, which also runs the full source suite,
 browser and XLSX qualification. Essential preparation has a 30-minute deadline; full preparation
-has a 60-minute deadline. Both use process-tree
+has a 90-minute total deadline for its serial Windows/browser/package matrix;
+individual test timeouts and all acceptance gates remain unchanged. Both use process-tree
 termination and cleanup after expiry. A failure never produces a successful receipt. Receipts bind
 the selected profile and its fixed gate list, so former receipts require requalification.
 Successful preparation emits receipt, manifest, SBOM and TGZ.

package/templates/.agents/skills/zaip-skill-setup/SKILL.md

@@ -40,6 +40,31 @@ Create the disposable dashboard database only from canonical `.agents/records` a
 7. Após a instalação, use `$zaip-skill-dev-environment` para inventariar apenas nomes e presença de pré-requisitos. Para configurar o projeto, personalizar perfis Codex ou seguir os primeiros passos, use `$zaip-skill-config`.
 8. A instalação deixa `beta` como ramo padrão de frontend, backend e banco, mas não cria uma branch Supabase hospedada, integração GitHub, credencial ou custo adicional. A configuração protegida de migrations é uma escolha posterior e explícita pelo `$zaip-skill-config`.
 
+## Ativação Codex em instalação e atualização
+
+Sempre consulte `node .agents/runtime/bin/zaip.mjs hook status --json` após instalar
+ou atualizar. `doctor` reporta hooks separadamente da validade dos arquivos.
+Use hooks somente do repositório; não instale fallback global. Preserve terceiros
+e configurações personalizadas na migração, com backup dos hooks ZAIP removidos.
+
+Sem prova atual, informe “Arquivos instalados; integração Codex ainda não validada”.
+Oriente: “Clique no ícone de âncora laranja, revise os hooks ZAIP-AIOS e clique em
+Permitir tudo. Se houver terceiros, selecione somente ZAIP. Confira os interruptores.”
+Termine com **Depois de aprovar os hooks, pode me avisar para validar?** Essa pergunta
+substitui o CTA Git/configuração abaixo enquanto a ativação estiver pendente.
+Não peça nova aprovação quando a integração atual já estiver validada.
+
+Após o aviso, confira eventos reais pelo Codex: leitura segura e um subagente pequeno
+com início/término observados, autorizado no onboarding. Executar o script direto
+não prova aprovação. Sem confirmação, consultas e planejamento continuam disponíveis;
+entregas dependentes da integração aguardam validação. Nunca autoaprove a trust store.
+
+Stop só ocorre depois da resposta: confirme essa segunda etapa na interação seguinte,
+com recibo exato, sem gerar continuação automática. `closure_pending` não é sucesso.
+Mudanças de scripts/configuração invalidam evidência anterior; atualização sempre
+reverifica, mas não exige aprovação repetida sem necessidade. Ausência de prova é
+“não confirmado”, não prova de recusa. Telemetria pendente não deve apagar respostas.
+
 ## Resposta final obrigatória após instalação
 
 Este contrato vale para a **resposta final do assistente no chat**, além do output da CLI. Aplique-o mesmo quando o usuário pediu apenas o comando npx, a instalação começou sem skills disponíveis ou esta skill só foi descoberta depois do init. Releia esta seção antes de responder. A existência de project.yaml recém-instalado não deve desviar a resposta para uma configuração automática.
@@ -66,7 +91,7 @@ Deseja ajuda para configurar seu repositório Git?
 - Substitua VERSÃO pela versão instalada, sem prefixo v no URL. Obtenha números e resultados da execução; dado ausente deve aparecer como “não informado”. Não declare sucesso de SQLite/doctor quando não executados ou falhos. Dry-run e instalação falha não usam a frase de sucesso.
 - Se não houver repositório, use “O diretório ainda não possui um repositório Git configurado.” Outros estados devem descrever a pendência real. Git, identidade, repositório, commit inicial e GitHub não são pré-requisitos de instalação; informe que podem ser configurados depois. Estado local não comprova autenticação.
 - Com GitHub pendente ou inconclusivo, termine com **Deseja ajuda para configurar seu repositório Git?** Com GitHub configurado localmente, substitua apenas a pergunta por **Deseja ajuda para realizar a configuração inicial do ZAIP-AIOS?**
-- Termine com exatamente uma dessas perguntas. Não escreva nada depois dela nem ofereça as duas alternativas juntas. Antes de enviar, confirme: bullets presentes; versão clicável no npm correto; pergunta correspondente ao estado e última linha da resposta.
+- Termine com exatamente uma pergunta: aprovação dos hooks enquanto não verificada, ou a pergunta Git/configuração correspondente quando a integração estiver validada. Não escreva nada depois dela nem ofereça alternativas juntas. Antes de enviar, confirme: bullets presentes; versão clicável no npm correto; pergunta correspondente ao estado e última linha da resposta.
 
 ## Aceite e encerramento do onboarding
 

package/templates/.agents/skills/zaip-skill-task/references/commit-policy.md

@@ -18,7 +18,14 @@ Um hook local pode ser ignorado com `--no-verify` e não é uma fronteira de seg
 
 PreToolUse localiza a Run pela correlação exata de sessão/turno e valida o registro canônico. Índice ausente, desatualizado ou Run terminal exige captura/reconciliação explícita; não autoriza pela última Task global.
 
-Stop lê apenas linhas completas acrescentadas ao transcript. Um recibo em `.local/hooks/stop-<hash>.json` guarda cursor e provas da sessão/turno. Use `node .agents/runtime/bin/zaip.mjs hook recover-stop --session SESSION --turn TURN` para repetir o evento exato após corrigir a causa. O prazo do hook é 8 segundos dentro dos 10 segundos do host. Falhas e descendentes ativos deixam pendência explícita; ausência de gates/finalizador leva ao bloqueio canônico, sem sucesso artificial. Uma continuação síncrona é solicitada no máximo uma vez para evitar ciclo de Stop.
+Stop lê apenas linhas completas acrescentadas ao transcript. Um recibo em `.local/hooks/stop-<hash>.json` guarda cursor e provas da sessão/turno. Use `node .agents/runtime/bin/zaip.mjs hook recover-stop --session SESSION --turn TURN` para repetir o evento exato após corrigir a causa. O prazo técnico do hook é 8 segundos dentro dos 10 segundos do host; não é um limite de tempo para a entrega. Falhas e descendentes ativos deixam pendência explícita; ausência de gates/finalizador leva ao bloqueio canônico, sem sucesso artificial. Stop nunca solicita continuação automática nem substitui a resposta. A CLI conduz o fechamento antes da resposta; a confirmação do evento terminal do host ocorre na interação seguinte.
+
+A recuperação CLI explícita acompanha o mesmo recibo em uma chamada ativa do Codex,
+com até 45 segundos de trabalho e limite externo de 50 segundos; não amplia o prazo
+do hook disparado pelo host nem instala execução após o encerramento do Codex.
+Essa diferença permite concluir reconciliações legítimas mais lentas que 8 segundos.
+Timeout ou falta de prova mantém `pending`; somente confirmação canônica permite
+`persisted`. Acompanhe a sessão até sua saída terminal.
 
 SubagentStart/Stop persiste recibo antes do processo em segundo plano, permite três tentativas limitadas e só confirma JSON de captura canônica. `node .codex/hooks/zaip-subagent-lifecycle.mjs --replay-pending` recupera até três recibos completos por execução (inspeção limitada a 256 entradas). Recibos sem status ou identidade observada exigem o fallback manual idempotente. Não remova a captura manual enquanto não houver confirmação verificável. O contexto de governança do SubagentStart é preservado.
 

package/templates/.agents/zaip-aios/VERSION

@@ -1 +1 @@
-4.2
+4.3

package/templates/.agents/zaip-aios/guides/14-troubleshooting.md

@@ -11,7 +11,7 @@ Se uma Task estiver presa em executing/verifying, use o popup Reconciliar para o
 
 Se o problema for de instalacao ou integridade, consulte `framework.lock.yaml`.
 
-Se “finalizar” tentou entregar um PRD `draft`, confira adapters/skills: o correto é lapidar e mover para `ready`. Se uma DAG nova cruza SPECs, una as capacidades em uma SPEC e mantenha a dependência entre suas Tasks. PRD cancelado não reabre; crie sucessor `rework`.
+Se “finalizar o documento” tentou entregar um PRD `draft`, confira adapters/skills: criar ou lapidar mantém `draft`; somente pedido explícito promove para `ready`. Pedido de executar pode preparar e ir diretamente para execução. DAG entre SPECs deve preservar os vínculos e dependências no PreparedPlan do PRD, sem consolidar documentos silenciosamente. PRD cancelado não reabre; crie sucessor `rework`.
 
 ## Repetição, orçamento e recibos
 
@@ -32,3 +32,54 @@ A tolerância de dez minutos para Run órfã no reparo manual não é prazo de
 desistência de Task em atividade. Um timeout operacional também não comprova
 falha do produto. Veja [autonomia](19-assurance-e-autonomia.md) e
 [relay de fechamento](16-lifecycle-e-reconciliacao.md).
+
+## Hooks e retomada no Codex
+
+### Classificar antes de corrigir
+
+`Falhou` indica erro técnico do hook; `Bloqueado` indica uma decisão de política.
+Uma contagem histórica não prova regressão atual. Reproduza a operação autorizada
+com o hook ativo e compare o motivo, a sessão e o turno da nova execução.
+
+| Caso | Comportamento esperado e teste |
+| --- | --- |
+| Stop com `invalid stop hook JSON output` | A saída usa `{}` ou `decision: block` com `reason`, nunca um `hookSpecificOutput` de Stop. Testar todos os caminhos de saída, inclusive erro e continuação. |
+| Resposta útil substituída por aviso de telemetria no Stop | Pendência de transcript, contabilização, lock ou CLI fica no recibo e retorna `{}`, sem criar outro prompt. Somente estado de Task própria comprovado nesta invocação pode pedir uma continuação; `stop_hook_active` impede repetição. |
+| Transcript local `\\?\C:\...` | Normalizar o namespace local nas duas camadas de verificação. UNC de rede, devices, links e sessão divergente continuam recusados. |
+| Executor nativo bloqueado por correlação | Conferir sessão do pai + turno do filho, além da sessão nativa do filho. Registrar somente vínculo comprovado; não usar a Task global mais recente. |
+| Busca textual por `AC-...`, `Remove-Item` ou `;` | Diferenciar argumento literal de comando executável. Leituras literais não viram mutação por palavras na pesquisa; redirecionamentos e composição destrutiva continuam protegidos. |
+| Git com separadores | Um separador dentro de argumento entre aspas é texto. Separadores fora das aspas continuam exigindo chamadas Git separadas. |
+| Hook repetido em Usuário e Projeto | O instalador só retira registro global reconhecidamente ZAIP após verificar os hooks canônicos do projeto; preserva terceiros e mantém fallback quando não houver confirmação. |
+
+O vínculo local do executor é conferido contra os escopos e o estado da Task
+canônica. Ele não permite que o filho edite seus próprios bindings ou registros
+de autoridade. Patches também verificam os ancestrais físicos: junctions, links
+e hardlinks não viram uma autorização para escapar do escopo textual.
+
+A migração global publica a nova configuração sem substituir um arquivo que um
+editor tenha recriado durante a operação. Em conflito, preserva a versão do
+usuário e o backup original, informa o caminho recuperável e não declara sucesso.
+Mesmo no sucesso, o arquivo original permanece recuperável em
+`config.toml.zaip-saved-<id>` junto à configuração privada do Codex. Isso preserva
+também gravações tardias de um editor que mantinha o arquivo anterior aberto.
+Uma segunda execução sem mudanças não cria outro backup. Esses arquivos não
+devem ser publicados nem removidos automaticamente.
+
+Um Stop sem transcript deixa recibo pendente, sem inventar conclusão. Repetição da
+mesma sessão/turno pode reutilizar o caminho já recebido; outro turno não pode.
+Esse recibo não é motivo para solicitar uma nova resposta do modelo: permitir o
+encerramento da interface não significa aprovar ou concluir registros canônicos.
+Falhas permanecem explícitas e recuperáveis; não se promete execução após o Codex parar.
+Transcripts grandes avançam por cursor limitado e podem exigir mais de uma
+recuperação; acompanhe o avanço, não faça varredura global nem apague o recibo.
+
+### Recuperação segura
+
+- `Bloqueado` com caminho fora do repositório ou Git composto pode ser uma recusa de segurança correta; não é `Falhou`. Separe comandos Git e use somente os caminhos externos autorizados no helper de release.
+- Correlação ausente não autoriza escolher a última Task global. O resolvedor procura também o nome da sessão histórica do thread exato, valida seu cabeçalho/workspace e lê somente esse transcript; um chat antigo não perde identidade por ultrapassar três dias.
+- Runs históricas já gravadas com turno local não se tornam correlacionadas por inferência. Preserve-as; uma retomada com turno observado deve capturar sua identidade real antes de mutações persistentes.
+- Falha de verificação antes de Gui usa [o reparo canônico](../../skills/zaip-skill-execution/references/correction-cycle.md). A barreira de um finalizador já iniciado não pode ser reaberta.
+- EPERM transitório ao ler um lock incumbente no Windows permite no máximo três leituras dentro do deadline. EPERM persistente, EACCES, processo vivo ou contenção inválida continuam falhando fechado; nunca apague um lock vivo para obter verde.
+- Depois de atualizar os hooks, aprovar o conteúdo modificado não comprova que PreToolUse está ativo: confirme o interruptor e execute cenários reais novos. Estatísticas antigas não são apagadas nem transformadas em aprovações.
+- `doctor` acusa `.agents/local`: preserve qualquer conteúdo legado antes de migrá-lo para `.local`. Somente diretórios comprovadamente vazios podem ser removidos de forma não recursiva, com Task e turno correlacionados; não suprima o diagnóstico nem apague histórico para obter aprovação.
+- Um agente de entrega/orquestração aparece com modelo/esforço fixos em Sol mesmo após ajuste: confira a origem canônica e regenere os adaptadores. As preferências do catálogo não são travas; a seleção explícita deve seguir o ledger. O schema da sessão pode continuar carregando o perfil anterior até recarga pelo host. Não reinicie o computador, não troque identidade do agente e não declare Astra observado sem metadados reais. Testes determinísticos provam a política, mas não substituem a homologação nativa Sol/high → Sol/high → Astra/high.