@zaip-ai/cli 6.2.0 → 7.5.0

package/templates/.agents/skills/zaip-skill-worktree-recovery/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: zaip-skill-worktree-recovery
+description: Recover verified lifecycle roots and shared writers across worktrees, or preserve an eligible orphan checkout. Use for missing Run records, continuation conflicts, terminal writer ownership or failed managed worktree attachment.
+---
+
+# Recuperar worktree preservando evidências
+
+Use a [política padrão](references/default-policy.md) para seleção da árvore,
+versão única, manutenção e eventual limpeza já autorizada, sem perguntas de rotina.
+
+Quando houver Task conhecida, comece por `task workspace TASK --inspect --json`.
+O diagnóstico somente leitura distingue versão, owner ativo, claim inválida e
+checkout canônico; siga `next_action`. Ele não concede escrita nem fecha árvores.
+
+Para records gravados em worktree, `Run V2 not found`, conflito de recibo entre
+raízes ou escritor terminal com alterações, siga [recuperação de lifecycle e
+writer](references/lifecycle-roots.md). Esse fluxo preserva registros e produto;
+o procedimento de checkout órfão abaixo atende outra condição de recuperação.
+
+Antes de preparar outra árvore ou retomar execução, confira a versão ativa do
+repositório. `release_version_conflict` impede executar outra versão, incluindo
+em outro chat/worktree; planos futuros podem ficar draft. A recuperação de uma
+árvore existente preserva backup, ownership e writer lock e não libera outra
+versão. A limpeza continua restrita ao alvo inequívoco e à ferramenta oficial
+ou comando seguro já autorizado, preservando raiz e branches protegidas.
+
+Use a autorização humana vigente para recuperar o caso delimitado. Para defeito
+comprovado do framework sem recuperação normal, aplique `RULE-FRAMEWORK-MAINTENANCE`
+e a skill oficial: caso elegível coberto dispensa nova confirmação, exige saída
+antes de retomar a entrega e não resolve ownership por si só. Uma falha de ownership não autoriza editar bancos,
+marcadores do aplicativo, claims, recibos antigos ou remover registros Git.
+
+1. Registre uma vez a raiz, SHA, operação e thread observadas, erro nativo e o
+   pedido humano integral. Consulte os artefatos do aplicativo. Se já existe
+   vínculo, prefira seu arquivamento oficial com snapshot. Se a criação falhou,
+   tente a anexação oficial uma vez por mudança concreta de estado. Não repita
+   a mesma falha, nem crie outro worktree para escapar dela.
+2. Sem recuperação nativa, siga [o procedimento](references/procedure.md).
+   `inspect` verifica checkout secundário registrado, detached, ancestral do
+   candidato, sem alterações, ignorados, links, submódulos ou flags que escondam
+   mudanças. Falha ou timeout interrompe: não altere arquivos para obter aceite.
+3. Com autorização de preservação, `preserve` cria um bundle completo, restaura
+   seus objetos numa área temporária e emite recibo somente após verificar a
+   árvore. O checkout fica intacto, registrado e com propriedade ainda não
+   recuperada. O estado é `preserved-not-attached`, nunca “arquivado”.
+4. `verify` revalida o checkout e o backup antes de cada uso. A recuperação só
+   permite considerar aquele checkout limpo como preservado. Não autoriza
+   trabalho nele, publicação, coleta fictícia, exclusão ou reaproveitamento de
+   uma qualificação vinculada a outro SHA.
+5. No builder, o publicador local e o avanço aceitam o recibo explícito por
+   `--worktree-recovery`. Demais worktrees e todos os outros gates continuam
+   bloqueantes. Consumidores usam apenas inspeção/preservação, sem presumir que
+   seu pipeline suporta esse recibo.
+6. Depois, se o aplicativo reconhecer o vínculo, arquive pela ferramenta
+   oficial. Preserve o bundle e o recibo. Enquanto isso, não remova o checkout,
+   não declare limpeza total e não prometa que a falha do aplicativo nunca
+   ocorrerá. Sem novo estado/evidência, pare com uma condição de retomada.
+
+Automação significa executar esse fluxo finito sob autorização existente, não
+aprovar automaticamente casos ambíguos. Alterações de produto, staged, exclusões
+ou ignorados desconhecidos continuam recusadas. Se um checkout já preservado
+recebeu somente registros de lifecycle/telemetria e spool local, siga a modalidade
+restrita [de preservação de metadata](references/metadata-overlay.md). Ela exige
+inventário exato revisado e novo recibo, mantém o antigo e não recupera ownership.
+
+Se o backup histórico não estiver disponível, não fabrique base clean ou recibo.
+A modalidade [completa autossuficiente](references/complete-preservation.md)
+preserva HEAD mais metadata atuais com inventário revisado e restauração própria.
+Exige marker de retenção existente intacto, registra seu hash e mantém explícita
+a limitação de prova histórica inválida no dashboard; não recupera ownership.

