@ghl-ai/aw 0.1.92 → 0.2.0

package/install-aw-usage-hooks.mjs

@@ -1,105 +1,41 @@
-// install-aw-usage-hooks.mjs — Self-sufficient producer-hook install.
+// install-aw-usage-hooks.mjs — install the aw-usage telemetry hooks on `aw init`.
 //
-// Why this exists:
-//   The aw-usage-*.js producer hooks (which emit telemetry events to the
-//   live cloud DB) used to live in aw-ecc and required a separate install +
-//   manual wiring into ~/.claude/settings.json. Devs running
-//     npm install -g @ghl-ai/aw && aw init
-//   would NOT get telemetry flowing — there was a silent gap in the
-//   installer. This module bundles the producer scripts into @ghl-ai/aw
-//   and writes them + the hook wiring during `aw init` so that
-//   step-1-then-step-2 is genuinely sufficient.
+// This repo is the single source of truth for the aw-usage hook scripts
+// (libs/aw/hooks/aw-usage/). aw-ecc no longer ships or wires them.
 //
 // What it does on `aw init`:
-//   1. Copies bundled aw-usage scripts (libs/aw/hooks/aw-usage/*.js) into
-//      ~/.claude/scripts/hooks/
-//   2. Copies the supporting lib files (aw-usage-telemetry.js, aw-pricing.js)
-//      into ~/.claude/scripts/lib/
-//   3. Non-destructively MERGES five hook phases into ~/.claude/settings.json:
-//        SessionStart, UserPromptSubmit, PostToolUse, PostToolUseFailure, Stop
-//      (Each phase array gets ONE new entry appended, with `description` so
-//       it can be identified + re-applied on future runs.)
-//   4. Ensures ~/.aw/telemetry/config.json exists with machine_id + enabled
-//      (so the hooks can self-resolve their config on first fire).
+//   1. Copies the bundled scripts to ~/.aw/aw-usage/{hooks,lib,package.json}
+//      — one harness-neutral location used by Claude Code, Codex, git
+//      post-commit and the Cursor adapter.
+//   2. Merges the Claude Code entries into ~/.claude/settings.json: one
+//      "AW usage telemetry" entry per phase (SessionStart, UserPromptSubmit,
+//      PostToolUse, PostToolUseFailure, Stop) plus one
+//      "AW-managed: aw-memory stop hooks" entry. Legacy entries pointing at
+//      ~/.aw-ecc, ${CLAUDE_PLUGIN_ROOT} or ~/.claude/scripts are replaced;
+//      unrelated hooks are kept in order.
+//   3. Ensures ~/.aw/telemetry/config.json exists with machine_id + enabled.
 //
-// What it does NOT do:
-//   - Overwrite existing hooks (the graphify SessionStart, plugin hooks, etc.
-//     are preserved verbatim — we only append).
-//   - Set telemetry_url. Default (omitted) → events go to the production API
-//     at services.leadconnectorhq.com. Devs can override locally for
-//     localhost testing.
-//   - Touch ~/.codex/. Codex hook wiring is handled separately (TODO: extend
-//     here when we have the same pattern stabilized for Codex).
+// startup.mjs (aw link / pull / startup / post-upgrade) runs the same copy
+// and merge through aw-usage-wiring.mjs, so both writers always agree.
 //
-// Idempotent: re-running `aw init` is a no-op once everything is in place.
+// It does NOT set telemetry_url (default: production API) and does not touch
+// ~/.codex (see hooks/codex-home.mjs). Idempotent: re-running is a no-op.
 
