@pathbit/agentdevkit 0.0.17 → 0.0.19

package/.pbai4devs/commands/sincronizar/COMMAND.md

@@ -4,14 +4,16 @@ description: Atualiza ou confere os apontamentos compartilhados dos agentes.
 
 # Sincronizar
 
-Entrada: sem argumentos usa `--force` para reparar; `--check` só confere.
+Entrada: este comando agêntico usa o script local com `--force` para reparar;
+`--check` só confere. O `sync` da CLI usa as fontes locais e não implica
+`--force`; `update` usa as fontes da versão do pacote executado.
 Pré-requisitos: Node.js 24+ e manifesto `.pbai4devs/espelhos.conf` válido.
 
 Siga [sincronizar-agentes](../../skills/projeto/sincronizar-agentes/SKILL.md)
 e execute o script correspondente pelo seletor. A reconstrução repara
-apontamentos e remove saídas obsoletas cuja propriedade do kit foi comprovada,
-com backup local. Recursos, configurações e links humanos são preservados,
-inclusive quando seus nomes coincidem com os destinos do kit.
+apontamentos e remove saídas obsoletas cuja propriedade do kit foi comprovada.
+Recursos adicionais, configurações, pastas e links humanos são preservados,
+inclusive em colisões de nomes. O backup local não substitui o histórico Git.
 Após reparar, execute também `--check`.
 
 Respeite os clientes registrados no manifesto. Para mudar a seleção salva,

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

@@ -98,10 +98,33 @@ function localBlock(current, first, last, body) {
   return text.slice(0, start) + block + text.slice(finish);
 }
 