package/templates/.agents/skills/zaip-skill-worktree-recovery/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Recuperar worktree e lifecycle"
+  short_description: "Recupera records e writer preservando o histórico"
+  default_prompt: "Use $zaip-skill-worktree-recovery para recuperar um worktree preservando suas evidencias."

package/templates/.agents/skills/zaip-skill-worktree-recovery/references/complete-preservation.md

@@ -0,0 +1,70 @@
+# Preservação completa sem backup histórico disponível
+
+Use somente com autorização delimitada para um secundário já retido, registrado,
+detached e ancestral do candidato atual. Esta modalidade cria prova nova de HEAD
+e metadata atuais; não reconstrói recibos antigos nem comprova ownership do app.
+Não repita attachment já falho sem mudança concreta de estado.
+
+Primeiro coordene todos os escritores e a coleta já em voo. O marker v1 existente
+deve continuar físico, estável e com identidade root/worktree/SHA correspondente.
+Seu recibo histórico pode estar ausente. O dashboard já exclui da coleta tanto
+retenção válida quanto inválida: manter esse marker conserva proteção negativa,
+mas o dashboard continuará reportando `invalid` se a prova histórica faltar.
+O novo recibo registra o hash do marker intacto; não o edita, substitui ou apaga.
+
+1. Gere e revise o inventário completo com a API `completeInventory(root,
+   worktree, preservedSha)` ou com o comando somente leitura:
+
+   ```text
+   node .agents/skills/zaip-skill-worktree-recovery/scripts/recovery.mjs inventory-complete --repository ROOT --worktree CHECKOUT --sha PRESERVED_SHA
+   ```
+
+   Salve a saída JSON para revisão em arquivo físico, fora do secundário. Confira
+   cada path, status, tamanho e hash. O index deve equivaler a HEAD sem staged;
+   seu hash também fica vinculado ao inventário. Produto, exclusões, conflitos,
+   flags ocultas, links/hardlinks e ignorados desconhecidos são recusados.
+
+2. Com autorização vigente, use diretório novo e exclusivo sob pai físico:
+
+   ```text
+   node .agents/skills/zaip-skill-worktree-recovery/scripts/recovery.mjs preserve-complete --repository ROOT --worktree CHECKOUT --sha PRESERVED_SHA --manifest REVIEWED_JSON --provider codex --thread-id OBSERVED_THREAD_UUID --run-id OBSERVED_CURRENT_RUN_ID --request-file HUMAN_REQUEST_UTF8 --output NEW_DIRECTORY
+   ```
+
+   UUID e Run são observações da operação atual, fornecidas pelo host; não use
+   IDs sintéticos, operação histórica presumida ou UUID do pai como se fosse o
+   filho. Não existe `operation-id` obrigatório nesta modalidade. Proveniência
+   declarada não concede ownership. O pedido humano integral fica local.
+
+3. O helper reinspeciona o inventário, copia metadata, cria bundle completo de
+   HEAD, confere conectividade e restaura árvore mais overlay em área independente.
+   Hashes e estado são revalidados antes de emitir
+   `zaip-preserved-worktree-complete-v1`. Não depende de recibo/bundle anterior.
+   Destino existente, inclusive parcial, falha fechado e permanece preservado;
+   não há replay de escrita nem limpeza automática do backup.
+
+4. Verifique antes de cada uso pelo comando existente:
+
+   ```text
+   node .agents/skills/zaip-skill-worktree-recovery/scripts/recovery.mjs verify --repository ROOT --receipt NEW_DIRECTORY/receipt.json --sha CURRENT_CANDIDATE_SHA
+   ```
+
+   A restauração independente ocorre uma vez na criação. O verificador confere
+   sua vinculação a tree, bundle e inventário; revalida hashes antes/depois,
+   bundle verify/list-heads, index, conjunto completo de metadata, marker intacto
+   e ancestralidade sem repetir checkout do histórico. Drift bloqueia; nunca
+   atualize manifesto ou marker silenciosamente. Os gates existentes aceitam o
+   novo tipo por `verifyRecovery`, mantendo o requisito de único secundário.
+
+As duas modalidades de metadata compartilham allowlist estrita: records de
+lifecycle/runs/telemetria nos formatos existentes e somente spool/cursor/writer-id
+nos spellings `.local/...` ou `.agents/private/state/...` das mesmas famílias.
+Spool novo pode ser untracked ou ignored; staged e paths private genéricos não
+são aceitos. A migração de armazenamento não cria autorização de prefixo.
+Limites continuam 2.048 arquivos, 16 MiB por metadata e 128 MiB total. Packs Git
+são lidos por streaming e comandos Git têm prazo; não aplique limite de metadata
+ao bundle completo. Conteúdo com credenciais aparentes é recusado sem ecoar bytes.
+
+Resultado: `preserved-not-attached`. O secundário, seu index, cadastro e marker
+continuam intactos. Nenhuma permissão para exclusão, publicação, qualificação
+fictícia, edição de claims ou correção manual de ownership é concedida. Recibos,
+spool e bundles são privados e não entram em assets públicos ou pacote npm.

