@zaip-ai/cli 6.2.0 → 7.5.0

package/templates/.agents/skills/zaip-skill-lifecycle-closure/references/empty-usage-lock.md

@@ -0,0 +1,56 @@
+# Empty usage-attribution lock recovery (Windows)
+
+Use only for `.agents/records/runs/.usage-attribution.lock` in the explicitly
+authorized workspace. Preserve the current delivery, candidate, evidence and
+observed native identities. This procedure does not approve publication or close
+Tasks. Other layouts, nonempty malformed files and unsupported platforms remain
+blocked.
+
+The attribution protocol enters its critical section only after a complete lock
+publication. Its writers do not truncate an acquired lock. Historical exclusive
+writes could expose an empty file before writing completed. New main and recovery
+locks publish the fully flushed payload atomically and exclusively. Do not claim
+that this mechanism proves the cause of every empty file.
+
+Before recovery, inventory known writers and coordinate them; use official
+maintenance with tracking enabled and preserve pending hook observations. If an
+external writer or evidence of truncation of an already acquired lock is present,
+stop and isolate that writer first. A handle lock does not prove that a process
+with a previously closed handle has left its critical section. Never accept an
+unknown protocol as the attribution protocol.
+
+The directory fence prevents rename/delete replacement. Win32 rename requires
+write sharing on those directory handles; it does not establish protection from
+a hostile writer changing reparse metadata in place. This is a coordinated local
+maintenance procedure, not recovery on an adversarial filesystem. Evidence of
+such a writer, an untrusted parent, or an unexplained path change blocks recovery.
+
+1. Enter authorized maintenance through `zaip-skill-maintenance-enter`.
+2. Preview with `node .agents/skills/zaip-skill-lifecycle-closure/scripts/recover-empty-usage-lock.mjs`.
+   This reads only: native exclusive access must succeed; the target must be the
+   physical regular zero-byte file with a single link. Reparse paths, an open
+   writer/reader handle or inconclusive metadata refuse recovery.
+3. After reviewing the preview and writer inventory, choose one fresh UUID and run
+   the same command with `--apply --receipt-id UUID`. Reuse that UUID after an
+   interruption; do not create a new attempt to evade a rejected receipt.
+4. Verify `.agents/private/state/usage-lock-recovery/UUID.intent.json` and `UUID.result.json`.
+   The intent is durable before mutation. The native helper holds the original
+   handle with share mode zero while revalidating file identity and renaming to
+   `.usage-attribution.lock.quarantine-UUID` without replacement. It verifies the
+   same identity afterwards. The preserved empty file remains beside the original.
+   All ancestor directory handles remain open without delete sharing, preventing
+   concurrent directory renames or replacement until verification completes.
+   Receipts publish complete flushed contents exclusively. An interrupted staging
+   file is retained; replay accepts a second hard link only when it is the exact
+   publisher staging identity beside that receipt, never an arbitrary hard link.
+5. Replay the same receipt once: it authenticates the preserved backup and never
+   touches a replacement at the original path. Missing/mismatched backups or
+   receipts fail closed. Do not hand-edit receipts or fabricate PID/lease values.
+6. Exit maintenance, verify the real hook observation, then replay the exact
+   interrupted canonical operation. A new writer must acquire its own real lock
+   normally. Qualify changed code proportionally; prior results apply only to their
+   verified inputs. Preserve failed attempts and partial collection evidence.
+
+Rollback is preservation, not reinsertion over a new owner: retain the quarantine
+and receipts. Do not move the old file over a live replacement. If runtime repair
+fails, keep publication blocked and diagnose the exact failed stage.

package/templates/.agents/skills/zaip-skill-lifecycle-closure/references/late-finalization.md