-function gitCommand(root, args, input) {
+function gitCommand(root, args, input, encoding = 'utf8') {
   const env = { ...process.env };
   for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE']) delete env[key];
-  return spawnSync('git', [...(['ls-files', 'rm'].includes(args[0]) ? ['--literal-pathspecs'] : []), '-C', root, ...args], { input, encoding: 'utf8', env, windowsHide: true, maxBuffer: 16 * 1024 * 1024 });
+  return spawnSync('git', [...(['ls-files', 'rm'].includes(args[0]) ? ['--literal-pathspecs'] : []), '-C', root, ...args], { input, encoding, env, windowsHide: true, maxBuffer: 16 * 1024 * 1024 });
+}
+
+// Compare exact bytes first. Only accept Git's plain text CRLF conversion when
+// effective attributes prove it applies and no custom transformation can run.
+// This deliberately does not invoke hash-object or repository-defined filters.
+export function indexContentMatches(root, path, working, indexed) {
+  if (working.equals(indexed)) return true;
+  const attributes = gitCommand(root, ['check-attr', '-z', 'text', 'eol', 'filter', 'working-tree-encoding', 'ident', '--', path]);
+  if (attributes.status !== 0) return false;
+  const parts = attributes.stdout.split('\0');
+  const values = {};
+  for (let i = 0; i + 2 < parts.length; i += 3) values[parts[i + 1]] = parts[i + 2];
+  const absent = value => value === 'unspecified' || value === 'unset';
+  if (!absent(values.filter) || !absent(values['working-tree-encoding']) || !absent(values.ident) || values.text === 'unset') return false;
+  const config = gitCommand(root, ['config', '--bool', 'core.autocrlf']);
+  if (config.status !== 0 && config.status !== 1) return false;
+  const textEnabled = values.text === 'set' || values.text === 'auto' || ['lf', 'crlf'].includes(values.eol) || config.status === 0 && config.stdout.trim() === 'true';
+  if (!textEnabled || !working.includes(13) || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(working.toString('latin1'))) return false;
+  try {
+    const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(working);
+    if (text.replaceAll('\r\n', '').includes('\r')) return false;
+    return Buffer.from(text.replaceAll('\r\n', '\n')).equals(indexed);
+  } catch { return false; }
 }
 
 function checkedOutput(path) {
@@ -309,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;
@@ -347,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); }
@@ -364,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) {
@@ -389,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'
@@ -401,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;
@@ -413,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.');
@@ -433,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);
@@ -458,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 }); }
@@ -477,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(', ')}`);
@@ -486,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 });
@@ -502,25 +545,39 @@ export function planUntrack(root, expectedHashes = {}) {
   if (!candidates.length || !localStat(root)) return { root, paths: [], hashes: {}, index: '', conflicts: [] };
   const result = gitCommand(root, ['ls-files', '--stage', '-z']);
   if (result.status !== 0) {
-    if (result.error?.code === 'ENOENT' || /not a git repository/i.test(result.stderr || '')) return { root, paths: [], hashes: {}, index: '', conflicts: [] };
+    if (result.error?.code === 'ENOENT' || /not a git repository/i.test(result.stderr || '')) {
+      // Fail closed if a repository exists even when Git cannot be launched.
+      let directory = root;
+      while (true) {
+        if (localStat(join(directory, '.git'))) throw new Error('Nao foi possivel consultar o Git deste projeto; indice e arquivos preservados.');
+        const parent = dirname(directory);
+        if (parent === directory) break;
+        directory = parent;
+      }
+      return { root, paths: [], hashes: {}, index: '', conflicts: [] };
+    }
     throw new Error(result.error?.message || result.stderr || 'Falha ao ler indice Git.');
   }
   const conflicts = [];
   const records = result.stdout.split('\0').filter(Boolean);
-  const wanted = new Set(candidates);
+  const folded = new Map();
+  for (const path of candidates) folded.set(path.toLowerCase(), [...(folded.get(path.toLowerCase()) || []), path]);
   const matches = new Map();
   for (const record of records) {
     const position = record.indexOf('\t'), path = record.slice(position + 1);
-    if (position < 0 || !wanted.has(path)) continue;
-    matches.set(path, [...(matches.get(path) || []), record]);
+    if (position < 0) continue;
+    for (const candidate of folded.get(path.toLowerCase()) || []) {
+      matches.set(candidate, [...(matches.get(candidate) || []), record]);
+    }
   }
   const paths = [...matches.keys()].filter(path => {
     const file = checkedLocalPath(join(root, path));
     const entries = matches.get(path);
     const match = entries.length === 1 && entries[0].match(/^\d+ ([a-f0-9]+) 0\t/);
-    const blob = match ? gitCommand(root, ['cat-file', 'blob', match[1]]) : null;
-    const owned = localStat(file) && createHash('sha256').update(readFileSync(file)).digest('hex') === expectedHashes[path];
-    const indexOwned = blob?.status === 0 && createHash('sha256').update(blob.stdout).digest('hex') === expectedHashes[path];
+    const blob = match ? gitCommand(root, ['cat-file', 'blob', match[1]], undefined, null) : null;
+    const data = localStat(file) ? readFileSync(file) : null;
+    const owned = data && createHash('sha256').update(data).digest('hex') === expectedHashes[path];
+    const indexOwned = entries[0]?.slice(entries[0].indexOf('\t') + 1) === path && blob?.status === 0 && data && indexContentMatches(root, path, data, blob.stdout);
     if (!owned || !indexOwned) conflicts.push(path);
     return owned && indexOwned;
   });

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

@@ -12,6 +12,9 @@ node --test .pbai4devs/scripts/sincronizar-agentes/tests/TEST.mjs
 
 `--check` só confere; a execução normal atualiza os recursos. `--force` salva
 conflitos em `.agent-tests/` antes de reparar os caminhos gerenciados.
+O [comando agêntico](../../commands/sincronizar/COMMAND.md) usa `--force` por
+padrão; executar este script diretamente não ativa essa opção. A CLI oferece
+`sync --dry-run --json` para consultar o plano antes de aplicá-lo.
 Recursos nativos humanos recebem um bloco curto com a referência ao hub.
 Texto, frontmatter e nomes existentes são preservados. O estado guarda só o
 hash desse bloco; edições externas continuam permitidas. Um bloco alterado
@@ -35,12 +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.

package/.pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs

@@ -3,6 +3,7 @@
 import { chmodSync, cpSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, posix, resolve } from 'node:path';
 import { randomUUID, createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
 import { requireNode, projectRoot, isMain } from '../lib/runtime.mjs';
 import { buildCatalog } from '../lib/catalog.mjs';
 import { resourcePath } from '../lib/resource-path.mjs';
@@ -10,7 +11,7 @@ import { adapterManifest, resolveAdapters } from '../lib/adapters.mjs';
 import { nativePathBoundary } from '../lib/native-paths.mjs';
 import { canonicalEntrypoint, resolveEntrypoint, entrypointReference, renderEntrypointImports, mergeManagedContent, stripManagedContent } from '../lib/managed-content.mjs';
 import { mergeTomlContent, stripTomlContent } from '../lib/managed-toml.mjs';
-import { mergeGitignore, validateIgnoreClients, renderClientIgnore, isGeneratedOutput, planLocalIgnore, applyLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, ignoreBegin, ignoreEnd } from '../lib/gitignore.mjs';
+import { mergeGitignore, validateIgnoreClients, renderClientIgnore, isGeneratedOutput, planLocalIgnore, applyLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, planUntrack, ignoreBegin, ignoreEnd } from '../lib/gitignore.mjs';
 import { stateDirectory } from '../lib/state-path.mjs';
 
 const marker = '<!-- gerado: sincronizar-agentes -->';
@@ -79,6 +80,28 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   requireNode();
   root = realpathSync(resolve(root));
   const absolute = value => join(root, ...value.split('/'));
+  function assertGitReadableForChanges() {
+    // A project may be nested in a worktree; .git can be a file or directory.
+    // If that marker exists we must not treat an unavailable Git executable,
+    // an invalid repository or an unreadable index as a Git-free project.
+    let folder = root, found = false;
+    while (true) {
+      if (stat(join(folder, '.git'))) { found = true; break; }
+      const parent = dirname(folder);
+      if (parent === folder) break;
+      folder = parent;
+    }
+    if (!found) return false;
+    const env = { ...process.env };
+    for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE']) delete env[key];
+    const probe = spawnSync('git', ['-C', root, 'rev-parse', '--is-inside-work-tree'], {
+      encoding: 'utf8', env, windowsHide: true, timeout: 20000,
+    });
+    if (probe.error || probe.status !== 0 || probe.stdout.trim() !== 'true') {
+      fail('Nao foi possivel consultar o Git deste projeto; sincronizacao bloqueada para preservar arquivos e indice.');
+    }
+    return true;
+  }
   function safe(value) {
     if (typeof value !== 'string' || !value || /^[A-Za-z]:/.test(value) || /[|\\\x00-\x1f\x7f]/.test(value) || value.split('/').some(part => !part || part === '.' || part === '..')) fail(`Caminho invalido: ${value}`);
     let current = root;
@@ -130,7 +153,6 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     const recorded = recordedHash === digest;
     return isReference(text) && recorded;
   };
-  const onlyReferences = value => { const files = scan(value); return files.length > 0 && ![...preserved.keys()].some(path => path === value || path.startsWith(`${value}/`)) && files.every(file => /\.(md|mdc|toml)$/i.test(file) && referenceFile(file)); };
   const protectedPath = value => /^(workflows(?:\/|$)|settings\.json$|extensions\.json$)/.test(value.slice(value.indexOf('/') + 1).toLowerCase());
   const agents = new Map();
   const formats = new Map();
@@ -295,6 +317,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const remove = new Set();
   const backup = new Set();
   const conflicts = new Set();
+  const protectedConflicts = new Set();
   const expected = new Map();
   const managedBlocks = {};
   const generatedFiles = {};
@@ -307,17 +330,31 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   function planRemove(value, custom = false) {
     safe(value);
     if (!managed(value) || protectedPath(value)) fail(`Limpeza fora dos espelhos ou caminho protegido: ${value}`);
+    // Directories, unowned files and edited references can contain project
+    // data even when --force is used. Only a recorded, unchanged reference
+    // may be removed; empty directories are never removed recursively.
+    if (!stat(safe(value))?.isFile() || !referenceFile(value)) {
+      remember(value, 'existing-file');
+      if (custom) { conflicts.add(value); protectedConflicts.add(value); }
+      return;
+    }
     remove.add(value);
     if (custom) backup.add(value);
   }
   function cleanScope(value) {
     if (preserveBoundary(value)) return;
-    if (!stat(safe(value))) return;
-    if (stat(safe(value)).isDirectory() && !scan(value).length) return;
-    if (Object.keys(priorBlocks).some(path => path === value || path.startsWith(value + '/'))) return;
-    if (onlyReferences(value)) planRemove(value);
-    else if (claimed(value)) remember(value, 'edited-generated-file');
-    else remember(value);
+    const info = stat(safe(value));
+    if (!info) return;
+    const files = info.isDirectory() ? scan(value) : [value];
+    if (info.isDirectory() && !files.length) { remember(value, 'existing-directory'); return; }
+    let hasHumanContent = false;
+    for (const file of files) {
+      if (expected.has(file) || priorBlocks[file] || protectedPath(file)) continue;
+      if (referenceFile(file)) planRemove(file);
+      else if (claimed(file)) { remember(file, 'edited-generated-file'); hasHumanContent = true; }
+      else { remember(file); hasHumanContent = true; }
+    }
+    if (hasHumanContent && info.isDirectory()) remember(value);
   }
   const registries = new Map();
   const discoveryOutputs = {};
@@ -551,6 +588,22 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const omittedRows = new Set([...legacy, ...missing.map(native => native.index)]);
   const finalConfig = rows.filter((row, index) => !omittedRows.has(index)).join('\n').replace(/\n*$/, '\n');
   const configChanged = !configExists || configText !== finalConfig;
+  // Every planned write/removal may cover a different staged version. Compare
+  // the worktree bytes with the index before touching any path, even in force
+  // mode, and repeat immediately before applying the transaction.
+  const affected = sorted([...removals, ...changed, ...registries.keys(), ...ignoreFiles.keys(), ...rootEntryChanges.map(([name]) => name), ...(configChanged ? [config] : [])]);
+  const emptyHash = createHash('sha256').update(Buffer.alloc(0)).digest('hex');
+  const affectedHashes = Object.fromEntries(affected.flatMap(value => {
+    const info = stat(safe(value));
+    if (info && !info.isFile()) return []; // A type conflict already blocks application.
+    return [[value, info ? createHash('sha256').update(readFileSync(absolute(value))).digest('hex') : emptyHash]];
+  }));
+  const hadGit = Object.keys(affectedHashes).length ? assertGitReadableForChanges() : false;
+  const affectedIndex = planUntrack(root, affectedHashes);
+  for (const path of affectedIndex.conflicts) {
+    conflicts.add(path);
+    remember(path, 'staged-content-preserved');
+  }
   function capture(value) {
     const file = safe(value), info = stat(file);
     if (!info) return null;
@@ -576,15 +629,15 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     let parent = posix.dirname(value);
     while (parent !== '.') { if (stat(safe(parent))?.isDirectory()) originalDirectories.add(parent); parent = posix.dirname(parent); }
   }
-  const touched = new Set(), createdDirectories = new Set(), restoredDirectories = new Set();
-  const prunedDirectories = new Map();
-  let restoring = false;
+  const touched = new Set(), createdDirectories = new Set();
   const summary = { changed: changed.length + rootEntryChanges.length, stale: removals.length, conflicts: conflicts.size, missing: missing.length, legacy: legacy.length, registries: registries.size, gitignores: ignoreFiles.size, manifests: configExists ? 0 : 1, localIgnores: localStatus.changed + localStatus.missing.length + localStatus.trackedOutputs.length + (localStatus.status === 'no-git' ? 1 : 0) };
   const dirty = Object.values(summary).some(Boolean);
   output(`${summary.changed} desatualizadas; ${summary.stale} obsoletas; ${summary.conflicts} conflitos; ${summary.missing} origens nativas ausentes; ${summary.legacy} documentos antigos; ${summary.registries} indices derivados; ${summary.gitignores} gitignores; ${summary.localIgnores} exclusoes locais.`);
   if (localStatus.status === 'no-git') output('Git ausente: apos git init, execute a sincronizacao para proteger os arquivos locais.');
   const preservedPaths = sorted(preserved.keys()).map(path => preserved.get(path));
   if (check) return { ...summary, ownedOutputs, managedBlocks, preserved: preservedPaths, exitCode: dirty ? 1 : 0 };
+  if (affectedIndex.conflicts.length) fail(`Indice Git contem alteracoes proprias; arquivos preservados: ${sorted(affectedIndex.conflicts).join(', ')}`);
+  if (protectedConflicts.size) fail(`Conteudo proprio preservado; resolva a colisao antes de sincronizar: ${sorted(protectedConflicts).join(', ')}`);
   if (conflicts.size) fail(`Use --force para reconstruir somente os caminhos gerenciados: ${sorted(conflicts).join(', ')}`);
   if (localStatus.missing.length) fail(`Regras humanas reabrem derivados locais: ${localStatus.missing.join(', ')}`);
   if (localPlan) assertLocalIgnoreUnchanged(localPlan);
@@ -594,7 +647,6 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     while (parent !== '.' && !stat(safe(parent))) { missing.push(parent); parent = posix.dirname(parent); }
     for (const directory of missing.reverse()) {
       mkdirSync(safe(directory)); createdDirectories.add(directory);
-      if (restoring) restoredDirectories.add(directory);
     }
   }
   function mutate(value, action, text) {
@@ -649,40 +701,27 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   }
   try {
     if (localPlan) assertLocalIgnoreUnchanged(localPlan);
+    if (Object.keys(affectedHashes).length) {
+      if (!assertGitReadableForChanges() && hadGit) fail('Git deixou de estar disponivel antes da sincronizacao; arquivos preservados.');
+      const current = planUntrack(root, affectedHashes);
+      if (current.conflicts.length || current.index !== affectedIndex.index) fail('Indice Git mudou antes da sincronizacao; conteudo preservado.');
+    }
     for (const value of removals) mutate(value, () => rmSync(safe(value), { recursive: true, force: true }), null);
     for (const value of changed) mutate(value, () => atomic(value, expected.get(value)), expected.get(value));
     for (const [value, text] of registries) mutate(value, () => atomic(value, text), text);
     for (const [value, text] of ignoreFiles) mutate(value, () => atomic(value, text), text);
     for (const [value, text] of rootEntryChanges) mutate(value, () => atomic(value, text), text);
     if (configChanged) mutate(config, () => atomic(config, finalConfig), finalConfig);
-    // Só os ancestrais de remoções conhecidas são candidatos à limpeza.
-    for (const value of removals) {
-      let parent = posix.dirname(value);
-      const boundary = value.split('/').slice(0, 2).join('/');
-      while (parent.startsWith(boundary + '/') || parent === boundary) {
-        const info = stat(safe(parent));
-        if (!info?.isDirectory() || readdirSync(absolute(parent)).length) break;
-        rmdirSync(safe(parent)); prunedDirectories.set(parent, info.mode & 0o777); parent = posix.dirname(parent);
-      }
-    }
+    // Directory ownership is not recorded: keep even empty parent directories.
     if (localPlan) applyLocalIgnore(localPlan);
   } catch (error) {
     const failures = [];
-    restoring = true;
     for (const value of [...touched].reverse()) {
       try {
         if (fingerprint(capture(value)) !== currentHashes.get(value)) fail(`Mudanca concorrente preservada: ${value}`);
         restore(value, originals.get(value));
       } catch (failure) { failures.push(failure); }
     }
-    for (const [directory, mode] of [...prunedDirectories].sort(([left], [right]) => right.length - left.length)) {
-      try {
-        if (!stat(safe(directory))) ensureDirectory(`${directory}/.restore-probe`);
-        const info = stat(safe(directory));
-        if (!info?.isDirectory() || !restoredDirectories.has(directory) && (info.mode & 0o777) !== mode) fail(`Diretorio concorrente preservado: ${directory}`);
-        chmodSync(safe(directory), mode);
-      } catch (failure) { failures.push(failure); }
-    }
     for (const directory of sorted(createdDirectories).sort((a, b) => b.length - a.length)) {
       try { if (!originalDirectories.has(directory) && stat(safe(directory))?.isDirectory() && !readdirSync(absolute(directory)).length) rmdirSync(safe(directory)); }
       catch (failure) { failures.push(failure); }