package/templates/.agents/skills/zaip-skill-worktree-recovery/references/default-policy.md

@@ -0,0 +1,53 @@
+# Política padrão: versões e recuperação
+
+Uma versão em implementação por repositório Git. Planejamento futuro pode ficar
+draft; a mensagem de conflito informa a versão atual e exige publicar/encerrar
+esse ciclo antes de iniciar outra. Abrir outro chat ou worktree não remove o gate.
+Não altere `target_release`, grants, locks ou estado do ciclo para contorná-lo.
+
+`task workspace TASK --inspect --json` não requer nova claim. `other_owner_active`
+exige aguardar/coordenação; `same_task_owner_active` exige reutilizar o responsável
+exato; `terminal_owner` permite solicitar transferência pelo comando canônico,
+que ainda verifica diff e descendentes. `shared_claim_invalid`,
+`isolated_claim_conflict` e `owner_unavailable` exigem preservar e diagnosticar,
+não apagar registros. `canonical_checkout_required` informa a raiz correta.
+Em `release_version_conflict`, mantenha o trabalho futuro em draft até fechar a
+versão atual; este diagnóstico não autoriza publicar.
+
+Falha de correlação nativa: use `subagent inspect-local` com o UUID próprio do
+filho observado no host, o Run pai exato e, se necessário, o turno observado.
+Não passe o UUID do principal como se fosse o filho. Quando o host só expõe
+agent_path/estado terminal, use o fallback canônico elegível; ele não prova
+modelo, sessão nem concede writer antecipado. Limitação privada do aplicativo
+permanece explícita. Manutenção segue a autorização e a skill existentes.
+
+Prefira o checkout adequado já existente. Não pergunte por rotina se deve criar
+worktree. Quando a estratégia autorizada exigir isolamento na mesma versão,
+use a ferramenta oficial e atribua escopos disjuntos; o diretório isolado não
+isola sozinho hooks, claims, registros ou o contexto do host. Confirme a raiz
+operacional efetiva antes da primeira escrita. Um contexto de hook incorreto
+exige recuperação real, não variáveis que alegam outro owner.
+
+| Situação observada | Ação padrão | Condição de parada |
+| --- | --- | --- |
+| Outra versão ativa | Recusar cedo com versão atual e próximo passo; permitir planejamento | Não iniciar build, Run ou nova árvore da próxima versão |
+| Checkout adequado e writer livre | Reutilizar com o escopo autorizado | Ownership ou claim conflitante |
+| Criação nativa falhou, checkout existe | Consultar status/artefatos; anexar uma vez com o caminho retornado | Mesma falha sem mudança de estado |
+| Árvore reconhecida, trabalho concluído | Preservar ignorados necessários e arquivar pelo aplicativo com snapshot | Conteúdo necessário sem preservação |
+| Ownership não recuperável | `inspect`, `preserve`, `verify` conforme contrato existente | Árvore suja/desconhecida ou backup não verificável |
+| Defeito no framework impede recuperação | Manutenção oficial quando a autorização vigente inclui esse reparo; corrigir, testar e sair | Falta de escopo, credencial ou informação realmente necessária |
+
+Limpeza de branches é uma operação separada e só ocorre se necessária e coberta
+pela autorização existente para o alvo. Comprove raiz física, branch exata,
+writer ausente, backup verificável, ausência em outros worktrees e ancestralidade
+já integrada. Preserve branch principal/protegida. Prefira arquivamento oficial;
+remoção Git explicitamente autorizada usa operações não forçadas e caminhos
+literais verificados. Não use `reset --hard`, `clean -fd`, `branch -D`, remoção
+recursiva calculada ou edição do banco de ownership como recuperação padrão.
+Sem prova suficiente, mantenha o material e explique o bloqueio concreto.
+
+Reutilize autorização vigente; não peça “continuar” nem outra confirmação apenas
+porque a etapa mudou. Uma ferramenta do host que exige ação humana real continua
+sendo um limite externo. Não declare que corrigiu ownership sem confirmação do
+aplicativo. Preserve log, SHA e motivo de cada tentativa; repita somente quando
+uma nova evidência justifica a tentativa.

package/templates/.agents/skills/zaip-skill-worktree-recovery/references/lifecycle-roots.md