@@ -0,0 +1,158 @@
+# Avaliação administrativa tardia pelo Gui
+
+Use somente quando o Stop já encerrou a raiz responsável e bloqueou sua
+Task/Change/Execution por ausência de finalização. Um Run `completed` descreve o
+término físico; não comprova aceite da entrega.
+
+Esta recuperação exige autorização humana observada, principal nativo do mesmo
+thread e uma avaliação nova e real do Gui. Não recrie um filho no turno antigo,
+não altere `run.started`/`run.finished` e não invente a decisão que faltou.
+
+Preparação, avaliação e captura ocorrem somente em manutenção oficial autorizada,
+com governança desativada e tracking ligado. O comando verifica o estado emitido
+pelo script de manutenção; editar um booleano isoladamente não satisfaz o contrato.
+Não desabilite hooks nem crie grants para fazer o Gui trabalhar. Após a captura,
+saia da manutenção antes de retomar a entrega governada.
+
+## Sequência e limites
+
+1. Inspecione os IDs exatos, o recibo Stop e o ledger. Preserve provas, alterações
+   locais, candidato e histórico. Não repita Stop se ele já convergiu o grafo.
+2. Prepare a recuperação oficial para a raiz terminal. O recibo deve vincular a
+   autorização atual e o snapshot do grafo antes da avaliação. Divergência de
+   identidade, decisão existente ou sucessor ativo impede uma nova avaliação.
+
+   ```text
+   node .agents/runtime/bin/zaip.mjs run late-finalization RUN-ID --prepare --direct-authorization "MENSAGEM HUMANA EXATA" --json
+   ```
+
+   Preserve o `permit_id`, o `snapshot_sha256` e o packet retornados. Não edite o
+   recibo nem use uma autorização diferente da mensagem nativa observada.
+
+   Se a preparação recusar o principal, não acrescente flags `--codex-hook-*`
+   manualmente e não reutilize um receipt de outra chamada. Durante manutenção
+   oficial, o diagnóstico observacional fica em
+   `.agents/private/state/hooks/diagnostics/late-finalization/<hash-thread-turn>/<slot>.json`:
+   até 32 eventos por turno, até 2 KiB por evento, sem rotação entre turnos. Ele
+   não concede autoridade. Correlacione o turno, horário e rota antes de atribuir
+   uma falha. `receipt_written` comprova emissão; não comprova que o host aplicou
+   `updatedInput` nem que o CLI consumiu o receipt. Se o receipt exato permanecer
+   sem consumo e a preparação falhar, preserve ambos e interrompa as tentativas
+   até resolver essa integração. Não libere a entrega por outro caminho.
+
+   O estágio `stdout_written` registra somente booleanos do envelope, presença
+   das flags e escrita completa; recusas do principal incluem apenas contagens
+   das flags recebidas. Emissão não equivale a consumo: confirme o prepare real
+   e seu permit. Não forneça flags manualmente nem atribua uma falha intermitente
+   ao host sem evidência da entrada e saída correspondentes.
+3. Encaminhe ao Gui somente o diagnóstico e as evidências necessárias. Sua tarefa
+   é avaliar o bloqueio administrativo, sem editar produto, publicar ou conceder
+   aceite. Use a identidade do catálogo e preserve a identidade nativa observada.
+4. Capture o resultado terminal real pelo comando oficial. A única conclusão
+   admitida por esta recuperação é `blocked`. O evento administrativo é aditivo e
+   separado da finalização normal; nunca representa um Gui histórico.
+
+   ```text
+   node .agents/runtime/bin/zaip.mjs run late-finalization RUN-ID --capture --permit LATE-ID --native-session UUID-OBSERVADO --native-turn TURNO-OBSERVADO --native-transcript LOCATOR-OBSERVADO --direct-authorization "MESMA MENSAGEM HUMANA" --json
+   ```
+
+   O resultado vem do transcript terminal, com `permit_id`, `target_run_id`,
+   `snapshot_sha256`, `outcome: "blocked"` e `summary`. Não forneça uma decisão
+   criada pelo principal como substituto do resultado do Gui.
+   A autorização é relida do turno exato com o parser canônico, incluindo
+   mensagens `response_item` identificadas como `user.text`. Conteúdo adicional
+   de página ou coordenação não substitui a mensagem humana; revogação humana
+   posterior invalida o consentimento. Preserve a mensagem normalizada e o hash
+   do permit, sem copiar conteúdo de outro turno para satisfazer a verificação.
+   Use o locator exato observado do transcript; não pesquise todo o histórico.
+5. Confira o evento persistido e o replay idempotente. Alterações do grafo,
+   ancestralidade incompatível ou resultado conflitante continuam bloqueando.
+6. Reative a governança pelo script oficial de saída de manutenção e retome a
+   continuação oficial. O replan, as cotas restantes, o writer, as provas
+   do candidato e o Gui final da nova tentativa continuam obrigatórios. Esta
+   avaliação não aprova a release nem substitui os critérios de aceite.
+
+Ao interromper, preserve o recibo e os resultados originais. Reutilize o mesmo
+recibo e a mesma avaliação no replay; não crie outra identidade para compensar
+uma falha parcial. Se os pré-requisitos mudaram, diagnostique a divergência antes
+de qualquer nova tentativa.
+
+## Modalidade v2: interrupção nativa explícita e autoridade anterior
+
+O protocolo `late-blocked-finalization-v2` é uma rota distinta e opt-in. Admite
+somente a divergência comprovada entre `run.finished: completed` local e um único
+`event_msg/turn_aborted` nativo, com `reason: interrupted`, no turno exato da raiz.
+EOF, timeout, ausência de eventos, cancelamento e falha não autorizam esta rota.
+O contrato registra `native_status: interrupted` e `local_status: completed`
+separadamente. Não cria recibo Stop nem altera o término original.
+
+Use somente um permit **v1 já avaliado pelo Gui real**, pertencente ao predecessor
+direto (`continuation_of_run_id`) da mesma Task/Change/Execution e thread. A
+autenticação relê o humano canônico, contexto, permit e resultado nativo daquele
+Gui. O snapshot anterior vincula a avaliação anterior; o novo permit fixa um
+snapshot novo do grafo atual. Um JSON local isolado não concede autoridade.
+Texto histórico restrito a outra recuperação ou com limites ambíguos é recusado.
+
+```text
+node .agents/runtime/bin/zaip.mjs run late-finalization RUN-ID --prepare --closure-proof interrupted --authority-permit LATE-ANTERIOR --terminal-transcript sessions/AAAA/MM/DD/LOCATOR-EXATO.jsonl --direct-authorization "MENSAGEM HUMANA ATUAL EXATA" --json
+```
+
+O principal atual continua autenticado pelo hook, ativo, sem ancestry e no mesmo
+thread. A mensagem atual não recebe palavras novas de autorização: a autoridade
+histórica está identificada separadamente pelo permit anterior autenticado.
+Capture com as mesmas três opções da modalidade e as opções de Gui/permit da
+sequência v1. Somente um Gui real iniciado **depois** do novo permit pode emitir
+o parecer, exclusivamente `blocked`.
+
+Prepare, capture e consumo frozen reautenticam a autoridade histórica e examinam
+as mensagens humanas posteriores do transcript exato. Revogação, cancelamento
+ou possível restrição/ambiguidade bloqueiam. O parser ignora metadados de página
+e delegação. Transcript rotacionado para outro locator exige diagnóstico; não há
+busca global nem seleção de autorização histórica arbitrária.
+
+Perguntas informativas e limites de branch para concluir a mesma entrega não
+revogam consentimento. O verificador reconhece formas explícitas de retirada
+(incluindo “Não quero mais a recuperação” e “Eu revogo a autorização”) e comandos
+que restrinjam a recuperação a explicar/planejar. Não é interpretação geral de
+linguagem natural; escopo histórico restrito ou identidade divergente permanece
+bloqueado. Gates de qualificação, publicação e proteção continuam independentes.
+
+A prova nativa fixa identidade física do arquivo e hash de um prefixo terminado
+na linha de interrupção. Appends posteriores são permitidos; substituição,
+truncamento, alteração do prefixo, terminal duplicado ou conflitante bloqueiam.
+O leitor autentica cabeçalho/cwd/ancestry, percorre janelas fixas em chunks de
+256 KiB e usa projeção canônica com limite de 1 MiB por registro, sem alocar o
+arquivo inteiro. Appends não invalidam o prefixo; alterações dos bytes já
+observados exigem nova observação estável. Mensagens humanas projetadas além do
+limite são recusadas para não ocultar uma restrição.
+
+A modalidade exige quiescência: nenhuma Run sucessora/descendente ativa,
+nenhum filho nativo ativo, nenhuma Task com lease de escopo conflitante, ledger
+de recuperação conhecido sem reserva pendente, sem writer lock e sem claim de
+workspace ativo ou desconhecido. Leituras inválidas falham fechadas; nunca
+remova lock, claim ou reserva para satisfazer a verificação. As verificações
+usam os locks canônicos existentes e são repetidas antes da captura. Não há
+inspeção global de processos nem inferência de quiescência por tempo decorrido.
+
+No replay de uma continuação frozen já journalizada, os bytes originais,
+postimages canônicos, entrada do sucessor e compare-and-swap do ciclo são
+validados antes da reautenticação. Somente a Task retomada e o sucessor exatos
+daquele journal podem estar ativos; outros writers, filhos, leases e reservas
+continuam bloqueando. Isso permite recuperar falha parcial após retomar a Task
+ou criar sua Run, sem duplicar tentativa nem permitir um sucessor arbitrário.
+
+Esta modalidade mantém v1 intacto, não amplia cotas, não atualiza o ledger, não
+altera candidato e não aprova entrega/publicação. O consumo frozen revalida
+provas e snapshot antes de permitir a continuação oficial existente.
+
+## Aceite da correção (ambas as modalidades)
+
+- O fluxo legítimo aceita somente Gui nativo, terminal e vinculado ao principal
+  atual e à autorização observada.
+- `completed`, identidade divergente, grafo alterado, sucessor ativo e decisões
+  conflitantes são recusados sem modificar a entrega histórica.
+- Replay não duplica avaliação; interrupções preservam a possibilidade de
+  recuperação sem sobrescrever evidências.
+- A continuação consome o contrato administrativo e mantém o ledger anterior.
+- Testes de contrato não substituem a execução real; publicação exige sua própria
+  qualificação e prova remota.