-import { readFileSync, writeFileSync, mkdirSync, copyFileSync, existsSync, readdirSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { homedir, hostname, userInfo } from 'node:os';
 import { createHash } from 'node:crypto';
+import {
+  copyAwUsageScripts,
+  mergeClaudeAwUsageHooks,
+  missingAwUsageFiles,
+} from './aw-usage-wiring.mjs';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-// Bundled layout (mirrors aw-ecc/scripts/) so the scripts' relative
-// `require('../lib/aw-usage-telemetry')` paths resolve correctly:
-//   libs/aw/hooks/aw-usage/
-//     ├── package.json    ("type": "commonjs" — overrides parent ESM)
-//     ├── hooks/          (7 scripts)
-//     └── lib/            (aw-usage-telemetry.js, aw-pricing.js)
-const BUNDLED_ROOT = join(__dirname, 'hooks', 'aw-usage');
-const BUNDLED_HOOKS_DIR = join(BUNDLED_ROOT, 'hooks');
-const BUNDLED_LIB_DIR = join(BUNDLED_ROOT, 'lib');
 const HOME = homedir();
-
-// IDE targets we install into. Claude Code is the only fully-wired target.
-// Cursor + Codex are deliberately deferred — copying scripts without wiring
-// the matching hooks.json was misleading (events never fired). A follow-up
-// PR will wire ~/.cursor/hooks/hooks.json properly.
-const IDE_TARGETS = [
-  { name: 'Claude Code',  configFile: join(HOME, '.claude', 'settings.json'),  scriptsRoot: join(HOME, '.claude', 'scripts'),  shouldWireConfig: true  },
-];
-
-const HOOK_SCRIPTS = [
-  'aw-usage-prompt-submit.js',
-  'aw-usage-post-tool-use.js',
-  'aw-usage-post-tool-use-failure.js',
-  'aw-usage-session-start.js',
-  'aw-usage-stop.js',
-  'aw-usage-telemetry-send.js',
-  'aw-usage-commit-created.js',
-];
-
-const LIB_FILES = [
-  'aw-usage-telemetry.js',
-  'aw-pricing.js',
-];
-
-// Hook description marker — used to detect prior install + idempotent re-apply.
-const MARKER = 'AW usage telemetry';
+const CLAUDE_SETTINGS = join(HOME, '.claude', 'settings.json');
 
 // ── Helpers ──────────────────────────────────────────────────────────
 
-function safeMkdir(dir) {
-  try { mkdirSync(dir, { recursive: true }); } catch { /* best effort */ }
-}
-
-// Tri-state result so callers can distinguish a real failure from a no-op:
-//   'copied'    — wrote bytes
-//   'unchanged' — destination already matches source byte-for-byte
-//   'failed'    — source missing OR write/read threw (permissions, EBUSY, …)
-function copyIfChanged(src, dest) {
-  if (!existsSync(src)) return 'failed';
-  try {
-    if (existsSync(dest)) {
-      const a = readFileSync(src);
-      const b = readFileSync(dest);
-      if (a.equals(b)) return 'unchanged';
-    }
-    copyFileSync(src, dest);
-    return 'copied';
-  } catch { return 'failed'; }
-}
-
 function generateMachineId() {
   return createHash('sha256')
     .update(`${hostname()}:${userInfo().username}`)
@@ -110,7 +46,7 @@ function generateMachineId() {
 
 function ensureTelemetryConfig() {
   const cfgPath = join(HOME, '.aw', 'telemetry', 'config.json');
-  safeMkdir(dirname(cfgPath));
+  mkdirSync(dirname(cfgPath), { recursive: true });
   let cfg = {};
   if (existsSync(cfgPath)) {
     try { cfg = JSON.parse(readFileSync(cfgPath, 'utf8')); } catch { cfg = {}; }
@@ -130,93 +66,33 @@ function ensureTelemetryConfig() {
 
 // ── settings.json hook merge ─────────────────────────────────────────
 
-function settingsHookEntry(scriptName, description, scriptsRoot, withMatcher) {
-  // Use $HOME so the path is portable across machines. Shell expansion
-  // applies when Claude invokes the command.
-  const portablePath = scriptsRoot
-    .replace(HOME, '$HOME')
-    .split(/[\\/]/).join('/');
-  const cmd = `node "${portablePath}/hooks/${scriptName}"`;
-  const entry = {
-    hooks: [{
-      type: 'command',
-      command: cmd,
-      async: true,
-      timeout: 10,
-    }],
-    description,
-  };
-  if (withMatcher) entry.matcher = '*';
-  return entry;
-}
-
-function alreadyWired(phaseArray, expectedCommand) {
-  if (!Array.isArray(phaseArray)) return false;
-  return phaseArray.some(group =>
-    Array.isArray(group?.hooks) &&
-    group.hooks.some(h => h?.command === expectedCommand)
-  );
-}
-
-function isLegacyAwUsageHookGroup(group, expectedCommand, scriptName) {
-  if (!Array.isArray(group?.hooks)) return false;
-  const commands = group.hooks
-    .map(h => h?.command)
-    .filter(command => typeof command === 'string');
-  const hasExpected = commands.includes(expectedCommand);
-  const hasLegacyAwUsage = commands.some((command) => {
-    const normalized = command.split('\\').join('/');
-    return command.includes(scriptName) &&
-      (normalized.includes('/.aw-ecc/') || command.includes('${CLAUDE_PLUGIN_ROOT}'));
-  });
-  return !hasExpected && hasLegacyAwUsage;
-}
-
-function mergeSettings(configFile, scriptsRoot) {
-  safeMkdir(dirname(configFile));
-  let cfg = {};
-  if (existsSync(configFile)) {
-    try { cfg = JSON.parse(readFileSync(configFile, 'utf8')); } catch { cfg = {}; }
-  }
-  cfg.hooks = cfg.hooks && typeof cfg.hooks === 'object' && !Array.isArray(cfg.hooks)
-    ? cfg.hooks
-    : {};
-
-  const phases = [
-    { name: 'SessionStart',       script: 'aw-usage-session-start.js',         desc: `${MARKER}: session_start`,                              matcher: false },
-    { name: 'UserPromptSubmit',   script: 'aw-usage-prompt-submit.js',         desc: `${MARKER}: prompt_submitted with slash-command detection`, matcher: false },
-    { name: 'PostToolUse',        script: 'aw-usage-post-tool-use.js',         desc: `${MARKER}: skill/agent/error/test/sdlc events`,         matcher: true  },
-    { name: 'PostToolUseFailure', script: 'aw-usage-post-tool-use-failure.js', desc: `${MARKER}: tool_error on failure`,                      matcher: true  },
-    { name: 'Stop',               script: 'aw-usage-stop.js',                  desc: `${MARKER}: response_completed with tokens + cost`,       matcher: true  },
-  ];
-
-  let changed = 0;
-  for (const phase of phases) {
-    // Normalize: existing config may have a non-array value here from a manual
-    // edit or another tool — don't trust truthiness, demand an array.
-    cfg.hooks[phase.name] = Array.isArray(cfg.hooks[phase.name]) ? cfg.hooks[phase.name] : [];
-    const entry = settingsHookEntry(phase.script, phase.desc, scriptsRoot, phase.matcher);
-    const before = cfg.hooks[phase.name].length;
-    cfg.hooks[phase.name] = cfg.hooks[phase.name].filter(group =>
-      !isLegacyAwUsageHookGroup(group, entry.hooks[0].command, phase.script)
-    );
-    changed += before - cfg.hooks[phase.name].length;
-    if (!alreadyWired(cfg.hooks[phase.name], entry.hooks[0].command)) {
-      cfg.hooks[phase.name].push(entry);
-      changed++;
-    }
+// Returns null when the file exists but is not a JSON object, so callers
+// never overwrite (and wipe) a settings.json they cannot understand.
+function readSettings(configFile) {
+  if (!existsSync(configFile)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(configFile, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
   }
+}
 
-  if (changed > 0) {
-    writeFileSync(configFile, JSON.stringify(cfg, null, 2) + '\n');
-  }
-  return { added: changed, configFile };
+/** @returns {'written'|'unchanged'|'unreadable'} */
+function mergeSettings(configFile, installed) {
+  const cfg = readSettings(configFile);
+  if (cfg === null) return 'unreadable';
+  const hooks = mergeClaudeAwUsageHooks(cfg.hooks, { installed });
+  if (JSON.stringify(hooks) === JSON.stringify(cfg.hooks)) return 'unchanged';
+  mkdirSync(dirname(configFile), { recursive: true });
+  writeFileSync(configFile, JSON.stringify({ ...cfg, hooks }, null, 2) + '\n');
+  return 'written';
 }
 
 // ── Main entry ───────────────────────────────────────────────────────
 
 /**
- * Install the aw-usage producer hooks into ~/.claude/.
+ * Install the aw-usage hooks into ~/.aw/aw-usage and ~/.claude/settings.json.
  * Idempotent — safe to re-run.
  *
  * @returns {{
@@ -227,61 +103,34 @@ function mergeSettings(configFile, scriptsRoot) {
  *   libUnchanged: number,
  *   libFailed: number,
  *   targetsConfigured: string[],
+ *   settingsUnreadable: string | null,
  *   telemetryConfigInitialized: boolean,
  * }}
  */
 export function installAwUsageHooks() {
+  const copy = copyAwUsageScripts(HOME);
   const result = {
-    scriptsCopied: 0,
-    scriptsUnchanged: 0,
-    scriptsFailed: 0,
-    libCopied: 0,
-    libUnchanged: 0,
-    libFailed: 0,
+    scriptsCopied: copy.byDir.hooks.copied,
+    scriptsUnchanged: copy.byDir.hooks.unchanged,
+    scriptsFailed: copy.byDir.hooks.failed,
+    libCopied: copy.byDir.lib.copied,
+    libUnchanged: copy.byDir.lib.unchanged,
+    // package.json is part of the lib layer: it makes require() work.
+    libFailed: copy.byDir.lib.failed + copy.byDir.root.failed,
     targetsConfigured: [],
+    settingsUnreadable: null,
     telemetryConfigInitialized: false,
   };
 
-  if (!existsSync(BUNDLED_HOOKS_DIR) || !existsSync(BUNDLED_LIB_DIR)) {
-    // Bundled scripts missing — nothing to install. Caller can decide.
-    return result;
-  }
-
-  // 1. Copy scripts + lib to each IDE target
-  for (const target of IDE_TARGETS) {
-    const hooksDest = join(target.scriptsRoot, 'hooks');
-    const libDest = join(target.scriptsRoot, 'lib');
-    safeMkdir(hooksDest);
-    safeMkdir(libDest);
-
-    for (const name of HOOK_SCRIPTS) {
-      const src = join(BUNDLED_HOOKS_DIR, name);
-      const dest = join(hooksDest, name);
-      const r = copyIfChanged(src, dest);
-      if (r === 'copied') result.scriptsCopied++;
-      else if (r === 'unchanged') result.scriptsUnchanged++;
-      else result.scriptsFailed++;
-    }
-    for (const name of LIB_FILES) {
-      const src = join(BUNDLED_LIB_DIR, name);
-      const dest = join(libDest, name);
-      const r = copyIfChanged(src, dest);
-      if (r === 'copied') result.libCopied++;
-      else if (r === 'unchanged') result.libUnchanged++;
-      else result.libFailed++;
-    }
-
-    // 2. Merge hook wiring into settings.json (Claude only for now)
-    if (target.shouldWireConfig && target.configFile) {
-      const { added, configFile } = mergeSettings(target.configFile, target.scriptsRoot);
-      if (added > 0) result.targetsConfigured.push(`${target.name}:${configFile}`);
-    }
-  }
-
-  // 3. Bootstrap telemetry config
-  const { changed } = ensureTelemetryConfig();
-  result.telemetryConfigInitialized = changed;
+  // If any file failed to copy, mergeSettings keeps the existing entries
+  // instead of pointing Claude at an incomplete ~/.aw/aw-usage. A file can
+  // exist and still fail to copy (unreadable, read-only), so check both.
+  const installed = copy.failed === 0 && missingAwUsageFiles(HOME).length === 0;
+  const merge = mergeSettings(CLAUDE_SETTINGS, installed);
+  if (merge === 'written') result.targetsConfigured.push(`Claude Code:${CLAUDE_SETTINGS}`);
+  if (merge === 'unreadable') result.settingsUnreadable = CLAUDE_SETTINGS;
 
+  result.telemetryConfigInitialized = ensureTelemetryConfig().changed;
   return result;
 }
 
@@ -297,7 +146,8 @@ export function formatAwUsageHooksInstallReport(result) {
   // Surface failures even when everything else is a no-op, so an install that
   // silently lost files doesn't masquerade as "already up to date".
   const failedTotal = (result.scriptsFailed || 0) + (result.libFailed || 0);
-  if (failedTotal > 0) parts.push(`⚠ ${failedTotal} failed (check ~/.claude/scripts/ permissions)`);
+  if (failedTotal > 0) parts.push(`⚠ ${failedTotal} failed (check ~/.aw/aw-usage/ permissions)`);
+  if (result.settingsUnreadable) parts.push(`⚠ ${result.settingsUnreadable} is not valid JSON, left unchanged`);
   if (parts.length === 0) return 'aw-usage hooks already up to date';
   return `aw-usage hooks: ${parts.join(' · ')}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.92",
+  "version": "0.2.0",
   "description": "Agentic Workspace CLI — pull, push & manage agents, skills and commands from the registry",
   "type": "module",
   "bin": {
@@ -36,6 +36,7 @@
     "update.mjs",
     "hooks.mjs",
     "hooks/",
+    "aw-usage-wiring.mjs",
     "install-aw-usage-hooks.mjs",
     "startup.mjs",
     "ecc.mjs",

package/startup.mjs

@@ -9,6 +9,17 @@ import {
   getCodexHomePhaseDefinitions,
   isManagedCodexHomeEntry,
 } from './hooks/codex-home.mjs';
+import {
+  copyAwUsageScripts,
+  ensureAwUsageVersion,
+  mergeClaudeAwUsageHooks,
+  missingAwUsageFiles,
+  removeClaudeAwUsageHooks,
+  warnIncompleteAwUsageInstall,
+  warnStuckAwUsageFiles,
+  warnUnreadableClaudeSettings,
+} from './aw-usage-wiring.mjs';
+import { codexHooksFeatureEnabled, ensureCodexHooksFeature } from './codex.mjs';
 
 const STARTUP_PREFS_FILENAME = 'startup-preferences.json';
 const ENABLED_MODE = 'enabled';
@@ -33,34 +44,6 @@ const CLAUDE_ROUTER_COMMAND =
   'for f in "$HOME/.aw/.aw_registry/aw/skills/using-aw-skills/hooks/session-start.sh" "$HOME/.aw_registry/aw/skills/using-aw-skills/hooks/session-start.sh" "$HOME/.aw/.aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh" "$HOME/.aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh"; do [ -f "$f" ] && exec bash "$f"; done; exit 0';
 const CLAUDE_REMINDER_COMMAND =
   'bash -lc \'exec bash "${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/scripts/hooks/session-start-rules-context.sh"\'';
-const CLAUDE_TELEMETRY_DESCRIPTION = 'AW usage telemetry';
-const CLAUDE_TELEMETRY_HOOKS = [
-  {
-    phase: 'SessionStart',
-    matcher: undefined,
-    command: 'test -f "$HOME/.aw-ecc/scripts/hooks/aw-usage-session-start.js" && node "$HOME/.aw-ecc/scripts/hooks/aw-usage-session-start.js" || true',
-  },
-  {
-    phase: 'PostToolUse',
-    matcher: 'Skill|Agent|Shell|Bash',
-    command: 'test -f "$HOME/.aw-ecc/scripts/hooks/aw-usage-post-tool-use.js" && node "$HOME/.aw-ecc/scripts/hooks/aw-usage-post-tool-use.js" || true',
-  },
-  {
-    phase: 'Stop',
-    matcher: undefined,
-    command: 'STDIN="$(cat)"; test -f "$HOME/.aw-ecc/scripts/hooks/aw-usage-stop.js" && printf \'%s\' "$STDIN" | node "$HOME/.aw-ecc/scripts/hooks/aw-usage-stop.js" || true; test -f "$HOME/.aw-ecc/scripts/hooks/aw-memory-intent-capture.js" && printf \'%s\' "$STDIN" | node "$HOME/.aw-ecc/scripts/hooks/aw-memory-intent-capture.js" || true; test -f "$HOME/.aw-ecc/scripts/hooks/aw-memory-sync.js" && printf \'%s\' "$STDIN" | node "$HOME/.aw-ecc/scripts/hooks/aw-memory-sync.js" || true',
-  },
-  {
-    phase: 'PostToolUseFailure',
-    matcher: undefined,
-    command: 'test -f "$HOME/.aw-ecc/scripts/hooks/aw-usage-post-tool-use-failure.js" && node "$HOME/.aw-ecc/scripts/hooks/aw-usage-post-tool-use-failure.js" || true',
-  },
-  {
-    phase: 'UserPromptSubmit',
-    matcher: undefined,
-    command: 'test -f "$HOME/.aw-ecc/scripts/hooks/aw-usage-prompt-submit.js" && node "$HOME/.aw-ecc/scripts/hooks/aw-usage-prompt-submit.js" || true',
-  },
-];
 const CURSOR_SESSION_START_COMMAND = 'node .cursor/hooks/session-start.js';
 const CURSOR_SESSION_START_DESCRIPTION = 'Load previous context and detect environment';
 const REPO_CURSOR_SESSION_START_COMMAND = 'bash "$(git rev-parse --show-toplevel)/hooks/aw-session-start"';
@@ -257,86 +240,42 @@ function hasCommandHook(entry, command) {
     );
 }
 
-function isManagedClaudeTelemetryEntry(entry) {
-  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) {
-  const entry = {
-    hooks: [
-      {
-        type: 'command',
-        command: hookDef.command,
-      },
-    ],
-    description: CLAUDE_TELEMETRY_DESCRIPTION,
-  };
-  if (hookDef.matcher) {
-    entry.matcher = hookDef.matcher;
-  }
-  return entry;
-}
-
-/**
- * Resolve the filesystem path from a telemetry hook command.
- * Commands look like: node "$HOME/.aw-ecc/scripts/hooks/aw-usage-stop.js"
- */
-function resolveHookScriptPath(command, homeDir) {
-  const match = command.match(/"\$HOME\/([^"]+)"/);
-  if (match) return join(homeDir, match[1]);
-  const matchBare = command.match(/\$HOME\/(\S+)/);
-  if (matchBare) return join(homeDir, matchBare[1]);
+// null = settings.json exists but is not a JSON object. Every Claude writer
+// here returns early on null so an unreadable file is never replaced.
+function readClaudeSettings(settingsPath) {
+  if (!existsSync(settingsPath)) return {};
+  const config = readJson(settingsPath, null);
+  if (isObject(config)) return config;
+  warnUnreadableClaudeSettings(settingsPath);
   return null;
 }
 
+// Claude aw-usage telemetry + AW memory Stop entries. The shape and the merge
+// live in aw-usage-wiring.mjs so this writer and install-aw-usage-hooks.mjs
+// always produce the same settings.json.
 function enableClaudeTelemetryHooks(homeDir = homedir()) {
-  const settingsPath = join(homeDir, '.claude', 'settings.json');
-  const config = readJson(settingsPath, {});
-  ensureHooksObject(config);
-
-  let changed = false;
-
-  for (const hookDef of CLAUDE_TELEMETRY_HOOKS) {
-    const current = Array.isArray(config.hooks[hookDef.phase]) ? config.hooks[hookDef.phase] : [];
-    const managed = current.filter(isManagedClaudeTelemetryEntry);
-
-    // Only register hooks whose script files actually exist on disk.
-    // On version downgrade the aw-ecc clone may not have them — registering
-    // hooks for missing scripts causes MODULE_NOT_FOUND crashes.
-    const scriptPath = resolveHookScriptPath(hookDef.command, homeDir);
-    if (scriptPath && !existsSync(scriptPath)) {
-      // Script missing — remove any stale telemetry entries for this phase
-      if (managed.length > 0) {
-        const cleaned = current.filter(e => !isManagedClaudeTelemetryEntry(e));
-        if (cleaned.length > 0) {
-          config.hooks[hookDef.phase] = cleaned;
-        } else {
-          delete config.hooks[hookDef.phase];
-        }
-        changed = true;
-      }
-      continue;
-    }
+  // Refresh the scripts first: Codex wrappers and git hooks run them too,
+  // and this path runs after every aw link / pull / upgrade.
+  const copy = copyAwUsageScripts(homeDir);
+  const absent = missingAwUsageFiles(homeDir);
+  // On disk but not refreshed (read-only, unreadable): the old content stays.
+  const stuck = copy.missing.filter(rel => !absent.includes(rel));
+  if (absent.length > 0) warnIncompleteAwUsageInstall(absent);
+  // The version warning already names a stuck package.json, with both versions.
+  const versionWarned = absent.length === 0 && !ensureAwUsageVersion(homeDir);
+  const unreported = versionWarned ? stuck.filter(rel => rel !== 'package.json') : stuck;
+  if (unreported.length > 0) warnStuckAwUsageFiles(unreported);
 
-    // If exactly one properly described entry exists, nothing to do
-    if (managed.length === 1 && managed[0].description === CLAUDE_TELEMETRY_DESCRIPTION) continue;
-
-    // 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;
-  }
-
-  if (!changed) return [];
+  const settingsPath = join(homeDir, '.claude', 'settings.json');
+  const config = readClaudeSettings(settingsPath);
+  if (config === null) return [];
 
-  if (isEmptyObject(config.hooks)) {
-    delete config.hooks;
-  }
+  // Old and new scripts do not mix, so a stuck file blocks wiring like an absent one.
+  const installed = absent.length === 0 && stuck.length === 0;
+  const hooks = mergeClaudeAwUsageHooks(config.hooks, { installed });
+  if (JSON.stringify(hooks) === JSON.stringify(config.hooks)) return [];
 
-  writeJson(settingsPath, config);
+  writeJson(settingsPath, { ...config, hooks });
   return [settingsPath];
 }
 
@@ -344,36 +283,17 @@ function disableClaudeTelemetryHooks(homeDir = homedir()) {
   const settingsPath = join(homeDir, '.claude', 'settings.json');
   if (!existsSync(settingsPath)) return [];
 
-  const config = readJson(settingsPath, {});
-  if (!isObject(config.hooks)) return [];
-
-  let changed = false;
-
-  for (const hookDef of CLAUDE_TELEMETRY_HOOKS) {
-    const current = Array.isArray(config.hooks[hookDef.phase]) ? config.hooks[hookDef.phase] : null;
-    if (!current) continue;
+  const config = readClaudeSettings(settingsPath);
+  if (config === null || !isObject(config.hooks)) return [];
 
-    const filtered = current.filter(entry => !isManagedClaudeTelemetryEntry(entry));
-    if (filtered.length !== current.length) {
-      changed = true;
-      if (filtered.length > 0) {
-        config.hooks[hookDef.phase] = filtered;
-      } else {
-        delete config.hooks[hookDef.phase];
-      }
-    }
-  }
-
-  if (!changed) return [];
+  const hooks = removeClaudeAwUsageHooks(config.hooks);
+  if (JSON.stringify(hooks) === JSON.stringify(config.hooks)) return [];
 
-  if (isEmptyObject(config.hooks)) {
-    delete config.hooks;
-  }
-
-  if (!pruneEmptySettingsFile(settingsPath, config)) {
-    writeJson(settingsPath, config);
+  const next = { ...config, hooks };
+  if (isEmptyObject(hooks)) delete next.hooks;
+  if (!pruneEmptySettingsFile(settingsPath, next)) {
+    writeJson(settingsPath, next);
   }
-
   return [settingsPath];
 }
 
@@ -410,7 +330,8 @@ function isManagedCodexStopEntry(entry) {
 
 function disableClaudeStartup(homeDir = homedir()) {
   const settingsPath = join(homeDir, '.claude', 'settings.json');
-  const config = readJson(settingsPath, {});
+  const config = readClaudeSettings(settingsPath);
+  if (config === null) return [];
   ensureHooksObject(config);
 
   const before = JSON.stringify(config.hooks);
@@ -481,7 +402,8 @@ export function purgeManagedClaudeStartupHooks(homeDir = homedir()) {
 
 function enableClaudeStartup(homeDir = homedir()) {
   const settingsPath = join(homeDir, '.claude', 'settings.json');
-  const config = readJson(settingsPath, {});
+  const config = readClaudeSettings(settingsPath);
+  if (config === null) return [];
   ensureHooksObject(config);
 
   const before = JSON.stringify(config.hooks);
@@ -551,40 +473,17 @@ function hasCodexHooksEnabled(homeDir = homedir()) {
   if (!existsSync(configPath)) return false;
 
   try {
-    return /^\s*codex_hooks\s*=\s*true\b/m.test(readFileSync(configPath, 'utf8'));
+    return codexHooksFeatureEnabled(readFileSync(configPath, 'utf8'));
   } catch {
     return false;
   }
 }
 
-function ensureCodexHookEnabled(content) {
-  if (/^\s*codex_hooks\s*=\s*true\b/m.test(content)) {
-    return content;
-  }
-
-  if (/^\s*codex_hooks\s*=\s*false\b/m.test(content)) {
-    return content.replace(/^\s*codex_hooks\s*=\s*false\b.*$/m, 'codex_hooks = true');
-  }
-
-  const featuresHeaderMatch = content.match(/^\[features\]\s*$/m);
-  if (featuresHeaderMatch && featuresHeaderMatch.index !== undefined) {
-    const insertAt = featuresHeaderMatch.index + featuresHeaderMatch[0].length;
-    return `${content.slice(0, insertAt)}\ncodex_hooks = true${content.slice(insertAt)}`;
-  }
-
-  const trimmed = content.trimEnd();
-  if (trimmed.length === 0) {
-    return '[features]\ncodex_hooks = true\n';
-  }
-
-  return `${trimmed}\n\n[features]\ncodex_hooks = true\n`;
-}
-
 function enableCodexStartup(homeDir = homedir()) {
   const updatedFiles = [];
   const configPath = codexConfigPath(homeDir);
   const currentConfig = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
-  const nextConfig = ensureCodexHookEnabled(currentConfig);
+  const nextConfig = ensureCodexHooksFeature(currentConfig);
 
   if (!existsSync(configPath) || nextConfig !== currentConfig) {
     mkdirSync(dirname(configPath), { recursive: true });