@ghl-ai/aw 0.1.42-beta.9 → 0.1.42

package/commands/init.mjs

@@ -13,15 +13,15 @@ import {
   readFileSync,
   rmSync,
   realpathSync,
-  appendFileSync,
 } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { join, dirname, sep } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
+import * as p from '@clack/prompts';
 import * as config from '../config.mjs';
 import * as fmt from '../fmt.mjs';
-import { chalk } from '../fmt.mjs';
+import { chalk, setSilent } from '../fmt.mjs';
 import { linkWorkspace } from '../link.mjs';
 import { generateCommands, copyInstructions, initAwDocs, syncHomeHarnessInstructions } from '../integrate.mjs';
 import { setupMcp } from '../mcp.mjs';
@@ -29,8 +29,10 @@ import { applyStoredStartupPreferences, ensureAwRuntimeHook } from '../startup.m
 import { installLocalCommitHook } from '../hooks.mjs';
 import { autoUpdate, promptUpdate } from '../update.mjs';
 import { installGlobalHooks } from '../hooks.mjs';
-import { installAwEcc } from '../ecc.mjs';
+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 {
   initPersistentClone,
   isValidClone,
@@ -88,24 +90,65 @@ function syncHomeAndProjectInstructions(cwd, namespace) {
   }
 }
 
-// ── Ensure ~/.aw/.gitignore has personal/local entries ───────────────────
-
-const AW_GITIGNORE_ENTRIES = [
+// ── Ensure ~/.aw/.git/info/exclude has the whitelist block ─────────────
+//
+// Strategy: only .aw_registry/, .aw_rules/, content/ are tracked — everything
+// else at the top level of ~/.aw/ is local-only (telemetry/, hooks/, logs,
+// .DS_Store, etc.). We write to .git/info/exclude (not tracked .gitignore)
+// so upstream pulls never conflict.
+
+const AW_MANAGED_BEGIN = '# BEGIN aw-managed (do not edit; managed by `aw init`)';
+const AW_MANAGED_END   = '# END aw-managed';
+
+const AW_MANAGED_BLOCK = [
+  AW_MANAGED_BEGIN,
+  '# Whitelist: only these top-level entries are tracked; everything else is local-only.',
+  '/*',
+  '!/.aw_registry',
+  '!/.aw_rules',
+  '!/content',
+  '',
+  '# Nested local state within whitelisted dirs',
+  '/.aw_registry/.sync-config.json',
+  AW_MANAGED_END,
+  '',
+].join('\n');
+
+// Legacy flat lines appended by earlier versions of ensureAwGitignore — strip on upgrade
+// so we don't leave stale rules lingering outside the managed block.
+const LEGACY_GITIGNORE_LINES = new Set([
   '.aw_registry/.sync-config.json',
   'hooks/',
-];
+  '# aw: personal/local — do not commit',
+]);
 
-function ensureAwGitignore(awHome) {
-  // Use .git/info/exclude so the tracked .gitignore stays clean
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function ensureAwGitignore(awHome) {
   const excludePath = join(awHome, '.git', 'info', 'exclude');
   let existing = '';
-  try { existing = readFileSync(excludePath, 'utf8'); } catch { /* doesn't exist yet */ }
-  const missing = AW_GITIGNORE_ENTRIES.filter(e => !existing.includes(e));
-  if (missing.length === 0) return;
-  const block = (existing.endsWith('\n') || existing === '' ? '' : '\n')
-    + '# aw: personal/local — do not commit\n'
-    + missing.join('\n') + '\n';
-  try { appendFileSync(excludePath, block); } catch { /* best effort */ }
+  try { existing = readFileSync(excludePath, 'utf8'); } catch (err) { void err; /* doesn't exist yet */ }
+
+  // Strip any prior aw-managed block so re-rendering is idempotent.
+  const blockRegex = new RegExp(
+    `${escapeRegex(AW_MANAGED_BEGIN)}[\\s\\S]*?${escapeRegex(AW_MANAGED_END)}\\n?`,
+    'g'
+  );
+  const withoutManaged = existing.replace(blockRegex, '');
+
+  // Strip legacy flat lines (pre-whitelist implementation).
+  const cleaned = withoutManaged
+    .split('\n')
+    .filter(line => !LEGACY_GITIGNORE_LINES.has(line.trim()))
+    .join('\n');
+
+  const prefix = cleaned === '' || cleaned.endsWith('\n') ? cleaned : cleaned + '\n';
+  const next = prefix + AW_MANAGED_BLOCK;
+
+  if (next === existing) return; // already up to date
+  try { writeFileSync(excludePath, next); } catch (err) { void err; /* best effort */ }
 }
 
 // ── IDE tasks for auto-pull ─────────────────────────────────────────────
@@ -137,11 +180,11 @@ function installIdeTasks() {
         existing.tasks = existing.tasks || [];
         existing.tasks.push(vscodeTask.tasks[0]);
         writeFileSync(tasksPath, JSON.stringify(existing, null, 2) + '\n');
-        fmt.logStep(`Added auto-pull task to ${ide}`);
+        fmt.logStep(`Auto-sync task added to ${ide}`);
       } catch { /* corrupted tasks.json, skip */ }
     } else {
       writeFileSync(tasksPath, JSON.stringify(vscodeTask, null, 2) + '\n');
-      fmt.logStep(`Added auto-pull task to ${ide}`);
+      fmt.logStep(`Auto-sync task added to ${ide}`);
     }
   }
 }