package/templates/.agents/skills/zaip-skill-lifecycle-closure/references/local-catalog-closure.md

@@ -0,0 +1,37 @@
+# Fechamento com qualificação local assinada
+
+Use quando uma release `local-catalog-v1` publicada mantém Task/Execution abertas.
+Preserve candidato, tag, npm, recibo assinado e produtores das Evidences.
+
+1. Confirme os IDs exatos e se o responsável ainda está aberto. Uma decisão nativa
+   de Gui pode existir sem ter sido persistida. Não crie outra Task/tentativa para
+   substituir uma falha de gravação. Responsável já terminal segue o contrato de
+   recuperação pós-publicação, não este replay.
+2. Confira a linha do avanço em `.agents/config/release-cycle.json`. A prova local
+   usa `qualification: {kind,id,receipt_sha256}`; não invente `ci_run_id` nem misture
+   os dois formatos. O histórico, Task coordenadora e SHA continuam obrigatórios.
+3. O avanço local registra automaticamente os caminhos dos inputs em
+   `.agents/private/state/release-closure/<SHA>.json`. Para um avanço anterior à correção, registre
+   somente os caminhos existentes com o comando abaixo. Esse arquivo não autoriza
+   conclusão: o resolver reautentica assinatura, catálogo, assets, notas e publicação.
+
+   ```text
+   node scripts/local-catalog-closure-inputs.mjs --repository ROOT --sha SHA --receipt RECEIPT --artifacts DIRECTORY --notes-file NOTES.md
+   ```
+
+4. Se o runtime instalado ainda exige exclusivamente Actions, aplique a correção
+   de manutenção autorizada e seus testes focados. Preserve a procedência da fonte
+   e do runtime. Nunca edite o registro do ciclo, gates ou Evidences para fazê-los
+   parecer compatíveis. Uma prova ausente/adulterada mantém o bloqueio.
+5. Reative a governança e confira um hook real. Com o responsável ainda aberto,
+   repita a captura exata do Stop de Gui com sua sessão, turno, pai, decisão,
+   Evidences e lista de arquivos observados. Não fabrique outra aprovação nem
+   confunda status nativo com resultado da Task.
+6. Leia Task, Change, Execution e Run após o relay. Somente estados canônicos
+   terminais comprovam conclusão. Preserve o recibo de fechamento. O push de
+   metadados usa o helper local-catalog, sem alterar tag/npm nem repetir as suítes.
+
+Critérios de aceite da compatibilidade: avanço local autenticado aceito; identidade
+mista, SHA/Task/histórico divergentes e verificação recusada rejeitados; rota Actions
+preservada; gravação de caminhos idempotente e sem substituir inputs conflitantes;
+replay real conclui os mesmos registros. Não prometa ausência absoluta de falhas.

