@ghl-ai/aw 0.1.58-beta.0 → 0.1.58

package/cli.mjs

@@ -168,13 +168,10 @@ function printHelp() {
     cmd('aw mcp status', 'Show global AW MCP mode for Claude/Cursor/Codex'),
     cmd('aw mcp disable', 'Remove AW-managed MCP server across Claude/Cursor/Codex'),
     cmd('aw mcp enable', 'Restore AW-managed MCP server across Claude/Cursor/Codex'),
-    cmd('aw integrations', 'Manage third-party integrations (Codex, Caveman, etc)'),
-    cmd('aw integrations add <key>', 'Install a specific tool (e.g. codex, caveman)'),
+    cmd('aw integrations', 'Manage third-party integrations (Codex, Caveman, Context Mode, etc)'),
+    cmd('aw integrations add <key>', 'Install a specific tool (e.g. codex, caveman, context-mode)'),
     cmd('aw integrations remove <key>', 'Remove a tool'),
     cmd('aw integrations bundle <name>', 'Install a preset bundle'),
-    cmd('aw integration add <name>', 'Configure an installed local integration, e.g. context-mode'),
-    cmd('aw integration status <name>', 'Show local integration health'),
-    cmd('aw integration remove <name>', 'Remove AW-managed local integration entries'),
     cmd('aw drop <path>', 'Stop syncing or delete local content'),
     cmd('aw nuke', 'Remove entire .aw_registry/ & start fresh'),
     cmd('aw daemon install', 'Auto-pull on a schedule (macOS launchd / Linux cron)'),

package/commands/init.mjs

@@ -18,7 +18,7 @@ import {
 import { execSync } from 'node:child_process';
 import { join, dirname, sep } from 'node:path';
 import { homedir } from 'node:os';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as p from '@clack/prompts';
 import * as config from '../config.mjs';
 import * as fmt from '../fmt.mjs';
@@ -26,7 +26,7 @@ import { chalk, setSilent } from '../fmt.mjs';
 import { linkWorkspace } from '../link.mjs';
 import { generateCommands, copyInstructions, initAwDocs, syncHomeHarnessInstructions } from '../integrate.mjs';
 import { setupMcp } from '../mcp.mjs';
-import { ensureContextModeIntegration, isContextModeRequested } from '../integrations/context-mode.mjs';
+import { isContextModeRequested } from '../integrations/context-mode.mjs';
 import { applyStoredStartupPreferences, ensureAwRuntimeHook, isDefaultRoutingEnabled } from '../startup.mjs';
 import { installLocalCommitHook } from '../hooks.mjs';
 import { autoUpdate, promptUpdate } from '../update.mjs';
@@ -35,7 +35,7 @@ import { loadConfig as ensureTelemetryConfig } from '../telemetry.mjs';
 import { installAwEcc, AW_ECC_TAG } from '../ecc.mjs';
 import { removeWorkspaceHookDefaults } from '../codex.mjs';
 import { readHookManifest, pruneStaleHooks, writeHookManifest } from '../hook-cleanup.mjs';
-import { promptAndInstall, autoInstallIntegrations } from '../integrations.mjs';
+import { installIntegration, autoInstallIntegrations } from '../integrations.mjs';
 import {
   initPersistentClone,
   isValidClone,
@@ -65,6 +65,41 @@ const HOME = (() => { try { return realpathSync(_rawHome); } catch { return _raw
 const GLOBAL_AW_DIR = join(HOME, '.aw_registry');
 const AW_HOME = join(HOME, '.aw');
 
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function writeHookManifestBestEffort(manifest, context) {
+  try {
+    writeHookManifest(manifest);
+  } catch (error) {
+    fmt.logWarn(`Could not persist hook manifest${context ? ` ${context}` : ''}: ${errorMessage(error)}`);
+  }
+}
+
+export async function syncEccAfterAwUpdate(updateResult, cwd, { silent = false } = {}) {
+  if (updateResult?.status !== 'upgraded' || !updateResult.packageRoot) {
+    return { synced: false, reason: updateResult?.reason || updateResult?.status || 'not-upgraded' };
+  }
+
+  const eccModulePath = join(updateResult.packageRoot, 'ecc.mjs');
+  if (!existsSync(eccModulePath)) {
+    return { synced: false, reason: 'missing-ecc-module' };
+  }
+
+  try {
+    const moduleUrl = `${pathToFileURL(eccModulePath).href}?aw-post-update=${Date.now()}`;
+    const ecc = await import(moduleUrl);
+    await ecc.installAwEcc(cwd, { silent });
+    return { synced: true, eccVersion: ecc.AW_ECC_TAG || null };
+  } catch (err) {
+    if (!silent) {
+      fmt.logWarn(`AW updated, but post-update ECC sync failed: ${err.message}`);
+    }
+    return { synced: false, reason: err.message };
+  }
+}
+
 function syncRulesTargets(targetDir) {
   const rulesSrc = join(AW_HOME, RULES_SOURCE_DIR);
   if (!existsSync(rulesSrc)) return false;
@@ -94,23 +129,24 @@ function syncHomeAndProjectInstructions(cwd, namespace) {
   }
 }
 
-function maybeConfigureContextMode(args, { silent = false } = {}) {
+async function maybeConfigureContextMode(args, { silent = false } = {}) {
   if (!isContextModeRequested(args, process.env)) {
     return null;
   }
 
-  const result = ensureContextModeIntegration(HOME, {
+  const result = await installIntegration('context-mode', {
+    home: HOME,
     env: process.env,
     silent,
   });
 
   if (!silent) {
-    for (const warning of result.warnings) {
+    for (const warning of result.warnings || []) {
       fmt.logWarn(warning);
     }
-    if (result.changedFiles.length > 0) {
+    if ((result.changedFiles || []).length > 0) {
       fmt.logStep(`Context Mode configured (${result.changedFiles.length} file${result.changedFiles.length === 1 ? '' : 's'})`);
-    } else if (result.warnings.length > 0) {
+    } else if ((result.warnings || []).length > 0) {
       fmt.logWarn('Context Mode was requested but not configured');
     } else {
       fmt.logStep('Context Mode already configured');
@@ -404,7 +440,7 @@ export async function initCommand(args) {
     ensureAwRuntimeHook(HOME);
     syncHomeAndProjectInstructions(cwd, freshCfg?.namespace || team);
     await setupMcp(HOME, freshCfg?.namespace || team, { silent });
-    maybeConfigureContextMode(args, { silent });
+    await maybeConfigureContextMode(args, { silent });
     applyStoredStartupPreferences(HOME);
     const removedLegacyStartupFiles = cwd !== HOME ? removeWorkspaceHookDefaults(cwd) : [];
     installGlobalHooks();
@@ -444,7 +480,7 @@ export async function initCommand(args) {
     if (!silent) fmt.logStep(`IDE wired — ${chalk.bold(symlinks)} symlinks · ${chalk.bold(commands)} commands`);
 
     // Write hook manifest after all hook installation is complete
-    try { writeHookManifest({ eccVersion: AW_ECC_TAG, awVersion: VERSION }); } catch { /* best effort */ }
+    writeHookManifestBestEffort({ eccVersion: AW_ECC_TAG, awVersion: VERSION });
 
     // Auto-install suggested integrations (Codex, Caveman, Graphify, etc) - unless --no-integrations
     let installedIntegrations = [];
@@ -454,7 +490,14 @@ export async function initCommand(args) {
 
     if (silent) {
       if (silentSpinner) { silentSpinner.stop('Done'); setSilent(false); }
-      autoUpdate(await args._updateCheck);
+      const updateResult = autoUpdate(await args._updateCheck);
+      const postUpdateEcc = await syncEccAfterAwUpdate(updateResult, cwd, { silent: true });
+      if (postUpdateEcc.synced) {
+        writeHookManifestBestEffort(
+          { eccVersion: postUpdateEcc.eccVersion, awVersion: updateResult.to },
+          'after AW update',
+        );
+      }
     } else {
       fmt.outro([
         `⟁  ${isNewSubTeam ? `Sub-team ${chalk.cyan(folderName)} added` : 'Up to date'}`,
@@ -565,7 +608,7 @@ export async function initCommand(args) {
     Promise.resolve(syncHomeAndProjectInstructions(cwd, team)),
     setupMcp(HOME, team, { silent }),
   ]);
-  maybeConfigureContextMode(args, { silent });
+  await maybeConfigureContextMode(args, { silent });
   // applyStoredStartupPreferences reads settings written by ECC — keep after batch B
   applyStoredStartupPreferences(HOME);
   const removedLegacyStartupFiles = cwd !== HOME ? removeWorkspaceHookDefaults(cwd) : [];
@@ -630,7 +673,7 @@ export async function initCommand(args) {
 
   // Write hook manifest after all hook installation is complete, including
   // bundled usage hooks, so `aw nuke` can prune AW-managed settings entries.
-  try { writeHookManifest({ eccVersion: AW_ECC_TAG, awVersion: VERSION }); } catch { /* best effort */ }
+  writeHookManifestBestEffort({ eccVersion: AW_ECC_TAG, awVersion: VERSION });
 
   // Auto-install suggested integrations (Codex, Caveman, Graphify, etc) - unless --no-integrations
   let installedIntegrations = [];

package/commands/integration.mjs

@@ -1,43 +1,52 @@
+// commands/integration.mjs — Deprecated compatibility wrapper for `aw integration`.
+
 import { homedir } from 'node:os';
 
 import * as fmt from '../fmt.mjs';
-import { listIntegrations, resolveIntegration } from '../integrations/index.mjs';
+import { getIntegrationSummary, INTEGRATIONS } from '../integrations.mjs';
+import { integrationsCommand } from './integrations.mjs';
 
-function printWarnings(warnings = []) {
-  for (const warning of warnings) {
-    fmt.logWarn(warning);
+function requireKnownIntegration(key) {
+  if (!key) {
+    fmt.cancel(`Missing integration name. Known integrations: ${Object.keys(INTEGRATIONS).join(', ')}`);
+  }
+  if (!INTEGRATIONS[key]) {
+    fmt.cancel(`Unknown integration: ${key}`);
   }
 }
 
-function printChangedFiles(changedFiles = []) {
-  if (changedFiles.length === 0) return;
-  fmt.note(changedFiles.map(file => file.replace(homedir(), '~')).join('\n'), 'Changed files');
-}
-
-function requireIntegration(name) {
-  if (!name) {
-    fmt.cancel('Missing integration name. Known integrations: context-mode');
+function printStatus(key, home) {
+  const status = getIntegrationSummary(key, { home, env: process.env });
+  if (!status) {
+    fmt.cancel(`Unknown integration: ${key}`);
   }
 
-  try {
-    return resolveIntegration(name);
-  } catch (err) {
-    fmt.cancel(err.message);
-  }
+  fmt.note(
+    [
+      `state: ${status.state}`,
+      `installed: ${status.installed}`,
+      `configured: ${status.configured}`,
+      status.version ? `version: ${status.version}` : null,
+      status.path ? `path: ${status.path}` : null,
+      `summary: ${status.summary}`,
+    ].filter(Boolean).join('\n'),
+    key,
+  );
 }
 
 export async function integrationCommand(args) {
-  const [subcommand = 'list', name] = args._positional;
+  const [subcommand = 'list', key] = args._positional;
   const home = homedir();
 
   if (args['--help']) {
     fmt.intro('aw integration');
+    fmt.logWarn('`aw integration` is deprecated. Use `aw integrations` for new automation.');
     fmt.note(
       [
         'aw integration list',
-        'aw integration add context-mode [--dry-run]',
-        'aw integration status context-mode',
-        'aw integration remove context-mode [--dry-run]',
+        'aw integration add <key> [--dry-run] [--strict]',
+        'aw integration status <key>',
+        'aw integration remove <key> [--dry-run]',
       ].join('\n'),
       'Usage',
     );
@@ -45,67 +54,19 @@ export async function integrationCommand(args) {
     return;
   }
 
-  if (subcommand === 'list') {
-    fmt.intro('aw integration list');
-    const rows = listIntegrations(home, { env: process.env });
-    fmt.note(
-      rows.map(row => `${row.name}  ${row.state}  ${row.summary}`).join('\n'),
-      'Known integrations',
-    );
-    fmt.outro('Done');
-    return;
-  }
-
-  const integration = requireIntegration(name);
-
-  if (subcommand === 'add') {
-    fmt.intro(`aw integration add ${integration.name}`);
-    const result = integration.add(home, {
-      env: process.env,
-      dryRun: args['--dry-run'] === true,
-    });
-    printWarnings(result.warnings);
-    printChangedFiles(result.changedFiles);
-    if (result.changedFiles.length > 0) {
-      fmt.outro(`${integration.name} configured`);
-    } else if (result.warnings.length > 0) {
-      fmt.outro(`${integration.name} not configured; binary is missing or config was unsafe to edit`);
-    } else {
-      fmt.outro(`${integration.name} already configured`);
-    }
-    return;
-  }
-
-  if (subcommand === 'remove') {
-    fmt.intro(`aw integration remove ${integration.name}`);
-    const result = integration.remove(home, {
-      dryRun: args['--dry-run'] === true,
-    });
-    printWarnings(result.warnings);
-    printChangedFiles(result.changedFiles);
-    fmt.outro(result.changedFiles.length > 0
-      ? `${integration.name} removed`
-      : `${integration.name} not configured`);
-    return;
-  }
+  fmt.logWarn('`aw integration` is deprecated. Use `aw integrations` instead.');
 
   if (subcommand === 'status') {
-    fmt.intro(`aw integration status ${integration.name}`);
-    const status = integration.status(home, { env: process.env });
-    fmt.note(
-      [
-        `state: ${status.state}`,
-        `installed: ${status.installed}`,
-        `configured: ${status.configured}`,
-        status.version ? `version: ${status.version}` : null,
-        status.path ? `path: ${status.path}` : null,
-        `summary: ${status.summary}`,
-      ].filter(Boolean).join('\n'),
-      integration.name,
-    );
+    requireKnownIntegration(key);
+    fmt.intro(`aw integration status ${key}`);
+    printStatus(key, home);
     fmt.outro('Done');
     return;
   }
 
+  if (['list', 'add', 'remove', 'bundle'].includes(subcommand)) {
+    return integrationsCommand(args);
+  }
+
   fmt.cancel(`Unknown integration subcommand: ${subcommand}. Use add / remove / status / list`);
 }

package/commands/integrations.mjs

@@ -1,16 +1,53 @@
 // commands/integrations.mjs — CLI command: aw integrations add/remove/list/bundle
 
+import { homedir } from 'node:os';
+
 import * as p from '@clack/prompts';
 import * as fmt from '../fmt.mjs';
 import { chalk } from '../fmt.mjs';
 import {
   INTEGRATIONS,
   BUNDLES,
+  getIntegrationSummaries,
   installIntegration,
+  integrationSucceeded,
   removeIntegration,
-  getInstalledList,
 } from '../integrations.mjs';
 
+function availableKeys() {
+  return Object.keys(INTEGRATIONS).join(', ');
+}
+
+function printWarnings(warnings = []) {
+  for (const warning of warnings) fmt.logWarn(warning);
+}
+
+function printChangedFiles(changedFiles = []) {
+  if (!changedFiles.length) return;
+  fmt.note(changedFiles.map(file => file.replace(homedir(), '~')).join('\n'), 'Changed files');
+}
+
+function printContextModeAddResult(result) {
+  printWarnings(result.warnings);
+  if (result.plannedInstall) {
+    fmt.note(result.install?.commandLine || 'install context-mode@latest', 'Planned package install');
+  }
+  if (result.binary?.present) {
+    fmt.note(
+      [
+        `binary: ${result.binary.path}`,
+        `source: ${result.binary.source}`,
+        result.installedPackage ? 'package: installed during this run' : 'package: reused existing binary',
+      ].filter(Boolean).join('\n'),
+      'Context Mode',
+    );
+  }
+  printChangedFiles(result.changedFiles);
+  if (result.configuredHarnesses?.length) {
+    fmt.note(result.configuredHarnesses.join('\n'), 'Configured surfaces');
+  }
+}
+
 export async function integrationsCommand(args) {
   const subcommand = args._positional[0];
 
@@ -39,92 +76,16 @@ async function cmdList() {
     subtitle: '  Available tools and MCP servers',
   });
 
-  const installed = getInstalledList();
-
-  // Group by type
-  const plugins = Object.entries(INTEGRATIONS).filter(
-    ([, i]) => i.type === 'plugin'
-  );
-  const remoteRcps = Object.entries(INTEGRATIONS).filter(
-    ([, i]) => i.type === 'remote-mcp'
-  );
-  const universalInstallers = Object.entries(INTEGRATIONS).filter(
-    ([, i]) => i.type === 'universal-installer'
-  );
-  const pythonClis = Object.entries(INTEGRATIONS).filter(
-    ([, i]) => i.type === 'python-cli'
+  const rows = getIntegrationSummaries({ home: homedir(), env: process.env });
+  fmt.note(
+    rows.map(row => `${row.name.padEnd(14)} ${row.state.padEnd(11)} ${row.summary}`).join('\n'),
+    'Available integrations',
   );
 
-  const typeIcon = (type) =>
-    type === 'plugin' ? '🔌' : type === 'remote-mcp' ? '🌐' : type === 'universal-installer' ? '🪨' : '⚙️';
-
-  // Installed section
-  if (installed.length > 0) {
-    fmt.logMessage(`\n${chalk.bold.underline('Installed')}`);
-    for (const key of installed) {
-      const integration = INTEGRATIONS[key];
-      if (!integration) continue;
-      fmt.logSuccess(`  ${typeIcon(integration.type)} ${integration.label}`);
-    }
-  }
-
-  // Available Plugins
-  fmt.logMessage(`\n${chalk.bold.underline('Available Plugins')}`);
-  for (const [key, integration] of plugins) {
-    if (!installed.includes(key)) {
-      fmt.logMessage(
-        `  🔌 ${integration.label.padEnd(25)} — ${integration.description}`
-      );
-    }
-  }
-
-  // Available Remote MCPs
-  fmt.logMessage(`\n${chalk.bold.underline('Available Remote MCPs')}`);
-  for (const [key, integration] of remoteRcps) {
-    if (!installed.includes(key)) {
-      fmt.logMessage(
-        `  🌐 ${integration.label.padEnd(25)} — ${integration.description}`
-      );
-    }
-  }
-
-  // Universal Installers
-  if (universalInstallers.length > 0) {
-    fmt.logMessage(`\n${chalk.bold.underline('Universal Tools')}`);
-    for (const [key, integration] of universalInstallers) {
-      if (!installed.includes(key)) {
-        fmt.logMessage(
-          `  🪨 ${integration.label.padEnd(25)} — ${integration.description}`
-        );
-      }
-    }
-  }
-
-  // Python CLIs
-  if (pythonClis.length > 0) {
-    fmt.logMessage(`\n${chalk.bold.underline('Available Python Tools')}`);
-    for (const [key, integration] of pythonClis) {
-      if (!installed.includes(key)) {
-        fmt.logMessage(
-          `  🐍 ${integration.label.padEnd(25)} — ${integration.description}`
-        );
-      }
-    }
-  }
-
-  // Bundles
-  fmt.logMessage(`\n${chalk.bold.underline('Bundles')}`);
-  for (const [bundleKey, bundle] of Object.entries(BUNDLES)) {
-    fmt.logMessage(
-      `  📦 ${bundle.label.padEnd(25)} — ${bundle.description}`
-    );
-    fmt.logMessage(
-      `     Includes: ${bundle.includes.map((k) => INTEGRATIONS[k].label).join(', ')}`
-    );
-  }
-
   fmt.logMessage(`\n${chalk.dim('Commands:')}`);
   fmt.logMessage(`  aw integrations add <key>      Install a specific tool`);
+  fmt.logMessage(`  aw integrations add <key> --dry-run`);
+  fmt.logMessage(`  aw integrations add context-mode --strict`);
   fmt.logMessage(`  aw integrations remove <key>   Remove a tool`);
   fmt.logMessage(`  aw integrations bundle <name>  Install a preset bundle`);
 }
@@ -142,12 +103,11 @@ async function cmdAdd(args) {
 
   if (!INTEGRATIONS[key]) {
     // Suggest similar keys
-    const available = Object.keys(INTEGRATIONS);
     fmt.cancel(
       [
         `Unknown integration: ${chalk.red(key)}`,
         '',
-        `Available: ${available.join(', ')}`,
+        `Available: ${availableKeys()}`,
       ].join('\n')
     );
   }
@@ -155,13 +115,33 @@ async function cmdAdd(args) {
   const integration = INTEGRATIONS[key];
   fmt.intro(`Installing ${integration.label}`);
 
-  const success = await installIntegration(key, { silent: false });
+  const result = await installIntegration(key, {
+    home: homedir(),
+    env: process.env,
+    dryRun: args['--dry-run'] === true,
+    silent: false,
+  });
 
-  if (success) {
-    fmt.outro(`✓ ${integration.label} installed successfully`);
-  } else {
-    fmt.cancel(`Failed to install ${integration.label}`);
+  if (integration.type === 'context-mode') {
+    printContextModeAddResult(result);
+    if (!result.success) {
+      const message = result.error === 'partial-config'
+        ? `${integration.label} was only partially configured`
+        : `${integration.label} was not configured`;
+      if (args['--strict'] === true) {
+        fmt.cancel(message);
+      }
+      fmt.outro(message);
+      return;
+    }
+    fmt.outro(args['--dry-run'] === true
+      ? `${integration.label} install/config dry run complete`
+      : `${integration.label} configured`);
+    return;
   }
+
+  if (!integrationSucceeded(result)) fmt.cancel(`Failed to install ${integration.label}`);
+  fmt.outro(`✓ ${integration.label} installed successfully`);
 }
 
 // ────────────────────────────────────────────────────────────────────────────────
@@ -176,12 +156,11 @@ async function cmdRemove(args) {
   }
 
   if (!INTEGRATIONS[key]) {
-    const available = Object.keys(INTEGRATIONS);
     fmt.cancel(
       [
         `Unknown integration: ${chalk.red(key)}`,
         '',
-        `Available: ${available.join(', ')}`,
+        `Available: ${availableKeys()}`,
       ].join('\n')
     );
   }
@@ -189,13 +168,18 @@ async function cmdRemove(args) {
   const integration = INTEGRATIONS[key];
   fmt.intro(`Removing ${integration.label}`);
 
-  const success = await removeIntegration(key, { silent: false });
+  const result = await removeIntegration(key, {
+    home: homedir(),
+    dryRun: args['--dry-run'] === true,
+    silent: false,
+  });
 
-  if (success) {
-    fmt.outro(`✓ ${integration.label} removed successfully`);
-  } else {
-    fmt.cancel(`Failed to remove ${integration.label}`);
-  }
+  printWarnings(result.warnings);
+  printChangedFiles(result.changedFiles);
+  if (!integrationSucceeded(result)) fmt.cancel(`Failed to remove ${integration.label}`);
+  fmt.outro(args['--dry-run'] === true
+    ? `${integration.label} removal dry run complete`
+    : `✓ ${integration.label} removed successfully`);
 }
 
 // ────────────────────────────────────────────────────────────────────────────────
@@ -244,8 +228,8 @@ async function cmdBundle(args) {
   // Install all
   let successCount = 0;
   for (const key of bundle.includes) {
-    const success = await installIntegration(key, { silent: false });
-    if (success) successCount++;
+    const result = await installIntegration(key, { silent: false });
+    if (integrationSucceeded(result)) successCount++;
   }
 
   fmt.outro(

package/ecc.mjs

@@ -12,7 +12,12 @@ import { applyStoredStartupPreferences } from "./startup.mjs";
 
 const AW_ECC_REPO_SSH = "git@github.com:shreyansh-ghl/aw-ecc.git";
 const AW_ECC_REPO_HTTPS = "https://github.com/shreyansh-ghl/aw-ecc.git";
-export const AW_ECC_TAG = "v1.4.62";
+export const AW_ECC_TAG = "v1.4.63";
+const REQUIRED_ECC_FILES = [
+  "package.json",
+  "scripts/install-apply.js",
+  "scripts/sync-ecc-to-codex.sh",
+];
 
 const MARKETPLACE_NAME = "aw-marketplace";
 const PLUGIN_KEY = `aw@${MARKETPLACE_NAME}`;
@@ -85,11 +90,15 @@ async function cloneWithRefAsync(url, ref, dest) {
   }
 }
 
+function hasRequiredEccFiles(dest) {
+  return REQUIRED_ECC_FILES.every((relPath) => existsSync(join(dest, relPath)));
+}
+
 async function cloneOrUpdateAsync(tag, dest) {
   const overrideUrl = process.env.AW_ECC_CLONE_URL;
   const overrideRef = process.env.AW_ECC_CLONE_REF?.trim();
 
-  if (existsSync(join(dest, ".git"))) {
+  if (existsSync(join(dest, ".git")) && hasRequiredEccFiles(dest)) {
     try {
       if (!overrideUrl && !overrideRef) {
         await runA(`git -C ${dest} fetch --quiet --depth 1 origin tag ${tag}`);
@@ -102,6 +111,7 @@ async function cloneOrUpdateAsync(tag, dest) {
       }
       // Restore working tree — pruneStaleHooks may have deleted tracked files
       await runA(`git -C ${dest} checkout -- .`);
+      if (!hasRequiredEccFiles(dest)) throw new Error("aw-ecc checkout is missing required files");
       return;
     } catch { /* fall through to fresh clone */ }
   }
@@ -188,7 +198,7 @@ function cloneOrUpdate(tag, dest) {
   // AW_ECC_CLONE_REF lets aw init install ECC from a non-default branch or tag.
   const overrideRef = process.env.AW_ECC_CLONE_REF?.trim();
 
-  if (existsSync(join(dest, ".git"))) {
+  if (existsSync(join(dest, ".git")) && hasRequiredEccFiles(dest)) {
     try {
       if (!overrideUrl && !overrideRef) {
         run(`git -C ${dest} fetch --quiet --depth 1 origin tag ${tag}`);
@@ -201,6 +211,7 @@ function cloneOrUpdate(tag, dest) {
       }
       // Restore working tree — pruneStaleHooks may have deleted tracked files
       run(`git -C ${dest} checkout -- .`);
+      if (!hasRequiredEccFiles(dest)) throw new Error("aw-ecc checkout is missing required files");
       return;
     } catch { /* fall through to fresh clone */ }
   }

package/git.mjs

@@ -453,6 +453,7 @@ export function detectChanges(awHome, registryDir) {
     if (!line || line.length < 3) continue;
     const xy = line.slice(0, 2);
     const filePath = line.slice(3).trim();
+    if (filePath === `${registryDir}/.aw-upgrade.log`) continue;
     const registryPath = filePath.startsWith(registryDir + '/') ? filePath.slice(registryDir.length + 1) : filePath;
     const entry = { path: filePath, registryPath };
 
@@ -485,6 +486,7 @@ export function getStagedFiles(awHome, registryDir) {
       if (!line) continue;
       const [status, filePath] = line.split('\t');
       if (!filePath?.startsWith(registryDir + '/')) continue;
+      if (filePath === `${registryDir}/.aw-upgrade.log`) continue;
       result.push({
         path: filePath,
         registryPath: filePath.slice(registryDir.length + 1),