@@ -0,0 +1,106 @@
+# Raízes de lifecycle, retomada e escritor compartilhado
+
+Use para recuperar a mesma entrega autorizada quando o Codex está vinculado a
+uma worktree e a edição ocorre na principal, ou quando uma reserva terminal
+impede adquirir o checkout com alterações preservadas. Anexação do aplicativo,
+origem dos records e diretório de edição são vínculos distintos.
+
+## Selecionar a origem comprovada
+
+Registre Task, Change, Execution, Run, sessão/turno observados e as raízes físicas
+indicadas pelo diagnóstico. Use manifestos e IDs exatos; não procure a última
+Task global. Confira worktree registrada no mesmo repositório Git, perfil/modelo
+congelados e ausência de dono ou descendente concorrente.
+
+Novas capturas usam a resolução canônica normal antes da materialização. Para
+records legados existentes em uma worktree, a CLI oferece `--lifecycle-root`.
+Essa opção seleciona o armazenamento original; `--workspace` seleciona a edição.
+Execute no checkout principal, mantendo a identidade nativa real do host.
+
+Todos os identificadores e caminhos abaixo são marcadores a substituir pelos
+valores observados, e os caminhos de raiz devem ser absolutos. Use a CLI instalada:
+
+```text
+node .agents/runtime/bin/zaip.mjs task workspace TASK --run RUN --lifecycle-root RAIZ_ORIGINAL --workspace RAIZ_PRINCIPAL --json
+```
+
+A admissão autenticada vincula os seletores à origem durável. Comandos seguintes
+consultam essa fonte, mesmo após transferência do writer. Não copie records,
+claims ou recibos para a principal. Cópia divergente, origem de outro repositório,
+metadados ausentes ou perfil incompatível exigem resolver o diagnóstico; o
+conteúdo de um JSON local não constitui autorização.
+
+## Escolher a retomada pelo estado real
+
+Reutilize a autorização humana vigente que cubra a operação. O argumento
+`--direct-authorization` referencia o pedido efetivamente observado; não invente
+um novo pedido nem use texto de documentação como consentimento.
+
+**Mesma Run ainda ativa, novo turno nativo.** Use a ponte oficial do principal,
+com o turno predecessor observado. Ela não cria tentativa nem reescreve a Run:
+
+```text
+node .agents/runtime/bin/zaip.mjs run continue-principal RUN --task TASK --task-owner RUN --execution EXECUTION --from-turn TURNO_ANTERIOR --run RUN --lifecycle-root RAIZ_ORIGINAL --json
+```
+
+Essa recuperação exige a mesma sessão, Task/Execution, modelo/esforço compatíveis
+e writer comprovado na principal. `run continue` não é um comando válido. Para
+subagentes, use o fluxo próprio de continuação nativa documentado na skill de
+execução; não reutilize o principal nem invente ancestralidade.
+
+**Task blocked com Run encerrada.** Em novo turno autenticado, crie a sucessora
+da mesma entrega. Não passe `--run` com o ID terminal à captura:
+
+```text
+node .agents/runtime/bin/zaip.mjs conversation start --intent continue --task TASK --lifecycle-root RAIZ_ORIGINAL --direct-authorization "PEDIDO_HUMANO_OBSERVADO" --json
+```
+
+**Task failed.** Primeiro solicite o rework oficial da tentativa falhada, depois
+capture a nova Run. Não altere manualmente status, contador ou plano:
+
+```text
+node .agents/runtime/bin/zaip.mjs task rework TASK --run RUN_FALHADA --lifecycle-root RAIZ_ORIGINAL --direct-authorization "PEDIDO_HUMANO_OBSERVADO" --json
+node .agents/runtime/bin/zaip.mjs conversation start --intent continue --task TASK --work-type rework --lifecycle-root RAIZ_ORIGINAL --direct-authorization "PEDIDO_HUMANO_OBSERVADO" --json
+```
+
+Após uma captura bem-sucedida, use o ID novo retornado em `task workspace` e nos
+comandos seguintes. Os bytes da Run terminal permanecem imutáveis. Completed ou
+cancelled não se tornam execução ativa pela simples troca de flags.
+
+Rework interrompido usa journal e compara a transição exata dos três records,
+predecessor e origem nativa. Repita somente a mesma operação autenticada depois
+de identificar a interrupção; uma retomada válida não incrementa duas vezes.
+Drift ou journal inválido bloqueia sem apagar histórico, fabricar recibos ou
+escolher uma cópia conveniente dos registros.
+
+## Dono terminal com alterações no checkout
+
+No checkout compartilhado já resolvido, preserve primeiro a baseline exata.
+Esses comandos são etapas separadas: o primeiro não transfere a reserva.
+
+```text
+node .agents/runtime/bin/zaip.mjs task workspace TASK --run RUN --preserve-owner RUN_DONO_ANTERIOR --json
+node .agents/runtime/bin/zaip.mjs task workspace TASK --run RUN --recover-snapshot SHA256_RETORNADO --json
+```
+
+Entre as etapas não altere HEAD, refs, índice ou arquivos. A segunda verifica o
+snapshot e compara a reserva antes da transferência. Preserve o snapshot, sua
+baseline e autoria anterior; a transferência não atribui alterações antigas à
+nova Task. Dono/filho ativo, links, credenciais, conflito Git ou mudança concorrente
+continuam impedindo a recuperação.
+
+Restore de verificação ocorre apenas em diretório novo e isolado: compare bundle,
+índice bruto e split index, staged/unstaged, renomeações, modos e exclusões com o
+manifesto. Isso não restaura ownership automaticamente. Não execute reset,
+remoção da worktree ou staging amplo para obter aceite.
+
+## Verificar o resultado
+
+Confirme que captura, workspace/claim, leitura de Run/Execution, validação e
+fechamento encontram os mesmos registros. Registre origem, edição, IDs e resultado
+sanitizados. Testes locais de interrupção/concorrência não provam eventos nativos
+de outro host. Uma limitação real de metadados deve identificar a capacidade
+ausente e a recuperação suportada; não desligue governança ou atribua sucesso.
+
+Recuperar lifecycle e writer não concede push, deploy, SQL ou acesso a provedores.
+Publicação continua vinculada à autorização, candidato e destino exatos.

