@ghl-ai/aw 0.1.38-beta.0 → 0.1.38-beta.3

package/cli.mjs

@@ -4,8 +4,9 @@ import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as fmt from './fmt.mjs';
-import { chalk } from './fmt.mjs';
+import { chalk, CancelError } from './fmt.mjs';
 import { checkForUpdate, notifyUpdate } from './update.mjs';
+import { startSpan } from './telemetry.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf8')).version;
@@ -24,6 +25,7 @@ const COMMANDS = {
   link:    () => import('./commands/link-project.mjs').then(m => m.linkProjectCommand),
   nuke:    () => import('./commands/nuke.mjs').then(m => m.nukeCommand),
   daemon:  () => import('./commands/daemon.mjs').then(m => m.daemonCommand),
+  telemetry: () => import('./commands/telemetry.mjs').then(m => m.telemetryCommand),
 };
 
 function parseArgs(argv) {
@@ -109,6 +111,13 @@ function printHelp() {
     cmd('aw daemon install --interval 30m', 'Set custom interval (e.g. 30m, 2h, 3600)'),
     cmd('aw daemon uninstall', 'Stop the background daemon'),
     cmd('aw daemon status', 'Check if daemon is running'),
+    cmd('aw slack-sim run <scenario>', 'Replay Slack-like scenarios against real runtime'),
+    cmd('aw slack-sim list-scenarios', 'List built-in Slack simulator scenarios'),
+
+    sec('Settings'),
+    cmd('aw telemetry status', 'Show telemetry status'),
+    cmd('aw telemetry disable', 'Opt out of anonymous analytics'),
+    cmd('aw telemetry enable', 'Re-enable analytics'),
 
     sec('Examples'),
     '',
@@ -158,9 +167,21 @@ export async function run(argv) {
   }
 
   if (command && COMMANDS[command]) {
+    const span = await startSpan(command, args);
+    span.notice();
     args._updateCheck = updateCheck;
-    const handler = await COMMANDS[command]();
-    await handler(args);
+    try {
+      const handler = await COMMANDS[command]();
+      await handler(args);
+      await span.end({ status: 'completed' });
+    } catch (err) {
+      if (err instanceof CancelError) {
+        await span.end({ status: 'cancelled', error_type: 'CancelError' });
+        process.exit(err.exitCode ?? 1);
+      }
+      await span.end({ status: 'failed', error_type: err.constructor.name });
+      throw err;
+    }
     notifyUpdate(await updateCheck);
     return;
   }
@@ -170,5 +191,5 @@ export async function run(argv) {
     process.exit(0);
   }
 
-  fmt.cancel(`Unknown command: ${command}`);
+  fmt.cancelAndExit(`Unknown command: ${command}`);
 }

package/codex.mjs

@@ -1,6 +1,6 @@
 // codex.mjs — Project-local Codex defaults for AW/ECC startup.
 
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
 import { getSupportedHarnessPhaseEntries } from './hook-manifest.mjs';
@@ -750,10 +750,6 @@ function ensureManagedScript(filePath, content, marker) {
   if (existsSync(filePath)) {
     const existing = readFileSync(filePath, 'utf8');
     if (existing === content) {
-      if (!isExecutableScript(filePath)) {
-        chmodSync(filePath, 0o755);
-        return true;
-      }
       return false;
     }
     if (!existing.includes(marker)) {
@@ -762,8 +758,7 @@ function ensureManagedScript(filePath, content, marker) {
   }
 
   mkdirSync(dirname(filePath), { recursive: true });
-  writeFileSync(filePath, content, { mode: 0o755 });
-  chmodSync(filePath, 0o755);
+  writeFileSync(filePath, content);
   return true;
 }
 
@@ -786,14 +781,6 @@ function hasTomlSection(content, sectionName) {
   return pattern.test(content);
 }
 
-function isExecutableScript(filePath) {
-  try {
-    return (statSync(filePath).mode & 0o111) !== 0;
-  } catch {
-    return false;
-  }
-}
-
 function tidyToml(content) {
   const normalized = content
     .replace(/\r\n/g, '\n')

package/commands/init.mjs

@@ -26,6 +26,7 @@ import { linkWorkspace } from '../link.mjs';
 import { generateCommands, copyInstructions, initAwDocs, syncHomeHarnessInstructions } from '../integrate.mjs';
 import { setupMcp } from '../mcp.mjs';
 import { applyStoredStartupPreferences, ensureAwRuntimeHook } from '../startup.mjs';
+import { installLocalCommitHook } from '../hooks.mjs';
 import { autoUpdate, promptUpdate } from '../update.mjs';
 import { installGlobalHooks } from '../hooks.mjs';
 import { installAwEcc } from '../ecc.mjs';
@@ -100,7 +101,7 @@ function installIdeTasks() {
       {
         label: 'aw: sync registry',
         type: 'shell',
-        command: 'aw init --silent',
+        command: 'AW_TRIGGER=ide:task aw init --silent',
         presentation: { reveal: 'silent', panel: 'shared', close: true },
         runOptions: { runOn: 'folderOpen' },
         problemMatcher: [],
@@ -221,7 +222,7 @@ export async function initCommand(args) {
     }
 
     if (choice === 'platform-only') {
-      namespace = null; team = null; subTeam = null; folderName = null;
+      namespace = 'platform'; team = 'platform'; subTeam = null; folderName = null;
     }
   }
 
@@ -310,6 +311,7 @@ export async function initCommand(args) {
     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) {
       autoUpdate(await args._updateCheck);
@@ -397,8 +399,8 @@ export async function initCommand(args) {
     }
   }
 
-  // Create sync config
-  const cfg = config.create(GLOBAL_AW_DIR, { namespace: team, user });
+  // Create sync config — default to 'platform' when no namespace specified
+  const cfg = config.create(GLOBAL_AW_DIR, { namespace: team || 'platform', user });
   if (folderName) {
     config.addPattern(GLOBAL_AW_DIR, folderName);
   }
@@ -445,6 +447,7 @@ export async function initCommand(args) {
   const projectRegistryDir = cwd !== HOME ? join(cwd, '.aw', REGISTRY_DIR) : null;
   const awDirForLinks = (projectRegistryDir && existsSync(projectRegistryDir)) ? projectRegistryDir : null;
   const symlinks = linkWorkspace(HOME, awDirForLinks, { silent: true });
+  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`);

package/commands/link-project.mjs

@@ -11,6 +11,7 @@ import { linkWorkspace } from '../link.mjs';
 import { generateCommands } from '../integrate.mjs';
 import { removeWorkspaceHookDefaults } from '../codex.mjs';
 import { applyStoredStartupPreferences } from '../startup.mjs';
+import { installLocalCommitHook } from '../hooks.mjs';
 
 const HOME = homedir();
 const AW_HOME = join(HOME, '.aw');
@@ -43,8 +44,10 @@ export function linkProjectCommand(args) {
     const symlinks = linkWorkspace(HOME, awDirForLinks, { silent: true });
     const commands = generateCommands(HOME, { silent: true });
     applyStoredStartupPreferences(HOME);
+    installLocalCommitHook(cwd);
     const removedLegacyStartupFiles = removeWorkspaceHookDefaults(cwd);
     fmt.logSuccess(`Already linked — refreshed ${chalk.bold(symlinks)} IDE symlinks · ${chalk.bold(commands)} commands${removedLegacyStartupFiles.length > 0 ? ` · removed ${removedLegacyStartupFiles.length} legacy repo startup file${removedLegacyStartupFiles.length > 1 ? 's' : ''}` : ''}`);
+
     return;
   }
 
@@ -55,6 +58,7 @@ export function linkProjectCommand(args) {
     const symlinks = linkWorkspace(HOME, awDirForLinks, { silent: true });
     const commands = generateCommands(HOME, { silent: true });
     applyStoredStartupPreferences(HOME);
+    installLocalCommitHook(cwd);
     const removedLegacyStartupFiles = removeWorkspaceHookDefaults(cwd);
     fmt.logSuccess([
       `Project linked — ${chalk.bold(symlinks)} IDE symlinks · ${chalk.bold(commands)} commands`,

package/commands/nuke.mjs

@@ -148,19 +148,24 @@ async function removeProjectSymlinks() {
   }
 
   // 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 { stdout: hookFiles } = await exec(
-    `find "${HOME}" -maxdepth 5 -path "*/.git/hooks/post-checkout" -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');
-      if (content.includes('aw: auto-link registry') || content.includes('ln -s "$AW_REGISTRY"')) {
-        unlinkSync(hookPath);
-        hooksRemoved++;
-      }
-    } catch { /* best effort */ }
+  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
+        if (content.includes('aw:') || content.includes('aw: auto-link registry') || content.includes('ln -s "$AW_REGISTRY"')) {
+          unlinkSync(hookPath);
+          hooksRemoved++;
+        }
+      } catch { /* best effort */ }
+    }
   }
 
   return { removed, hooksRemoved };
@@ -209,8 +214,8 @@ function removeIdeTasks() {
 
 export async function nukeCommand(args) {
   // Catch unhandled errors and surface them instead of letting clack show generic "Something went wrong"
-  process.on('uncaughtException', (e) => { fmt.cancel(`Unexpected error: ${e.message}`); });
-  process.on('unhandledRejection', (e) => { fmt.cancel(`Unexpected error: ${e?.message ?? e}`); });
+  process.on('uncaughtException', (e) => { fmt.cancelAndExit(`Unexpected error: ${e.message}`); });
+  process.on('unhandledRejection', (e) => { fmt.cancelAndExit(`Unexpected error: ${e?.message ?? e}`); });
 
   fmt.intro('aw nuke');
 

package/commands/pull.mjs

@@ -44,7 +44,7 @@ export async function pullCommand(args) {
   const silent = args['--silent'] === true || args._silent === true;
 
   const log = {
-    cancel: silent ? () => { process.exit(0); } : fmt.cancel,
+    cancel: silent ? (msg) => { throw new fmt.CancelError(msg || 'silent cancel', { exitCode: 0 }); } : fmt.cancel,
     logInfo: silent ? () => {} : fmt.logInfo,
     logSuccess: silent ? () => {} : fmt.logSuccess,
     logStep: silent ? () => {} : fmt.logStep,

package/commands/push-rules.mjs

@@ -5,7 +5,7 @@ import { tmpdir } from 'node:os';
 
 import * as fmt from '../fmt.mjs';
 import { chalk } from '../fmt.mjs';
-import { REGISTRY_BASE_BRANCH, REGISTRY_REPO, RULES_SOURCE_DIR } from '../constants.mjs';
+import { REGISTRY_BASE_BRANCH, REGISTRY_REPO, RULES_SOURCE_DIR, AW_CO_AUTHOR } from '../constants.mjs';
 import { syncFileTree } from '../file-tree.mjs';
 
 function normalizeSlashes(path) {
@@ -147,7 +147,7 @@ function pushRulesTree(sourceRoot, { repo, dryRun, cwd }) {
     const prTitle = buildRulesPrTitle(sourceRoot, cwd);
     const prBody = buildRulesPrBody(sourceRoot, sourceType, cwd);
 
-    execSync('git commit -m "registry: sync platform rules"', { cwd: tempDir, stdio: 'pipe' });
+    execSync(`git commit -m "registry: sync platform rules\n\n${AW_CO_AUTHOR}"`, { cwd: tempDir, stdio: 'pipe' });
     s2.stop('Rules sync prepared');
 
     const s3 = fmt.spinner();

package/commands/push.mjs

@@ -1,7 +1,8 @@
 // commands/push.mjs — Push local agents/skills to registry via PR using persistent git clone
 
 import { existsSync, statSync, readFileSync, appendFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { exec as execCb, execFile as execFileCb } from 'node:child_process';
 import { promisify } from 'node:util';
 import { homedir } from 'node:os';
@@ -10,7 +11,7 @@ const exec = promisify(execCb);
 const execFile = promisify(execFileCb);
 import * as fmt from '../fmt.mjs';
 import { chalk } from '../fmt.mjs';
-import { REGISTRY_REPO, REGISTRY_URL, REGISTRY_BASE_BRANCH, REGISTRY_DIR } from '../constants.mjs';
+import { REGISTRY_REPO, REGISTRY_URL, REGISTRY_BASE_BRANCH, REGISTRY_DIR, AW_CO_AUTHOR } from '../constants.mjs';
 import { resolveInput } from '../paths.mjs';
 import { walkRegistryTree } from '../registry.mjs';
 import {
@@ -25,6 +26,9 @@ import {
 } from '../git.mjs';
 import { hasRulesChanges, isRulesPushInput, pushRulesCommand } from './push-rules.mjs';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VERSION = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8')).version;
+
 const PUSHABLE_TYPES = ['agents', 'skills', 'commands', 'evals', 'references'];
 
 // ── PR content generation ────────────────────────────────────────────
@@ -187,11 +191,14 @@ function generateCommitMsg(files) {
   const deletedParts = Object.entries(groupBy(deleted, 'type')).map(([t, items]) => `${items.length} ${singular(t, items.length)} removed`);
   const countParts = [...addedParts, ...deletedParts];
 
+  const version = VERSION;
+  const trailer = `\n\nGenerated-By: aw/${version}\n${AW_CO_AUTHOR}`;
+
   if (files.length === 1) {
     const f = files[0];
-    return `registry: ${f.deleted ? 'remove' : 'add'} ${f.type}/${f.slug} ${f.deleted ? 'from' : 'to'} ${f.namespace}`;
+    return `registry: ${f.deleted ? 'remove' : 'add'} ${f.type}/${f.slug} ${f.deleted ? 'from' : 'to'} ${f.namespace}${trailer}`;
   }
-  return `registry: sync ${files.length} files (${countParts.join(', ')})`;
+  return `registry: sync ${files.length} files (${countParts.join(', ')})${trailer}`;
 }
 
 // ── Batch file collection from folder ────────────────────────────────

package/commands/slack-sim.mjs

@@ -0,0 +1,128 @@
+import * as fmt from '../fmt.mjs';
+import { loadScenario, listBuiltInScenarios } from '../slack-sim/scenario.mjs';
+import { printDryRun, printScenarioIntro, printState } from '../slack-sim/render.mjs';
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function slackSimCommand(args) {
+  const [subcommand = 'list-scenarios', scenarioRef] = args._positional;
+
+  if (args['--help']) {
+    printHelp();
+    return;
+  }
+
+  if (subcommand === 'list-scenarios') {
+    fmt.intro('aw slack-sim list-scenarios');
+    const scenarios = listBuiltInScenarios();
+    fmt.note(
+      scenarios.map((s) => `${s.name}  ${fmt.chalk.dim(s.path)}`).join('\n'),
+      'Built-in scenarios',
+    );
+    fmt.outro('Done');
+    return;
+  }
+
+  if (!['run', 'replay'].includes(subcommand)) {
+    fmt.cancel(`Unknown slack-sim subcommand: ${subcommand}`);
+    return;
+  }
+
+  const scenario = loadScenario(scenarioRef);
+  const useHttp = Boolean(args['--api-base']) && !args['--in-process'];
+
+  printScenarioIntro(scenario, useHttp ? 'http' : 'in-process');
+  fmt.note(
+    [
+      `source: ${scenario.__file}`,
+      `actions: ${scenario.actions.length}`,
+      `org: ${scenario.session.orgId}`,
+      `team: ${scenario.session.teamId}`,
+    ].join('\n'),
+    'Scenario',
+  );
+
+  if (args['--dry-run']) {
+    printDryRun(scenario);
+    fmt.outro('Dry run complete');
+    return;
+  }
+
+  const transport = useHttp
+    ? await (await import('../slack-sim/http.mjs')).createHttpTransport({
+        apiBase: args['--api-base'],
+        orgId: scenario.session.orgId,
+        teamId: scenario.session.teamId,
+      })
+    : await (await import('../slack-sim/in-process.mjs')).createInProcessTransport();
+
+  try {
+    await transport.start?.();
+    let currentChannel = scenario.defaults.channel;
+    let currentThreadTs = scenario.defaults.threadTs;
+    for (let i = 0; i < scenario.actions.length; i++) {
+      const action = scenario.actions[i];
+      const actionResult = await transport.runAction(action, scenario);
+      currentChannel = actionResult?.channel || action.channel || currentChannel;
+      currentThreadTs = actionResult?.threadTs || action.threadTs || action.thread_ts || (action.type === 'app_mention_top_level' ? actionResult?.ts : currentThreadTs);
+      const state = await transport.getState({
+        channel: currentChannel,
+        threadTs: currentThreadTs,
+      });
+      if (action.type === 'assert') {
+        assertState(state, action);
+        fmt.logSuccess(`Assertion ${i + 1} passed`);
+        continue;
+      }
+      printState(i, action, state);
+      if (args['--wait-for-finish'] && state.status === 'running' && action.type !== 'wait') {
+        await sleep(250);
+      }
+    }
+    fmt.outro('Scenario complete');
+  } finally {
+    await transport.close?.();
+  }
+}
+
+function assertState(state, action) {
+  const failures = [];
+  if (action.status && state.status !== action.status) failures.push(`expected status=${action.status}, got ${state.status}`);
+  if (action.prRole && state.prRole !== action.prRole) failures.push(`expected prRole=${action.prRole}, got ${state.prRole}`);
+  if (action.pollerActive !== undefined && state.pollerActive !== action.pollerActive) {
+    failures.push(`expected pollerActive=${action.pollerActive}, got ${state.pollerActive}`);
+  }
+  if (action.checkpointActive !== undefined && state.checkpointActive !== action.checkpointActive) {
+    failures.push(`expected checkpointActive=${action.checkpointActive}, got ${state.checkpointActive}`);
+  }
+  if (action.prUrlIncludes && !String(state.prUrl || '').includes(action.prUrlIncludes)) {
+    failures.push(`expected prUrl to include "${action.prUrlIncludes}", got ${state.prUrl || '<none>'}`);
+  }
+  if (action.threadContains) {
+    const haystack = (state.messages || []).map((m) => m.text).join('\n');
+    if (!haystack.includes(action.threadContains)) failures.push(`expected thread to contain "${action.threadContains}"`);
+  }
+  if (action.threadNotContains) {
+    const haystack = (state.messages || []).map((m) => m.text).join('\n');
+    if (haystack.includes(action.threadNotContains)) failures.push(`expected thread to not contain "${action.threadNotContains}"`);
+  }
+
+  if (failures.length) {
+    throw new Error(failures.join('; '));
+  }
+}
+
+function printHelp() {
+  fmt.intro('aw slack-sim');
+  fmt.note(
+    [
+      'aw slack-sim list-scenarios',
+      'aw slack-sim run <scenario-file-or-name> [--dry-run] [--in-process] [--api-base <url>]',
+      'aw slack-sim replay <scenario-file-or-name> [--dry-run] [--in-process] [--api-base <url>]',
+    ].join('\n'),
+    'Usage',
+  );
+  fmt.outro('Done');
+}

package/commands/telemetry.mjs

@@ -0,0 +1,31 @@
+// commands/telemetry.mjs — `aw telemetry [enable|disable|status]`
+
+import { enableTelemetry, disableTelemetry, getStatus } from '../telemetry.mjs';
+import * as fmt from '../fmt.mjs';
+import { chalk } from '../fmt.mjs';
+
+export async function telemetryCommand(args) {
+  const sub = args._positional?.[0];
+
+  if (sub === 'disable') {
+    disableTelemetry();
+    fmt.logSuccess('Telemetry disabled. No anonymous usage data will be sent.');
+    return;
+  }
+
+  if (sub === 'enable') {
+    enableTelemetry();
+    fmt.logSuccess('Telemetry enabled. Anonymous usage stats help improve aw.');
+    return;
+  }
+
+  // status (default)
+  const status = getStatus();
+  fmt.intro('aw telemetry');
+  fmt.logStep(`Status:     ${status.enabled ? chalk.green('enabled') : chalk.red('disabled')}`);
+  fmt.logStep(`Machine ID: ${chalk.dim(status.machine_id)}`);
+  fmt.logStep(`Config:     ${chalk.dim(status.config_path)}`);
+  fmt.logMessage('');
+  fmt.logMessage(`  ${chalk.dim('aw telemetry disable')}  — opt out of anonymous analytics`);
+  fmt.logMessage(`  ${chalk.dim('aw telemetry enable')}   — re-enable analytics`);
+}

package/config.mjs

@@ -38,7 +38,7 @@ export function save(workspaceDir, config) {
 export function create(workspaceDir, { namespace, user }) {
   const config = {
     ...DEFAULTS,
-    namespace: namespace || null,
+    namespace: namespace || 'platform',
     user: user || '',
     include: [],
   };

package/constants.mjs

@@ -27,3 +27,10 @@ export const AW_HOME = join(homedir(), '.aw');
 
 /** Directory in platform-docs repo containing platform rules (pulled into .aw_registry/.aw_rules/) */
 export const RULES_SOURCE_DIR = '.aw_rules';
+/** Telemetry endpoint — override with AW_TELEMETRY_URL env var */
+export const TELEMETRY_URL = process.env.AW_TELEMETRY_URL || 'https://services.leadconnectorhq.com/agentic-workspace/api/telemetry/events';
+
+/** AW bot identity for Co-Authored-By trailers */
+export const AW_BOT_NAME = 'AW';
+export const AW_BOT_EMAIL = process.env.AW_BOT_EMAIL || '273421570+ghl-aw@users.noreply.github.com';
+export const AW_CO_AUTHOR = `Co-Authored-By: ${AW_BOT_NAME} <${AW_BOT_EMAIL}>`;

package/ecc.mjs

@@ -10,7 +10,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.20";
+export const AW_ECC_TAG = "v1.4.22";
 
 const MARKETPLACE_NAME = "aw-marketplace";
 const PLUGIN_KEY = `aw@${MARKETPLACE_NAME}`;
@@ -37,6 +37,14 @@ const TARGET_STATE = {
   codex:  { state: ".codex/ecc-install-state.json" },
 };
 
+// User-owned config files that must never be clobbered by aw-ecc install.
+// If these files already exist before `aw init`, we preserve them exactly.
+const PROTECTED_CONFIG_BY_TARGET = {
+  claude: [".claude/settings.json", ".claude.json"],
+  cursor: [".cursor/settings.json", ".cursor/mcp.json"],
+  codex: [".codex/config.toml"],
+};
+
 function run(cmd, opts = {}) {
   return execSync(cmd, { stdio: "pipe", ...opts });
 }
@@ -55,6 +63,59 @@ function cloneWithRef(url, ref, dest) {
   }
 }
 
+function readIfExists(path) {
+  try { return existsSync(path) ? readFileSync(path, "utf8") : null; } catch { return null; }
+}
+
+function snapshotProtectedConfigs(home, target) {
+  const relPaths = PROTECTED_CONFIG_BY_TARGET[target] || [];
+  return relPaths.map((relPath) => {
+    const absPath = join(home, relPath);
+    const content = readIfExists(absPath);
+    return {
+      relPath,
+      absPath,
+      existedBeforeInstall: content !== null,
+      contentBeforeInstall: content,
+    };
+  });
+}
+
+function restoreProtectedConfigs(snapshot) {
+  let restored = 0;
+  for (const entry of snapshot) {
+    if (entry.existedBeforeInstall) {
+      const current = readIfExists(entry.absPath);
+      if (current === entry.contentBeforeInstall) continue;
+      try {
+        mkdirSync(dirname(entry.absPath), { recursive: true });
+        writeFileSync(entry.absPath, entry.contentBeforeInstall ?? "");
+        restored++;
+      } catch { /* best effort */ }
+      continue;
+    }
+
+    // If aw-ecc created a protected settings file from scratch, remove it.
+    // AW should not own these user config files.
+    try {
+      if (existsSync(entry.absPath)) {
+        rmSync(entry.absPath, { force: true });
+        restored++;
+      }
+    } catch { /* best effort */ }
+  }
+  return restored;
+}
+
+function relProtectedPath(absPath, home) {
+  const normalized = String(absPath || "").replace(/\\/g, "/");
+  for (const rel of Object.values(PROTECTED_CONFIG_BY_TARGET).flat()) {
+    const full = join(home, rel).replace(/\\/g, "/");
+    if (normalized === full) return rel;
+  }
+  return null;
+}
+
 function cloneOrUpdate(tag, dest) {
   // AW_ECC_CLONE_URL overrides the remote (used in tests to point at a local fake repo)
   const overrideUrl = process.env.AW_ECC_CLONE_URL;
@@ -175,10 +236,14 @@ export async function installAwEcc(
   if (!silent) fmt.logStep("Installing aw-ecc engine...");
 
   const repoDir = eccDir();
+  const home = homedir();
 
   try {
     cloneOrUpdate(AW_ECC_TAG, repoDir);
 
+    // Ensure telemetry state directory exists (vendor-agnostic, shared across IDEs)
+    mkdirSync(join(home, ".aw", "telemetry"), { recursive: true });
+
     // Claude Code: plugin install via marketplace CLI (proper agent dispatch)
     if (targets.includes("claude")) {
       try {
@@ -196,6 +261,8 @@ export async function installAwEcc(
       });
       for (const target of fileCopyTargets) {
         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
@@ -219,6 +286,10 @@ export async function installAwEcc(
           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 */ }
       }
     }
@@ -249,10 +320,18 @@ export function uninstallAwEcc({ silent = false } = {}) {
     try {
       const data = JSON.parse(readFileSync(statePath, "utf8"));
       for (const op of data.operations || []) {
-        if (op.destinationPath && existsSync(op.destinationPath)) {
-          rmSync(op.destinationPath, { recursive: true, force: true });
+        if (!op.destinationPath) continue;
+        const absPath = op.destinationPath.startsWith("/") ? op.destinationPath : join(HOME, op.destinationPath);
+        const relProtected = relProtectedPath(absPath, HOME);
+        if (relProtected) {
+          // Never delete user settings files as part of aw-ecc uninstall.
+          // AW-specific MCP removal is handled separately in removeMcpConfig().
+          continue;
+        }
+        if (existsSync(absPath)) {
+          rmSync(absPath, { recursive: true, force: true });
           removed++;
-          pruneEmptyParents(op.destinationPath, join(HOME, cfg.state.split("/")[0]));
+          pruneEmptyParents(absPath, join(HOME, cfg.state.split("/")[0]));
         }
       }
       rmSync(statePath, { force: true });

package/fmt.mjs

@@ -72,7 +72,21 @@ export const isCancel = p.isCancel;
 
 export const spinner = () => p.spinner();
 
+export class CancelError extends Error {
+  constructor(message, { exitCode = 1 } = {}) {
+    super(message);
+    this.name = 'CancelError';
+    this.exitCode = exitCode;
+  }
+}
+
 export function cancel(msg) {
+  p.cancel(msg);
+  throw new CancelError(msg);
+}
+
+/** Hard exit — for use in process exception handlers where throwing is unsafe */
+export function cancelAndExit(msg) {
   p.cancel(msg);
   process.exit(1);
 }