package/templates/.agents/skills/zaip-skill-lifecycle-closure/references/post-publication-task-first.md

@@ -79,7 +79,7 @@ sendo a manutenção. Não crie turnos artificiais para contornar exclusividade.
 4. Conclua a manutenção com seu Gui real. Depois consuma o recibo:
 
    ```text
-   node .agents/runtime/bin/zaip.mjs task resume-post-publication TASK-HISTORICA --receipt .local/recovery/post-publication/HASH-RETORNADO.json --json
+   node .agents/runtime/bin/zaip.mjs task resume-post-publication TASK-HISTORICA --receipt .agents/private/state/recovery/post-publication/HASH-RETORNADO.json --json
    ```
 
 5. Use a raiz sucessora retornada para o fechamento histórico autorizado. Preserve

package/templates/.agents/skills/zaip-skill-lifecycle-closure/scripts/empty-lock-native.cs

@@ -0,0 +1,113 @@
+using System;
+using System.ComponentModel;
+using System.Collections.Generic;
+using System.IO;
+using System.Runtime.InteropServices;
+using System.Text;
+using Microsoft.Win32.SafeHandles;
+
+// The handle remains exclusive through inspection, rename and verification.
+public static class ZaipEmptyLockNative {
+  [StructLayout(LayoutKind.Sequential)] struct Info {
+    public uint Attributes;
+    public System.Runtime.InteropServices.ComTypes.FILETIME Created, Accessed, Written;
+    public uint Volume, SizeHigh, SizeLow, Links, IndexHigh, IndexLow;
+  }
+  public sealed class Result {
+    public string identity { get; set; }
+    public string path { get; set; }
+    public long size { get; set; }
+    public bool moved { get; set; }
+  }
+  [DllImport("kernel32.dll", CharSet=CharSet.Unicode, SetLastError=true)]
+  static extern SafeFileHandle CreateFileW(string name, uint access, uint share, IntPtr security, uint disposition, uint flags, IntPtr template);
+  [DllImport("kernel32.dll", SetLastError=true)]
+  static extern bool GetFileInformationByHandle(SafeFileHandle file, out Info info);
+  [DllImport("kernel32.dll", CharSet=CharSet.Unicode, SetLastError=true)]
+  static extern uint GetFinalPathNameByHandleW(SafeFileHandle file, StringBuilder path, uint length, uint flags);
+  [DllImport("kernel32.dll", SetLastError=true)]
+  static extern bool SetFileInformationByHandle(SafeFileHandle file, int kind, IntPtr data, uint size);
+  static string Full(string path) { return System.IO.Path.GetFullPath(path).TrimEnd('\\'); }
+  sealed class ParentFence : IDisposable {
+    internal readonly List<SafeFileHandle> Handles = new List<SafeFileHandle>();
+    public void Dispose() {
+      for(int n=Handles.Count-1;n>=0;n--) Handles[n].Dispose();
+    }
+  }
+  // Retain every ancestor top-down without delete sharing. Write sharing is
+  // required by Win32 rename. This fences rename/replacement, not a hostile
+  // filesystem writer changing reparse metadata in place (outside this protocol).
+  public static IDisposable FenceParents(string path) {
+    var paths=new List<string>();
+    for(string p=System.IO.Path.GetDirectoryName(Full(path));p!=null;p=System.IO.Path.GetDirectoryName(p)) paths.Add(p);
+    paths.Reverse();
+    var fence=new ParentFence();
+    try {
+      foreach(string p in paths) {
+        var h=CreateFileW(p,0x80000000u,3,IntPtr.Zero,3,0x02200000u,IntPtr.Zero);
+        fence.Handles.Add(h);
+        if(h.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
+        Info i;
+        if(!GetFileInformationByHandle(h,out i)) throw new Win32Exception(Marshal.GetLastWin32Error());
+        if((i.Attributes & 0x10u)==0 || (i.Attributes & 0x400u)!=0 || !String.Equals(Final(h),Full(p),StringComparison.OrdinalIgnoreCase))
+          throw new IOException("Physical, non-reparse parent required");
+      }
+      return fence;
+    } catch { fence.Dispose(); throw; }
+  }
+  static string Identity(Info i) { return i.Volume.ToString("x8")+":"+i.IndexHigh.ToString("x8")+i.IndexLow.ToString("x8"); }
+  static string Final(SafeFileHandle handle) {
+    var b=new StringBuilder(32768);
+    uint n=GetFinalPathNameByHandleW(handle,b,(uint)b.Capacity,0);
+    if (n==0 || n>=b.Capacity) throw new Win32Exception(Marshal.GetLastWin32Error());
+    string s=b.ToString();
+    if (s.StartsWith(@"\\?\UNC\")) s=@"\\"+s.Substring(8);
+    else if(s.StartsWith(@"\\?\")) s=s.Substring(4);
+    return Full(s);
+  }
+  static Info Check(SafeFileHandle h, string expectedPath, string expectedId) {
+    Info i;
+    if (!GetFileInformationByHandle(h,out i)) throw new Win32Exception(Marshal.GetLastWin32Error());
+    if ((i.Attributes & (0x10u|0x400u)) != 0 || i.Links != 1 || i.SizeHigh != 0 || i.SizeLow != 0)
+      throw new IOException("Only a regular, single-link, empty lock is recoverable");
+    string observedPath=Final(h);
+    if (!String.Equals(observedPath,Full(expectedPath),StringComparison.OrdinalIgnoreCase))
+      throw new IOException("Physical lock path differs: "+observedPath+"; expected: "+Full(expectedPath));
+    if (!String.IsNullOrEmpty(expectedId) && Identity(i) != expectedId)
+      throw new IOException("Lock identity changed");
+    return i;
+  }
+  public static Result InspectOrMove(string path, string backup, string expectedIdentity) {
+    path=Full(path);
+    bool move=!String.IsNullOrEmpty(backup);
+    if (move) {
+      backup=Full(backup);
+      if (String.IsNullOrEmpty(expectedIdentity) || !String.Equals(System.IO.Path.GetDirectoryName(path),System.IO.Path.GetDirectoryName(backup),StringComparison.OrdinalIgnoreCase))
+        throw new IOException("Move requires exact identity and same-directory quarantine");
+    }
+    // OPEN_EXISTING, no sharing, OPEN_REPARSE_POINT. Never create/truncate the target.
+    using(var parents=(ParentFence)FenceParents(path))
+    using(var h=CreateFileW(path,0x80010000u,0,IntPtr.Zero,3,0x00200000u,IntPtr.Zero)) {
+      if(h.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
+      Info before=Check(h,path,expectedIdentity);
+      if(move) {
+        // Full destination is safe only while every ancestor remains fenced.
+        // RootDirectory-relative rename is not supported by this Win32 boundary.
+        byte[] name=Encoding.Unicode.GetBytes(backup);
+        int offset=IntPtr.Size==8 ? 20 : 12;
+        // Win32 consumes a NUL-terminated FileName even though FileNameLength
+        // excludes that terminator. Never let it read beyond the allocation.
+        int length=offset+name.Length+2;
+        IntPtr data=Marshal.AllocHGlobal(length);
+        try {
+          Marshal.Copy(new byte[length],0,data,length); // ReplaceIfExists=false
+          Marshal.WriteInt32(data,offset-4,name.Length);
+          Marshal.Copy(name,0,IntPtr.Add(data,offset),name.Length);
+          if(!SetFileInformationByHandle(h,3,data,(uint)length)) throw new Win32Exception(Marshal.GetLastWin32Error());
+          Check(h,backup,Identity(before));
+        } finally { Marshal.FreeHGlobal(data); }
+      }
+      return new Result { identity=Identity(before), path=move ? backup : path, size=0, moved=move };
+    }
+  }
+}

package/templates/.agents/skills/zaip-skill-lifecycle-closure/scripts/empty-lock-native.ps1

@@ -0,0 +1,9 @@
+param(
+  [Parameter(Mandatory=$true)][string]$Path,
+  [string]$Backup,
+  [string]$ExpectedIdentity
+)
+$ErrorActionPreference = 'Stop'
+Add-Type -Path (Join-Path $PSScriptRoot 'empty-lock-native.cs')
+$result = [ZaipEmptyLockNative]::InspectOrMove($Path, $Backup, $ExpectedIdentity)
+ConvertTo-Json -Compress -InputObject $result

package/templates/.agents/skills/zaip-skill-lifecycle-closure/scripts/recover-empty-usage-lock.mjs

@@ -0,0 +1,194 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  existsSync,
+  linkSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { parseDocument } from "../../zaip-skill-github-deploy/scripts/yaml-parser.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const emptyHash = createHash("sha256").update("").digest("hex");
+const uuid = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
+const same = (a, b) => resolve(a).toLowerCase() === resolve(b).toLowerCase();
+function publishReceipt(path, value) {
+  const staging = `${path}.${randomUUID()}.pending`;
+  // The public name never exists until the complete receipt has been flushed.
+  // An interrupted process may leave its staging file as preserved evidence.
+  writeFileSync(staging, JSON.stringify(value, null, 2), { flag: "wx", flush: true });
+  try {
+    linkSync(staging, path);
+  } finally {
+    unlinkSync(staging);
+  }
+}
+function physical(root, target, create = false) {
+  const offset = relative(root, target);
+  if (offset.startsWith("..") || isAbsolute(offset)) throw Error("Recovery path leaves root");
+  let current = root;
+  for (const part of offset.split(/[\\/]/).filter(Boolean)) {
+    current = resolve(current, part);
+    if (create && !existsSync(current)) mkdirSync(current);
+    if (lstatSync(current).isSymbolicLink() || !same(realpathSync(current), current))
+      throw Error("Linked recovery path refused");
+  }
+  return current;
+}
+function readJson(root, path, receipt = false) {
+  physical(root, path);
+  const info = lstatSync(path, { bigint: true });
+  if (!info.isFile() || info.size > 65536n) throw Error("Invalid recovery receipt");
+  if (info.nlink !== 1n) {
+    // A crash after publication can retain the publisher's staging hard link.
+    // Accept only that exact physical identity; preserve it for investigation.
+    if (!receipt || info.nlink !== 2n) throw Error("Unexpected receipt hard link");
+    const prefix = `${basename(path)}.`;
+    const matches = readdirSync(dirname(path))
+      .filter(
+        (name) =>
+          name.startsWith(prefix) &&
+          name.endsWith(".pending") &&
+          uuid.test(name.slice(prefix.length, -8)),
+      )
+      .filter((name) => {
+        const staging = physical(root, resolve(dirname(path), name));
+        const s = lstatSync(staging, { bigint: true });
+        return s.isFile() && s.dev === info.dev && s.ino === info.ino && s.nlink === 2n;
+      });
+    if (matches.length !== 1) throw Error("Published receipt has an unrecognized hard link");
+  }
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+function maintenance(root) {
+  const config = physical(root, resolve(root, ".agents/config/project.yaml"));
+  const doc = parseDocument(readFileSync(config, "utf8"), { strict: true, uniqueKeys: true });
+  if (
+    doc.errors.length ||
+    doc.warnings.length ||
+    doc.getIn(["zaip", "enabled"]) !== false ||
+    doc.getIn(["tracking", "enabled"]) !== true
+  )
+    throw Error("Recovery requires official maintenance with tracking enabled");
+  const state = readJson(root, resolve(root, ".agents/private/state/zaip-maintenance/state.json"));
+  if (state.schema_version !== 1 || state.phase !== "active" || !same(state.root, root))
+    throw Error("Active maintenance receipt required");
+}
+export function nativeEmptyLock(path, backup, identity) {
+  // biome-ignore lint/suspicious/noUndeclaredEnvVars: Native maintenance runs outside Turbo and uses the Windows OS directory.
+  if (process.platform !== "win32" || !process.env.SystemRoot)
+    throw Error("Exclusive native recovery is Windows-only");
+  const args = [
+    "-NoProfile",
+    "-NonInteractive",
+    "-File",
+    resolve(here, "empty-lock-native.ps1"),
+    "-Path",
+    path,
+  ];
+  if (backup) args.push("-Backup", backup, "-ExpectedIdentity", identity);
+  else if (identity) args.push("-ExpectedIdentity", identity);
+  return JSON.parse(
+    execFileSync(
+      // biome-ignore lint/suspicious/noUndeclaredEnvVars: Native maintenance runs outside Turbo and uses the Windows OS directory.
+      resolve(process.env.SystemRoot, "System32/WindowsPowerShell/v1.0/powershell.exe"),
+      args,
+      {
+        encoding: "utf8",
+        windowsHide: true,
+        timeout: 30000,
+        maxBuffer: 65536,
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    ),
+  );
+}
+export function recoverEmptyUsageLock({ root = process.cwd(), receiptId, apply = false } = {}) {
+  root = realpathSync(resolve(root));
+  maintenance(root);
+  const path = resolve(root, ".agents/records/runs/.usage-attribution.lock");
+  physical(root, dirname(path));
+  const receiptRoot = resolve(root, ".agents/private/state/usage-lock-recovery");
+  if (!apply)
+    return {
+      read_only: true,
+      root,
+      lock: nativeEmptyLock(path),
+      recovery_requires: "explicit apply and a stable receipt UUID; no owner inferred",
+    };
+  if (!uuid.test(receiptId ?? ""))
+    throw Error("Explicit receipt UUID required for recoverable apply");
+  physical(root, receiptRoot, true);
+  const intentPath = resolve(receiptRoot, `${receiptId}.intent.json`);
+  const resultPath = resolve(receiptRoot, `${receiptId}.result.json`);
+  let intent;
+  if (existsSync(intentPath)) intent = readJson(root, intentPath, true);
+  else {
+    const observed = nativeEmptyLock(path);
+    intent = {
+      schema_version: 1,
+      root,
+      path,
+      backup: `${path}.quarantine-${receiptId}`,
+      identity: observed.identity,
+      sha256: emptyHash,
+      receipt_id: receiptId,
+      created_at: new Date().toISOString(),
+      owner: "unavailable",
+      protocol: "empty-prepublication-native-handle-v1",
+    };
+    publishReceipt(intentPath, intent);
+  }
+  assert.equal(intent.schema_version, 1);
+  assert.equal(intent.root, root);
+  assert.equal(intent.path, path);
+  assert.equal(intent.receipt_id, receiptId);
+  assert.equal(intent.backup, `${path}.quarantine-${receiptId}`);
+  assert.equal(intent.protocol, "empty-prepublication-native-handle-v1");
+  assert.equal(intent.sha256, emptyHash);
+  assert.match(intent.identity, /^[a-f0-9]{8}:[a-f0-9]{16}$/);
+  // A prior rename may have completed before its result was saved. Inspect only its backup.
+  const replay = existsSync(intent.backup);
+  maintenance(root);
+  const observed = replay
+    ? nativeEmptyLock(intent.backup, undefined, intent.identity)
+    : nativeEmptyLock(path, intent.backup, intent.identity);
+  assert.equal(observed.identity, intent.identity);
+  const result = {
+    schema_version: 1,
+    receipt_id: receiptId,
+    root,
+    original_path: path,
+    backup_path: intent.backup,
+    identity: intent.identity,
+    backup_sha256: emptyHash,
+    recovered: true,
+    owner: "unavailable",
+    completed_at: new Date().toISOString(),
+  };
+  if (existsSync(resultPath)) {
+    const previous = readJson(root, resultPath, true);
+    for (const key of Object.keys(result).filter((k) => k !== "completed_at"))
+      assert.deepEqual(previous[key], result[key]);
+  } else publishReceipt(resultPath, result);
+  return { ...result, replayed: replay, result_path: resultPath };
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  const args = process.argv.slice(2),
+    options = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--apply") options.apply = true;
+    else if (args[i] === "--root") options.root = args[++i];
+    else if (args[i] === "--receipt-id") options.receiptId = args[++i];
+    else throw Error("Use [--root PATH] [--apply --receipt-id UUID]");
+  }
+  console.log(JSON.stringify(recoverEmptyUsageLock(options)));
+}

package/templates/.agents/skills/zaip-skill-local-credentials/SKILL.md

@@ -5,6 +5,8 @@ description: Resolve an authorized action's local credential from project-scoped
 
 # Resolver credenciais locais
 
+Se o backend/ação usa Infisical, siga [o cofre](../zaip-skill-infisical/SKILL.md). Resolva aqui apenas seu bootstrap explicitamente selecionado; não exporte o cofre nem procure dotenv como fallback de indisponibilidade/recusa.
+
 Use antes de bloquear uma ação já autorizada que dependa de credencial. Esta skill
 não autoriza publicação, login, gasto ou outra ação externa; ela apenas resolve a
 credencial local mínima que a ação autorizada já exige.
@@ -41,3 +43,28 @@ credencial local mínima que a ação autorizada já exige.
 
 Leia [o procedimento de resolução](references/dotenv-resolution.md) antes de usar
 dotenv em uma ação externa ou de alto impacto.
+
+## Descobrir somente nomes
+
+O hook aceita esta listagem literal na raiz física do repositório, sem conteúdo:
+
+```sh
+rg --files --no-config --hidden --no-ignore -g '.env' -g '.env.local' -g '!**/node_modules/**' -g '!**/.git/**' -g '!.local/**' -g '!.agents/private/**' .
+```
+
+Troque `.` por um único diretório relativo explicitamente selecionado, entre aspas
+se contiver espaços. Globs positivos são nomes literais `.env` ou `.env.<slug>`;
+não use curingas positivos. Exclusões permitidas: `!**/node_modules/**`, `!**/.git/**`,
+`!**/dist/**`, `!**/build/**`, `!**/.cache/**`, `!.local/**`, `!.agents/private/**`.
+`--no-config` é obrigatório; o comando não segue links. Operandos que sejam links,
+caminhos externos ou traversal são recusados, assim como pipes, redirecionamentos,
+comandos compostos e opções adicionais. A listagem não autoriza abrir arquivos,
+não prova sua autenticidade e não libera conteúdo ou enumeração de variáveis.
+Antes de qualquer uso autorizado, mantenha a verificação física e a resolução
+delimitada descritas acima. O hook não é um sandbox atômico contra mudanças de
+filesystem entre a revisão e a execução.
+
+Para SSH, use o onboarding modular de [Hostinger/SSH](../zaip-skill-hostinger-cloudflare-terraform/references/vps-onboarding.md).
+Uma referência externa nomeada exige autorização explícita do caminho físico e passa somente pelo runner delimitado;
+não amplia a busca dotenv, não autoriza leitura da chave privada pelo agente e não permite procurar outras identidades.
+O runner deriva a fingerprint pública da referência selecionada, preserva passphrase e verifica permissões sem alterá-las silenciosamente.