@pathbit/agentdevkit 0.0.18 → 0.0.20

package/.pbai4devs/scripts/lib/gitignore.mjs

@@ -332,26 +332,6 @@ function ambiguousExceptions(root, location, clientRoots, artifacts) {
   return conflicts;
 }
 
-function foreignHiddenClients(plan) {
-  if (!plan.location) return [];
-  const content = localRead(plan.location.exclude) || '', ranges = [];
-  let start = null;
-  content.split(/\r?\n/).forEach((line, index) => {
-    const begin = line.match(/^# BEGIN AGENTDEVKIT LOCAL ([a-f0-9]{16})$/);
-    const end = line.match(/^# END AGENTDEVKIT LOCAL ([a-f0-9]{16})$/);
-    if (begin) start = { id: begin[1], line: index + 1 };
-    else if (end && start?.id === end[1]) { ranges.push({ ...start, end: index + 1 }); start = null; }
-  });
-  const probes = plan.clientRoots.filter(path => { const item = localStat(join(plan.root, path)); return !item || item.isDirectory() && !item.isSymbolicLink(); }).map(path => `${path}/.agentdevkit-human-probe.md`);
-  if (!probes.length) return [];
-  const { paths, matches } = ignoreMatches(plan.location, probes);
-  return paths.flatMap((path, index) => {
-    const match = matches.get(path);
-    if (!match || match.pattern.startsWith('!') || resolve(plan.location.top, match.source) !== plan.location.exclude) return [];
-    return ranges.some(range => `# BEGIN AGENTDEVKIT LOCAL ${range.id}` !== plan.first && match.line >= range.line && match.line <= range.end) ? [probes[index]] : [];
-  });
-}
-
 function localIgnoreSource(location, source) {
   const path = resolve(location.top, source);
   if (path === location.exclude) return true;
@@ -370,6 +350,21 @@ function ignoreMatches(location, probes) {
   return { paths, matches };
 }
 
+// A nested .gitignore cannot reopen a project hidden by an ignored ancestor.
+// Detect this before claiming that its client exceptions are effective.
+function ignoredProjectAncestors(location) {
+  if (!location.prefix) return [];
+  const segments = location.prefix.split('/');
+  const paths = segments.map((_part, index) => segments.slice(0, index + 1).join('/'));
+  const result = gitCommand(location.top, ['check-ignore', '--verbose', '--no-index', '--stdin', '-z'], `${paths.join('\0')}\0`);
+  if (result.error || ![0, 1].includes(result.status)) throw new Error(result.error?.message || result.stderr || 'Falha ao conferir ancestrais Git.');
+  const values = result.stdout.split('\0'), ignored = [];
+  for (let index = 0; index + 3 < values.length; index += 4) {
+    if (!values[index + 2].startsWith('!')) ignored.push(`Ancestral Git ignorado: ${values[index + 3]}/; reabra-o no .gitignore do repositorio pai`);
+  }
+  return ignored;
+}
+
 function localRoot(value) {
   const missing = []; let parent = resolve(value);
   while (!localStat(parent)) { missing.unshift(parent.slice(dirname(parent).length + 1)); parent = dirname(parent); }
@@ -387,15 +382,17 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   const artifacts = artifactPolicy(templateFile);
   if (template.split('{{OUTPUTS}}').length !== 2) throw new Error('local.ignore exige um unico {{OUTPUTS}}.');
   if (template.split('{{ROOTS}}').length > 2) throw new Error('local.ignore permite um unico {{ROOTS}}.');
-  // A client directory can also contain human instructions and settings. Only
-  // whole files owned by the kit belong in the local output exclusion list.
-  const roots = [];
+  // Client roots are ignored locally. Projects can explicitly opt in to a
+  // complete client with a literal negation in their own root .gitignore.
   const localPolicy = join(templateRoot || root, '.pbai4devs/templates/clients/ADAPTERS.json');
   const policy = JSON.parse(readFileSync(checkedLocalPath(localStat(localPolicy) ? localPolicy : fileURLToPath(new URL('../../templates/clients/ADAPTERS.json', import.meta.url))), 'utf8'));
   const clientRoots = [...new Set(policy.adapters.flatMap(adapter => [adapter.root, ...(adapter.extraRoots || [])]))];
   if (clientRoots.some(path => typeof path !== 'string' || !/^\.[a-z0-9][a-z0-9-]*$/.test(path) || ['.git', '.pbai4devs', '.agent-tests'].includes(path))) throw new Error('Raiz de cliente invalida para exclusao.');
+  const roots = [...clientRoots];
   const privateClients = privateClientPolicy(templateFile, clientRoots);
-  const paths = [...new Set([...outputs.map(checkedOutput), ...template.split(/\r?\n/).filter(line => line.startsWith('/')).map(line => checkedOutput(line.slice(1)))])].sort();
+  const outputPaths = [...new Set(outputs.map(checkedOutput))];
+  const paths = [...new Set([...outputPaths, ...template.split(/\r?\n/).filter(line => line.startsWith('/')).map(line => checkedOutput(line.slice(1)))])]
+    .filter(path => !roots.some(client => path === client || path.startsWith(`${client}/`))).sort();
   const info = gitCommand(resolved.parent, ['rev-parse', '--show-toplevel', '--git-path', 'info/exclude']);
   let location = null;
   if (info.status === 0) {
@@ -412,6 +409,19 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
     throw new Error(`Nao foi possivel localizar Git: ${info.error?.message || info.stderr}`);
   }
   const id = createHash('sha256').update(root).digest('hex').slice(0, 16);
+  const projectIgnore = join(root, '.gitignore'), projectIgnoreStat = localStat(projectIgnore);
+  const literalExceptions = projectIgnoreStat?.isFile() && !projectIgnoreStat.isSymbolicLink()
+    ? new Set(readFileSync(projectIgnore, 'utf8').replace(/^\uFEFF/, '').split(/\r?\n/)) : new Set();
+  const requestedRoots = location ? roots.filter(client => literalExceptions.has(`!/${client}/`) || literalExceptions.has(`!${client}/`)) : [];
+  const optCandidates = requestedRoots.filter(client => safeIgnoreProbe(root, `${client}/.agentdevkit-opt-in-probe`));
+  // A later rule or an ancestor can override a literal negation. Consult Git
+  // before accepting it, including when the client folder does not yet exist.
+  const optProbes = optCandidates.map(client => `${client}/.agentdevkit-opt-in-probe`);
+  const optMatches = location && optProbes.length ? ignoreMatches(location, optProbes) : { paths: [], matches: new Map() };
+  const optedRoots = optCandidates.filter((_client, index) => {
+    const match = optMatches.matches.get(optMatches.paths[index]);
+    return !match || match.pattern.startsWith('!');
+  });
   const first = `# BEGIN AGENTDEVKIT LOCAL ${id}`, last = `# END AGENTDEVKIT LOCAL ${id}`;
   const fixed = template.replace('{{ROOTS}}', roots.map(path => `/${path}/`).join('\n')).replace('{{OUTPUTS}}', paths.filter(path => !roots.some(root => path === root || path.startsWith(root + '/'))).map(path => `/${escapePattern(path)}`).join('\n'))
     + '\n# Estado privado dos clientes\n' + privateClients.rules.join('\n') + '\n'
@@ -424,10 +434,9 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   const target = location?.exclude;
   const before = target ? localRead(target) : null, after = target ? localBlock(before, first, last, body) : null;
   const edits = before === after ? [] : [{ path: target, before, after, beforeMode: localMode(target) }];
-  const probes = [...paths, ...rootProbes(root, roots)];
+  const probes = [...paths, ...rootProbes(root, roots.filter(client => !optedRoots.includes(client)))];
   const existingPrivate = privateClients.probes.filter(path => localStat(join(root, path.split('/')[0]))?.isDirectory() && safeIgnoreProbe(root, path));
   const artifactPaths = [...new Set([...artifactProbes(root, artifacts), ...existingPrivate, ...(location ? [...visibleArtifactProbes(root, location, artifacts), ...visiblePrivateProbes(root, location, clientRoots)] : [])])];
-  const wanted = new Set(probes.map(path => location?.prefix ? `${location.prefix}/${path}` : path));
   if (location && !before?.includes(first)) {
     const ignored = ignoreMatches(location, [...probes, ...artifactPaths].filter(path => safeIgnoreProbe(root, path)));
     if (ignored.paths.every(path => { const match = ignored.matches.get(path); return match && !match.pattern.startsWith('!') && localIgnoreSource(location, match.source); })) edits.length = 0;
@@ -436,14 +445,16 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   const tracked = location ? gitCommand(location.top, ['ls-files', '-z']).stdout.split('\0').filter(path => {
     if (!path.startsWith(prefix)) return false;
     const local = path.slice(prefix.length);
-    return wanted.has(path) || artifactPath(local, artifacts) || clientRoots.includes(local.split('/')[0]) && isGeneratedOutput(local);
+    // Git ignore never untracks existing files. Report private data and test
+    // artifacts, but don't flag legitimate already-tracked project content.
+    return artifactPath(local, artifacts) || clientRoots.includes(local.split('/')[0]) && isGeneratedOutput(local);
   }).map(path => path.slice(prefix.length)) : [];
-  return { root, status: location ? 'git' : 'no-git', location, paths, roots, clientRoots, artifactPatterns: artifacts, artifactProbes: artifactPaths, privateProbes: privateClients.probes, edits, trackedOutputs: tracked, first, last };
+  return { root, status: location ? 'git' : 'no-git', location, paths, outputPaths, roots, requestedRoots, optedRoots, clientRoots, artifactPatterns: artifacts, artifactProbes: artifactPaths, privateProbes: privateClients.probes, edits, trackedOutputs: tracked, first, last };
 }
 
 export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
   const missing = [];
-  if (plan.location) missing.push(...ambiguousExceptions(plan.root, plan.location, plan.clientRoots || [], plan.artifactPatterns || []), ...foreignHiddenClients(plan));
+  if (plan.location) missing.push(...((plan.requestedRoots || []).length ? ignoredProjectAncestors(plan.location) : []), ...ambiguousExceptions(plan.root, plan.location, plan.clientRoots || [], plan.artifactPatterns || []));
   const replacements = replacedBlocks.map(item => {
     const path = canonicalExisting(checkedLocalPath(resolve(item.path))), inside = relative(localRoot(plan.root).root, path);
     if (isAbsolute(inside) || inside === '..' || inside.startsWith(`..${sep}`) || !Number.isInteger(item.firstLine) || !Number.isInteger(item.lastLine) || item.firstLine < 1 || item.lastLine < item.firstLine || !/^[a-f0-9]{64}$/.test(item.sha256)) throw new Error('Faixa de ignore gerenciado invalida.');
@@ -456,9 +467,9 @@ export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
     return { ...item, path };
   });
   if (plan.location && (plan.paths.length || plan.artifactProbes?.length)) {
-    missing.push(...plan.paths.filter(path => !safeIgnoreProbe(plan.root, path)));
+    missing.push(...new Set([...plan.paths, ...(plan.outputPaths || [])].filter(path => !safeIgnoreProbe(plan.root, path))));
     const privateProbes = (plan.privateProbes || []).filter(path => localStat(join(plan.root, path.split('/')[0]))?.isDirectory() && safeIgnoreProbe(plan.root, path));
-    const probes = [...new Set([...plan.paths, ...rootProbes(plan.root, plan.roots || []), ...(plan.artifactProbes || []), ...privateProbes,
+    const probes = [...new Set([...plan.paths, ...rootProbes(plan.root, (plan.roots || []).filter(client => !(plan.optedRoots || []).includes(client))), ...(plan.artifactProbes || []), ...privateProbes,
       ...(plan.artifactPatterns ? visibleArtifactProbes(plan.root, plan.location, plan.artifactPatterns) : []),
       ...visiblePrivateProbes(plan.root, plan.location, plan.clientRoots || [])])].filter(path => safeIgnoreProbe(plan.root, path));
     const { paths: relativePaths, matches } = ignoreMatches(plan.location, probes);
@@ -481,12 +492,13 @@ export function assertLocalIgnoreUnchanged(plan) {
   }
 }
 
-function atomicLocalWrite(path, content, mode, published) {
+function atomicLocalWrite(path, content, mode, published, beforePublish) {
   const temporary = `${path}.agentdevkit-${randomUUID()}`;
   try {
     writeFileSync(temporary, content, { flag: 'wx' });
     if (mode !== null && mode !== undefined) chmodSync(temporary, mode);
     const writtenMode = localMode(temporary);
+    beforePublish?.();
     renameSync(temporary, path);
     published?.(writtenMode);
   } finally { rmSync(temporary, { force: true }); }
@@ -500,7 +512,10 @@ export function applyLocalIgnore(plan) {
   try {
     for (const edit of plan.edits) {
       mkdirSync(dirname(edit.path), { recursive: true });
-      atomicLocalWrite(edit.path, edit.after, edit.beforeMode, mode => written.push({ edit, mode }));
+      atomicLocalWrite(edit.path, edit.after, edit.beforeMode, mode => written.push({ edit, mode }), () => {
+        checkedLocalPath(edit.path);
+        if (localRead(edit.path) !== edit.before || localMode(edit.path) !== edit.beforeMode) throw new Error(`Exclusao alterada antes de publicar; conteudo preservado: ${edit.path}`);
+      });
     }
     const verified = checkLocalIgnore({ ...plan, edits: [], trackedOutputs: [] });
     if (verified.missing.length) throw new Error(`Regras humanas reabrem derivados locais: ${verified.missing.join(', ')}`);
@@ -509,7 +524,12 @@ export function applyLocalIgnore(plan) {
     for (const { edit, mode } of written.reverse()) {
       try {
         if (localRead(edit.path) !== edit.after || localMode(edit.path) !== mode) continue;
-        if (edit.before === null) rmSync(edit.path, { force: true }); else atomicLocalWrite(edit.path, edit.before, edit.beforeMode);
+        const checkPublished = () => {
+          checkedLocalPath(edit.path);
+          if (localRead(edit.path) !== edit.after || localMode(edit.path) !== mode) throw new Error(`Exclusao alterada durante rollback; conteudo preservado: ${edit.path}`);
+        };
+        if (edit.before === null) { checkPublished(); rmSync(edit.path, { force: true }); }
+        else atomicLocalWrite(edit.path, edit.before, edit.beforeMode, undefined, checkPublished);
       } catch (failure) { rollbackErrors.push(failure); }
     }
     if (rollbackErrors.length) throw new AggregateError([error, ...rollbackErrors], `${error.message}; rollback incompleto: ${rollbackErrors.map(failure => failure.message).join('; ')}`, { cause: error });

package/.pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs

@@ -49,6 +49,20 @@ export function validateToolConfig(name, value) {
       }
     }
   }
+  if (value.optionalExecutables !== undefined) {
+    if (download.provider !== 'npm' || !value.optionalExecutables || typeof value.optionalExecutables !== 'object' || Array.isArray(value.optionalExecutables) || !Object.keys(value.optionalExecutables).length) fail(`Mapa de executaveis opcionais invalido: ${name}`);
+    for (const [platform, files] of Object.entries(value.optionalExecutables)) {
+      if (!value.platforms.includes(platform) || !Array.isArray(files) || !files.length) fail(`Plataforma de executaveis opcionais invalida: ${name}/${platform}`);
+      const seen = new Set();
+      for (const item of files) {
+        if (!item || typeof item !== 'object' || Array.isArray(item) || Object.keys(item).sort().join(',') !== 'file,package'
+          || !/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(item.package || '') || seen.has(item.package)
+          || typeof item.file !== 'string' || !item.file || item.file.includes('\0') || item.file.includes('\\') || item.file.includes(':')
+          || item.file.split('/').some(part => !part || part === '.' || part === '..')) fail(`Executavel opcional deve ser relativo ao pacote: ${name}`);
+        seen.add(item.package);
+      }
+    }
+  }
   if (value.scripts?.entry !== 'SCRIPT.mjs' || Object.keys(value.scripts).length !== 1) fail(`Script invalido; use scripts.entry=SCRIPT.mjs: ${name}`);
   if (value.nodeMinimum !== undefined) fail(`nodeMinimum foi substituido pelo requisito comum Node >=24: ${name}`);
   const environmentKeys = new Set();
@@ -162,7 +176,7 @@ export function binaryInvocation(prefix, name, args = [], binaryName = name.spli
   if (typeof bin !== 'string' || !bin || bin.includes('\0')) fail(`Executavel ausente ou invalido: ${name}`);
   const binary = resolve(base, bin); const traversal = relative(base, binary);
   if (isAbsolute(traversal) || traversal === '..' || traversal.startsWith('..' + (process.platform === 'win32' ? '\\' : '/'))) fail('Executavel fora do pacote.');
-  const resolved = relative(prefix, realpathSync(binary));
+  const resolved = relative(realpathSync(prefix), realpathSync(binary));
   if (isAbsolute(resolved) || resolved === '..' || resolved.startsWith('..' + (process.platform === 'win32' ? '\\' : '/'))) fail('Executavel fora da instalacao local.');
   const header = Buffer.alloc(128); const handle = openSync(binary, 'r');
   try { readSync(handle, header, 0, header.length, 0); } finally { closeSync(handle); }
@@ -203,25 +217,57 @@ function execute(prefix, entry, args, capture = false, input, environment, runti
   return result.status ?? 1;
 }
 
-function prepareExecutables(prefix, entry, platform) {
-  const files = entry.executables?.[platform];
-  if (!files || process.platform === 'win32') return;
+async function prepareExecutables(prefix, entry, platform, pkg, lock, fetchOptional) {
+  const files = entry.executables?.[platform] || [];
+  const optional = entry.optionalExecutables?.[platform] || [];
+  if (!files.length && !optional.length) return;
   const within = (base, file) => { const child = relative(base, file); return !isAbsolute(child) && child !== '..' && !child.startsWith(`..${sep}`); };
   const stage = realpathSync(prefix);
   const packageRoot = realpathSync(join(prefix, 'node_modules', entry.download.package));
   if (!within(stage, packageRoot)) fail(`Pacote fora do staging: ${entry.name}`);
-  const targets = files.map(file => {
-    const target = realpathSync(join(packageRoot, file));
-    if (!within(packageRoot, target)) fail(`Executavel fora do pacote: ${entry.name}/${file}`);
+  const declared = optional.filter(item => Object.hasOwn(pkg.optionalDependencies || {}, item.package));
+  const targets = [];
+  const collect = (base, file, label) => {
+    const target = realpathSync(join(base, file));
+    if (!within(base, target)) fail(`Executavel fora do pacote: ${label}`);
     const info = lstatSync(target);
-    if (!info.isFile()) fail(`Executavel nao e arquivo regular: ${entry.name}/${file}`);
-    return { target, mode: (info.mode & 0o777) | 0o111 };
-  });
-  for (const { target, mode } of targets) chmodSync(target, mode);
+    if (!info.isFile()) fail(`Executavel nao e arquivo regular: ${label}`);
+    targets.push({ target, mode: (info.mode & 0o777) | 0o111 });
+  };
+  // Older releases contain all of their binaries in the main package. Newer
+  // releases declare a host package; inspect every legacy file that exists so
+  // the upstream launcher cannot prefer an unchecked file over that package.
+  for (const file of files) {
+    let exists = false;
+    try { lstatSync(join(packageRoot, file)); exists = true; } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (exists || !declared.length) collect(packageRoot, file, `${entry.name}/${file}`);
+  }
+  if (declared.length) {
+    let installed = 0;
+    for (const item of declared) {
+      const version = pkg.optionalDependencies[item.package];
+      if (!versionPattern.test(version || '')) fail(`Versao de executavel opcional invalida: ${item.package}`);
+      const directory = sourcePath(prefix, join('node_modules', item.package));
+      try { lstatSync(directory); } catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+      const optionalRoot = realpathSync(directory);
+      if (!within(realpathSync(join(prefix, 'node_modules')), optionalRoot)) fail(`Pacote opcional fora de node_modules: ${item.package}`);
+      const manifest = json(join(optionalRoot, 'package.json'));
+      const record = lock.packages?.[`node_modules/${item.package}`];
+      const official = await fetchOptional(item.package, version);
+      const tarball = new URL(official.dist?.tarball);
+      if (official.name !== item.package || official.version !== version || tarball.origin !== registry.slice(0, -1)
+        || !decodeURIComponent(tarball.pathname).startsWith(`/${item.package}/-/`) || tarball.search || tarball.hash
+        || !official.dist?.integrity?.startsWith('sha512-') || manifest.name !== item.package || manifest.version !== version
+        || record?.version !== version || record.integrity !== official.dist.integrity || record.resolved !== official.dist.tarball) fail(`Pacote opcional instalado nao corresponde ao registro oficial: ${item.package}`);
+      collect(optionalRoot, item.file, `${item.package}/${item.file}`); installed++;
+    }
+    if (!installed) fail(`Executavel opcional ausente para ${entry.name}/${platform}; instale as dependencias opcionais.`);
+  }
+  if (process.platform !== 'win32') for (const { target, mode } of targets) chmodSync(target, mode);
 }
 
 export class ToolManager {
-  constructor({ root = projectRoot, catalog, fetchRelease, install, npm = npmCli, nodeVersion = process.versions.node, platform = process.platform, arch = process.arch } = {}) {
+  constructor({ root = projectRoot, catalog, fetchRelease, fetchOptional, install, npm = npmCli, nodeVersion = process.versions.node, platform = process.platform, arch = process.arch } = {}) {
     this.root = resolve(root); this.home = join(this.root, '.pbai4devs/tools'); this.target = `${platform}-${arch}`;
     this.nodeVersion = nodeVersion; this.npm = npm;
     this.catalog = catalog ?? loadCatalog(this.root);
@@ -232,11 +278,19 @@ export class ToolManager {
       if (!response.ok) fail(`Registro indisponivel: HTTP ${response.status}`);
       return response.json();
     });
+    this.fetchOptional = fetchOptional || (async (name, version) => {
+      const response = await fetch(`${registry}${encodeURIComponent(name)}/${version}`, { signal: AbortSignal.timeout(20000) });
+      if (!response.ok) fail(`Registro indisponivel para ${name}: HTTP ${response.status}`);
+      return response.json();
+    });
     this.installPackage = install || (async (prefix, packageName, version, entry, runtime) => {
       if (entry.download.provider === 'github-release') return installNative(prefix, entry, this.target);
       const environment = toolEnvironment(entry, this.local(entry.name), runtime);
-      const result = spawnSync(runtime.file, [this.npm(runtime, environment), 'install', '--prefix', prefix, '--cache', join(this.home, '.cache/npm'), '--registry', entry.download.registry, '--ignore-scripts', '--omit=dev', '--no-audit', '--no-fund', '--save-exact', `${packageName}@${version}`], {
-        cwd: prefix, encoding: 'utf8', timeout: 180000,
+      // npm resolves cwd but not --prefix, yielding invalid lock paths when
+      // ancestors are aliases such as macOS /var -> /private/var.
+      const npmPrefix = realpathSync(storagePath(this.root, prefix, 'directory'));
+      const result = spawnSync(runtime.file, [this.npm(runtime, environment), 'install', '--prefix', npmPrefix, '--cache', join(this.home, '.cache/npm'), '--registry', entry.download.registry, '--ignore-scripts', '--omit=dev', '--no-audit', '--no-fund', '--save-exact', `${packageName}@${version}`], {
+        cwd: npmPrefix, encoding: 'utf8', timeout: 180000,
         env: { ...environment, npm_config_engine_strict: 'true', npm_config_update_notifier: 'false', PUPPETEER_SKIP_DOWNLOAD: 'true', PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: '1' }
       });
       if (result.error || result.status !== 0) fail(`npm: ${result.error?.message || result.stderr?.trim() || result.status}`, result.status ?? 1);
@@ -438,7 +492,7 @@ export class ToolManager {
       else {
         const pkg = json(join(stage, 'node_modules', entry.download.package, 'package.json')); const lock = json(join(stage, 'package-lock.json'));
         if (pkg.name !== entry.download.package || pkg.version !== release.version || lock.packages?.[`node_modules/${entry.download.package}`]?.integrity !== release.dist.integrity) fail('Pacote instalado nao corresponde ao registro.');
-        prepareExecutables(stage, entry, this.target);
+        await prepareExecutables(stage, entry, this.target, pkg, lock, this.fetchOptional);
       }
       execute(stage, entry, entry.probe, true, entry.probeInput, toolEnvironment(entry, local, runtime), runtime);
       this.storage(name); storagePath(this.root, target, 'directory');

package/.pbai4devs/scripts/preparar-ferramentas/tests/TEST.mjs

@@ -1,6 +1,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, readdirSync, existsSync, copyFileSync, symlinkSync, unlinkSync, chmodSync, statSync, renameSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, readdirSync, existsSync, copyFileSync, symlinkSync, unlinkSync, chmodSync, statSync, renameSync, realpathSync } from 'node:fs';
 import { resolve, join, dirname, delimiter } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
@@ -519,6 +519,26 @@ writeFileSync(join(prefix, 'npm-proof.json'), JSON.stringify({args,path:process.
   assert.equal(JSON.parse(readFileSync(join(local, 'CURRENT.json'), 'utf8')).nodePath, process.execPath);
 });
 
+test('npm recebe staging canonico quando a raiz usa alias simbolico', async t => {
+  const config = tool(); const { root } = fixture(t, { 'test-tool': config });
+  const alias = join(root, 'project-alias');
+  if (!createSymlink(t, root, alias, 'dir')) return;
+  const npm = join(root, 'fake-npm.cjs');
+  writeFileSync(npm, `const { mkdirSync, writeFileSync, realpathSync } = require('node:fs');
+const { join } = require('node:path');
+${packageFiles.toString()}
+const prefix = process.argv[process.argv.indexOf('--prefix') + 1];
+if (prefix !== realpathSync(prefix) || process.cwd() !== prefix) process.exit(91);
+packageFiles(prefix, 'test-tool', '1.0.0');
+writeFileSync(join(prefix, 'canonical-proof.json'), JSON.stringify({prefix,cwd:process.cwd()}));
+`);
+  const manager = new ToolManager({ root: alias, catalog: { 'test-tool': config }, npm: () => npm, fetchRelease: async () => release('1.0.0') });
+  const installed = await manager.install('test-tool');
+  const proof = JSON.parse(readFileSync(join(installed.prefix, 'canonical-proof.json'), 'utf8'));
+  assert.equal(proof.cwd, proof.prefix); assert.ok(proof.prefix.startsWith(realpathSync(root)));
+  assert.equal(manager.check('test-tool').version, '1.0.0');
+});
+
 test('setup padrao prepara todas as ferramentas compativeis e confirma cada instalacao', async t => {
   const unsupported = { ...tool('unsupported-tool'), platforms: [process.platform === 'darwin' ? 'linux-x64' : 'darwin-arm64'] };
   const { root, manager, state, local } = fixture(t, { 'test-tool': tool(), 'unsupported-tool': unsupported });
@@ -599,6 +619,62 @@ test('executables valida plataforma e caminhos relativos sem autorizar comandos
   }
 });
 
+test('executaveis opcionais validam pacotes e caminhos sem permitir escapes', () => {
+  const target = platformKey(); const base = tool();
+  const good = { [target]: [{ package: '@owner/cli-host', file: 'bin/probe' }] };
+  assert.deepEqual(validateToolConfig('test-tool', { ...base, optionalExecutables: good }).optionalExecutables, good);
+  for (const item of [
+    { package: '../outside', file: 'bin/probe' }, { package: '@owner/cli-host', file: '../outside' },
+    { package: '@owner/cli-host', file: '/absolute' }, { package: '@owner/cli-host', file: 'C:\\outside' },
+    { package: '@owner/cli-host', file: 'bin/probe', extra: true }
+  ]) assert.throws(() => validateToolConfig('test-tool', { ...base, optionalExecutables: { [target]: [item] } }), /opcional|relativo/);
+  assert.throws(() => validateToolConfig('test-tool', { ...base, optionalExecutables: { [target]: [good[target][0], good[target][0]] } }), /relativo/);
+});
+
+test('atualizacao aceita layout opcional e preserva versao anterior se dependencia falhar', async t => {
+  const targets = process.platform === 'win32' ? [platformKey()] : [platformKey(), 'win32-x64'];
+  for (const target of targets) await t.test(target, async subtest => {
+    const name = '@owner/cli-host'; const isWindowsTarget = target.startsWith('win32-');
+    const config = { ...tool(), platforms: [target], ...(!isWindowsTarget ? { executables: { [target]: ['bin/legacy'] } } : {}), optionalExecutables: { [target]: [{ package: name, file: 'bin/probe' }] } };
+    const [platform, arch] = target.split('-');
+    const { manager, state, local, root } = fixture(subtest, { 'test-tool': config }, { platform, arch });
+    let scenario = 'legacy'; const outside = join(root, 'outside-native'); const probe = join(root, 'probe-executado'); writeFileSync(outside, 'untouched'); chmodSync(outside, 0o644);
+    const officialTarball = version => `https://registry.npmjs.org/${name}/-/cli-host-${version}.tgz`;
+    manager.fetchOptional = async (pkgName, version) => ({ name: pkgName, version, dist: { tarball: officialTarball(version), integrity: 'sha512-fixture' } });
+    manager.installPackage = (prefix, pkgName, version) => {
+      packageFiles(prefix, pkgName, version);
+      const base = join(prefix, 'node_modules', pkgName); mkdirSync(join(base, 'bin'));
+      if (scenario === 'legacy') { writeFileSync(join(base, 'bin/legacy'), 'legacy'); return; }
+      const manifestFile = join(base, 'package.json'); const manifest = JSON.parse(readFileSync(manifestFile));
+      manifest.optionalDependencies = { [name]: version }; writeFileSync(manifestFile, JSON.stringify(manifest));
+      writeFileSync(join(base, 'cli.cjs'), `require('node:fs').writeFileSync(${JSON.stringify(probe)}, 'executado'); console.log(${JSON.stringify(version)});`);
+      if (scenario === 'missing') return;
+      const optional = join(prefix, 'node_modules', name);
+      if (scenario === 'package-link') { mkdirSync(dirname(optional), { recursive: true }); symlinkSync(root, optional, 'dir'); return; }
+      mkdirSync(join(optional, 'bin'), { recursive: true });
+      writeFileSync(join(optional, 'package.json'), JSON.stringify({ name, version: scenario === 'version' ? '9.9.9' : version }));
+      const lockFile = join(prefix, 'package-lock.json'); const lock = JSON.parse(readFileSync(lockFile));
+      lock.packages[`node_modules/${name}`] = { version, integrity: scenario === 'integrity' ? 'sha512-other-registry' : 'sha512-fixture', resolved: scenario === 'registry' ? `https://example.invalid/${name}/-/cli-host-${version}.tgz` : officialTarball(version) };
+      writeFileSync(lockFile, JSON.stringify(lock));
+      if (scenario === 'escape') symlinkSync(outside, join(optional, 'bin/probe'));
+      else { writeFileSync(join(optional, 'bin/probe'), 'probe'); chmodSync(join(optional, 'bin/probe'), 0o644); }
+      if (scenario === 'legacy-escape') symlinkSync(outside, join(base, 'bin/legacy'));
+    };
+    await manager.install('test-tool'); const before = readFileSync(join(local, 'CURRENT.json'), 'utf8'); state.version = '2.0.0';
+    for (scenario of ['missing', 'version', 'integrity', 'registry', ...(process.platform === 'win32' ? [] : ['escape', 'package-link', ...(!isWindowsTarget ? ['legacy-escape'] : [])])]) {
+      await assert.rejects(manager.update('test-tool'), /ausente|corresponde|fora do pacote|nao pode ser um link/);
+      assert.equal(readFileSync(join(local, 'CURRENT.json'), 'utf8'), before);
+      assert.equal(manager.check('test-tool').version, '1.0.0');
+      assert.equal(existsSync(probe), false);
+      assert.ok(readdirSync(local).every(entry => !entry.startsWith('.stage-')));
+    }
+    if (process.platform !== 'win32') assert.equal(statSync(outside).mode & 0o777, 0o644);
+    scenario = 'optional'; const updated = await manager.update('test-tool');
+    assert.equal(updated.version, '2.0.0'); assert.equal(manager.check('test-tool').version, '2.0.0');
+    if (process.platform !== 'win32') assert.equal(statSync(join(updated.prefix, 'node_modules', name, 'bin/probe')).mode & 0o777, 0o755);
+  });
+});
+
 test('executables prepara somente binarios da plataforma no staging antes de executar probe real', { skip: process.platform === 'win32' }, async t => {
   const other = process.platform === 'darwin' ? 'linux-x64' : 'darwin-arm64';
   const config = { ...tool(), platforms: [platformKey(), other], executables: { [platformKey()]: ['native/probe with space'], [other]: ['native/unused'] } };

package/.pbai4devs/scripts/sincronizar-agentes/README.md

@@ -38,16 +38,14 @@ Após a instalação, depende somente de Node e do hub local, sem o pacote npm.
 Ele respeita os clientes escolhidos, sem recriar os desmarcados. Para trocar
 a seleção, use `agentdevkit agents <lista>`; não edite o manifesto gerado.
 
-Os derivados ficam locais: catálogos, manifesto, estado e apontamentos são
-excluídos pelo Git. O bloco em `.git/info/exclude` preserva regras próprias;
-sem Git, informa que a proteção fica pendente até `git init` e sincronização.
-Somente arquivos integralmente gerados são excluídos; pastas de clientes podem
-conter arquivos humanos versionados. Conteúdo próprio não é desindexado pela
-presença de um bloco gerenciado.
+O bloco local em `.git/info/exclude` ignora as pastas de clientes por padrão;
+sem Git, a proteção fica pendente até `git init` e sincronização. Para incluir
+uma pasta, use uma exceção literal no `.gitignore` da raiz, como `!/.claude/`.
+Isso também vale para `.github` e `.vscode`, que podem conter arquivos humanos.
+Arquivos já rastreados e o índice não são alterados automaticamente.
 Entradas novas usam os templates; hashes em `state/derived.json` permitem
 atualizar arquivos gerados e blocos separadamente, preservando alterações humanas.
-`--check` também acusa derivados ainda rastreados; não altera o índice.
+`--check` somente verifica; não altera o índice.
 Apontamentos obsoletos podem ser removidos quando a propriedade é comprovada;
 arquivos e pastas próprios, inclusive os adicionais dentro do mesmo recurso,
-devem permanecer. Na CLI, confira `untrackedPaths` antes de aplicar: saídas
-geradas comprovadas podem deixar de ser rastreadas, sem excluir seus bytes.
+devem permanecer.

package/.pbai4devs/scripts/sincronizar-agentes/tests/LOCAL_IGNORE.mjs

@@ -42,7 +42,7 @@ test('sem Git preserva ignore e informa pendência; após git init protege outpu
   git(root, ['add', '--all']);
   const tracked = git(root, ['ls-files', '-z']).split('\0').filter(Boolean);
   for (const path of outputs) assert.equal(tracked.includes(path), false, path);
-  for (const path of ['.github/workflows/ci.yml', '.github/ISSUE_TEMPLATE/bug.yml', '.vscode/settings.json', '.github/skills/human/SKILL.md']) assert.ok(tracked.includes(path), path);
+  for (const path of ['.github/workflows/ci.yml', '.github/ISSUE_TEMPLATE/bug.yml', '.vscode/settings.json', '.github/skills/human/SKILL.md']) assert.equal(tracked.includes(path), false, path);
 });
 
 test('prefixos e projetos distintos preservam blocos locais independentes', t => {
@@ -58,13 +58,49 @@ test('prefixos e projetos distintos preservam blocos locais independentes', t =>
   assert.match(content, /first\\ space/); assert.match(content, /second/);
 });
 
-test('check identifica negação humana e outputs rastreados sem alterar o índice', t => {
+test('projeto aninhado sob ancestral ignorado falha antes de alterar índices ou excludes', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, '.gitignore', '/.github/\n');
+  const child = join(root, '.github/project');
+  put(child, '.gitignore', '!/.claude/\n');
+  put(child, '.claude/custom.md', 'instruções próprias\n');
+  const exclude = readFileSync(join(root, '.git/info/exclude'));
+  const index = git(root, ['ls-files', '--stage', '-z']);
+  const plan = planLocalIgnore(child, { outputs: ['.claude/custom.md'] });
+  assert.ok(checkLocalIgnore(plan).missing.some(value => value.includes('Ancestral Git ignorado: .github/')));
+  assert.throws(() => applyLocalIgnore(plan), /Ancestral Git ignorado/);
+  assert.deepEqual(readFileSync(join(root, '.git/info/exclude')), exclude);
+  assert.equal(git(root, ['ls-files', '--stage', '-z']), index);
+  assert.equal(readFileSync(join(child, '.claude/custom.md'), 'utf8'), 'instruções próprias\n');
+  put(root, '.gitignore', '/.github/\n!/.github/\n');
+  const opened = planLocalIgnore(child, { outputs: ['.claude/custom.md'] });
+  applyLocalIgnore(opened);
+  assert.equal(checkLocalIgnore(planLocalIgnore(child, { outputs: ['.claude/custom.md'] })).ok, true);
+  assert.equal(spawnSync('git', ['-C', root, 'check-ignore', '--no-index', '-q', '.github/project/.claude/custom.md']).status, 1);
+});
+
+test('opt-in aninhado respeita também excludesFile configurado pelo usuário', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, 'global-ignore', '/.private/\n');
+  git(root, ['config', '--local', 'core.excludesFile', join(root, 'global-ignore')]);
+  const child = join(root, '.private/project');
+  put(child, '.gitignore', '!/.claude/\n');
+  put(child, '.claude/custom.md', 'instruções próprias\n');
+  const before = readFileSync(join(root, '.git/info/exclude'));
+  const plan = planLocalIgnore(child);
+  assert.ok(checkLocalIgnore(plan).missing.some(value => value.includes('Ancestral Git ignorado: .private/')));
+  assert.throws(() => applyLocalIgnore(plan), /Ancestral Git ignorado/);
+  assert.deepEqual(readFileSync(join(root, '.git/info/exclude')), before);
+  assert.equal(readFileSync(join(child, '.claude/custom.md'), 'utf8'), 'instruções próprias\n');
+});
+
+test('check identifica negação humana sem alterar nem diagnosticar conteúdo rastreado legítimo', t => {
   const root = fixture(t), outputs = ['generated.md']; git(root, ['init', '-q']);
   put(root, 'generated.md', 'gerado'); git(root, ['add', 'generated.md']);
   applyLocalIgnore(planLocalIgnore(root, { outputs }));
   put(root, '.gitignore', '!/generated.md\n');
   const result = checkLocalIgnore(planLocalIgnore(root, { outputs }));
-  assert.equal(result.ok, false); assert.deepEqual(result.missing, outputs); assert.deepEqual(result.trackedOutputs, outputs);
+  assert.equal(result.ok, false); assert.deepEqual(result.missing, outputs); assert.deepEqual(result.trackedOutputs, []);
   assert.equal(git(root, ['ls-files', 'generated.md']).trim(), 'generated.md');
 });
 
@@ -89,7 +125,7 @@ test('exceções de templates preservam o ignore raiz e protegem dados privados'
   assert.ok(git(root, ['check-ignore', '--no-index', '.cursor/.CACHE/private.json']).includes('.cursor/.CACHE/private.json'));
   assert.ok(git(root, ['check-ignore', '--no-index', '.cursor/.cache/private.json']).includes('.cursor/.cache/private.json'));
   const visible = spawnSync('git', ['-C', root, 'check-ignore', '--no-index', '-q', '.cursor/human.md']);
-  assert.equal(visible.status, 1);
+  assert.equal(visible.status, 0);
   applyLocalIgnore(planLocalIgnore(root));
   assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), updated);
   put(root, '.gitignore', updated + '# edição humana posterior\n');
@@ -134,12 +170,12 @@ test('negação humana posterior é informada sem reescrever a raiz', t => {
   const root = fixture(t); git(root, ['init', '-q']);
   put(root, '.gitignore', '# humano\n'); applyLocalIgnore(planLocalIgnore(root));
   const path = join(root, '.gitignore');
-  writeFileSync(path, readFileSync(path, 'utf8') + '!/.cursor/.env.production\n');
+  writeFileSync(path, readFileSync(path, 'utf8') + '!/.cursor/\n!/.cursor/.env.production\n');
   put(root, '.cursor/.env.production', 'privado');
   const plan = planLocalIgnore(root);
   assert.ok(checkLocalIgnore(plan).missing.includes('.cursor/.env.production'));
   assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
-  assert.equal(readFileSync(path, 'utf8'), '# humano\n!/.cursor/.env.production\n');
+  assert.equal(readFileSync(path, 'utf8'), '# humano\n!/.cursor/\n!/.cursor/.env.production\n');
 });
 
 test('planejamento sem Git não modifica ignore nem edição humana posterior', t => {
@@ -193,11 +229,13 @@ test('desindexação não descarta edição humana staged com workingtree restau
   assert.equal(readFileSync(join(root, 'generated.md'), 'utf8'), 'gerado\n');
 });
 
-test('configurações humanas dos clientes continuam versionáveis', t => {
+test('configurações humanas podem ser versionadas após exceção explícita', t => {
   const root = fixture(t); git(root, ['init', '-q']);
   applyLocalIgnore(planLocalIgnore(root));
   put(root, '.codex/config.toml', 'local'); put(root, '.claude/settings.json', 'local');
   put(root, '.github/settings.json', 'fonte'); put(root, '.vscode/settings.json', 'fonte');
+  put(root, '.gitignore', '!/.codex/\n!/.claude/\n!/.github/\n!/.vscode/\n');
+  assert.equal(checkLocalIgnore(planLocalIgnore(root)).ok, true);
   git(root, ['add', '--all']);
   const tracked = git(root, ['ls-files', '-z']).split('\0');
   assert.equal(tracked.includes('.codex/config.toml'), true);
@@ -205,6 +243,53 @@ test('configurações humanas dos clientes continuam versionáveis', t => {
   assert.ok(tracked.includes('.github/settings.json')); assert.ok(tracked.includes('.vscode/settings.json'));
 });
 
+test('exceções de raiz usam precedência real e mantêm credenciais ignoradas', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, '.gitignore', '!/.claude/\n!/.github/\n');
+  put(root, '.claude/skills/team/SKILL.md', 'skill humana\n');
+  put(root, '.claude/auth.json', 'segredo');
+  put(root, '.github/workflows/ci.yml', 'workflow humano\n');
+  put(root, '.vscode/settings.json', 'configuração humana\n');
+  const original = readFileSync(join(root, '.gitignore'));
+  const plan = planLocalIgnore(root, { outputs: ['.claude/skills/team/SKILL.md', '.github/workflows/ci.yml'] });
+  assert.ok(plan.optedRoots.includes('.claude'));
+  assert.ok(plan.optedRoots.includes('.github'));
+  applyLocalIgnore(plan);
+  assert.equal(checkLocalIgnore(planLocalIgnore(root)).ok, true);
+  for (const path of ['.claude/skills/team/SKILL.md', '.github/workflows/ci.yml']) {
+    assert.equal(spawnSync('git', ['-C', root, 'check-ignore', '--no-index', '-q', path]).status, 1, path);
+  }
+  for (const path of ['.claude/auth.json', '.vscode/settings.json']) {
+    assert.equal(spawnSync('git', ['-C', root, 'check-ignore', '--no-index', '-q', path]).status, 0, path);
+  }
+  assert.deepEqual(readFileSync(join(root, '.gitignore')), original);
+  put(root, '.gitignore', '!/.claude/\n/.claude/\n');
+  const overridden = planLocalIgnore(root);
+  assert.equal(overridden.optedRoots.includes('.claude'), false);
+  assert.equal(spawnSync('git', ['-C', root, 'check-ignore', '--no-index', '-q', '.claude/skills/team/SKILL.md']).status, 0);
+  put(root, '.gitignore', '!/.claude/\n!/.claude/**\n');
+  assert.throws(() => applyLocalIgnore(planLocalIgnore(root)), /Regras humanas/);
+});
+
+test('derivados e entradas legítimas já rastreados permanecem no índice com ou sem opt-in', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, '.claude/skills/team/SKILL.md', 'skill rastreada\n');
+  put(root, '.github/workflows/ci.yml', 'workflow rastreado\n');
+  put(root, 'AGENTS.md', 'instruções rastreadas\n');
+  git(root, ['add', '--all']);
+  const before = git(root, ['ls-files', '--stage', '-z']);
+  const outputs = ['.claude/skills/team/SKILL.md', '.github/workflows/ci.yml', 'AGENTS.md'];
+  applyLocalIgnore(planLocalIgnore(root, { outputs }));
+  assert.equal(checkLocalIgnore(planLocalIgnore(root, { outputs })).ok, true);
+  assert.equal(git(root, ['ls-files', '--stage', '-z']), before);
+  put(root, '.gitignore', '!/.claude/\n');
+  const opted = planLocalIgnore(root, { outputs });
+  assert.ok(opted.optedRoots.includes('.claude'));
+  applyLocalIgnore(opted);
+  assert.equal(checkLocalIgnore(planLocalIgnore(root, { outputs })).ok, true);
+  assert.equal(git(root, ['ls-files', '--stage', '-z']), before);
+});
+
 test('artefatos vêm da política compartilhada e rastreados são informados', t => {
   const root = fixture(t); git(root, ['init', '-q']);
   put(root, '.agent-tests/human.txt', 'evidência humana'); git(root, ['add', '-f', '.agent-tests/human.txt']);
@@ -271,12 +356,13 @@ test('probes reconhecem exceções humanas para nomes reais de Playwright', asyn
   });
 });
 
-test('milhares de caminhos usam stdin e não ampliam metadata de área já ignorada', t => {
+test('milhares de caminhos usam stdin sem ampliar metadata de área já ignorada', t => {
   const root = fixture(t); git(root, ['init', '-q']); put(root, '.gitignore', '/ignored/\n');
   const before = readFileSync(join(root, '.git/info/exclude'), 'utf8');
   const target = join(root, 'ignored'); mkdirSync(target);
-  const outputs = Array.from({ length: 1500 }, (_, index) => `.github/skills/generated-${index}-${'x'.repeat(45)}/SKILL.md`);
+  const outputs = Array.from({ length: 1500 }, (_, index) => `generated-${index}-${'x'.repeat(45)}.md`);
   const plan = planLocalIgnore(target, { outputs });
+  assert.ok(plan.paths.length >= 1500);
   assert.deepEqual(plan.edits, []); assert.equal(checkLocalIgnore(plan).ok, true);
   applyLocalIgnore(plan); assert.equal(readFileSync(join(root, '.git/info/exclude'), 'utf8'), before);
   assert.deepEqual(planUntrack(target, Object.fromEntries(outputs.map(path => [path, 'a'.repeat(64)]))).paths, []);
@@ -341,16 +427,17 @@ test('cliente não selecionado com symlink próprio não é atravessado pelo pro
   assert.deepEqual(readdirSync(outside), before);
 });
 
-test('preflight dispensa somente regras de bloco substituído com hash válido', t => {
+test('preflight valida hash do bloco substituído sem impor exclusão sobre cliente optado', t => {
   const root = fixture(t); git(root, ['init', '-q']);
   const block = '# BEGIN AGENT IGNORE\r\n!/generated.md\r\n# END AGENT IGNORE';
+  put(root, '.gitignore', '!/.github/\n');
   put(root, '.github/.gitignore', `# Humano\r\n${block}\r\n!/human.md\r\n`);
   const plan = planLocalIgnore(root, { outputs: ['.github/generated.md', '.github/human.md'] });
   const replacement = { path: join(root, '.github/.gitignore'), firstLine: 2, lastLine: 4, sha256: createHash('sha256').update(block).digest('hex') };
-  assert.deepEqual(checkLocalIgnore(plan).missing, ['.github/generated.md', '.github/human.md']);
-  assert.deepEqual(checkLocalIgnore(plan, { replacedBlocks: [replacement] }).missing, ['.github/human.md']);
+  assert.deepEqual(checkLocalIgnore(plan).missing, []);
+  assert.deepEqual(checkLocalIgnore(plan, { replacedBlocks: [replacement] }).missing, []);
   assert.throws(() => checkLocalIgnore(plan, { replacedBlocks: [{ ...replacement, sha256: '0'.repeat(64) }] }), /Bloco de ignore mudou/);
-  assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
+  assert.doesNotThrow(() => applyLocalIgnore(plan));
   assert.equal(readFileSync(join(root, '.github/.gitignore'), 'utf8'), `# Humano\r\n${block}\r\n!/human.md\r\n`);
 });
 
@@ -490,14 +577,14 @@ test('dependências já ignoradas não causam conflito, mas ignores visíveis s
   assert.ok(checkLocalIgnore(planLocalIgnore(root)).missing.some(value => value.includes('!.playwright-*/')));
 });
 
-test('bloco antigo de outro caminho não oculta arquivos humanos silenciosamente', t => {
+test('bloco de outra worktree não bloqueia a política local de clientes', t => {
   const root = fixture(t); git(root, ['init', '-q']);
   const old = '# BEGIN AGENTDEVKIT LOCAL 0123456789abcdef\n/.claude/\n# END AGENTDEVKIT LOCAL 0123456789abcdef\n';
   put(root, '.git/info/exclude', old);
   const plan = planLocalIgnore(root);
-  assert.ok(checkLocalIgnore(plan).missing.includes('.claude/.agentdevkit-human-probe.md'));
-  assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
-  assert.equal(readFileSync(join(root, '.git/info/exclude'), 'utf8'), old);
+  assert.equal(checkLocalIgnore(plan).missing.length, 0);
+  assert.doesNotThrow(() => applyLocalIgnore(plan));
+  assert.ok(readFileSync(join(root, '.git/info/exclude'), 'utf8').startsWith(old));
 });
 
 test('artefatos já versionados são informados sem alterar o índice', t => {
@@ -555,6 +642,57 @@ test('escrita de exclusões preserva permissões e detecta alteração concorren
   assert.equal(statSync(exclude).mode & 0o777, 0o640);
 });
 
+test('alteração no exclude durante escrita temporária é preservada antes da promoção', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const file = join(root, '.git/info/exclude'), before = readFileSync(file, 'utf8');
+  const plan = planLocalIgnore(root), index = git(root, ['ls-files', '--stage', '-z']);
+  const write = fs.writeFileSync; let injected = false;
+  try {
+    fs.writeFileSync = (path, content, options) => {
+      const value = write(path, content, options);
+      if (!injected && String(path).startsWith(`${file}.agentdevkit-`)) {
+        injected = true;
+        write(file, `${before}\n# regra humana concorrente\n`);
+      }
+      return value;
+    };
+    syncBuiltinESMExports();
+    assert.throws(() => applyLocalIgnore(plan), /Exclusao alterada antes de publicar/);
+  } finally { fs.writeFileSync = write; syncBuiltinESMExports(); }
+  assert.equal(injected, true);
+  assert.equal(readFileSync(file, 'utf8'), `${before}\n# regra humana concorrente\n`);
+  assert.equal(git(root, ['ls-files', '--stage', '-z']), index);
+});
+
+test('alteração no exclude durante rollback não é substituída', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const file = join(root, '.git/info/exclude'), plan = planLocalIgnore(root);
+  const index = git(root, ['ls-files', '--stage', '-z']);
+  const write = fs.writeFileSync, remove = fs.rmSync;
+  let failed = false, injected = false;
+  try {
+    fs.rmSync = (path, options) => {
+      if (!failed && String(path).startsWith(`${file}.agentdevkit-`) && !existsSync(path)) {
+        failed = true; throw new Error('falha após promoção');
+      }
+      return remove(path, options);
+    };
+    fs.writeFileSync = (path, content, options) => {
+      const value = write(path, content, options);
+      if (failed && !injected && String(path).startsWith(`${file}.agentdevkit-`)) {
+        injected = true;
+        write(file, `${readFileSync(file, 'utf8')}\n# regra humana no rollback\n`);
+      }
+      return value;
+    };
+    syncBuiltinESMExports();
+    assert.throws(() => applyLocalIgnore(plan), /rollback incompleto.*conteudo preservado/s);
+  } finally { fs.rmSync = remove; fs.writeFileSync = write; syncBuiltinESMExports(); }
+  assert.equal(injected, true);
+  assert.match(readFileSync(file, 'utf8'), /# regra humana no rollback/);
+  assert.equal(git(root, ['ls-files', '--stage', '-z']), index);
+});
+
 test('ignore raiz mantém modo e bytes antes e depois de git init', { skip: process.platform === 'win32' }, t => {
   const root = fixture(t), ignore = join(root, '.gitignore');
   put(root, '.gitignore', '# humano\n'); chmodSync(ignore, 0o600);

package/.pbai4devs/scripts/verificar-recursos/tests/TEST.mjs

@@ -375,19 +375,36 @@ function ignoreFixture(t) {
   return context;
 }
 
-test('fontes novas permanecem elegíveis e derivados locais ficam fora do índice', t => {
+test('fontes permanecem elegíveis e pastas de clientes aceitam opt-in explícito', t => {
   const { root, file } = ignoreFixture(t);
   const outputs = ['.github/skills/generated/SKILL.md', '.vscode/.gitignore', '.github/.gitignore'];
-  applyLocalIgnore(planLocalIgnore(root, { outputs }));
-  const sources = ['src/new.mjs', 'bin/new.mjs', 'tests/new.test.mjs', 'scripts/release/new.mjs', '.github/workflows/own.yml', '.github/ISSUE_TEMPLATE/bug.yml', '.github/skills/human/SKILL.md', '.vscode/settings.json'];
+  const sources = ['src/new.mjs', 'bin/new.mjs', 'tests/new.test.mjs', 'scripts/release/new.mjs'];
+  const clients = ['.github/workflows/own.yml', '.github/ISSUE_TEMPLATE/bug.yml', '.github/skills/human/SKILL.md', '.vscode/settings.json'];
   const generated = [...outputs, '.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/espelhos.conf', '.pbai4devs/state/agentdevkit.json'];
-  for (const path of [...sources, ...generated]) file(path, 'fixture\n');
+  for (const path of [...sources, ...clients, ...generated.filter(path => !path.endsWith('/.gitignore'))]) file(path, 'fixture\n');
+  file('.github/auth.json', 'credencial local\n');
+  file('.vscode/logs/session.log', 'artefato local\n');
+  assert.equal(git(root, ['add', '--', clients[0], sources[0]]).status, 0);
+  const index = git(root, ['ls-files', '--stage', '-z']).stdout;
+  applyLocalIgnore(planLocalIgnore(root, { outputs }));
   assert.deepEqual(ignoredPaths(root, sources), []);
+  assert.deepEqual(new Set(ignoredPaths(root, clients)), new Set(clients));
   assert.deepEqual(new Set(ignoredPaths(root, generated)), new Set(generated));
+  assert.equal(git(root, ['ls-files', '--stage', '-z']).stdout, index);
+  for (const path of clients) assert.equal(readFileSync(join(root, path), 'utf8'), 'fixture\n', path);
+
+  const exceptions = '!/.github/\n!/.vscode/\n';
+  file('.gitignore', exceptions);
+  applyLocalIgnore(planLocalIgnore(root, { outputs }));
+  assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), exceptions);
+  assert.equal(git(root, ['ls-files', '--stage', '-z']).stdout, index);
+  assert.deepEqual(ignoredPaths(root, clients), []);
+  const privateFiles = ['.github/auth.json', '.vscode/logs/session.log'];
+  assert.deepEqual(new Set(ignoredPaths(root, privateFiles)), new Set(privateFiles));
   assert.equal(git(root, ['add', '--all']).status, 0);
   const tracked = git(root, ['ls-files', '-z']).stdout.split('\0');
-  for (const path of sources) assert.ok(tracked.includes(path), path);
-  for (const path of generated) assert.equal(tracked.includes(path), false, path);
+  for (const path of [...sources, ...clients, ...outputs]) assert.ok(tracked.includes(path), path);
+  for (const path of [...generated.filter(path => !outputs.includes(path)), ...privateFiles]) assert.equal(tracked.includes(path), false, path);
 });
 
 test('ignores locais cobrem resultados em qualquer caixa sem bloquear fixtures', t => {

package/.pbai4devs/templates/gitignore/TEMPLATE.md

@@ -7,14 +7,21 @@ description: Exemplo opcional de regras de ignore para o projeto.
 O `.gitignore` da raiz pertence ao projeto; o kit não o cria nem o altera.
 O projeto pode adotar este exemplo e seus próprios padrões se desejar.
 Regras de artefatos locais vêm de [shared.ignore](shared.ignore) e
-[agents.ignore](agents.ignore). As saídas calculadas usam
-[local.ignore](local.ignore) em `.git/info/exclude`; sem Git, essa proteção
-fica pendente até `git init` e sincronização, antes de adicionar arquivos.
+[agents.ignore](agents.ignore). As pastas dos clientes usam
+[local.ignore](local.ignore) em `.git/info/exclude`; o `.gitignore` deste hub
+não alcança pastas irmãs com `../`. As regras locais não são copiadas pelo Git:
+execute `init` ou `sync` em cada clone com Git inicializado, antes de adicionar
+arquivos. Worktrees do mesmo repositório podem compartilhar as exclusões;
+sem Git, essa proteção fica pendente.
 O sincronizador mantém o bloco `BEGIN AGENT IGNORE` / `END AGENT IGNORE`;
-regras próprias ficam fora dele, com exceções depois do bloco. Para permitir
-novos arquivos compartilhados, ajuste as fontes e sincronize. Raízes dedicadas
-dos clientes são locais. Em `.github` e `.vscode`, arquivos próprios continuam
-elegíveis; somente os derivados são excluídos.
+regras próprias ficam fora dele, com exceções depois do bloco. Arquivos já
+rastreados permanecem no índice; o kit não os desindexa automaticamente.
+Pastas dos clientes também podem conter arquivos humanos ainda não rastreados.
+Em especial, `.github` pode conter workflows e formulários do projeto.
+Para permitir o versionamento, acrescente uma exceção literal ao `.gitignore`
+da raiz, como `!/.claude/` ou `!/.github/`. Regras mais profundas continuam
+válidas. Evite exceções amplas como `!/.claude/**`, que podem expor arquivos
+privados e artefatos; `doctor` informa regras conflitantes.
 Ignore binários baixados por local, não por extensão: `.bat`, `.exe` e outros
 arquivos podem ser scripts ou fixtures necessários. Não use regras genéricas
 como `Release/`, `Scripts/` ou `Lib/` que escondam fontes e modelos.

package/.pbai4devs/templates/gitignore/shared.ignore

@@ -1,3 +1,4 @@
+# Pastas irmas: templates/gitignore/local.ignore e .git/info/exclude.
 # Derivados locais
 /catalog.json
 /skills.json

package/.pbai4devs/tools/agent-browser/TOOL.json

@@ -24,6 +24,14 @@
     "linux-arm64": ["bin/agent-browser-linux-arm64", "bin/agent-browser-linux-musl-arm64"],
     "linux-x64": ["bin/agent-browser-linux-x64", "bin/agent-browser-linux-musl-x64"]
   },
+  "optionalExecutables": {
+    "darwin-arm64": [{"package": "@agent-browser/cli-darwin-arm64", "file": "bin/agent-browser"}],
+    "darwin-x64": [{"package": "@agent-browser/cli-darwin-x64", "file": "bin/agent-browser"}],
+    "linux-arm64": [{"package": "@agent-browser/cli-linux-arm64-gnu", "file": "bin/agent-browser"}, {"package": "@agent-browser/cli-linux-arm64-musl", "file": "bin/agent-browser"}],
+    "linux-x64": [{"package": "@agent-browser/cli-linux-x64-gnu", "file": "bin/agent-browser"}, {"package": "@agent-browser/cli-linux-x64-musl", "file": "bin/agent-browser"}],
+    "win32-arm64": [{"package": "@agent-browser/cli-win32-x64-msvc", "file": "bin/agent-browser.exe"}],
+    "win32-x64": [{"package": "@agent-browser/cli-win32-x64-msvc", "file": "bin/agent-browser.exe"}]
+  },
   "scripts": {
     "entry": "SCRIPT.mjs"
   },

package/CHANGELOG.md

@@ -4,6 +4,16 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.20 — 2026-11-13
+
+- Atualização da ferramenta agent-browser compatível com sua distribuição atual.
+- Orientações para consultar e recuperar versões pelas tags publicadas.
+
+## 0.0.19 — 2026-11-13
+
+- Pastas dos clientes são ignoradas localmente por padrão, com exceções do projeto.
+- O índice Git e os arquivos já rastreados permanecem intactos.
+
 ## 0.0.18 — 2026-11-13
 
 - Sincronização preserva recursos próprios, colisões e alterações humanas.

package/README.en.md

@@ -13,7 +13,7 @@ Organize work with coding agents, from planning to verification. Keep skills,
 rules, commands and agent profiles in `.pbai4devs`; the kit generates the
 references each client can discover. Code lives in `src/`, product tests in
 `tests/`, and shared agent resources in `.pbai4devs/`. Generated client
-folders, entrypoints and preferences stay local and untracked.
+folders are ignored locally by default; projects can opt in to tracking them.
 See the [supported clients][clients].
 
 ## Start in your project

package/README.es.md

@@ -13,8 +13,8 @@ Organiza el trabajo con agentes de código, desde la planificación hasta la
 verificación. Mantén skills, reglas, comandos y perfiles en `.pbai4devs`;
 el kit genera las referencias de cada [cliente compatible][clients].
 El código vive en `src/`, las pruebas del producto en `tests/` y los recursos
-compartidos en `.pbai4devs/`. Las carpetas, entradas y preferencias generadas
-son locales y no se versionan.
+compartidos en `.pbai4devs/`. Las carpetas de clientes se ignoran localmente
+por defecto; cada proyecto puede elegir versionarlas.
 
 ## Empezar en tu proyecto
 

package/docs/guides/cli.md

@@ -85,10 +85,12 @@ comando agêntico [sincronizar](../../.pbai4devs/commands/sincronizar/COMMAND.md
 orienta executar o script com `--force`; ele não é o mesmo que `sync` da CLI.
 
 No Git, o kit preserva o `.gitignore` da raiz e pode atualizar
-`.git/info/exclude`. Se o plano indicar `untrackedPaths`, a operação pode
-retirar do índice saídas comprovadamente geradas, mantendo seus arquivos no
-disco. Confira a lista: `--dry-run` e `sync --check` não alteram o índice.
-Backups locais ficam em `.agent-tests/` e não substituem o histórico Git.
+`.git/info/exclude` para ocultar por padrão as pastas dos clientes. O projeto
+pode reabri-las no `.gitignore` da raiz, como em `!/.claude/`; consulte as
+[exceções e seus efeitos](installation.md#git-e-migração). Os comandos não
+retiram arquivos já rastreados do índice, e `untrackedPaths` permanece vazio
+por compatibilidade. Backups locais ficam em `.agent-tests/` e não substituem
+o histórico Git.
 
 ## Ferramentas
 

package/docs/guides/installation.md

@@ -87,7 +87,7 @@ O próximo passo é [preparar as ferramentas](prerequisites.md#depois-de-instala
 | Conteúdo | Tratamento |
 | --- | --- |
 | `.pbai4devs` com recursos e templates | Fonte compartilhada versionável. |
-| Skills, regras e comandos nos clientes | Apontamentos locais gerados. |
+| Recursos nos clientes | Apontamentos locais; pastas ignoradas por padrão. |
 | Entradas da raiz criadas pelo kit | Arquivos locais gerados. |
 | Índices, manifesto e seleção pessoal | Derivados locais ignorados. |
 | Código, documentos e configurações humanas | Preservados. |
@@ -102,12 +102,31 @@ identifica a licença dos recursos do AgentDevKit, sem redefinir a do projeto.
 
 ## Git e migração
 
-Um `.gitignore` dentro de `.pbai4devs` só controla essa árvore. Para os
-apontamentos externos, o kit gera exclusões locais do Git, sem ignorar
-workflows, formulários de issues ou configurações humanas em `.github`.
-O kit não cria nem altera o `.gitignore` da raiz. Sem Git, a exclusão local
-fica pendente; execute `git init` e `npx @pathbit/agentdevkit sync` antes de
-usar `git add`. No GitHub Packages, use o prefixo de registry da instalação.
+Um `.gitignore` dentro de `.pbai4devs` só controla essa árvore: `../` não
+alcança pastas irmãs. O kit gera regras em `.git/info/exclude` para ignorar
+por padrão as pastas dos clientes, sem alterar o `.gitignore` da raiz.
+Essas regras são locais, não acompanham o clone; execute `init` ou `sync`
+em cada clone com Git inicializado, antes de usar `git add`. Sem Git, a
+exclusão fica pendente até `git init` e sincronização.
+Worktrees do mesmo repositório podem compartilhar esse arquivo de exclusões.
+
+Para versionar uma pasta de cliente, o projeto pode acrescentar uma exceção
+literal ao seu próprio `.gitignore` da raiz, por exemplo:
+
+```gitignore
+!/.claude/
+!/.github/
+```
+
+A exceção da raiz tem precedência sobre `.git/info/exclude`; regras de um
+`.gitignore` mais profundo continuam valendo. Não use `!/.claude/**`: um
+curinga amplo pode reabrir credenciais e artefatos que devem ficar locais.
+O diagnóstico informa exceções que exponham esses arquivos.
+
+O padrão também oculta arquivos humanos ainda não rastreados nas pastas dos
+clientes. Em especial, `.github` pode conter workflows, formulários de issues
+e outras configurações do projeto; use `!/.github/` se precisar versioná-los.
+O mesmo cuidado vale para `.vscode` e configurações próprias de outros agentes.
 
 O bloco local também protege `.agent-tests`, `tmp`, `temp`, `.playwright*`
 e relatórios de testes, inclusive com letras maiúsculas e em subpastas.
@@ -119,15 +138,10 @@ de existir um arquivo correspondente. Examine a regra indicada no diagnóstico.
 Nomes próprios de artefatos e arquivos existentes também são conferidos;
 a validação fica restrita ao projeto e aos ignores de seus ancestrais.
 
-Arquivos já rastreados exigem migração do índice: apenas saídas identificadas
-do kit podem deixar de ser rastreadas, preservando seus bytes no disco.
-O plano informa esses caminhos em `untrackedPaths` antes de aplicar; examine-os
-e preserve alterações preparadas da equipe. `--dry-run` e `sync --check` não
-alteram o índice.
-Artefatos já rastreados são informados por `doctor` e `sync --check` para
-revisão; não são removidos automaticamente do índice.
-Revise o plano e os conflitos em um projeto existente; use `--dry-run` antes
-de aplicar. Conteúdo humano não deve ser classificado como saída do gerador.
+Ignorar uma pasta não retira arquivos já rastreados do índice. O kit preserva
+o índice, inclusive alterações preparadas; para mudar o rastreamento, o projeto
+decide a ação Git. `--dry-run` e `sync --check` também não alteram o índice.
+Revise o plano e os conflitos antes de aplicar em um projeto existente.
 
 ## Atualizar e escolher agentes
 
@@ -137,9 +151,9 @@ continua válida; `agents` consulta e `agents codex,claude` altera a seleção.
 necessárias para outro cliente, como `.agents` para Codex e Antigravity.
 
 Confira `update --dry-run --json` antes de atualizar um projeto existente.
-Revise arquivos criados, atualizados e removidos, conflitos, `preserved` e
-eventuais alterações do índice. `sync` usa as fontes já instaladas e não baixa
-uma nova versão. Consulte a [referência da CLI](cli.md) para todos os comandos.
+Revise arquivos criados, atualizados e removidos, conflitos e `preserved`.
+`sync` usa as fontes já instaladas e não baixa uma nova versão. Consulte a
+[referência da CLI](cli.md) para todos os comandos.
 
 Skills e outros recursos próprios podem coexistir com os do kit. Um nome
 igual não comprova propriedade: conteúdo humano e arquivos adicionais não
@@ -165,8 +179,8 @@ dele: atualizações alteram somente a contribuição do kit. Nomes de entradas
 com caixa diferente são reaproveitados quando há uma única opção.
 Comandos Gemini mantêm a referência dentro do valor `prompt` em TOML válido.
 Configurações que não são instruções não recebem uma mesclagem arbitrária.
-Arquivos mistos permanecem sob controle do Git do projeto; somente derivados
-integralmente gerados pelo kit recebem exclusão local.
+Arquivos mistos não passam a pertencer ao kit. Sua visibilidade para o Git
+também depende da regra aplicada à pasta do cliente.
 
 Links simbólicos preexistentes são preservados sem atravessá-los. O campo
 `preserved` informa rotas que continuam sob controle do projeto. Um formato

package/docs/guides/troubleshooting.md

@@ -164,8 +164,9 @@ não devem ser versionados. Verifique com `git status` e `git check-ignore -v
 retira automaticamente do Git; revise a remoção do índice sem apagar dados.
 
 O `.gitignore` do hub não controla pastas irmãs. Confira a proteção local
-gerada pelo kit, incluindo `info/exclude` nos repositórios Git. Preserve
-configurações humanas em `.github` e `.vscode` ao migrar arquivos antigos.
+gerada pelo kit em `info/exclude`. Para versionar configurações humanas novas
+em `.github` ou `.vscode`, reabra a pasta com `!/.github/` ou `!/.vscode/`
+no `.gitignore` da raiz. Confira as regras com `git check-ignore -v`.
 
 Para pedir ajuda, inclua SO/arquitetura, versões de Node/npm/AgentDevKit,
 comando executado, código de saída e trecho relevante do JSON, sem segredos.

package/docs/maintainers/maintenance.md

@@ -85,6 +85,28 @@ Também envia o mesmo pacote ao [npm público e GitHub Packages](packages.md),
 confere a integridade nos dois destinos e testa versão, instalação, diagnóstico
 e sincronização. O consumo pelo npm é anônimo; pelo GitHub, autenticado.
 
+A tag é a origem da publicação: `v0.0.19`, a release `v0.0.19` e os pacotes
+`0.0.19` apontam para a mesma entrega. A execução manual também exige a tag;
+não crie outra tag para uma versão nem mova uma tag já publicada.
+
+Para consultar o código de uma versão sem trocar os arquivos atuais:
+
+```console
+git fetch --tags
+git worktree add --detach ../AgentDevKit-v0.0.19 v0.0.19
+```
+
+Em um projeto atendido, fixe a versão desejada do pacote e revise o plano antes
+de aplicá-la:
+
+```console
+npx @pathbit/agentdevkit@0.0.19 update --dry-run --json
+```
+
+O comando usa aquela versão do kit; não reverte automaticamente o histórico
+Git nem arquivos próprios do projeto. Confira os conflitos e faça backup antes
+de aplicar uma versão anterior.
+
 Se o artifact expirou ou um job do CI falhou, use **Re-run all jobs** no CI
 original do push e aguarde todos os jobs. **Re-run failed jobs** pode manter o
 pacote de uma tentativa anterior, que a release não aceita. Depois reexecute

package/docs/product/design.md

@@ -60,13 +60,13 @@ bloco exigem revisão e não autorizam sobrescrever o arquivo com `--force`.
 Arquivos novos e integralmente gerados continuam com propriedade integral.
 Comandos TOML recebem a referência no valor de `prompt`, preservando as demais
 chaves. Configurações nativas fora desse escopo permanecem sob controle humano.
-Nunca é possível ignorar somente um trecho de arquivo no Git: arquivos mistos
-não entram nas exclusões do kit. Veja a [spec de integração][additive].
+Nunca é possível ignorar somente um trecho de arquivo no Git. Veja a
+[spec de integração][additive].
 
-Saídas identificadas são excluídas localmente do versionamento. O Git local
-usa `info/exclude`; fora de um repositório, a proteção fica no `.gitignore`
-da raiz. A política vem dos templates, não de listas copiadas por cliente.
-Os arquivos humanos de `.github` e `.vscode` continuam versionáveis.
+O Git usa `info/exclude` para ignorar localmente pastas de clientes, inclusive
+seus arquivos humanos ainda não rastreados. Exceções literais no `.gitignore`
+da raiz permitem versioná-las. Arquivos já rastreados e o índice permanecem;
+sem Git, a proteção fica pendente. A política vem dos templates.
 
 O estado registra versão, escolha e propriedade local. Índices e manifesto
 podem ser reconstruídos. Downloads, credenciais e relatórios ficam fora do

package/docs/specs/README.md

@@ -25,6 +25,8 @@ description: Incrementos verificáveis do AgentDevKit.
 - [Integração sem substituição][additive]: acréscimos em arquivos existentes.
 - [Compatibilidade com projetos reais][oss]: projetos públicos e exemplos reproduzíveis.
 - [Ignore do projeto](project-ignore/SPEC.md): preservar o arquivo da raiz.
+- [Ignore de clientes](client-ignore/SPEC.md): padrão local e exceções do projeto.
+- [Ferramenta e versões](tool-release/SPEC.md): atualização segura e tags de release.
 
 Cada incremento vincula requisitos, critérios, testes e evidências locais.
 

package/docs/specs/client-ignore/SPEC.md

@@ -0,0 +1,21 @@
+---
+description: Exclusão local de clientes com escolha explícita do projeto.
+---
+
+# Ignore de clientes
+
+O Git não aplica `../` no `.gitignore` do hub às pastas irmãs. O kit usa
+exclusões locais do Git e o projeto escolhe exceções no seu `.gitignore`.
+
+## Critérios de aceite
+
+- AC-001: Pastas de clientes são ignoradas por padrão em repositórios Git,
+  sem modificar o `.gitignore` da raiz.
+- AC-002: Uma exceção literal da raiz, como `!/.claude/`, permite versionar
+  o cliente e continua válida após instalação, atualização e sincronização.
+- AC-003: Credenciais e artefatos continuam protegidos; exceções inseguras
+  são informadas antes de qualquer mudança.
+- AC-004: Arquivos humanos e o índice Git, incluindo alterações preparadas,
+  são preservados. Arquivos já rastreados continuam rastreados.
+- AC-005: Documentação e testes explicam e verificam precedência, limites,
+  clones, clientes compartilhados, cenários sem Git e sistemas suportados.

package/docs/specs/tool-release/SPEC.md

@@ -0,0 +1,19 @@
+---
+description: Atualização segura do agent-browser e recuperação por versão.
+---
+
+# Atualização de ferramenta e versões
+
+O agent-browser passou a distribuir executáveis em pacotes opcionais por
+plataforma. A atualização deve funcionar sem perder instalações existentes.
+
+## Critérios de aceite
+
+- AC-001: O instalador aceita os layouts anterior e atual do agent-browser,
+  valida executáveis adequados à plataforma e comprova a versão instalada.
+- AC-002: Caminhos inválidos ou incompletos são recusados antes da troca;
+  falhas preservam a instalação anterior e não atravessam links inseguros.
+- AC-003: Cada release e pacote do fluxo aponta para a tag da mesma versão;
+  a documentação explica como consultar uma versão e simular seu uso.
+- AC-004: Testes automatizados cobrem layouts e falhas, e a CI verifica Linux,
+  Windows e macOS na matriz configurada antes da publicação.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pathbit/agentdevkit",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "description": "Shared skills, specifications and workflows for AI coding agents.",
   "type": "module",
   "license": "MIT",

package/src/install.mjs

@@ -4,7 +4,7 @@ import { chmodSync, closeSync, existsSync, fstatSync, lstatSync, openSync, readF
 import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { synchronize, isReference } from '../.pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs';
-import { isGeneratedOutput, planLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, applyLocalIgnore, planUntrack, applyUntrack, restoreUntrack, indexContentMatches } from '../.pbai4devs/scripts/lib/gitignore.mjs';
+import { isGeneratedOutput, planLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, applyLocalIgnore, indexContentMatches } from '../.pbai4devs/scripts/lib/gitignore.mjs';
 import { nativePathBoundary } from '../.pbai4devs/scripts/lib/native-paths.mjs';
 import { canonicalEntrypoint, resolveEntrypoint, entrypointReference, renderEntrypointImports, extractManagedBlock, managedBlockDigest, mergeManagedContent, stripManagedContent } from '../.pbai4devs/scripts/lib/managed-content.mjs';
 import { extractTomlManagedBlock, tomlManagedBlockDigest, mergeTomlContent, stripTomlContent } from '../.pbai4devs/scripts/lib/managed-toml.mjs';
@@ -698,16 +698,9 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     if (stagedChanges.length) fail('E_STAGED', `Staged content differs from the working tree for planned changes: ${stagedChanges.map(change => `${change.action} ${change.path}`).join(', ')}. Preserve and review these paths before updating.`);
     const retiredRoots = adapterRoots.filter(root => !active.roots.includes(root) && changes.some(change => change.action === 'remove' && change.path.startsWith(`${root}/`) && (previous?.files[change.path] || previous?.blocks[change.path])));
     const ownedOutputs = [...new Set([...synchronized.ownedOutputs, ...ownedEntrypoints, statePath])].filter(path => !mixedPaths.has(path) && !overlapsPreserved(path));
-    const hashes = {};
-    for (const [path, digest] of Object.entries(previous?.files || {})) if (path !== '.gitignore' && (ownedOutputs.includes(path) || !path.startsWith('.pbai4devs/')) && !mixedPaths.has(path) && !overlapsPreserved(path) && !aliasedEntrypoint(path)) hashes[path] = digest;
-    for (const path of ownedEntrypoints) { const current = read(target, path); if (current && (previous?.blocks[path] || derivedEntries[path] === hash(current))) hashes[path] = hash(current); }
-    for (const path of Object.keys(previous?.blocks || {})) if (path.endsWith('/.gitignore') && adapterRoots.some(root => path === `${root}/.gitignore`)) {
-      const current = read(target, path);
-      if (current) { const source = current.toString('utf8'), block = extractBlock(source, '# BEGIN AGENT IGNORE', '# END AGENT IGNORE'); if (block && source.trim() === block.trim() && hash(block) === previous.blocks[path]) hashes[path] = hash(current); }
-    }
-    if (previous && !migration) hashes[statePath] = hash(read(target, statePath));
-    const untrack = existsSync(target) ? planUntrack(target, hashes) : null;
-    if (migration && untrack?.paths.length) fail('E_STATE', 'State migration would change the Git index; preserve and resolve tracked outputs first.');
+    // Ignore rules affect only untracked files. Never remove existing index
+    // entries on behalf of the project; staged bytes are checked separately.
+    const untrack = { root: target, paths: [], hashes: {}, index: '', conflicts: [] };
     const localIgnore = planLocalIgnore(target, { outputs: ownedOutputs, templateRoot: stage });
     const localIgnoreCheck = checkLocalIgnore(localIgnore, { replacedBlocks: replacedIgnoreBlocks(target, changes, previous) });
     conflicts.push(...(untrack?.conflicts || []), ...localIgnoreCheck.missing);
@@ -759,14 +752,12 @@ export function applyPlan(plan) {
   for (const change of plan.changes) if ((before.get(change.path) ? hash(before.get(change.path)) : null) !== change.beforeHash) fail('E_CHANGED', `File changed after planning: ${change.path}`);
   for (const [path, content] of before) if (content) write(target, `${backup}/${path}`, content, beforeModes.get(path));
   const applied = [], removedDirectories = [];
-  let untracked = false;
   const assertOriginal = path => {
     const file = safePath(target, path), info = stat(file), bytes = before.get(path);
     if (bytes === null ? info !== null : !info?.isFile() || !readFileSync(file).equals(bytes) || (info.mode & 0o777) !== beforeModes.get(path)) fail('E_CHANGED', `File changed before writing: ${path}`);
   };
   try {
     for (const change of plan.changes) assertOriginal(change.path);
-    if (plan.untrack?.paths.length) { applyUntrack(plan.untrack); untracked = true; }
     for (const change of plan.changes) {
       assertOriginal(change.path);
       const file = safePath(target, change.path);
@@ -806,7 +797,7 @@ export function applyPlan(plan) {
     const changesFallback = plan.changes.some(change => change.path === '.gitignore');
     // Metadata is committed last; its writer rolls back partial writes itself.
     const ignored = applyLocalIgnore(changesFallback ? planLocalIgnore(target, { outputs: plan.ownedOutputs }) : plan.localIgnore);
-    return { changed: Boolean(plan.changes.length || ignored.changed || untracked), backup: [...before.values()].some(Boolean) ? backup : null };
+    return { changed: Boolean(plan.changes.length || ignored.changed), backup: [...before.values()].some(Boolean) ? backup : null };
   } catch (error) {
     const rollbackErrors = [], preserved = [];
     for (const removed of [...removedDirectories].sort((a, b) => a.path.length - b.path.length)) {
@@ -847,7 +838,6 @@ export function applyPlan(plan) {
     if (preserved.length) {
       try { error.rollbackPreservedPaths = preserved; } catch { /* Preserve a exceção original. */ }
     }
-    if (untracked) try { restoreUntrack(plan.untrack); } catch (failure) { rollbackErrors.push(failure); }
     if (rollbackErrors.length) throw Object.assign(new AggregateError([error, ...rollbackErrors], `${error.message}; rollback incompleto: ${rollbackErrors.map(failure => failure.message).join('; ')}`, { cause: error }), { code: error.code || 'E_OPERATION' });
     throw error;
   }