@@ -153,6 +196,16 @@ export async function initCommand(args) {
   let user = args['--user'] || '';
   const silent = args['--silent'] === true;
 
+  // In silent mode, suppress ALL fmt output and show a single spinner.
+  // setSilent(true) makes every fmt.* call a no-op — internal functions
+  // (hooks.mjs, mcp.mjs, integrate.mjs, ecc.mjs) are silenced automatically.
+  let silentSpinner = null;
+  if (silent) {
+    setSilent(true);
+    silentSpinner = p.spinner();
+    silentSpinner.start('Initializing...');
+  }
+
   fmt.intro(`aw init ${chalk.dim('v' + VERSION)}`);
 
   // ── Validate ──────────────────────────────────────────────────────────
@@ -283,6 +336,7 @@ export async function initCommand(args) {
       syncRulesTargets(cwd);
     }
     removeLegacyRegistryRules();
+    if (!silent) fmt.logStep('Rules synced');
 
     // Ensure project worktree sparse checkout matches the global clone.
     // Covers the case where a namespace was added from HOME (or another project)
@@ -292,13 +346,19 @@ export async function initCommand(args) {
       try { syncWorktreeSparseCheckout(AW_HOME, localAw); } catch { /* best effort */ }
     }
 
+    // Prune stale hooks from prior version before installing new ones
+    const oldManifest = readHookManifest();
+    if (oldManifest) pruneStaleHooks(oldManifest);
+
     await installAwEcc(cwd, { silent });
+
     ensureAwRuntimeHook(HOME);
     syncHomeAndProjectInstructions(cwd, freshCfg?.namespace || team);
     await setupMcp(HOME, freshCfg?.namespace || team, { silent });
     applyStoredStartupPreferences(HOME);
     const removedLegacyStartupFiles = cwd !== HOME ? removeWorkspaceHookDefaults(cwd) : [];
     installGlobalHooks();
+    if (!silent) fmt.logStep('Hooks and IDE integration configured');
 
     // Remove old local .git/hooks/post-checkout that pre-dates core.hooksPath (creates stale .aw_registry symlink)
     if (cwd !== HOME) {
@@ -325,13 +385,19 @@ export async function initCommand(args) {
 
     // Wire ~/.claude/.cursor/.codex to the project's registry when in a project,
     // so edits to project/.aw/.aw_registry/ are instantly visible in global IDE dirs.
+    if (!silent) fmt.logStep('Wiring IDE symlinks...');
     const projectRegistryDir = cwd !== HOME ? join(cwd, '.aw', REGISTRY_DIR) : null;
     const awDirForLinks = (projectRegistryDir && existsSync(projectRegistryDir)) ? projectRegistryDir : null;
     const symlinks = linkWorkspace(HOME, awDirForLinks, { silent: true });
     const commands = generateCommands(HOME, { silent: true });
     if (cwd !== HOME) installLocalCommitHook(cwd);
+    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 */ }
 
     if (silent) {
+      if (silentSpinner) { silentSpinner.stop('Done'); setSilent(false); }
       autoUpdate(await args._updateCheck);
     } else {
       fmt.outro([
@@ -377,7 +443,6 @@ export async function initCommand(args) {
   }
 
   fmt.note([
-    `${chalk.dim('source:')}     ~/.aw/ → ~/.aw_registry/ (symlink)`,
     folderName ? `${chalk.dim('namespace:')}  ${folderName}` : `${chalk.dim('namespace:')}  ${chalk.dim('none')}`,
     user ? `${chalk.dim('user:')}       ${user}` : null,
     `${chalk.dim('version:')}    v${VERSION}`,
@@ -402,7 +467,7 @@ export async function initCommand(args) {
   if (!awRegistryLstat) {
     try {
       symlinkSync(join(AW_HOME, REGISTRY_DIR), GLOBAL_AW_DIR);
-      fmt.logStep('Created ~/.aw_registry/ symlink');
+      fmt.logStep('Registry linked');
     } catch (e) {
       fmt.logWarn(`Could not create symlink ~/.aw_registry/: ${e.message}`);
     }
@@ -411,7 +476,7 @@ export async function initCommand(args) {
     try {
       rmSync(GLOBAL_AW_DIR);
       symlinkSync(join(AW_HOME, REGISTRY_DIR), GLOBAL_AW_DIR);
-      fmt.logStep('Updated ~/.aw_registry/ symlink');
+      fmt.logStep('Registry linked');
     } catch (e) {
       fmt.logWarn(`Could not update symlink ~/.aw_registry/: ${e.message}`);
     }
@@ -422,21 +487,32 @@ export async function initCommand(args) {
   if (folderName) {
     config.addPattern(GLOBAL_AW_DIR, folderName);
   }
+  // Parallel batch A: rules sync (HOME + cwd are independent targets)
   syncRulesTargets(HOME);
-  if (cwd !== HOME) {
-    syncRulesTargets(cwd);
-  }
+  if (cwd !== HOME) syncRulesTargets(cwd);
   removeLegacyRegistryRules();
+  if (!silent) fmt.logStep('Rules synced');
 
   // Step 3: Setup tasks, MCP, hooks
+  // Prune stale hooks from prior version before installing new ones
+  const oldManifestFresh = readHookManifest();
+  if (oldManifestFresh) pruneStaleHooks(oldManifestFresh);
+
   await installAwEcc(cwd, { silent });
+
   ensureAwRuntimeHook(HOME);
-  syncHomeAndProjectInstructions(cwd, team);
-  const mcpFiles = await setupMcp(HOME, team, { silent }) || [];
+
+  // Parallel batch B: post-ECC setup (instructions and MCP are independent)
+  const [, mcpFiles] = await Promise.all([
+    Promise.resolve(syncHomeAndProjectInstructions(cwd, team)),
+    setupMcp(HOME, team, { silent }),
+  ]);
+  // applyStoredStartupPreferences reads settings written by ECC — keep after batch B
   applyStoredStartupPreferences(HOME);
   const removedLegacyStartupFiles = cwd !== HOME ? removeWorkspaceHookDefaults(cwd) : [];
   const hooksInstalled = installGlobalHooks();
   installIdeTasks();
+  if (!silent) fmt.logStep('Hooks and IDE integration configured');
 
   // Remove old local .git/hooks/post-checkout that pre-dates core.hooksPath
   if (cwd !== HOME) {
@@ -462,18 +538,28 @@ export async function initCommand(args) {
 
   // Step 5: Wire ~/.claude/.cursor/.codex to the project's registry when in a project,
   // so edits to project/.aw/.aw_registry/ are instantly visible in global IDE dirs.
-  const ideSpinner = fmt.spinner();
-  ideSpinner.start('Wiring IDE symlinks...');
+  if (!silent) fmt.logStep('Wiring IDE symlinks...');
   const projectRegistryDir = cwd !== HOME ? join(cwd, '.aw', REGISTRY_DIR) : null;
   const awDirForLinks = (projectRegistryDir && existsSync(projectRegistryDir)) ? projectRegistryDir : null;
-  const symlinks = linkWorkspace(HOME, awDirForLinks, { silent: true });
+  // Parallel batch C: symlinks + commands are independent
   if (cwd !== HOME) installLocalCommitHook(cwd);
-  ideSpinner.message('Generating commands...');
-  const commands = generateCommands(HOME, { silent: true });
-  ideSpinner.stop(`IDE wired — ${chalk.bold(symlinks)} symlinks · ${chalk.bold(commands)} commands`);
+  const [symlinks, commands] = [
+    linkWorkspace(HOME, awDirForLinks, { silent: true }),
+    generateCommands(HOME, { silent: true }),
+  ];
+  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 */ }
+
+  // Ensure telemetry config exists (generates machine_id on first run)
+  ensureTelemetryConfig();
 
   // Offer to update if a newer version is available
-  await promptUpdate(await args._updateCheck);
+  if (!silent) await promptUpdate(await args._updateCheck);
+
+  // Stop silent spinner before outro (outro is already suppressed by setSilent)
+  if (silentSpinner) { silentSpinner.stop('Done'); setSilent(false); }
 
   fmt.outro([
     '⟁  Install complete',

package/commands/nuke.mjs

@@ -16,6 +16,7 @@ import { uninstallAwEcc } from '../ecc.mjs';
 import { removeMcpConfig } from '../mcp.mjs';
 import { listProjectWorktrees } from '../git.mjs';
 import { removeWorkspaceHookDefaults } from '../codex.mjs';
+import { readHookManifest, pruneStaleHooks, removeHookManifest } from '../hook-cleanup.mjs';
 
 const HOME = homedir();
 const GLOBAL_AW_DIR = join(HOME, '.aw_registry');
@@ -129,43 +130,34 @@ function removeIdeSymlinks() {
   return removed;
 }
 
-// 3. Find and remove ALL .aw_registry symlinks from project directories
+// 3. Find and remove ALL .aw_registry symlinks + legacy hooks from project directories.
+//    Uses a single batched find instead of 3 sequential ones for performance.
 async function removeProjectSymlinks() {
   let removed = 0;
+  let hooksRemoved = 0;
 
-  // Use find command for thorough search.
-  // Append "|| true" so find's exit code is always 0 (find exits 1 on permission-denied dirs).
-  const { stdout: registryLinks } = await exec(
-    `find "${HOME}" -maxdepth 4 -name ".aw_registry" -type l 2>/dev/null || true`,
+  // Single find: .aw_registry symlinks + legacy git hooks
+  const { stdout } = await exec(
+    `find "${HOME}" -maxdepth 5 \\( -name ".aw_registry" -type l -o -path "*/.git/hooks/post-checkout" -type f -o -path "*/.git/hooks/prepare-commit-msg" -type f \\) 2>/dev/null || true`,
     { encoding: 'utf8', timeout: 30000 }
   );
-  for (const linkPath of registryLinks.trim().split('\n').filter(Boolean)) {
-    try {
-      removeWorkspaceHookDefaults(dirname(linkPath));
-      unlinkSync(linkPath);
-      removed++;
-    } catch { /* best effort */ }
-  }
 
-  // Also remove legacy local .git/hooks/post-checkout installed by old aw versions
-  // and prepare-commit-msg hooks installed by installLocalCommitHook
-  let hooksRemoved = 0;
-  const hookNames = ['post-checkout', 'prepare-commit-msg'];
-  for (const hookName of hookNames) {
-    const { stdout: hookFiles } = await exec(
-      `find "${HOME}" -maxdepth 5 -path "*/.git/hooks/${hookName}" -type f 2>/dev/null || true`,
-      { encoding: 'utf8', timeout: 30000 }
-    );
-    for (const hookPath of hookFiles.trim().split('\n').filter(Boolean)) {
-      try {
-        const content = readFileSync(hookPath, 'utf8');
-        // Only remove hooks that AW installed — identified by our marker comment
+  for (const itemPath of stdout.trim().split('\n').filter(Boolean)) {
+    try {
+      if (itemPath.endsWith('.aw_registry')) {
+        // Registry symlink — clean workspace hooks then remove
+        removeWorkspaceHookDefaults(dirname(itemPath));
+        unlinkSync(itemPath);
+        removed++;
+      } else if (itemPath.includes('.git/hooks/')) {
+        // Legacy git hook — only remove if AW-installed
+        const content = readFileSync(itemPath, 'utf8');
         if (content.includes('aw:') || content.includes('aw: auto-link registry') || content.includes('ln -s "$AW_REGISTRY"')) {
-          unlinkSync(hookPath);
+          unlinkSync(itemPath);
           hooksRemoved++;
         }
-      } catch { /* best effort */ }
-    }
+      }
+    } catch { /* best effort */ }
   }
 
   return { removed, hooksRemoved };
@@ -232,6 +224,9 @@ export async function nukeCommand(args) {
 
   const manifest = loadManifest();
 
+  // Read hook manifest into memory before any deletion (manifest file lives in ~/.aw/hooks/)
+  const hookManifest = readHookManifest();
+
   // Use lstatSync (not existsSync) so a dangling symlink still shows as "found"
   let registryFound = false;
   try { lstatSync(GLOBAL_AW_DIR); registryFound = true; } catch { /* not present */ }
@@ -250,6 +245,9 @@ export async function nukeCommand(args) {
   const ideCount = removeIdeSymlinks();
   uninstallAwEcc();
   removeMcpConfig();
+  // Prune stale hook entries using manifest (catches entries not tracked by install-state)
+  if (hookManifest) pruneStaleHooks(hookManifest);
+  removeHookManifest();
   const totalIde = createdCount + ideCount;
   ideSpinner.stop(`IDE symlinks and commands removed${totalIde > 0 ? ` (${totalIde} files)` : ''}`);
 
@@ -294,45 +292,36 @@ export async function nukeCommand(args) {
     } catch { /* best effort */ }
   }
 
-  // 4b. Remove new-style .aw symlinks pointing to ~/.aw
-  // These are created by the symlink model and are NOT tracked by git worktree list.
+  // 4b+4c. Batched find for .aw symlinks and directories (single traversal instead of two).
   try {
-    const { stdout: awLinks } = await exec(
-      `find "${HOME}" -maxdepth 5 -name ".aw" -type l 2>/dev/null || true`,
+    const { stdout: awItems } = await exec(
+      `find "${HOME}" -maxdepth 5 -name ".aw" \\( -type l -o -type d \\) 2>/dev/null || true`,
       { encoding: 'utf8', timeout: 30000 }
     );
-    for (const linkPath of awLinks.trim().split('\n').filter(Boolean)) {
+    for (const itemPath of awItems.trim().split('\n').filter(Boolean)) {
+      if (itemPath === AW_HOME) continue; // skip ~/.aw itself
       try {
-        const target = readlinkSync(linkPath);
-        if (target === AW_HOME || target.endsWith('/.aw')) {
-          unlinkSync(linkPath);
-          wtRemoved++;
-        }
-      } catch { /* best effort */ }
-    }
-  } catch { /* best effort */ }
-
-  // 4c. Remove old-style .aw directories (git worktrees) that git worktree list missed.
-  // After ~/.aw is deleted these become dangling — find and clean them up.
-  try {
-    const { stdout: awDirs } = await exec(
-      `find "${HOME}" -maxdepth 5 -name ".aw" -type d 2>/dev/null || true`,
-      { encoding: 'utf8', timeout: 30000 }
-    );
-    for (const dirPath of awDirs.trim().split('\n').filter(Boolean)) {
-      if (dirPath === AW_HOME) continue; // skip ~/.aw itself
-      try {
-        const gitFile = join(dirPath, '.git');
-        const stat = lstatSync(gitFile);
-        if (stat.isFile()) {
-          const content = readFileSync(gitFile, 'utf8').trim();
-          // Old git worktree pointing into ~/.aw — safe to remove
-          if (content.includes(`${AW_HOME}/.git/`)) {
-            rmSync(dirPath, { recursive: true, force: true });
+        const stat = lstatSync(itemPath);
+        if (stat.isSymbolicLink()) {
+          // New-style symlink pointing to ~/.aw
+          const target = readlinkSync(itemPath);
+          if (target === AW_HOME || target.endsWith('/.aw')) {
+            unlinkSync(itemPath);
             wtRemoved++;
           }
+        } else if (stat.isDirectory()) {
+          // Old-style git worktree — check .git file
+          const gitFile = join(itemPath, '.git');
+          const gitStat = lstatSync(gitFile);
+          if (gitStat.isFile()) {
+            const content = readFileSync(gitFile, 'utf8').trim();
+            if (content.includes(`${AW_HOME}/.git/`)) {
+              rmSync(itemPath, { recursive: true, force: true });
+              wtRemoved++;
+            }
+          }
         }
-      } catch { /* not a worktree or already gone */ }
+      } catch { /* not a worktree/symlink or already gone */ }
     }
   } catch { /* best effort */ }
 

package/ecc.mjs

@@ -1,4 +1,6 @@
-import { execSync } from "node:child_process";
+import { execSync, exec as execCb } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(execCb);
 import {
   existsSync, readFileSync, readdirSync,
   mkdirSync, rmSync, writeFileSync, renameSync,
@@ -10,7 +12,7 @@ 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.38-beta.8";
+export const AW_ECC_TAG = "v1.4.41";
 
 const MARKETPLACE_NAME = "aw-marketplace";
 const PLUGIN_KEY = `aw@${MARKETPLACE_NAME}`;
@@ -63,6 +65,70 @@ function cloneWithRef(url, ref, dest) {
   }
 }
 
+// Async variants — allow event loop to tick so spinners can render.
+async function runA(cmd, opts = {}) {
+  const { stdout } = await execAsync(cmd, { ...opts, maxBuffer: 10 * 1024 * 1024 });
+  return stdout;
+}
+
+async function fetchOverrideRefAsync(dest, ref) {
+  await runA(`git -C ${dest} fetch --quiet --depth 1 origin ${ref}`);
+  await runA(`git -C ${dest} checkout --quiet FETCH_HEAD`);
+}
+
+async function cloneWithRefAsync(url, ref, dest) {
+  try {
+    await runA(`git clone --quiet --depth 1 --branch ${ref} "${url}" "${dest}"`);
+  } catch {
+    await runA(`git clone --quiet --depth 1 "${url}" "${dest}"`);
+    await fetchOverrideRefAsync(dest, ref);
+  }
+}
+
+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"))) {
+    try {
+      if (!overrideUrl && !overrideRef) {
+        await runA(`git -C ${dest} fetch --quiet --depth 1 origin tag ${tag}`);
+        await runA(`git -C ${dest} checkout --quiet ${tag}`);
+      } else {
+        if (overrideUrl) {
+          await runA(`git -C ${dest} remote set-url origin "${overrideUrl}"`);
+        }
+        await fetchOverrideRefAsync(dest, overrideRef || tag);
+      }
+      // Restore working tree — pruneStaleHooks may have deleted tracked files
+      await runA(`git -C ${dest} checkout -- .`);
+      return;
+    } catch { /* fall through to fresh clone */ }
+  }
+  if (existsSync(dest)) rmSync(dest, { recursive: true, force: true });
+  if (overrideUrl) {
+    if (overrideRef) {
+      await cloneWithRefAsync(overrideUrl, overrideRef, dest);
+    } else {
+      await runA(`git clone --quiet --depth 1 "${overrideUrl}" "${dest}"`);
+    }
+  } else {
+    if (overrideRef) {
+      try {
+        await cloneWithRefAsync(AW_ECC_REPO_SSH, overrideRef, dest);
+      } catch {
+        await cloneWithRefAsync(AW_ECC_REPO_HTTPS, overrideRef, dest);
+      }
+      return;
+    }
+    try {
+      await runA(`git clone --quiet --depth 1 --branch ${tag} ${AW_ECC_REPO_SSH} ${dest}`);
+    } catch {
+      await runA(`git clone --quiet --depth 1 --branch ${tag} ${AW_ECC_REPO_HTTPS} ${dest}`);
+    }
+  }
+}
+
 function readIfExists(path) {
   try { return existsSync(path) ? readFileSync(path, "utf8") : null; } catch { return null; }
 }
@@ -133,6 +199,8 @@ function cloneOrUpdate(tag, dest) {
         }
         fetchOverrideRef(dest, overrideRef || tag);
       }
+      // Restore working tree — pruneStaleHooks may have deleted tracked files
+      run(`git -C ${dest} checkout -- .`);
       return;
     } catch { /* fall through to fresh clone */ }
   }
@@ -259,13 +327,16 @@ export async function installAwEcc(
   { targets = ["cursor", "claude", "codex"], silent = false } = {},
 ) {
   if (process.env.AW_NO_ECC === '1') return;
-  if (!silent) fmt.logStep("Installing aw-ecc engine...");
 
   const repoDir = eccDir();
   const home = homedir();
 
+  const eccSpinner = silent ? null : fmt.spinner();
+
   try {
-    cloneOrUpdate(AW_ECC_TAG, repoDir);
+    if (eccSpinner) eccSpinner.start('Cloning aw-ecc engine...');
+    await cloneOrUpdateAsync(AW_ECC_TAG, repoDir);
+    if (eccSpinner) eccSpinner.message('Installing aw-ecc dependencies...');
 
     // Claude Code: plugin install via marketplace CLI (proper agent dispatch)
     if (targets.includes("claude")) {
@@ -279,7 +350,7 @@ export async function installAwEcc(
     // Claude + Cursor + Codex: file-copy via install-apply.js
     const fileCopyTargets = targets.filter((t) => FILE_COPY_TARGETS.includes(t));
     if (fileCopyTargets.length > 0) {
-      run("npm install --no-audit --no-fund --ignore-scripts --loglevel=error", {
+      await runA("npm install --no-audit --no-fund --ignore-scripts --loglevel=error", {
         cwd: repoDir,
       });
       // generate-aw-hooks.js produces hooks.json and hook script sources that
@@ -291,15 +362,14 @@ export async function installAwEcc(
           run(`node "${generateHooksScript}"`, { cwd: repoDir });
         } catch { /* best effort — older engine versions may not have this script */ }
       }
-      for (const target of fileCopyTargets) {
+      if (eccSpinner) eccSpinner.message('Applying aw-ecc to IDE targets...');
+      // Each target writes to disjoint paths (~/.claude/, ~/.cursor/, ~/.codex/) — safe to parallelize.
+      await Promise.all(fileCopyTargets.map(async (target) => {
         try {
           const snapshot = snapshotProtectedConfigs(home, target);
 
           // Always use HOME as cwd so files land in ~/.<target>/ globally.
           const runCwd = homedir();
-          // For claude: install the safe no-commands module set. The plugin
-          // already owns /aw:* command registration, and broader profiles with
-          // `--without baseline:commands` can fail on commands-core deps.
           const installArgs = target === "claude"
             ? `--target ${target} --modules ${CLAUDE_FILE_COPY_MODULES.join(",")}`
             : `--target ${target} --profile full`;
@@ -307,34 +377,24 @@ export async function installAwEcc(
             `node ${join(repoDir, "scripts/install-apply.js")} ${installArgs}`,
             { cwd: runCwd },
           );
-          // Move cursor commands into aw/ subfolder for namespace consistency
-          // so they're accessible as /aw:tdd, /aw:plan — same as Claude Code plugin.
           if (target === "cursor") {
             namespaceCursorCommands(runCwd);
-            // Cursor commands use hyphens (commands/aw/plan.md -> /aw-plan)
-            // but source skill/rule files use canonical colons (/aw:plan).
-            // Transform /aw: -> /aw- in installed cursor skill/rule files.
             transformCursorAwRefs(home);
           }
-          // Run sync script for codex: generates ~/.codex/prompts/*.md and
-          // merges AGENTS.md — Codex has no slash commands, so prompts are the
-          // equivalent of commands.
           if (target === "codex") {
             syncEccToCodex(repoDir);
           }
-
-          // Critical: preserve user-owned config files if they existed before
-          // running aw-ecc (aw should only add, never replace user settings).
           restoreProtectedConfigs(snapshot);
         } catch { /* target not supported — skip */ }
-      }
+      }));
     }
 
     applyStoredStartupPreferences();
 
-    if (!silent) fmt.logSuccess("aw-ecc engine installed");
+    if (eccSpinner) eccSpinner.stop('aw-ecc engine installed');
   } catch (err) {
-    if (!silent) fmt.logWarn(`aw-ecc install failed: ${err.message}`);
+    if (eccSpinner) eccSpinner.stop(chalk.yellow(`aw-ecc install failed: ${err.message}`));
+    else if (!silent) fmt.logWarn(`aw-ecc install failed: ${err.message}`);
   }
 }