package/templates/.agents/skills/zaip-skill-worktree-recovery/references/metadata-overlay.md

@@ -0,0 +1,45 @@
+# Preservar metadata posterior ao backup
+
+Esta modalidade cobre somente um secundário que já tem recibo clean-v1 e bundle
+íntegros, HEAD detached ancestral e index byte a byte igual ao preservado. Não
+serve para aceitar produto modificado, staged, exclusões, conflitos, links,
+hardlinks ou arquivos ignorados desconhecidos. `diagnose` é somente leitura;
+não é recibo nem aprovação.
+
+1. Preserve o pedido humano e a falha de attachment observada. Use a Task e o
+   escopo autorizados. Não repita attachment sem mudança concreta de estado.
+2. Encerre o dashboard pelo launcher oficial e confirme que sua coleta terminou
+   antes de preservar. Outros escritores precisam de coordenação equivalente.
+   O marcador não interrompe uma coleta que já estava em voo.
+   Gere o inventário com `metadataInventory(root, baseReceipt, candidateSha)` do
+   helper `scripts/metadata-overlay.mjs`. Revise a lista completa de paths,
+   status, tamanhos e hashes. O conjunto cobre todo delta tracked/untracked e
+   ignored; a seleção aceita somente records de lifecycle/runs/telemetria e os
+   formatos delimitados do spool/cursor local. Limites: 2.048 arquivos, 16 MiB
+   por arquivo e 128 MiB no total. Não aumente limites para contornar um caso.
+3. Sob a autorização vigente, execute:
+
+   ```text
+   node .agents/skills/zaip-skill-worktree-recovery/scripts/recovery.mjs preserve-metadata --repository ROOT --base-receipt OLD_RECEIPT --manifest REVIEWED_INVENTORY --request-file HUMAN_REQUEST --output NEW_DIRECTORY
+   ```
+
+   O helper autentica o backup anterior e reinspeciona o worktree, copia bytes
+   para destino exclusivo, restaura base+overlay em área nova e compara hashes.
+   Revalida o inventário antes de emitir `zaip-preserved-metadata-overlay-v1`.
+   Não altera o original, seu index, ownership, registro Git ou recibo antigo.
+   Após validar, emite marcador local de retenção no checkout principal. O
+   dashboard mantém a fonte no read-model e suspende apenas sua coleta automática,
+   expondo `retained_worktrees` e cobertura parcial; o primário continua elegível.
+   Marcador/recibo inválido impede escrita no secundário com diagnóstico.
+4. Use o novo recibo explícito em `--worktree-recovery`. O verificador confere
+   novamente o conjunto completo, cada hash e o backup anterior. Drift é bloqueio,
+   não retry automático, atualização silenciosa do manifesto ou autorização para
+   apagar arquivos. Identifique e coordene escritores pelo caminho oficial.
+5. Recibo e bytes ficam locais: não inclua spool bruto nos assets públicos,
+   pacote npm ou evidências sanitizadas. Retenção não transforma esses bytes em
+   eventos confiáveis nem os importa para a execução atual. Preserve o bundle
+   anterior junto do novo backup, pois a restauração depende dos dois.
+
+O resultado continua `preserved-not-attached`. Arquivamento futuro é exclusivo
+da ferramenta oficial quando ela reconhecer o vínculo. As provas não garantem
+ausência de futuras escritas; cada uso bloqueia se o estado observado mudar.

package/templates/.agents/skills/zaip-skill-worktree-recovery/references/procedure.md

