@ghl-ai/aw 0.1.42-beta.3 → 0.1.42-beta.31

package/commands/init.mjs

@@ -28,8 +28,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,
@@ -323,6 +325,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)
@@ -332,13 +335,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) {
@@ -365,11 +374,16 @@ 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) {
       autoUpdate(await args._updateCheck);
@@ -462,21 +476,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) {
@@ -502,15 +527,22 @@ 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);

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.3";
+export const AW_ECC_TAG = "v1.4.41-beta.1";
 
 const MARKETPLACE_NAME = "aw-marketplace";
 const PLUGIN_KEY = `aw@${MARKETPLACE_NAME}`;
@@ -63,6 +65,68 @@ 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);
+      }
+      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; }
 }
@@ -259,13 +323,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 +346,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 +358,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 +373,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}`);
   }
 }
 

package/hook-cleanup.mjs

@@ -0,0 +1,301 @@
+// hook-cleanup.mjs — Hook cleanup manifest for safe version transitions.
+//
+// writeHookManifest()  → snapshots all AW hook touchpoints to ~/.aw/hooks/manifest.json
+// readHookManifest()   → reads and validates the manifest
+// pruneStaleHooks()    → removes hook entries and runtime deps listed in a manifest
+// removeHookManifest() → deletes the manifest file
+
+import {
+  existsSync, mkdirSync, readFileSync, readdirSync,
+  rmSync, writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+const SCHEMA_VERSION = 'aw-hooks.v1';
+const HOME = homedir();
+const MANIFEST_PATH = join(HOME, '.aw', 'hooks', 'manifest.json');
+
+// ── Patterns matching AW-managed hook entries ────────────────────────────
+
+function isManagedClaudeEntry(entry) {
+  if (entry?.description === 'AW usage telemetry') return true;
+  const cmds = Array.isArray(entry?.hooks) ? entry.hooks.map(h => h?.command || '') : [];
+  return cmds.some(c => c.includes('aw-usage-'));
+}
+
+function isManagedCursorEntry(entry) {
+  const cmd = String(entry?.command || '');
+  return cmd.includes('.cursor/hooks/') || cmd.includes('aw-ecc');
+}
+
+function isManagedCodexEntry(entry) {
+  if (Array.isArray(entry?.hooks)) {
+    return entry.hooks.some(h => {
+      const cmd = String(h?.command || '');
+      return cmd.includes('.codex/hooks/') || cmd.includes('aw-ecc') || cmd.includes('aw-session-start');
+    });
+  }
+  return false;
+}
+
+// ── Read helpers ─────────────────────────────────────────────────────────
+
+function readJson(filePath) {
+  if (!existsSync(filePath)) return null;
+  try { return JSON.parse(readFileSync(filePath, 'utf8')); } catch { return null; }
+}
+
+function writeJson(filePath, data) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n');
+}
+
+// ── Collect current hook state ───────────────────────────────────────────
+
+function collectClaudeTouchpoints() {
+  const settingsPath = join(HOME, '.claude', 'settings.json');
+  const hooksJsonPath = join(HOME, '.claude', 'hooks', 'hooks.json');
+  const settings = readJson(settingsPath);
+  const phases = [];
+  if (settings?.hooks) {
+    for (const phase of Object.keys(settings.hooks)) {
+      const entries = settings.hooks[phase];
+      if (Array.isArray(entries) && entries.some(isManagedClaudeEntry)) {
+        phases.push(phase);
+      }
+    }
+  }
+  return {
+    settingsPath,
+    hooksJsonPath: existsSync(hooksJsonPath) ? hooksJsonPath : null,
+    managedPhases: phases,
+  };
+}
+
+function collectCursorTouchpoints() {
+  const hooksJsonPath = join(HOME, '.cursor', 'hooks.json');
+  const config = readJson(hooksJsonPath);
+  const phases = [];
+  if (config?.hooks) {
+    for (const phase of Object.keys(config.hooks)) {
+      const entries = config.hooks[phase];
+      if (Array.isArray(entries) && entries.some(isManagedCursorEntry)) {
+        phases.push(phase);
+      }
+    }
+  }
+  return { hooksJsonPath, managedPhases: phases };
+}
+
+function collectCodexTouchpoints() {
+  const hooksJsonPath = join(HOME, '.codex', 'hooks.json');
+  const configPath = join(HOME, '.codex', 'config.toml');
+  const config = readJson(hooksJsonPath);
+  const phases = [];
+  if (config?.hooks) {
+    for (const phase of Object.keys(config.hooks)) {
+      const entries = config.hooks[phase];
+      if (Array.isArray(entries) && entries.some(isManagedCodexEntry)) {
+        phases.push(phase);
+      }
+    }
+  }
+  return {
+    configPath: existsSync(configPath) ? configPath : null,
+    hooksJsonPath,
+    managedPhases: phases,
+  };
+}
+
+function collectGitTouchpoints() {
+  const hooksDir = join(HOME, '.aw', 'hooks');
+  const scripts = [];
+  if (existsSync(hooksDir)) {
+    try {
+      for (const entry of readdirSync(hooksDir)) {
+        // Exclude the manifest itself and hidden files
+        if (entry === 'manifest.json' || entry.startsWith('.')) continue;
+        scripts.push(entry);
+      }
+    } catch { /* best effort */ }
+  }
+  return { hooksDir, scripts };
+}
+
+function collectRuntimeDeps() {
+  const deps = [];
+  const hooksDir = join(HOME, '.aw-ecc', 'scripts', 'hooks');
+  const libDir = join(HOME, '.aw-ecc', 'scripts', 'lib');
+
+  if (existsSync(hooksDir)) {
+    try {
+      for (const entry of readdirSync(hooksDir)) {
+        if (entry.startsWith('aw-usage-')) {
+          deps.push(join(hooksDir, entry));
+        }
+      }
+    } catch { /* best effort */ }
+  }
+
+  const telemetryLib = join(libDir, 'aw-usage-telemetry.js');
+  if (existsSync(telemetryLib)) {
+    deps.push(telemetryLib);
+  }
+
+  return deps;
+}
+
+// ── Public API ───────────────────────────────────────────────────────────
+
+/**
+ * Write a hook manifest capturing all current AW hook touchpoints.
+ * @param {{ eccVersion: string, awVersion: string }} opts
+ * @returns {object} the written manifest
+ */
+export function writeHookManifest({ eccVersion, awVersion }) {
+  const manifest = {
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: new Date().toISOString(),
+    eccVersion,
+    awVersion,
+    touchpoints: {
+      claude: collectClaudeTouchpoints(),
+      cursor: collectCursorTouchpoints(),
+      codex: collectCodexTouchpoints(),
+      git: collectGitTouchpoints(),
+    },
+    runtimeDeps: collectRuntimeDeps(),
+  };
+
+  writeJson(MANIFEST_PATH, manifest);
+  return manifest;
+}
+
+/**
+ * Read and validate the hook manifest.
+ * @returns {object|null} the manifest, or null if missing/invalid
+ */
+export function readHookManifest() {
+  const data = readJson(MANIFEST_PATH);
+  if (!data || data.schemaVersion !== SCHEMA_VERSION) return null;
+  return data;
+}
+
+/**
+ * Remove hook entries and runtime deps listed in a manifest.
+ * Does NOT touch git hooks (handled by removeGlobalHooks).
+ * @param {object} manifest — from readHookManifest()
+ * @returns {number} count of items removed
+ */
+export function pruneStaleHooks(manifest) {
+  if (!manifest?.touchpoints) return 0;
+  let removed = 0;
+
+  // Claude: remove managed telemetry entries from settings.json
+  const claudeSettings = manifest.touchpoints.claude;
+  if (claudeSettings?.settingsPath && claudeSettings.managedPhases?.length > 0) {
+    const config = readJson(claudeSettings.settingsPath);
+    if (config?.hooks) {
+      let changed = false;
+      for (const phase of claudeSettings.managedPhases) {
+        const entries = config.hooks[phase];
+        if (!Array.isArray(entries)) continue;
+        const filtered = entries.filter(e => !isManagedClaudeEntry(e));
+        if (filtered.length !== entries.length) {
+          changed = true;
+          removed += entries.length - filtered.length;
+          if (filtered.length > 0) {
+            config.hooks[phase] = filtered;
+          } else {
+            delete config.hooks[phase];
+          }
+        }
+      }
+      if (changed) {
+        if (Object.keys(config.hooks).length === 0) delete config.hooks;
+        writeJson(claudeSettings.settingsPath, config);
+      }
+    }
+  }
+
+  // Cursor: remove managed entries from hooks.json
+  const cursorHooks = manifest.touchpoints.cursor;
+  if (cursorHooks?.hooksJsonPath && cursorHooks.managedPhases?.length > 0) {
+    const config = readJson(cursorHooks.hooksJsonPath);
+    if (config?.hooks) {
+      let changed = false;
+      for (const phase of cursorHooks.managedPhases) {
+        const entries = config.hooks[phase];
+        if (!Array.isArray(entries)) continue;
+        const filtered = entries.filter(e => !isManagedCursorEntry(e));
+        if (filtered.length !== entries.length) {
+          changed = true;
+          removed += entries.length - filtered.length;
+          if (filtered.length > 0) {
+            config.hooks[phase] = filtered;
+          } else {
+            delete config.hooks[phase];
+          }
+        }
+      }
+      if (changed) {
+        if (Object.keys(config.hooks).length === 0) delete config.hooks;
+        writeJson(cursorHooks.hooksJsonPath, config);
+      }
+    }
+  }
+
+  // Codex: remove managed entries from hooks.json
+  const codexHooks = manifest.touchpoints.codex;
+  if (codexHooks?.hooksJsonPath && codexHooks.managedPhases?.length > 0) {
+    const config = readJson(codexHooks.hooksJsonPath);
+    if (config?.hooks) {
+      let changed = false;
+      for (const phase of codexHooks.managedPhases) {
+        const entries = config.hooks[phase];
+        if (!Array.isArray(entries)) continue;
+        const filtered = entries.filter(e => !isManagedCodexEntry(e));
+        if (filtered.length !== entries.length) {
+          changed = true;
+          removed += entries.length - filtered.length;
+          if (filtered.length > 0) {
+            config.hooks[phase] = filtered;
+          } else {
+            delete config.hooks[phase];
+          }
+        }
+      }
+      if (changed) {
+        if (Object.keys(config.hooks).length === 0) delete config.hooks;
+        writeJson(codexHooks.hooksJsonPath, config);
+      }
+    }
+  }
+
+  // Runtime deps: remove aw-usage-* files
+  if (Array.isArray(manifest.runtimeDeps)) {
+    for (const dep of manifest.runtimeDeps) {
+      if (existsSync(dep)) {
+        try {
+          rmSync(dep, { force: true });
+          removed++;
+        } catch { /* best effort */ }
+      }
+    }
+  }
+
+  return removed;
+}
+
+/**
+ * Delete the manifest file.
+ */
+export function removeHookManifest() {
+  if (existsSync(MANIFEST_PATH)) {
+    rmSync(MANIFEST_PATH, { force: true });
+  }
+}
+
+// Export for testing
+export { MANIFEST_PATH, SCHEMA_VERSION };

package/hooks/codex-home.mjs

@@ -2,8 +2,7 @@ import { join } from 'node:path';
 
 import { getSupportedHarnessPhaseEntries } from '../hook-manifest.mjs';
 import {
-  buildDelegatingPhaseScript,
-  buildRegistryDelegatingPhaseScript,
+  buildRegistryDelegatingPhaseScriptWithTelemetry,
   buildReservedPhaseScript,
 } from './shared-phase-scripts.mjs';
 
@@ -19,7 +18,7 @@ const CODEX_HOME_PHASE_BLUEPRINTS = {
     scriptName: 'aw-session-start.sh',
     scriptMarker: '# aw-managed: codex-global-session-start',
     buildScriptContent() {
-      return buildRegistryDelegatingPhaseScript({
+      return buildRegistryDelegatingPhaseScriptWithTelemetry({
         marker: this.scriptMarker,
         phase: 'SessionStart',
         targetCandidates: [
@@ -27,6 +26,8 @@ const CODEX_HOME_PHASE_BLUEPRINTS = {
           '$HOME/.aw/.aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh',
         ],
         warningMessage: 'WARNING: AW using-aw-skills hook not found in ~/.aw_registry. Run aw init or aw pull platform.',
+        telemetryHookPath: '$HOME/.aw-ecc/scripts/hooks/aw-usage-session-start.js',
+        harnessEnv: 'codex',
       });
     },
     buildEntry(command) {

package/hooks/shared-phase-scripts.mjs

@@ -37,6 +37,53 @@ echo "{\\"hookSpecificOutput\\":{\\"hookEventName\\":\\"${phase}\\",\\"additiona
 `;
 }
 
