Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

fix: reconcile pre-exclusion .agents installs on claude and codex home upgrades

Affaan Mustafa8cfbc26797ca
diff --git a/scripts/install-apply.js b/scripts/install-apply.js
index 1435d2ff6..722f7d6b6 100755
--- a/scripts/install-apply.js
+++ b/scripts/install-apply.js
@@ -132,6 +132,13 @@ function printHumanPlan(plan, dryRun) {
}
}
+ if (Array.isArray(plan.reconciledExcludedPaths) && plan.reconciledExcludedPaths.length > 0) {
+ console.log('\nReconciled excluded paths:');
+ for (const removedPath of plan.reconciledExcludedPaths) {
+ console.log(`- removed ${removedPath}`);
+ }
+ }
+
if (!dryRun) {
console.log(`\nDone. Install-state written to ${plan.installStatePath}`);
}
diff --git a/scripts/lib/install/apply.js b/scripts/lib/install/apply.js
index fbab1293b..bd0f41fd5 100644
--- a/scripts/lib/install/apply.js
+++ b/scripts/lib/install/apply.js
@@ -34,6 +34,10 @@ const {
preserveUnwrittenFiles,
} = require('./ownership-guard');
const { cleanupLegacyOpencodeInstall } = require('./opencode-legacy-migration');
+const {
+ completeExcludedPathsReconciliation,
+ prepareExcludedPathsReconciliation,
+} = require('./excluded-paths-reconciliation');
const { buildInstallIndex, rewriteRelativeLinks } = require('./link-rewrite');
const { adaptAntigravityAgent } = require('./antigravity-agent');
@@ -449,9 +453,12 @@ function applyInstallPlanLocked(plan, dependencies = {}, settingsLockHeld = fals
if (typeof beforeInstallStateRead === 'function') {
beforeInstallStateRead({ plan });
}
- const migration = prepareHookConsentMigration(
+ const migration = prepareExcludedPathsReconciliation(
plan,
- prepareUserOwnedFileGuard(plan, prepareClaudeSkillMigration(plan))
+ prepareHookConsentMigration(
+ plan,
+ prepareUserOwnedFileGuard(plan, prepareClaudeSkillMigration(plan))
+ )
);
const appliedPlan = {
...plan,
@@ -666,17 +673,31 @@ function applyInstallPlanLocked(plan, dependencies = {}, settingsLockHeld = fals
];
}
+ let excludedPathsRemoved = [];
+ let excludedPathsWarnings = [];
+ try {
+ const excludedReconciliation = completeExcludedPathsReconciliation(migration, appliedPlan);
+ excludedPathsRemoved = excludedReconciliation.removedPaths;
+ excludedPathsWarnings = excludedReconciliation.warnings;
+ } catch (error) {
+ excludedPathsWarnings = [
+ `Excluded-paths reconciliation did not finish: ${error.message}. Previously managed files under excluded source paths were preserved; remove them manually or rerun the install.`,
+ ];
+ }
+
return {
...plan,
statePreview: finalState,
plannedOperations: [...plan.operations],
operations: migration.appliedOperations,
skippedOperations: migration.skippedOperations,
+ reconciledExcludedPaths: excludedPathsRemoved,
warnings: [
...(Array.isArray(plan.warnings) ? plan.warnings : []),
...migration.warnings,
...antigravityMigrationWarnings,
...opencodeMigrationWarnings,
+ ...excludedPathsWarnings,
],
applied: true,
};
diff --git a/scripts/lib/install/excluded-paths-reconciliation.js b/scripts/lib/install/excluded-paths-reconciliation.js
new file mode 100644
index 000000000..845dfd400
--- /dev/null
+++ b/scripts/lib/install/excluded-paths-reconciliation.js
@@ -0,0 +1,230 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const { readInstallState } = require('../install-state');
+const { assertWithinTrustedRoot } = require('../path-safety');
+const { getInstallTargetAdapter } = require('../install-targets/registry');
+
+/**
+ * Upgrade reconciliation for excluded source paths (issue #3116).
+ *
+ * Adapters can declare `excludedSourcePaths` (today: `.agents` for the Claude
+ * and Codex home targets). The exclusion stops new copy operations from being
+ * planned, but a home install created before the exclusion still has the
+ * copied files on disk and the copy operations recorded in install-state, so
+ * doctor keeps reporting drift and repair keeps restoring files the target
+ * never reads.
+ *
+ * prepareExcludedPathsReconciliation runs before the new state is written: it
+ * reads the previous install-state and drops the recorded managed operations
+ * whose source path is now excluded. completeExcludedPathsReconciliation runs
+ * after a successful apply: it removes the files those operations recorded,
+ * but only when the recorded content digest still matches, and prunes the
+ * emptied directories. Files the state does not own, modified files,
+ * symlinks, and anything outside the target root are preserved with a
+ * warning.
+ */
+
+function comparablePath(filePath) {
+ const resolvedPath = path.resolve(filePath);
+ return process.platform === 'win32' ? resolvedPath.toLowerCase() : resolvedPath;
+}
+
+function getReconcilingAdapter(plan) {
+ if (!plan || typeof plan.target !== 'string') {
+ return null;
+ }
+ let adapter;
+ try {
+ adapter = getInstallTargetAdapter(plan.target);
+ } catch {
+ return null;
+ }
+ return adapter && typeof adapter.excludesSourcePath === 'function' ? adapter : null;
+}
+
+function isRecordedExcludedManagedOperation(adapter, operation) {
+ return Boolean(
+ operation
+ && operation.ownership === 'managed'
+ && typeof operation.destinationPath === 'string'
+ && typeof operation.sourceRelativePath === 'string'
+ && adapter.excludesSourcePath(operation.sourceRelativePath)
+ );
+}
+
+function filterStateOperations(state, shouldDrop) {
+ if (!state || !Array.isArray(state.operations)) {
+ return state;
+ }
+ return {
+ ...state,
+ operations: state.operations.filter(operation => !shouldDrop(operation)),
+ };
+}
+
+function prepareExcludedPathsReconciliation(plan, migration) {
+ const adapter = getReconcilingAdapter(plan);
+ if (!adapter || !fs.existsSync(plan.installStatePath)) {
+ return { ...migration, excludedPathCandidates: [] };
+ }
+
+ const previousState = readInstallState(plan.installStatePath);
+ const candidates = ((previousState && previousState.operations) || [])
+ .filter(operation => isRecordedExcludedManagedOperation(adapter, operation));
+
+ if (candidates.length === 0) {
+ return { ...migration, excludedPathCandidates: [] };
+ }
+
+ const droppedDestinations = new Set(
+ candidates.map(operation => comparablePath(operation.destinationPath))
+ );
+ const shouldDrop = operation => Boolean(
+ operation
+ && typeof operation.destinationPath === 'string'
+ && droppedDestinations.has(comparablePath(operation.destinationPath))
+ && typeof operation.sourceRelativePath === 'string'
+ && adapter.excludesSourcePath(operation.sourceRelativePath)
+ );
+
+ return {
+ ...migration,
+ bridgeState: filterStateOperations(migration.bridgeState, shouldDrop),
+ finalState: filterStateOperations(migration.finalState, shouldDrop),
+ excludedPathCandidates: candidates,
+ };
+}
+
+function pathExists(filePath) {
+ try {
+ fs.lstatSync(filePath);
+ return true;
+ } catch (error) {
+ if (error && error.code === 'ENOENT') {
+ return false;
+ }
+ throw error;
+ }
+}
+
+function hashFileNoFollow(filePath) {
+ const flags = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0);
+ const descriptor = fs.openSync(filePath, flags);
+ try {
+ const before = fs.fstatSync(descriptor, { bigint: true });
+ if (!before.isFile()) {
+ throw new Error(`Refusing to read a non-file at ${filePath}`);
+ }
+ const content = fs.readFileSync(descriptor);
+ const after = fs.fstatSync(descriptor, { bigint: true });
+ const finalPathStat = fs.lstatSync(filePath, { bigint: true });
+ const unchanged = before.dev === after.dev
+ && before.ino === after.ino
+ && before.size === after.size
+ && after.dev === finalPathStat.dev
+ && after.ino === finalPathStat.ino
+ && after.size === finalPathStat.size;
+ if (finalPathStat.isSymbolicLink() || !finalPathStat.isFile() || !unchanged) {
+ throw new Error(`Refusing to read a file that changed during validation: ${filePath}`);
+ }
+ return crypto.createHash('sha256').update(content).digest('hex');
+ } finally {
+ fs.closeSync(descriptor);
+ }
+}
+
+function removeEmptyParents(startPath, targetRoot) {
+ let currentPath = path.dirname(startPath);
+ while (comparablePath(currentPath) !== comparablePath(targetRoot)) {
+ const safePath = assertWithinTrustedRoot(
+ currentPath,
+ targetRoot,
+ 'reconcile excluded install paths'
+ );
+ if (!pathExists(safePath)) {
+ currentPath = path.dirname(safePath);
+ continue;
+ }
+ const stat = fs.lstatSync(safePath);
+ if (!stat.isDirectory() || stat.isSymbolicLink() || fs.readdirSync(safePath).length > 0) {
+ return;
+ }
+ fs.rmdirSync(safePath);
+ currentPath = path.dirname(safePath);
+ }
+}
+
+function completeExcludedPathsReconciliation(migration, plan) {
+ const candidates = (migration && migration.excludedPathCandidates) || [];
+ const removedPaths = [];
+ const warnings = [];
+
+ for (const candidate of candidates) {
+ if (candidate.kind !== 'copy-file') {
+ continue;
+ }
+
+ let safePath;
+ try {
+ safePath = assertWithinTrustedRoot(
+ candidate.destinationPath,
+ plan.targetRoot,
+ 'reconcile excluded install paths'
+ );
+ } catch (error) {
+ warnings.push(
+ `Preserved previously managed file ${candidate.destinationPath}: ${error.message}`
+ );
+ continue;
+ }
+
+ if (!pathExists(safePath)) {
+ continue;
+ }
+
+ const stat = fs.lstatSync(safePath);
+ if (stat.isSymbolicLink() || !stat.isFile()) {
+ warnings.push(
+ `Preserved previously managed file ${safePath}: it is not a regular file; remove it manually if unwanted.`
+ );
+ continue;
+ }
+
+ if (typeof candidate.contentSha256 !== 'string') {
+ warnings.push(
+ `Preserved previously managed file ${safePath}: the recorded operation has no content digest, so the file cannot be verified unchanged; remove it manually if unwanted.`
+ );
+ continue;
+ }
+
+ let currentDigest;
+ try {
+ currentDigest = hashFileNoFollow(safePath);
+ } catch (error) {
+ warnings.push(`Preserved previously managed file ${safePath}: ${error.message}`);
+ continue;
+ }
+
+ if (currentDigest !== candidate.contentSha256.toLowerCase()) {
+ warnings.push(
+ `Preserved previously managed file ${safePath}: content changed after install; remove it manually if unwanted.`
+ );
+ continue;
+ }
+
+ fs.unlinkSync(safePath);
+ removedPaths.push(safePath);
+ removeEmptyParents(safePath, plan.targetRoot);
+ }
+
+ return { removedPaths, warnings };
+}
+
+module.exports = {
+ completeExcludedPathsReconciliation,
+ prepareExcludedPathsReconciliation,
+};
diff --git a/tests/scripts/install-apply.test.js b/tests/scripts/install-apply.test.js
index c1e935dcc..576ba4389 100644
--- a/tests/scripts/install-apply.test.js
+++ b/tests/scripts/install-apply.test.js
@@ -7,6 +7,7 @@ const fs = require('fs');
const os = require('os');
const path = require('path');
const { execFileSync, spawnSync } = require('child_process');
+const crypto = require('crypto');
const yaml = require('js-yaml');
const { applyInstallPlan } = require('../../scripts/lib/install/apply');
@@ -641,6 +642,134 @@ function runTests() {
}
})) passed++; else failed++;
+ if (test('reconciles legacy .agents files and state operations on Claude and Codex home upgrades', () => {
+ const homeDir = createTempDir('install-apply-home-');
+ const projectDir = createTempDir('install-apply-project-');
+ const digest = content => crypto.createHash('sha256').update(content).digest('hex');
+ const legacyOperation = (destinationPath, sourceRelativePath, installedContent) => ({
+ kind: 'copy-file',
+ moduleId: 'agents-core',
+ sourceRelativePath,
+ destinationPath,
+ strategy: 'preserve-relative-path',
+ ownership: 'managed',
+ scaffoldOnly: false,
+ contentSha256: digest(installedContent),
+ });
+ const writeFile = (filePath, content) => {
+ fs.mkdirSync(path.dirname(filePath), { recursive: true });
+ fs.writeFileSync(filePath, content);
+ };
+ const writeLegacyState = (statePath, target, operations) => {
+ writeFile(statePath, `${JSON.stringify({
+ schemaVersion: 'ecc.install.v1',
+ installedAt: '2026-09-01T00:00:00.000Z',
+ target,
+ request: {
+ profile: 'core',
+ modules: [],
+ includeComponents: [],
+ excludeComponents: [],
+ legacyLanguages: [],
+ legacyMode: false,
+ hookConsent: target.target === 'claude' ? 'enabled' : null,
+ },
+ resolution: { selectedModules: ['agents-core'], skippedModules: [] },
+ source: { repoVersion: '2.2.1', repoCommit: null, manifestVersion: 1 },
+ operations,
+ }, null, 2)}\n`);
+ };
+
+ try {
+ // Claude home seeded as installed before the .agents exclusion.
+ const claudeRoot = path.join(homeDir, '.claude');
+ const claudeStatePath = path.join(claudeRoot, 'ecc', 'install-state.json');
+ const claudeSkillCopy = path.join(claudeRoot, '.agents', 'skills', 'legacy-skill', 'SKILL.md');
+ const claudeModifiedCopy = path.join(claudeRoot, '.agents', 'plugins', 'marketplace.json');
+ const claudeUserFile = path.join(claudeRoot, '.agents', 'user-note.txt');
+ writeFile(claudeSkillCopy, '# legacy skill\n');
+ writeFile(claudeModifiedCopy, '{"edited": true}\n');
+ writeFile(claudeUserFile, 'user notes\n');
+ writeLegacyState(claudeStatePath, {
+ id: 'claude-home', target: 'claude', kind: 'home',
+ root: claudeRoot, installStatePath: claudeStatePath,
+ }, [
+ legacyOperation(claudeSkillCopy, '.agents/skills/legacy-skill/SKILL.md', '# legacy skill\n'),
+ legacyOperation(claudeModifiedCopy, '.agents/plugins/marketplace.json', '{"original": true}\n'),
+ ]);
+
+ const claudeResult = run(['--profile', 'core', '--enable-hooks'], { cwd: projectDir, homeDir });
+ assert.strictEqual(claudeResult.code, 0, claudeResult.stderr);
+
+ assert.ok(!fs.existsSync(claudeSkillCopy), 'Unchanged managed .agents file should be removed');
+ assert.ok(
+ claudeResult.stdout.includes(
+ `- removed ${path.join(fs.realpathSync(claudeRoot), '.agents', 'skills', 'legacy-skill', 'SKILL.md')}`
+ ),
+ 'Install output should log one line per removed path'
+ );
+ assert.strictEqual(
+ fs.readFileSync(claudeModifiedCopy, 'utf8'),
+ '{"edited": true}\n',
+ 'Modified managed file must be preserved'
+ );
+ assert.strictEqual(
+ fs.readFileSync(claudeUserFile, 'utf8'),
+ 'user notes\n',
+ 'Files the state does not own must not be touched'
+ );
+ assert.ok(
+ !fs.existsSync(path.join(claudeRoot, '.agents', 'skills')),
+ 'Emptied .agents subdirectories should be pruned'
+ );
+
+ const claudeState = readJson(claudeStatePath);
+ assert.ok(
+ !claudeState.operations.some(operation => (
+ String(operation.sourceRelativePath || '').replace(/\\/g, '/').split('/')[0] === '.agents'
+ )),
+ 'Claude install-state must drop the excluded .agents operations'
+ );
+ assert.ok(fs.existsSync(path.join(claudeRoot, 'agents', 'architect.md')));
+ assert.ok(fs.existsSync(path.join(claudeRoot, 'skills', 'tdd-workflow', 'SKILL.md')));
+
+ // Codex home seeded the same way; both recorded files are unchanged.
+ const codexRoot = path.join(homeDir, '.codex');
+ const codexStatePath = path.join(codexRoot, 'ecc-install-state.json');
+ const codexSkillCopy = path.join(codexRoot, '.agents', 'skills', 'legacy-skill', 'SKILL.md');
+ const codexMarketplaceCopy = path.join(codexRoot, '.agents', 'plugins', 'marketplace.json');
+ writeFile(codexSkillCopy, '# legacy skill\n');
+ writeFile(codexMarketplaceCopy, '{"original": true}\n');
+ writeLegacyState(codexStatePath, {
+ id: 'codex-home', target: 'codex', kind: 'home',
+ root: codexRoot, installStatePath: codexStatePath,
+ }, [
+ legacyOperation(codexSkillCopy, '.agents/skills/legacy-skill/SKILL.md', '# legacy skill\n'),
+ legacyOperation(codexMarketplaceCopy, '.agents/plugins/marketplace.json', '{"original": true}\n'),
+ ]);
+
+ const codexResult = run(['--target', 'codex', '--profile', 'core'], { cwd: projectDir, homeDir });
+ assert.strictEqual(codexResult.code, 0, codexResult.stderr);
+
+ assert.ok(
+ !fs.existsSync(path.join(codexRoot, '.agents')),
+ 'Fully reconciled .agents directory should be pruned from the Codex home'
+ );
+ const codexState = readJson(codexStatePath);
+ assert.ok(
+ !codexState.operations.some(operation => (
+ String(operation.sourceRelativePath || '').replace(/\\/g, '/').split('/')[0] === '.agents'
+ )),
+ 'Codex install-state must drop the excluded .agents operations'
+ );
+ assert.ok(fs.existsSync(path.join(codexRoot, 'agents', 'architect.md')));
+ assert.ok(fs.existsSync(path.join(codexRoot, 'skills', 'tdd-workflow', 'SKILL.md')));
+ } finally {
+ cleanup(homeDir);
+ cleanup(projectDir);
+ }
+ })) passed++; else failed++;
+
if (test('preserves existing top-level Claude rules and skills during managed install', () => {
const homeDir = createTempDir('install-apply-home-');
const projectDir = createTempDir('install-apply-project-');