@@ -0,0 +1,49 @@
+# Procedimento e critérios de aceite
+
+Use os valores reais observados. O pedido UTF-8 contém a autorização humana
+integral, sem credenciais. IDs documentam proveniência observada; não são prova
+de ownership do aplicativo. A prova do helper é a preservação material no Git.
+
+```text
+node .agents/skills/zaip-skill-worktree-recovery/scripts/recovery.mjs inspect --repository ROOT --worktree CHECKOUT --sha PRESERVED_SHA
+node .agents/skills/zaip-skill-worktree-recovery/scripts/recovery.mjs preserve --repository ROOT --worktree CHECKOUT --sha PRESERVED_SHA --provider codex --operation-id OPERATION_UUID --thread-id THREAD_UUID --request-file REQUEST_FILE --output NEW_BACKUP_DIRECTORY
+node .agents/skills/zaip-skill-worktree-recovery/scripts/recovery.mjs verify --repository ROOT --receipt NEW_BACKUP_DIRECTORY/receipt.json --sha CURRENT_CANDIDATE_SHA
+```
+
+O pai do diretório de backup deve existir e ser físico; não use o worktree
+preservado nem seu diretório Git como destino. A pasta nova é exclusiva. Replay
+idêntico revalida sem criar outro bundle; divergência/interrupção preserva a pasta
+parcial e bloqueia. Investigue a causa antes de escolher outra pasta de tentativa.
+Nunca apague o resultado parcial apenas para repetir.
+
+Se já houver um bundle completo do mesmo HEAD, acrescente
+`--source-bundle EXISTING_BUNDLE` a `preserve`: ele verifica identidade, copia sem
+sobrescrever e confere os bytes, evitando recompressão do histórico. A restauração
+continua obrigatória. Cada processo Git tem prazo e limite de saída; timeout tenta
+encerrar somente sua árvore de processos e bloqueia sem recibo bem-sucedido.
+Encerramento de descendentes não confirmado exige investigação, nunca retry cego.
+
+Aceite exige: bundle íntegro e restaurável; HEAD/tree preservados; nenhum arquivo
+de produto alterado; checkout ainda limpo; commit preservado ancestral do candidato;
+receipt correspondente à raiz física e ao único worktree adicional. A verificação
+é repetida no gate, pois um recibo não impede um processo externo de escrever.
+Bloqueios Git conhecidos impedem a prova; não se afirma ausência universal de
+processos concorrentes. Coordene escritores antes de preservar/publicar.
+
+No builder `local_catalog`, passe o mesmo `--worktree-recovery RECEIPT` ao
+`scripts/local-catalog-publication.mjs publish` e ao
+`scripts/release-cycle-gate.mjs advance`, e mantenha-o no posterior
+`scripts/local-catalog-closure.mjs push`. Nenhuma variável de ambiente dispensa
+o gate. Sem o argumento, vale o requisito normal de fechamento dos secundários.
+Recibo de preservação não é recibo assinado de qualificação: mantenha ambos.
+
+Valide cenários focados: replay idempotente; árvore restaurada; mudanças tracked,
+untracked e ignored; flags de índice; SHA divergente; checkout principal/externo;
+bundle ou recibo alterado; destino existente/inseguro; outro worktree adicional;
+revalidação após alteração. Não execute catálogo de release para diagnosticar
+ownership. Alteração no candidato exige a política de qualificação vigente.
+
+Reversão operacional: pare de fornecer o recibo; o gate volta a exigir fechamento.
+Nenhum arquivo original precisa ser restaurado, pois não foi removido. O bundle
+continua disponível para recuperação Git revisada. Não edite ownership para
+conseguir arquivar e não use limpeza manual como “fallback automático”.

package/templates/.agents/skills/zaip-skill-worktree-recovery/scripts/complete-preservation.mjs