+export function buildRegistryDelegatingPhaseScriptWithTelemetry({
+  marker,
+  phase,
+  targetCandidates,
+  warningMessage,
+  telemetryHookPath,
+  harnessEnv,
+}) {
+  const targetsBlock = targetCandidates
+    .map(target => `  "${target}"`)
+    .join('\n');
+  const escapedWarning = escapeDoubleQuotes(warningMessage);
+
+  return `#!/usr/bin/env bash
+${marker}
+set -euo pipefail
+
+# Capture stdin so we can feed it to both telemetry and the AW router delegate.
+STDIN=$(cat)
+
+# Fire telemetry (non-blocking, all output suppressed).
+TELEMETRY_HOOK="${telemetryHookPath}"
+if [[ -f "$TELEMETRY_HOOK" ]] && command -v node >/dev/null 2>&1; then
+  printf '%s' "$STDIN" | AW_HARNESS=${harnessEnv} node "$TELEMETRY_HOOK" >/dev/null 2>&1 || true
+fi
+
+TARGETS=(
+${targetsBlock}
+)
+
+for target in "\${TARGETS[@]}"; do
+  if [[ -f "\$target" ]]; then
+    printf '%s' "$STDIN" | bash "\$target"
+    exit $?
+  fi
+done
+
+CONTEXT="# AW Session Context
+
+${escapedWarning}"
+
+JSON_CONTEXT=$(printf '%s' "\$CONTEXT" | python3 -c 'import json, sys; print(json.dumps(sys.stdin.read()))')
+
+echo "{\\"hookSpecificOutput\\":{\\"hookEventName\\":\\"${phase}\\",\\"additionalContext\\":\${JSON_CONTEXT}}}"
+`;
+}
+
 export function buildDelegatingPhaseScript({
   marker,
   targetPath,

package/hooks.mjs

@@ -95,6 +95,16 @@ if [ -f ".aw/.git" ] && command -v aw >/dev/null 2>&1; then
   AW_TRIGGER=hook:post-commit aw link >/dev/null 2>&1 &
 fi
 
+# Fire commit_created telemetry if commit has AW co-author trailer
+if git log -1 --format='%b' HEAD 2>/dev/null | grep -qF "Co-Authored-By: AW"; then
+  TELEMETRY_HOOK="$HOME/.aw-ecc/scripts/hooks/aw-usage-commit-created.js"
+  if command -v node >/dev/null 2>&1 && [ -f "$TELEMETRY_HOOK" ]; then
+    COMMIT_HASH="$(git rev-parse --short HEAD 2>/dev/null || echo unknown)"
+    BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)"
+    node "$TELEMETRY_HOOK" "$COMMIT_HASH" "$BRANCH" >/dev/null 2>&1
+  fi
+fi
+
 # Chain to previous hooksPath
 PREV_PATH_FILE="$HOME/.aw/hooks/.previous-hooks-path"
 if [ -f "$PREV_PATH_FILE" ]; then
@@ -258,10 +268,31 @@ fi
 exit 0
 `;
 
+// Standalone post-commit for local .git/hooks/ installation.
+// Fires commit_created telemetry when the commit has AW co-author trailer.
+const LOCAL_POST_COMMIT = `#!/bin/sh
+# aw: local post-commit hook (installed by aw init)
+
+# Skip aw temp dirs
+case "$(pwd)" in /tmp/aw-*|/var/folders/*/aw-*|*/.aw|*/.aw/*) exit 0 ;; esac
+
+# Fire commit_created telemetry if commit has AW co-author trailer
+if git log -1 --format='%b' HEAD 2>/dev/null | grep -qF "Co-Authored-By: AW"; then
+  TELEMETRY_HOOK="$HOME/.aw-ecc/scripts/hooks/aw-usage-commit-created.js"
+  if command -v node >/dev/null 2>&1 && [ -f "$TELEMETRY_HOOK" ]; then
+    COMMIT_HASH="$(git rev-parse --short HEAD 2>/dev/null || echo unknown)"
+    BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)"
+    node "$TELEMETRY_HOOK" "$COMMIT_HASH" "$BRANCH" >/dev/null 2>&1
+  fi
+fi
+
+exit 0
+`;
+
 /**
- * Install prepare-commit-msg hook into a project's local .git/hooks/.
- * This covers repos where another tool (e.g. Claude Code) sets a local
- * core.hooksPath that overrides the global one.
+ * Install prepare-commit-msg and post-commit hooks into a project's local
+ * .git/hooks/. This covers repos where another tool (e.g. Claude Code) sets
+ * a local core.hooksPath that overrides the global one.
  *
  * @param {string} projectDir — root of the project (must contain .git/)
  */
@@ -297,6 +328,15 @@ export function installLocalCommitHook(projectDir) {
 
     writeFileSync(hookPath, LOCAL_PREPARE_COMMIT_MSG);
     chmodSync(hookPath, '755');
+
+    // Also install post-commit for commit_created telemetry
+    const postCommitPath = join(hooksDir, 'post-commit');
+    const shouldWritePostCommit = !existsSync(postCommitPath)
+      || readFileSync(postCommitPath, 'utf8').includes('aw:');
+    if (shouldWritePostCommit) {
+      writeFileSync(postCommitPath, LOCAL_POST_COMMIT);
+      chmodSync(postCommitPath, '755');
+    }
   } catch { /* best effort */ }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.42-beta.3",
+  "version": "0.1.42-beta.31",
   "description": "Agentic Workspace CLI — pull, push & manage agents, skills and commands from the registry",
   "type": "module",
   "bin": {
@@ -26,6 +26,7 @@
     "slack-sim/",
     "file-tree.mjs",
     "apply.mjs",
+    "hook-cleanup.mjs",
     "hook-manifest.mjs",
     "update.mjs",
     "hooks.mjs",

package/render-rules.mjs

@@ -351,6 +351,7 @@ For every non-trivial request, execute these steps in order before any substanti
    - /aw-review → Read aw-review/SKILL.md
    - /aw-deploy → Read aw-deploy/SKILL.md
    - /aw-ship → Read aw-ship/SKILL.md
+   - /aw-feature → Read aw-feature/SKILL.md
 
 4. **Follow the skill's behavior** — produce the artifacts the skill defines, not general-knowledge answers.
 

package/startup.mjs

@@ -16,6 +16,11 @@ const DISABLED_MODE = 'disabled';
 const CLAUDE_DISABLE_DESCRIPTION = 'AW-managed override: disable automatic AW session routing';
 const CLAUDE_TELEMETRY_DESCRIPTION = 'AW usage telemetry';
 const CLAUDE_TELEMETRY_HOOKS = [
+  {
+    phase: 'SessionStart',
+    matcher: undefined,
+    command: 'node "$HOME/.aw-ecc/scripts/hooks/aw-usage-session-start.js"',
+  },
   {
     phase: 'PostToolUse',
     matcher: 'Skill|Agent|Shell|Bash',
@@ -168,7 +173,10 @@ function hasCommandHook(entry, command) {
 }
 
 function isManagedClaudeTelemetryEntry(entry) {
-  return entry?.description === CLAUDE_TELEMETRY_DESCRIPTION;
+  if (entry?.description === CLAUDE_TELEMETRY_DESCRIPTION) return true;
+  // Also match legacy entries (no description) by command pattern
+  const cmds = Array.isArray(entry?.hooks) ? entry.hooks.map(h => h?.command || '') : [];
+  return cmds.some(c => c.includes('aw-usage-'));
 }
 
 function buildClaudeTelemetryEntry(hookDef) {
@@ -196,10 +204,14 @@ function enableClaudeTelemetryHooks(homeDir = homedir()) {
 
   for (const hookDef of CLAUDE_TELEMETRY_HOOKS) {
     const current = Array.isArray(config.hooks[hookDef.phase]) ? config.hooks[hookDef.phase] : [];
-    // Skip if already present
-    if (current.some(isManagedClaudeTelemetryEntry)) continue;
+    const managed = current.filter(isManagedClaudeTelemetryEntry);
+
+    // If exactly one properly described entry exists, nothing to do
+    if (managed.length === 1 && managed[0].description === CLAUDE_TELEMETRY_DESCRIPTION) continue;
 
-    config.hooks[hookDef.phase] = [...current, buildClaudeTelemetryEntry(hookDef)];
+    // Remove all legacy/duplicate telemetry entries, then add the canonical one
+    const cleaned = current.filter(e => !isManagedClaudeTelemetryEntry(e));
+    config.hooks[hookDef.phase] = [...cleaned, buildClaudeTelemetryEntry(hookDef)];
     changed = true;
   }