@@ -0,0 +1,252 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, mkdtemp, open, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { query } from "./git-process.mjs";
+import { metadataFiles, stableBytes } from "./metadata-overlay.mjs";
+import { digest, inside, inspectState, physical, readJson } from "./worktree-proof.mjs";
+
+export const completeKind = "zaip-preserved-worktree-complete-v1";
+const inventoryKind = "zaip-complete-preservation-inventory-v1";
+const action = "preserve-current-head-and-metadata";
+
+// Stream history packs: metadata's 16 MiB limit must not truncate a complete Git bundle.
+async function bundleDigest(directory) {
+  const path = await physical(join(directory, "candidate.bundle"), false);
+  const before = await lstat(path, { bigint: true });
+  assert(before.nlink === 1n, "Linked complete bundle");
+  const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const opened = await handle.stat({ bigint: true });
+    assert(opened.isFile() && opened.nlink === 1n, "Invalid complete bundle");
+    assert(process.platform === "win32" || opened.dev === before.dev, "Bundle volume changed");
+    const hash = createHash("sha256");
+    for await (const chunk of handle.createReadStream({ autoClose: false })) hash.update(chunk);
+    await physical(path, false);
+    const named = await lstat(path, { bigint: true });
+    const after = await handle.stat({ bigint: true });
+    assert(named.dev === before.dev && after.dev === opened.dev, "Bundle volume changed");
+    for (const row of [before, named, after])
+      for (const key of ["ino", "size", "nlink", "mtimeNs", "ctimeNs"])
+        assert(row[key] === opened[key], "Bundle changed while hashing");
+    return hash.digest("hex");
+  } finally {
+    await handle.close();
+  }
+}
+
+async function markerIdentity(state) {
+  const path = `.agents/private/state/worktree-preservation/v1/${digest(Buffer.from(state.worktree))}.json`;
+  const bytes = await stableBytes(state.root, path);
+  assert(bytes.length <= 16384, "Retention marker exceeds bound");
+  const marker = JSON.parse(bytes.toString("utf8"));
+  assert(
+    marker.kind === "zaip-retained-worktree-capture-v1" &&
+      marker.root === state.root &&
+      marker.worktree === state.worktree &&
+      marker.sha === state.sha &&
+      typeof marker.receipt === "string" &&
+      /^[a-f0-9]{64}$/.test(marker.receipt_sha256),
+    "Existing retention marker identity differs",
+  );
+  // Its old receipt may be unavailable. This proves only unchanged negative capture protection.
+  return { path, sha256: digest(bytes) };
+}
+
+/** Read-only, requires an already retained detached ancestor; never creates a receipt or marker. */
+export async function completeInventory(rootPath, worktreePath, sha) {
+  const state = await inspectState(rootPath, worktreePath, sha);
+  await query(state.worktree, ["diff-index", "--cached", "--quiet", sha, "--"]);
+  const marker = await markerIdentity(state);
+  const files = await metadataFiles(state);
+  assert.deepEqual(
+    await inspectState(state.root, state.worktree, sha),
+    state,
+    "Worktree changed during complete inventory",
+  );
+  assert.deepEqual(await markerIdentity(state), marker, "Retention marker changed");
+  const { status, ignored, ...identity } = state;
+  return { kind: inventoryKind, ...identity, marker, files };
+}
+
+function safeDestination(inventory, directory) {
+  for (const source of [inventory.worktree, inventory.common])
+    assert(
+      directory !== source && !inside(source, directory),
+      "Unsafe complete backup destination",
+    );
+}
+
+function provenance(value) {
+  assert(
+    value?.provider === "codex" &&
+      /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(value.thread_id ?? "") &&
+      /^RUN-\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-[A-Z0-9-]+$/.test(value.run_id ?? ""),
+    "Observed current thread and Run provenance required; no app ownership is claimed",
+  );
+}
+
+async function storedFiles(directory, inventory) {
+  for (const item of inventory.files) {
+    const bytes = await stableBytes(directory, `overlay/${item.path}`);
+    assert(
+      bytes.length === item.bytes && digest(bytes) === item.sha256,
+      "Complete backup metadata bytes changed",
+    );
+  }
+}
+
+async function verifyBundle(directory, inventory) {
+  const bundle = await physical(join(directory, "candidate.bundle"), false);
+  await query(inventory.root, ["bundle", "verify", bundle]);
+  assert(
+    (await query(inventory.root, ["bundle", "list-heads", bundle]))
+      .split(/\r?\n/)
+      .includes(`${inventory.sha} HEAD`),
+    "Complete bundle does not preserve exact HEAD",
+  );
+  return bundle;
+}
+
+async function restore(directory, inventory) {
+  const bundle = await verifyBundle(directory, inventory);
+  const probe = await mkdtemp(join(tmpdir(), "zaip-complete-restore-"));
+  try {
+    await query(probe, ["clone", "--quiet", "--no-checkout", bundle, "."], 120000);
+    await query(probe, ["checkout", "--quiet", "--detach", inventory.sha], 120000);
+    assert(
+      (await query(probe, ["rev-parse", "HEAD^{tree}"])) === inventory.tree,
+      "Complete restored tree differs",
+    );
+    await query(probe, ["fsck", "--connectivity-only", "--no-reflogs", "--no-dangling"], 120000);
+    for (const item of inventory.files) {
+      const bytes = await stableBytes(directory, `overlay/${item.path}`);
+      const target = join(probe, item.path);
+      await mkdir(dirname(target), { recursive: true });
+      await physical(dirname(target));
+      await writeFile(target, bytes);
+      const restored = await stableBytes(probe, item.path);
+      assert(
+        restored.length === item.bytes && digest(restored) === item.sha256,
+        "Complete restored metadata differs",
+      );
+    }
+  } finally {
+    assert(dirname(probe) === resolve(tmpdir()) && (await physical(probe)) === probe);
+    await rm(probe, { recursive: true });
+  }
+}
+
+/** Recheck exact restored bytes without repeating the creation-time checkout of history. */
+export async function verifyComplete(root, receiptPath, candidateSha) {
+  const file = await physical(receiptPath, false);
+  const receiptBytes = await stableBytes(dirname(file), basename(file));
+  assert(receiptBytes.length <= 1024 * 1024, "Complete receipt exceeds bound");
+  const receipt = JSON.parse(receiptBytes.toString("utf8"));
+  assert(
+    receipt.kind === completeKind &&
+      receipt.state === "preserved-not-attached" &&
+      receipt.authorization?.action === action &&
+      typeof receipt.authorization.request === "string" &&
+      receipt.authorization.request.trim().length >= 20 &&
+      digest(Buffer.from(receipt.authorization.request)) === receipt.authorization.sha256 &&
+      receipt.restore_verification === "complete-bundle-and-metadata-restore-v1",
+    "Invalid complete preservation authority or restoration proof",
+  );
+  provenance(receipt.provenance);
+  assert((await query(root, ["rev-parse", "HEAD"])) === candidateSha, "Publication HEAD changed");
+  const inventory = receipt.inventory;
+  assert(inventory?.kind === inventoryKind, "Invalid complete inventory kind");
+  assert(
+    receipt.restored_tree === inventory.tree &&
+      receipt.restored_bundle_sha256 === receipt.bundle_sha256 &&
+      receipt.restored_inventory_sha256 === digest(Buffer.from(JSON.stringify(inventory))),
+    "Complete restoration binding differs",
+  );
+  const current = await completeInventory(root, inventory.worktree, inventory.sha);
+  assert.deepEqual(current, inventory, "Live complete preservation inventory drift");
+  const directory = dirname(file);
+  safeDestination(current, directory);
+  assert(
+    (await bundleDigest(directory)) === receipt.bundle_sha256,
+    "Complete preservation bundle changed",
+  );
+  await storedFiles(directory, current);
+  await verifyBundle(directory, current);
+  assert.deepEqual(
+    await completeInventory(root, inventory.worktree, inventory.sha),
+    current,
+    "Worktree changed during complete verification",
+  );
+  assert((await bundleDigest(directory)) === receipt.bundle_sha256);
+  await storedFiles(directory, current);
+  assert.deepEqual(
+    await stableBytes(dirname(file), basename(file)),
+    receiptBytes,
+    "Receipt changed",
+  );
+  return {
+    state: receipt.state,
+    worktree: current.worktree,
+    sha: current.sha,
+    receipt_sha256: digest(receiptBytes),
+    retained_metadata_files: current.files.length,
+  };
+}
+
+export async function preserveComplete(input) {
+  const observed = { provider: input.provider, thread_id: input.threadId, run_id: input.runId };
+  provenance(observed);
+  const reviewed = await readJson(input.manifest);
+  const before = await completeInventory(input.root, input.worktree, input.sha);
+  assert.deepEqual(before, reviewed, "Reviewed complete inventory differs");
+  const request = await readFile(await physical(input.requestFile, false), "utf8");
+  assert(request.trim().length >= 20, "Explicit human preservation request required");
+  const directory = resolve(input.output);
+  safeDestination(before, directory);
+  await physical(dirname(directory));
+  // Exclusive creation: interrupted output remains for diagnosis, never overwritten or removed.
+  await mkdir(directory);
+  await physical(directory);
+  for (const item of before.files) {
+    const bytes = await stableBytes(before.worktree, item.path);
+    assert(
+      bytes.length === item.bytes && digest(bytes) === item.sha256,
+      "Metadata changed before copy",
+    );
+    const target = join(directory, "overlay", item.path);
+    await mkdir(dirname(target), { recursive: true });
+    await physical(dirname(target));
+    await writeFile(target, bytes, { flag: "wx", mode: 0o600 });
+  }
+  const bundle = join(directory, "candidate.bundle");
+  await query(before.worktree, ["bundle", "create", bundle, "HEAD"], 120000);
+  const bundleSha256 = await bundleDigest(directory);
+  await storedFiles(directory, before);
+  await restore(directory, before);
+  assert.deepEqual(
+    await completeInventory(input.root, input.worktree, input.sha),
+    before,
+    "Worktree changed during complete preservation",
+  );
+  assert((await bundleDigest(directory)) === bundleSha256);
+  await storedFiles(directory, before);
+  const receipt = {
+    kind: completeKind,
+    state: "preserved-not-attached",
+    inventory: before,
+    provenance: observed,
+    authorization: { action, request, sha256: digest(Buffer.from(request)) },
+    bundle_sha256: bundleSha256,
+    restore_verification: "complete-bundle-and-metadata-restore-v1",
+    restored_tree: before.tree,
+    restored_bundle_sha256: bundleSha256,
+    restored_inventory_sha256: digest(Buffer.from(JSON.stringify(before))),
+    created_at: new Date().toISOString(),
+  };
+  const file = join(directory, "receipt.json");
+  await writeFile(file, `${JSON.stringify(receipt, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+  return verifyComplete(input.root, file, await query(before.root, ["rev-parse", "HEAD"]));
+}