@ghl-ai/aw 0.1.73 → 0.1.77

package/codex.mjs

@@ -88,14 +88,27 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 ROOT_DIR="$(cd "\${SCRIPT_DIR}/.." && pwd)"
-TARGET_SCRIPT="\$ROOT_DIR/.aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh"
 
-if [[ ! -f "\$TARGET_SCRIPT" ]]; then
-  echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "WARNING: AW session-start hook not found at .aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh. Run aw pull platform or aw init."}}'
-  exit 0
-fi
-
-exec bash "\$TARGET_SCRIPT"
+# Resolve the using-aw-skills router. Prefer the aw/ namespace (canonical since the
+# platform/core -> aw skills rename); fall back to the platform/core mirror and the
+# global ~/.aw registry so a workspace with a partial local registry still routes.
+# Pointing only at platform/core injected an EMPTY router after the rename (the cause
+# of the SDLC skill-invocation regression).
+TARGET_CANDIDATES=(
+  "\$ROOT_DIR/.aw_registry/aw/skills/using-aw-skills/hooks/session-start.sh"
+  "\$HOME/.aw/.aw_registry/aw/skills/using-aw-skills/hooks/session-start.sh"
+  "\$ROOT_DIR/.aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh"
+  "\$HOME/.aw/.aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh"
+)
+
+for TARGET_SCRIPT in "\${TARGET_CANDIDATES[@]}"; do
+  if [[ -f "\$TARGET_SCRIPT" ]]; then
+    exec bash "\$TARGET_SCRIPT"
+  fi
+done
+
+echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "WARNING: AW using-aw-skills router not found in .aw_registry (aw/ or platform/core). Run aw pull aw or aw init."}}'
+exit 0
 `;
 
 export function ensureCodexWorkspaceDefaults(cwd) {

package/commands/doctor.mjs

@@ -141,6 +141,9 @@ function parseLegacyClaudeHookTargets(sessionStartEntries = []) {
   const targets = [];
   for (const entry of sessionStartEntries) {
     if (!Array.isArray(entry?.hooks)) continue;
+    // Only the deprecated platform/core path is "legacy"; the canonical aw/ path (used by
+    // the managed router's for-loop command) must NOT be treated as a stale hook.
+    if (entry?.description === 'AW-managed: using-aw-skills session router') continue;
     for (const hook of entry.hooks) {
       const command = String(hook?.command || '');
       if (!command.includes('.aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh')) continue;
@@ -582,21 +585,80 @@ function missingCoreClaudeCommandFiles(pluginRoot) {
     .filter(relativePath => !existsSync(join(pluginRoot, relativePath)));
 }
 
+const RUNTIME_HOOK_FIX = 'Run `aw init` or `aw pull platform` to restore the AW runtime hook.';
+
+// Anti-false-green gate. A session-start hook can be WIRED yet resolve to a HOLLOW
+// script that emits no routing card — the platform/core -> aw rename left exactly such
+// a stub. Existence alone is not enough: execute the resolved router and require its
+// output to actually name the router, so `aw doctor` reports a problem instead of PASS.
+function probeRouterCard(resolvedPath) {
+  if (process.platform === 'win32') return { status: 'warn', reason: 'exec-unavailable' };
+  let res;
+  try {
+    res = spawnSync('bash', [resolvedPath], {
+      input: '',
+      encoding: 'utf8',
+      timeout: 5000,
+      env: { ...process.env, CLAUDE_PLUGIN_ROOT: '1' },
+    });
+  } catch (error) {
+    return { status: 'fail', reason: 'exec-error', detail: error instanceof Error ? error.message : String(error) };
+  }
+  if (res.error || res.status !== 0) {
+    const detail = (res.error?.message || `exit ${res.status}`)
+      + (res.stderr ? ` :: ${String(res.stderr).trim().slice(-200)}` : '');
+    return { status: 'fail', reason: 'exec-error', detail };
+  }
+  // Substring detection on raw stdout — robust to JSON-escaping quirks (the real script
+  // escapes via python3 with an awk fallback); the hollow stub prints "ok" with no card.
+  const out = String(res.stdout || '');
+  if (!out.includes('using-aw-skills')) return { status: 'fail', reason: 'hollow' };
+  if (!out.includes('/aw:plan')) return { status: 'warn', reason: 'partial' };
+  return { status: 'pass', reason: 'card' };
+}
+
+function buildRuntimeHookCheck(resolvedPath, homeDir) {
+  if (!resolvedPath) {
+    return makeCheck('runtime-hook', 'AW runtime hook', 'fail',
+      'using-aw-skills hook is missing from ~/.aw_registry', RUNTIME_HOOK_FIX);
+  }
+  const shortPath = resolvedPath.replace(`${homeDir}/`, '~/');
+  const probe = probeRouterCard(resolvedPath);
+  if (probe.status === 'pass') {
+    return makeCheck('runtime-hook', 'AW runtime hook', 'pass',
+      `using-aw-skills router at ${shortPath} emits the routing card`);
+  }
+  if (probe.reason === 'exec-unavailable') {
+    return makeCheck('runtime-hook', 'AW runtime hook', 'warn',
+      `Found using-aw-skills hook at ${shortPath}; card content not verified on this platform`);
+  }
+  if (probe.status === 'warn') {
+    return makeCheck('runtime-hook', 'AW runtime hook', 'warn',
+      `using-aw-skills router at ${shortPath} emits a partial card (missing /aw:plan surface)`, RUNTIME_HOOK_FIX);
+  }
+  const why = probe.reason === 'hollow'
+    ? `using-aw-skills router at ${shortPath} resolves to a hollow script that emits no routing card`
+    : `using-aw-skills router at ${shortPath} resolved but failed to emit a card (${probe.detail || probe.reason})`;
+  return makeCheck('runtime-hook', 'AW runtime hook', 'fail', why, RUNTIME_HOOK_FIX);
+}
+
 function buildDoctorChecks(homeDir, cwd) {
   const startup = getStartupStatus(homeDir);
   const checks = [];
   const awRegistryDir = resolveAwRegistryDir(homeDir);
   const rulesDir = resolveRulesDir(homeDir);
 
+  // Resolve the on-disk using-aw-skills router, preferring the aw/ namespace (canonical
+  // since the platform/core -> aw rename) over the legacy platform/core mirror, then probe
+  // that it actually emits a routing card (not a hollow stub).
   const usingAwHookPath = [
+    join(homeDir, '.aw_registry', 'aw', 'skills', 'using-aw-skills', 'hooks', 'session-start.sh'),
+    join(homeDir, '.aw', '.aw_registry', 'aw', 'skills', 'using-aw-skills', 'hooks', 'session-start.sh'),
     join(homeDir, '.aw_registry', 'platform', 'core', 'skills', 'using-aw-skills', 'hooks', 'session-start.sh'),
     join(homeDir, '.aw', '.aw_registry', 'platform', 'core', 'skills', 'using-aw-skills', 'hooks', 'session-start.sh'),
   ].find(existsSync);
 
-  checks.push(usingAwHookPath
-    ? makeCheck('runtime-hook', 'AW runtime hook', 'pass', `Found using-aw-skills hook at ${usingAwHookPath.replace(`${homeDir}/`, '~/')}`)
-    : makeCheck('runtime-hook', 'AW runtime hook', 'fail', 'using-aw-skills hook is missing from ~/.aw_registry', 'Run `aw init` or `aw pull platform` to restore the AW runtime hook.'),
-  );
+  checks.push(buildRuntimeHookCheck(usingAwHookPath, homeDir));
 
   checks.push(startup.mode === 'enabled'
     ? makeCheck('routing-mode', 'Routing mode', 'pass', `Global routing mode is ${startup.mode}`)

package/commands/init.mjs

@@ -78,6 +78,19 @@ function writeHookManifestBestEffort(manifest, context) {
   }
 }
 
+function installAwUsageHooksBestEffort({ silent = false } = {}) {
+  ensureTelemetryConfig();
+
+  try {
+    if (!isDefaultRoutingEnabled(HOME, process.env)) return null;
+    const result = installAwUsageHooks();
+    return formatAwUsageHooksInstallReport(result);
+  } catch (e) {
+    if (!silent) fmt.note(`aw-usage hooks install: ${e.message}`, 'Telemetry');
+    return null;
+  }
+}
+
 function formatIntegrationStatusSummary(statuses, installedNow = []) {
   if (!statuses || statuses.length === 0) return null;
 
@@ -512,6 +525,8 @@ export async function initCommand(args) {
     if (cwd !== HOME) installLocalCommitHook(cwd);
     if (!silent) fmt.logStep(`IDE wired — ${chalk.bold(symlinks)} symlinks · ${chalk.bold(commands)} commands`);
 
+    const awUsageHooksReport = installAwUsageHooksBestEffort({ silent });
+
     // Write hook manifest after all hook installation is complete
     writeHookManifestBestEffort({ eccVersion: AW_ECC_TAG, awVersion: VERSION });
 
@@ -539,6 +554,7 @@ export async function initCommand(args) {
         '',
         `  ${chalk.green('✓')} Registry synced`,
         `  ${chalk.green('✓')} IDE refreshed — ${chalk.bold(symlinks)} symlinks · ${chalk.bold(commands)} commands`,
+        awUsageHooksReport ? `  ${chalk.green('✓')} ${awUsageHooksReport}` : null,
         removedLegacyStartupFiles.length > 0
           ? `  ${chalk.green('✓')} Removed ${removedLegacyStartupFiles.length} legacy repo startup file${removedLegacyStartupFiles.length > 1 ? 's' : ''}`
           : null,
@@ -686,25 +702,12 @@ export async function initCommand(args) {
   ];
   if (!silent) fmt.logStep(`IDE wired — ${chalk.bold(symlinks)} symlinks · ${chalk.bold(commands)} commands`);
 
-  // Ensure telemetry config exists (generates machine_id on first run)
-  ensureTelemetryConfig();
-
   // Install bundled aw-usage producer hooks into ~/.claude.
   // Copies the scripts + lib files and non-destructively merges 5 hook phases
   // (SessionStart, UserPromptSubmit, PostToolUse, PostToolUseFailure, Stop)
   // into ~/.claude/settings.json. Idempotent. After this, every Claude Code
   // session emits usage_events to the live telemetry API automatically.
-  let awUsageHooksReport = null;
-  try {
-    if (isDefaultRoutingEnabled(HOME, process.env)) {
-      const result = installAwUsageHooks();
-      awUsageHooksReport = formatAwUsageHooksInstallReport(result);
-    }
-  } catch (e) {
-    // Non-fatal — telemetry is observational. Surface the error in silent mode
-    // logs but don't block the install.
-    if (!silent) fmt.note(`aw-usage hooks install: ${e.message}`, 'Telemetry');
-  }
+  const awUsageHooksReport = installAwUsageHooksBestEffort({ silent });
 
   // Write hook manifest after all hook installation is complete, including
   // bundled usage hooks, so `aw nuke` can prune AW-managed settings entries.

package/commands/nuke.mjs

@@ -14,6 +14,7 @@ import { chalk } from '../fmt.mjs';
 import { removeGlobalHooks } from '../hooks.mjs';
 import { uninstallAwEcc } from '../ecc.mjs';
 import { removeMcpConfig } from '../mcp.mjs';
+import { purgeManagedClaudeStartupHooks, disableCursorAwRouting } from '../startup.mjs';
 import { removeContextModeIntegration } from '../integrations/context-mode.mjs';
 import { listProjectWorktrees } from '../git.mjs';
 import { removeWorkspaceHookDefaults } from '../codex.mjs';
@@ -245,6 +246,11 @@ export async function nukeCommand(args) {
   const createdCount = removeCreatedFiles(manifest);
   const ideCount = removeIdeSymlinks();
   uninstallAwEcc();
+  // Strip AW-managed startup hooks that enable installs into the user's settings
+  // (Claude SessionStart router + UserPromptSubmit reminder, Cursor AW session hook).
+  // uninstallAwEcc deliberately preserves user settings files, so these are removed here.
+  purgeManagedClaudeStartupHooks(HOME);
+  disableCursorAwRouting(HOME);
   removeMcpConfig();
   removeContextModeIntegration(HOME);
   // Prune stale hook entries using manifest (catches entries not tracked by install-state)

package/commands/push.mjs

@@ -201,6 +201,18 @@ function awDocsFeatureScope(featureSlug) {
   if (!slug || slug === 'true') {
     throw new Error('Missing feature slug. Use: aw push --aw-docs-only --feature <feature-slug>');
   }
+  if (slug.includes('/')) {
+    const stripped = normalizeRelPath(slug).replace(/^\.aw_docs\//, '');
+    if (AW_DOCS_ROOT_NAMESPACES.includes(stripped.split('/')[0])) {
+      // Root-namespace trees (e.g. pr-reviews/<repo>/pr-<n>/<run>) are valid —
+      // they are just passed positionally, not via --feature.
+      throw new Error(
+        `--feature takes a flat slug, but "${slug}" is a nested ${stripped.split('/')[0]} path. ` +
+        `Pass it positionally instead: aw push --aw-docs-only .aw_docs/${stripped}`
+      );
+    }
+    throw new Error(`Invalid feature slug "${slug}". Feature slugs may not contain "/". For nested doc trees use a root namespace path: aw push --aw-docs-only .aw_docs/pr-reviews/<repo>/pr-<n>/<run>`);
+  }
   if (!/^[A-Za-z0-9._-]+$/.test(slug)) {
     throw new Error(`Invalid feature slug "${slug}". Feature slugs may contain letters, numbers, dot, underscore, and dash only.`);
   }
@@ -1138,6 +1150,11 @@ function resolveColocatedEvals(registrySubDir, namespace, parentType, slug, chan
 // ── CODEOWNERS helpers ────────────────────────────────────────────────
 
 async function getGitHubUser() {
+  // GitHub App installation tokens cannot call `gh api user` (403), which made
+  // headless publishes namespace docs under "unknown". Allow CI to set the
+  // publish identity explicitly.
+  const override = (process.env.AW_DOCS_PUBLISH_USER || '').trim();
+  if (override) return override;
   try {
     const { stdout } = await exec('gh api user --jq .login');
     return stdout.trim();
@@ -1669,4 +1686,5 @@ export const __test__ = {
   awDocsRootScope,
   resolveAwDocsScope,
   assertDocsOnlyScopeOrAll,
+  getGitHubUser,
 };

package/commands/startup.mjs

@@ -73,13 +73,15 @@ function renderStatus() {
       : 'disabled';
   const claudeStatus = status.claudeDisabled
     ? 'disabled via ~/.claude/settings.json override'
-    : status.claudeLegacySessionStartPresent
-      ? 'enabled (legacy hook present; run aw routing enable to clean)'
-      : status.claudePluginEnabled && status.claudePluginInstalled
-        ? 'enabled (plugin installed)'
-        : status.claudePluginEnabled && !status.claudePluginInstalled
-          ? 'misconfigured (plugin enabled in settings but not installed)'
-          : 'disabled (plugin not installed)';
+    : status.claudeRouterPresent
+      ? 'enabled (managed router)'
+      : status.claudeLegacySessionStartPresent
+        ? 'enabled (legacy hook present; run aw routing enable to clean)'
+        : status.claudePluginEnabled && status.claudePluginInstalled
+          ? 'enabled (plugin installed)'
+          : status.claudePluginEnabled && !status.claudePluginInstalled
+            ? 'misconfigured (plugin enabled in settings but not installed)'
+            : 'disabled (plugin not installed)';
   const cursorStatus = status.cursorSessionStartPresent
     ? 'enabled'
     : status.cursorAnySessionStartPresent

package/ecc.mjs

@@ -12,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.66";
+export const AW_ECC_TAG = "v1.4.67";
 const REQUIRED_ECC_FILES = [
   "package.json",
   "scripts/install-apply.js",

package/hooks/aw-usage/hooks/aw-usage-commit-created.js

@@ -11,14 +11,23 @@
 
 'use strict';
 
-const { buildEvent, sendAsync, isDisabled } = require('../lib/aw-usage-telemetry');
+const {
+  buildEvent,
+  sendAsync,
+  isDisabled,
+  findRecentSdlcSessionForProject,
+} = require('../lib/aw-usage-telemetry');
 
 function buildCommitCreatedEvent({ commitHash = 'unknown', branch = 'unknown', cwd = process.cwd() } = {}) {
-  // Git hooks have no harness session context, but cwd lets buildEvent derive
-  // project_hash so the dashboard can correlate commits back to /aw:* sessions.
-  const event = buildEvent({ cwd }, 'commit_created', {
+  const linkedSession = findRecentSdlcSessionForProject(cwd);
+  const event = buildEvent({
+    cwd,
+    ...(linkedSession?.session_id ? { session_id: linkedSession.session_id } : {}),
+  }, 'commit_created', {
     commit_hash: commitHash,
+    commit_sha: commitHash,
     branch,
+    ...(linkedSession?.session_id ? { linked_session_source: 'project_recent_sdlc_session' } : {}),
   });
 
   // Override harness to 'git' since this fires from a git hook, not a harness.

package/hooks/aw-usage/hooks/aw-usage-post-tool-use.js

@@ -112,6 +112,44 @@ function getCommand(input) {
   );
 }
 
+function commandSegments(command) {
+  return String(command || '')
+    .split(/\n|&&|\|\||;/)
+    .map(segment => segment.trim())
+    .filter(Boolean)
+    .map(segment => segment.replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S+)\s+)*/, ''))
+    .filter(segment => !segment.startsWith('#'));
+}
+
+function detectDeployCommand(command) {
+  const patterns = [
+    { regex: /^(?:npx\s+)?aw\s+deploy\b/i, tool: 'aw', provider: 'aw' },
+    { regex: /^(?:npm|yarn|pnpm|bun)\s+(?:run\s+)?deploy(?::[a-z0-9_-]+)?\b/i, tool: 'package-script', provider: 'package-script' },
+    { regex: /^gcloud\s+run\s+deploy\b/i, tool: 'gcloud', provider: 'cloud-run' },
+    { regex: /^firebase\s+deploy\b/i, tool: 'firebase', provider: 'firebase' },
+    { regex: /^vercel\s+(?:deploy\b|--prod\b)/i, tool: 'vercel', provider: 'vercel' },
+    { regex: /^wrangler\s+(?:deploy|pages\s+deploy)\b/i, tool: 'wrangler', provider: 'cloudflare' },
+    { regex: /^helm\s+upgrade\b/i, tool: 'helm', provider: 'kubernetes' },
+    { regex: /^kubectl\s+(?:rollout\s+restart|set\s+image)\b/i, tool: 'kubectl', provider: 'kubernetes' },
+    { regex: /^gh\s+workflow\s+run\b.*\b(?:deploy|release|staging|production|prod)\b/i, tool: 'gh', provider: 'github-actions' },
+    { regex: /^aws\s+(?:ecs\s+update-service|lambda\s+update-function-code)\b/i, tool: 'aws', provider: 'aws' },
+    { regex: /^(?:sam|serverless|sls)\s+deploy\b/i, tool: 'serverless', provider: 'serverless' },
+  ];
+
+  for (const segment of commandSegments(command)) {
+    for (const pattern of patterns) {
+      if (pattern.regex.test(segment)) {
+        return {
+          deploy_tool: pattern.tool,
+          deploy_provider: pattern.provider,
+        };
+      }
+    }
+  }
+
+  return null;
+}
+
 function normalizeToolResult(input) {
   const rawToolResponse = parseMaybeJsonObject(input?.tool_response);
   const rawToolOutput = parseMaybeJsonObject(input?.tool_output);
@@ -232,6 +270,32 @@ function collectPostToolUseEvents(input, options = {}) {
 
   if (toolName === 'Shell' || toolName === 'Bash') {
     const cmd = getCommand(input);
+    const deploy = detectDeployCommand(cmd);
+    if (deploy) {
+      const deployPayload = {
+        ...deploy,
+        tool_name: toolName,
+        sdlc_correlated_command: slashCmd ? slashCmd.command_name : null,
+        sdlc_correlated_namespace: slashCmd ? slashCmd.command_namespace : null,
+        sdlc_correlated_is_sdlc_stage: slashCmd ? Boolean(slashCmd.is_sdlc_stage) : false,
+      };
+      const failed = isExplicitFailureExitCode(toolResult.exitCode)
+        || inferShellFailureFromMessage(toolName, toolResult.rawErrorMessage);
+
+      events.push({
+        eventType: 'deploy_triggered',
+        payload: deployPayload,
+      });
+      events.push({
+        eventType: failed ? 'deploy_failed' : 'deploy_success',
+        payload: {
+          ...deployPayload,
+          status: failed ? 'failed' : 'success',
+          ...(isExplicitFailureExitCode(toolResult.exitCode) ? { exit_code: toolResult.exitCode } : {}),
+        },
+      });
+    }
+
     // Codex skill detection: Bash commands that read SKILL.md files.
     if (!promptSkillOverride) {
       const skillCmdMatch = cmd.match(/\/skills\/([^/]+)\/SKILL\.md/i);
@@ -362,6 +426,7 @@ if (require.main === module) {
 
 module.exports = {
   collectPostToolUseEvents,
+  detectDeployCommand,
   detectSdlcArtifact,
   detectTestFramework,
   inferShellFailureFromMessage,

package/hooks/aw-usage/hooks/aw-usage-prompt-submit.js

@@ -109,7 +109,9 @@ function processPromptSubmitInput(input, deps = {}) {
 
   if (slash) {
     persistSkill(getSessionId(input), input?.turn_id || null, slash);
-    persistSlashCmd(getSessionId(input), slash);
+    persistSlashCmd(getSessionId(input), slash, {
+      cwd: input?.cwd || (input?.workspace_roots && input.workspace_roots[0]) || null,
+    });
     events.push({
       eventType: 'skill_invoked',
       payload: {

package/hooks/aw-usage/lib/aw-usage-telemetry.js

@@ -21,6 +21,7 @@ const SENDER_SCRIPT = path.join(__dirname, '..', 'hooks', 'aw-usage-telemetry-se
 const AW_HOME = path.join(os.homedir(), '.aw');
 const CONFIG_PATH = path.join(AW_HOME, 'telemetry', 'config.json');
 const SESSION_DIR = path.join(AW_HOME, 'telemetry', 'sessions');
+const SESSION_PROJECT_DIR = path.join(SESSION_DIR, 'by-project');
 const DEDUPE_DIR = path.join(os.tmpdir(), 'aw-usage-telemetry-dedupe');
 
 // ── Git config cache (once per process) ──────────────────────────────
@@ -157,6 +158,16 @@ function computeProjectHash(cwd) {
   return crypto.createHash('sha256').update(cwd).digest('hex').slice(0, 16);
 }
 
+function normalizeProjectHash(value) {
+  return typeof value === 'string' && /^[a-f0-9]{16}$/i.test(value) ? value.toLowerCase() : null;
+}
+
+function resolveProjectHash(context) {
+  if (!context || typeof context !== 'object') return null;
+  return normalizeProjectHash(context.project_hash || context.projectHash)
+    || computeProjectHash(context.cwd);
+}
+
 // ── Session file cleanup ─────────────────────────────────────────────
 // Prune session files older than SESSION_MAX_AGE_MS to prevent unbounded growth.
 // Called once per session start — best-effort, never blocks.
@@ -241,21 +252,40 @@ function readSessionSkill(sessionId, turnId) {
 // to the originating /aw:* invocation. Separate from `last_skill` because
 // the source is the prompt, not the tool, and the lifetime is the whole
 // session (not just one turn).
-function persistSessionSlashCommand(sessionId, slashCommand) {
+function writeProjectSessionIndex(projectHash, sessionId, slashCommand) {
+  if (!projectHash || !sessionId || !slashCommand?.is_sdlc_stage) return;
+  try {
+    fs.mkdirSync(SESSION_PROJECT_DIR, { recursive: true });
+    fs.writeFileSync(path.join(SESSION_PROJECT_DIR, `${projectHash}.json`), JSON.stringify({
+      project_hash: projectHash,
+      session_id: sessionId,
+      command_namespace: slashCommand.command_namespace || null,
+      command_name: slashCommand.command_name,
+      is_sdlc_stage: Boolean(slashCommand.is_sdlc_stage),
+      updated_at: new Date().toISOString(),
+    }));
+  } catch { /* ignore */ }
+}
+
+function persistSessionSlashCommand(sessionId, slashCommand, context = {}) {
   if (!sessionId || !slashCommand?.command_name) return;
   try {
     fs.mkdirSync(SESSION_DIR, { recursive: true });
     const state = readSessionState(sessionId);
+    const projectHash = resolveProjectHash(context) || state.project_hash || null;
     fs.writeFileSync(path.join(SESSION_DIR, sessionId + '.json'), JSON.stringify({
       ...state,
+      ...(projectHash ? { project_hash: projectHash } : {}),
       last_slash_command: {
         command_namespace: slashCommand.command_namespace || null,
         command_name: slashCommand.command_name,
         command_args: slashCommand.command_args || '',
         is_sdlc_stage: Boolean(slashCommand.is_sdlc_stage),
+        ...(projectHash ? { project_hash: projectHash } : {}),
         updated_at: new Date().toISOString(),
       },
     }));
+    writeProjectSessionIndex(projectHash, sessionId, slashCommand);
   } catch { /* ignore */ }
 }
 
@@ -265,6 +295,59 @@ function readSessionLastSlashCommand(sessionId) {
   return cmd;
 }
 
+function parseUpdatedAt(value) {
+  const millis = Date.parse(value || '');
+  return Number.isFinite(millis) ? millis : 0;
+}
+
+function isRecentSdlcSessionCandidate(candidate, projectHash, maxAgeMs) {
+  if (!candidate?.session_id) return false;
+  if (!candidate?.is_sdlc_stage) return false;
+  if (candidate.project_hash !== projectHash) return false;
+  const updatedAt = parseUpdatedAt(candidate.updated_at);
+  if (!updatedAt) return false;
+  return Date.now() - updatedAt <= maxAgeMs;
+}
+
+function readProjectSessionIndex(projectHash, maxAgeMs) {
+  try {
+    const candidate = JSON.parse(fs.readFileSync(path.join(SESSION_PROJECT_DIR, `${projectHash}.json`), 'utf8'));
+    return isRecentSdlcSessionCandidate(candidate, projectHash, maxAgeMs) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
+function findRecentSdlcSessionForProject(cwd, maxAgeMs = SESSION_MAX_AGE_MS) {
+  const projectHash = computeProjectHash(cwd);
+  if (!projectHash) return null;
+
+  const indexed = readProjectSessionIndex(projectHash, maxAgeMs);
+  if (indexed) return indexed;
+
+  let best = null;
+  try {
+    const entries = fs.readdirSync(SESSION_DIR);
+    for (const entry of entries) {
+      if (!entry.endsWith('.json')) continue;
+      const sessionId = entry.slice(0, -'.json'.length);
+      const state = readSessionState(sessionId);
+      const cmd = state.last_slash_command;
+      const candidate = {
+        session_id: sessionId,
+        project_hash: cmd?.project_hash || state.project_hash || null,
+        is_sdlc_stage: Boolean(cmd?.is_sdlc_stage),
+        updated_at: cmd?.updated_at || state.updated_at || null,
+      };
+      if (!isRecentSdlcSessionCandidate(candidate, projectHash, maxAgeMs)) continue;
+      if (!best || parseUpdatedAt(candidate.updated_at) > parseUpdatedAt(best.updated_at)) {
+        best = candidate;
+      }
+    }
+  } catch { /* ignore */ }
+  return best;
+}
+
 // ── Short-TTL dedupe guards ──────────────────────────────────────────
 
 function normalizeDedupePart(value) {
@@ -503,6 +586,7 @@ module.exports = {
   readSessionSkill,
   persistSessionSlashCommand,
   readSessionLastSlashCommand,
+  findRecentSdlcSessionForProject,
   readLastAssistantFromTranscript,
   resolvePromptText,
   getAwCliVersionDetails,

package/hooks/codex-home.mjs

@@ -26,6 +26,8 @@ const CODEX_HOME_PHASE_BLUEPRINTS = {
         marker: this.scriptMarker,
         phase: 'SessionStart',
         targetCandidates: [
+          '$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_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh',
           '$HOME/.aw/.aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh',
         ],

package/hooks.mjs

@@ -102,7 +102,7 @@ if git log -1 --format='%b' HEAD 2>/dev/null | grep -qF "Co-Authored-By: AW"; th
     TELEMETRY_HOOK="$HOME/.aw-ecc/scripts/hooks/aw-usage-commit-created.js"
   fi
   if command -v node >/dev/null 2>&1 && [ -f "$TELEMETRY_HOOK" ]; then
-    COMMIT_HASH="$(git rev-parse --short HEAD 2>/dev/null || echo unknown)"
+    COMMIT_HASH="$(git rev-parse HEAD 2>/dev/null || echo unknown)"
     BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)"
     node "$TELEMETRY_HOOK" "$COMMIT_HASH" "$BRANCH" "$(pwd)" >/dev/null 2>&1
   fi
@@ -286,7 +286,7 @@ if git log -1 --format='%b' HEAD 2>/dev/null | grep -qF "Co-Authored-By: AW"; th
     TELEMETRY_HOOK="$HOME/.aw-ecc/scripts/hooks/aw-usage-commit-created.js"
   fi
   if command -v node >/dev/null 2>&1 && [ -f "$TELEMETRY_HOOK" ]; then
-    COMMIT_HASH="$(git rev-parse --short HEAD 2>/dev/null || echo unknown)"
+    COMMIT_HASH="$(git rev-parse HEAD 2>/dev/null || echo unknown)"
     BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)"
     node "$TELEMETRY_HOOK" "$COMMIT_HASH" "$BRANCH" "$(pwd)" >/dev/null 2>&1
   fi

package/link.mjs

@@ -1,19 +1,41 @@
 // link.mjs — Create symlinks from IDE dirs → .aw_registry/
 
-import { existsSync, lstatSync, mkdirSync, readdirSync, unlinkSync, symlinkSync, rmdirSync, realpathSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, unlinkSync, symlinkSync, rmSync, rmdirSync, realpathSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { homedir } from 'node:os';
 import * as fmt from './fmt.mjs';
 import { getLocalRegistryDir } from './git.mjs';
 
-function forceSymlink(target, linkPath) {
-  try { unlinkSync(linkPath); } catch { /* not there yet */ }
+function forceSymlink(target, linkPath, { replaceManagedDir = false } = {}) {
+  try {
+    unlinkSync(linkPath);
+  } catch {
+    // unlinkSync does not remove a real directory. A stale copied dir from an older
+    // install (e.g. an ECC copy, or a previous copy-not-symlink install) can collide
+    // with the canonical symlink name — clear it so the registry symlink can take the
+    // name. Only do this for AW-managed catalog links, scoped by replaceManagedDir:
+    //   'skill' → only when the dir is itself a skill (has SKILL.md), so an unrelated
+    //             non-skill directory still surfaces the EEXIST error to the caller
+    //             instead of being silently deleted (no user-data loss).
+    //   true    → managed catalog dirs (evals/docs) that AW fully owns; a stale real
+    //             copy must be replaced or the canonical link is never refreshed.
+    try {
+      if (existsSync(linkPath) && lstatSync(linkPath).isDirectory()) {
+        const shouldReplace = replaceManagedDir === 'skill'
+          ? existsSync(join(linkPath, 'SKILL.md'))
+          : replaceManagedDir === true;
+        if (shouldReplace) {
+          rmSync(linkPath, { recursive: true, force: true });
+        }
+      }
+    } catch { /* best effort */ }
+  }
   symlinkSync(target, linkPath);
 }
 
 function linkNestedSkillRoot(target, linkPath, { silent }) {
   try {
-    forceSymlink(target, linkPath);
+    forceSymlink(target, linkPath, { replaceManagedDir: 'skill' });
     return true;
   } catch (error) {
     if (!silent) {
@@ -161,6 +183,9 @@ function cleanSymlinksRecursive(dir) {
  * Compute flat IDE name: namespace-slug (always includes namespace).
  */
 function flatName(ns, name) {
+  // Avoid a redundant namespace prefix when the skill/agent name already begins with
+  // the namespace (e.g. ns=aw, name=aw-plan -> aw-plan, not aw-aw-plan).
+  if (name === ns || name.startsWith(`${ns}-`)) return name;
   return `${ns}-${name}`;
 }
 
@@ -219,7 +244,7 @@ export function linkWorkspace(cwd, awDirOverride = null, { silent = false } = {}
     // Skills: per-skill directory symlinks (recursive for nested domain dirs)
     for (const { typeDirPath: skillsDir, segments } of findNestedTypeDirs(join(awDir, ns), 'skills')) {
       for (const skill of listDirs(skillsDir)) {
-        const flat = [ns, ...segments, skill].join('-');
+        const flat = flatName(ns, [...segments, skill].join('-'));
 
         for (const ide of IDE_DIRS) {
           const linkDir = join(cwd, ide, 'skills');
@@ -227,13 +252,13 @@ export function linkWorkspace(cwd, awDirOverride = null, { silent = false } = {}
           const linkPath = join(linkDir, flat);
           const targetPath = join(skillsDir, skill);
           const relTarget = relative(linkDir, targetPath);
-          try { forceSymlink(relTarget, linkPath); created++; } catch { /* best effort */ }
+          try { forceSymlink(relTarget, linkPath, { replaceManagedDir: 'skill' }); created++; } catch { /* best effort */ }
         }
       }
 
       for (const { skillDirPath, segments: skillSegments } of findSkillRootDirs(skillsDir)) {
         if (skillSegments.length <= 1) continue;
-        const flat = [ns, ...segments, ...skillSegments].join('-');
+        const flat = flatName(ns, [...segments, ...skillSegments].join('-'));
 
         for (const ide of IDE_DIRS) {
           const linkDir = join(cwd, ide, 'skills');
@@ -261,7 +286,7 @@ export function linkWorkspace(cwd, awDirOverride = null, { silent = false } = {}
             const linkPath = join(linkDir, flat);
             const targetPath = join(evalsDir, evalSlug);
             const relTarget = relative(linkDir, targetPath);
-            try { forceSymlink(relTarget, linkPath); created++; } catch { /* best effort */ }
+            try { forceSymlink(relTarget, linkPath, { replaceManagedDir: true }); created++; } catch { /* best effort */ }
           }
         }
       } else {
@@ -276,7 +301,7 @@ export function linkWorkspace(cwd, awDirOverride = null, { silent = false } = {}
               const linkPath = join(linkDir, flat);
               const targetPath = join(subDir, evalName);
               const relTarget = relative(linkDir, targetPath);
-              try { forceSymlink(relTarget, linkPath); created++; } catch { /* best effort */ }
+              try { forceSymlink(relTarget, linkPath, { replaceManagedDir: true }); created++; } catch { /* best effort */ }
             }
           }
         }
@@ -310,16 +335,16 @@ export function linkWorkspace(cwd, awDirOverride = null, { silent = false } = {}
       for (const { typeDirPath: skillsDir, segments } of findNestedTypeDirs(join(awDir, ns), 'skills')) {
         mkdirSync(agentsSkillsDir, { recursive: true });
         for (const skill of listDirs(skillsDir)) {
-          const flat = [ns, ...segments, skill].join('-');
+          const flat = flatName(ns, [...segments, skill].join('-'));
           const linkPath = join(agentsSkillsDir, flat);
           const targetPath = join(skillsDir, skill);
           const relTarget = relative(agentsSkillsDir, targetPath);
-          try { forceSymlink(relTarget, linkPath); created++; } catch { /* best effort */ }
+          try { forceSymlink(relTarget, linkPath, { replaceManagedDir: 'skill' }); created++; } catch { /* best effort */ }
         }
 
         for (const { skillDirPath, segments: skillSegments } of findSkillRootDirs(skillsDir)) {
           if (skillSegments.length <= 1) continue;
-          const flat = [ns, ...segments, ...skillSegments].join('-');
+          const flat = flatName(ns, [...segments, ...skillSegments].join('-'));
           const linkPath = join(agentsSkillsDir, flat);
           const relTarget = relative(agentsSkillsDir, skillDirPath);
           if (linkNestedSkillRoot(relTarget, linkPath, { silent })) created++;
@@ -378,7 +403,7 @@ export function linkWorkspace(cwd, awDirOverride = null, { silent = false } = {}
       mkdirSync(linkDir, { recursive: true });
       const linkPath = join(linkDir, 'docs');
       const relTarget = relative(linkDir, platformDocsDir);
-      try { forceSymlink(relTarget, linkPath); created++; } catch { /* best effort */ }
+      try { forceSymlink(relTarget, linkPath, { replaceManagedDir: true }); created++; } catch { /* best effort */ }
     }
   }
 

package/mcp.mjs

@@ -46,6 +46,10 @@ function envDisablesMcp(env = process.env) {
   return ['1', 'true', 'yes', 'on'].includes(value);
 }
 
+function hasInteractiveTerminal() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
 export function loadMcpPreferences(homeDir = HOME) {
   const prefs = readJson(mcpPrefsPath(homeDir), {});
   return {
@@ -126,8 +130,8 @@ function resolveGitHubToken(silent = false) {
       }
     } catch { /* not authenticated yet */ }
 
-    // 2b. Not authenticated — skip browser login in silent mode (no terminal)
-    if (silent) return null;
+    // 2b. Not authenticated — skip browser login when no terminal is available.
+    if (silent || !hasInteractiveTerminal()) return null;
 
     fmt.logStep('GitHub CLI found but not authenticated — launching login...');
     try {
@@ -237,8 +241,13 @@ async function resolveClickUpToken(silent = false, cwd = process.cwd()) {
     return existing.token;
   }
 
-  // In silent mode (git hooks, auto-pull) there is no terminal — skip prompt
-  if (silent) return null;
+  // In silent/non-TTY mode (git hooks, Jenkins, auto-pull) there is no safe
+  // terminal prompt. ClickUp is optional, so skip instead of letting Clack
+  // initialize node:tty and crash.
+  if (silent || !hasInteractiveTerminal()) {
+    if (!silent) fmt.logInfo('Skipping ClickUp — no interactive terminal available');
+    return null;
+  }
 
   // 3. Ask first — don't assume the user wants ClickUp
   const wantsClickUp = await p.select({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.73",
-  "description": "Agentic Workspace CLI \u2014 pull, push & manage agents, skills and commands from the registry",
+  "version": "0.1.77",
+  "description": "Agentic Workspace CLI — pull, push & manage agents, skills and commands from the registry",
   "type": "module",
   "bin": {
     "aw": "bin.js"
@@ -74,4 +74,4 @@
   "devDependencies": {
     "vitest": "^4.1.2"
   }
-}
+}

package/render-rules.mjs

@@ -358,11 +358,11 @@ ${GENERATED_MARKER}
 
 For every non-trivial request, execute these steps in order before any substantive response:
 
-1. **Load the router** — Read the using-aw-skills SKILL.md from the skills directory.
+1. **Load the router** — Read \`.cursor/skills/aw-using-aw-skills/SKILL.md\` from the active workspace first; if it is missing, fall back to \`~/.cursor/skills/aw-using-aw-skills/SKILL.md\`, then \`~/.agents/skills/aw-using-aw-skills/SKILL.md\`.
 
 2. **Select route** — using the decision tree below, pick the smallest correct AW route.
 
-3. **Read the stage skill** — you MUST Read the matching skill file before responding:
+3. **Read the stage skill** — you MUST Read the matching skill file before responding. Skills are in the active workspace \`.cursor/skills/\` first, then \`~/.cursor/skills/\`, then \`~/.agents/skills/\`:
    - /aw-adk → Read aw-adk/SKILL.md
    - /aw-publish → Read aw-publish/SKILL.md
    - /aw-plan → Read aw-plan/SKILL.md

package/startup.mjs

@@ -16,6 +16,18 @@ const DISABLED_MODE = 'disabled';
 const DISABLE_DEFAULT_ROUTING_ENV = 'AW_DISABLE_DEFAULT_ROUTING';
 
 const CLAUDE_DISABLE_DESCRIPTION = 'AW-managed override: disable automatic AW session routing';
+
+// using-aw-skills router hooks. The SessionStart hook injects the AW routing card once
+// per session; the UserPromptSubmit hook re-asserts it on every prompt (the stronger
+// always-on auto-trigger). Both were missing after the ecc->registry migration, which is
+// why SDLC skills stopped auto-triggering in Claude. The command resolves the first
+// existing on-disk router script across both registry roots and namespaces.
+const CLAUDE_ROUTER_DESCRIPTION = 'AW-managed: using-aw-skills session router';
+const CLAUDE_REMINDER_DESCRIPTION = 'AW-managed: using-aw-skills per-prompt reminder';
+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 =
+  'echo \'{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"[AW] using-aw-skills is active. Select the smallest correct AW route (/aw:plan, /aw:execute, /aw:verify, /aw:deploy, /aw:ship) before substantive work."}}\'';
 const CLAUDE_TELEMETRY_DESCRIPTION = 'AW usage telemetry';
 const CLAUDE_TELEMETRY_HOOKS = [
   {
@@ -47,6 +59,24 @@ const CLAUDE_TELEMETRY_HOOKS = [
 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"';
+
+// Deterministic local-Cursor AW router. Local Cursor previously had no AW session hook
+// (only an advisory .mdc rule the model could under-weight), so SDLC skills did not
+// auto-trigger. This managed sessionStart hook injects the using-aw-skills router via the
+// concise session-start.sh (CURSOR_PLUGIN_ROOT branch emits Cursor's {additional_context}).
+const CURSOR_AW_ROUTER_DESCRIPTION = 'AW-managed: using-aw-skills router';
+const CURSOR_AW_ROUTER_COMMAND = 'bash "$HOME/.cursor/hooks/aw-session-start.sh"';
+const CURSOR_AW_HOOK_MARKER = '# aw-managed: cursor-aw-session-start';
+const CURSOR_AW_HOOK_SCRIPT = `#!/usr/bin/env bash
+${CURSOR_AW_HOOK_MARKER}
+set -euo pipefail
+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
+  if [[ -f "$f" ]]; then
+    CURSOR_PLUGIN_ROOT=1 exec bash "$f"
+  fi
+done
+echo '{"additional_context": "[AW] using-aw-skills router not found in ~/.aw registry. Run aw pull aw or aw init."}'
+`;
 const REPO_CLAUDE_SESSION_START_COMMAND = '"$CLAUDE_PROJECT_DIR"/hooks/aw-session-start';
 const CODEX_HOME_PHASE_DEFINITIONS = getCodexHomePhaseDefinitions();
 const CODEX_HOME_PHASE_BY_NAME = new Map(
@@ -164,6 +194,9 @@ function hasClaudePluginCache(homeDir = homedir()) {
 }
 
 function isLegacyClaudeSessionStartEntry(entry) {
+  // The managed router intentionally lists the platform/core path as a fallback candidate;
+  // it is the current managed entry, not a stale legacy hook.
+  if (entry?.description === CLAUDE_ROUTER_DESCRIPTION) return false;
   return Array.isArray(entry?.hooks)
     && entry.hooks.some(hook =>
       hook?.type === 'command'
@@ -172,6 +205,38 @@ function isLegacyClaudeSessionStartEntry(entry) {
     );
 }
 
+function isManagedClaudeRouterEntry(entry) {
+  return entry?.description === CLAUDE_ROUTER_DESCRIPTION;
+}
+
+function isManagedClaudeReminderEntry(entry) {
+  return entry?.description === CLAUDE_REMINDER_DESCRIPTION;
+}
+
+// Orphaned `{ matcher: '*', hooks: [] }` stubs with no description accumulated in some
+// settings.json files and are invisible to the disable-override filter. Strip them.
+function isEmptyClaudeSessionStartStub(entry) {
+  return entry?.matcher === '*'
+    && Array.isArray(entry?.hooks)
+    && entry.hooks.length === 0
+    && !entry?.description;
+}
+
+function buildClaudeRouterEntry() {
+  return {
+    matcher: 'startup|resume|clear|compact',
+    hooks: [{ type: 'command', command: CLAUDE_ROUTER_COMMAND }],
+    description: CLAUDE_ROUTER_DESCRIPTION,
+  };
+}
+
+function buildClaudeReminderEntry() {
+  return {
+    hooks: [{ type: 'command', command: CLAUDE_REMINDER_COMMAND }],
+    description: CLAUDE_REMINDER_DESCRIPTION,
+  };
+}
+
 function hasCommandHook(entry, command) {
   return Array.isArray(entry?.hooks)
     && entry.hooks.some(hook =>
@@ -336,45 +401,98 @@ function disableClaudeStartup(homeDir = homedir()) {
   const config = readJson(settingsPath, {});
   ensureHooksObject(config);
 
+  const before = JSON.stringify(config.hooks);
+
   const current = Array.isArray(config.hooks.SessionStart) ? config.hooks.SessionStart : [];
-  const next = [
+  config.hooks.SessionStart = [
     {
       matcher: '*',
       hooks: [],
       description: CLAUDE_DISABLE_DESCRIPTION,
     },
-    ...current.filter(entry => !isManagedClaudeSessionStartOverride(entry) && !isLegacyClaudeSessionStartEntry(entry)),
+    // Strip everything enableClaudeStartup installs: the managed router, orphaned
+    // empty stubs, legacy platform/core entries, and any prior disable override.
+    ...current.filter(entry =>
+      !isManagedClaudeSessionStartOverride(entry)
+      && !isLegacyClaudeSessionStartEntry(entry)
+      && !isEmptyClaudeSessionStartStub(entry)
+      && !isManagedClaudeRouterEntry(entry)),
   ];
 
-  if (JSON.stringify(current) === JSON.stringify(next)) {
+  // Remove the managed per-prompt reminder installed by enableClaudeStartup.
+  if (Array.isArray(config.hooks.UserPromptSubmit)) {
+    const filtered = config.hooks.UserPromptSubmit.filter(entry => !isManagedClaudeReminderEntry(entry));
+    if (filtered.length > 0) config.hooks.UserPromptSubmit = filtered;
+    else delete config.hooks.UserPromptSubmit;
+  }
+
+  if (JSON.stringify(config.hooks) === before) {
     return [];
   }
 
-  config.hooks.SessionStart = next;
   writeJson(settingsPath, config);
   return [settingsPath];
 }
 
-function enableClaudeStartup(homeDir = homedir()) {
+// Full removal of every AW-managed Claude startup hook (router, reminder, disable
+// override, orphaned stubs, legacy entries) for `aw nuke` — restores settings.json
+// toward its pre-AW state and prunes the file/hooks object if nothing else remains.
+export function purgeManagedClaudeStartupHooks(homeDir = homedir()) {
   const settingsPath = join(homeDir, '.claude', 'settings.json');
   if (!existsSync(settingsPath)) return [];
-
   const config = readJson(settingsPath, {});
-  if (!isObject(config.hooks) || !Array.isArray(config.hooks.SessionStart)) {
-    return [];
+  if (!isObject(config.hooks)) return [];
+
+  const before = JSON.stringify(config.hooks);
+
+  if (Array.isArray(config.hooks.SessionStart)) {
+    const filtered = config.hooks.SessionStart.filter(entry =>
+      !isManagedClaudeSessionStartOverride(entry)
+      && !isLegacyClaudeSessionStartEntry(entry)
+      && !isEmptyClaudeSessionStartStub(entry)
+      && !isManagedClaudeRouterEntry(entry));
+    if (filtered.length > 0) config.hooks.SessionStart = filtered;
+    else delete config.hooks.SessionStart;
   }
+  if (Array.isArray(config.hooks.UserPromptSubmit)) {
+    const filtered = config.hooks.UserPromptSubmit.filter(entry => !isManagedClaudeReminderEntry(entry));
+    if (filtered.length > 0) config.hooks.UserPromptSubmit = filtered;
+    else delete config.hooks.UserPromptSubmit;
+  }
+
+  if (JSON.stringify(config.hooks) === before) return [];
+
+  if (isEmptyObject(config.hooks)) delete config.hooks;
+  if (!pruneEmptySettingsFile(settingsPath, config)) writeJson(settingsPath, config);
+  return [settingsPath];
+}
+
+function enableClaudeStartup(homeDir = homedir()) {
+  const settingsPath = join(homeDir, '.claude', 'settings.json');
+  const config = readJson(settingsPath, {});
+  ensureHooksObject(config);
 
-  const filtered = config.hooks.SessionStart.filter(
-    entry => !isManagedClaudeSessionStartOverride(entry) && !isLegacyClaudeSessionStartEntry(entry),
+  const before = JSON.stringify(config.hooks);
+
+  // SessionStart: install the using-aw-skills router. Drop AW disable-overrides,
+  // legacy platform/core router entries, orphaned empty stubs, and any prior managed
+  // router entry so re-runs replace rather than accumulate (idempotent).
+  const ssCurrent = Array.isArray(config.hooks.SessionStart) ? config.hooks.SessionStart : [];
+  const ssCleaned = ssCurrent.filter(entry =>
+    !isManagedClaudeSessionStartOverride(entry)
+    && !isLegacyClaudeSessionStartEntry(entry)
+    && !isEmptyClaudeSessionStartStub(entry)
+    && !isManagedClaudeRouterEntry(entry),
   );
-  if (filtered.length === config.hooks.SessionStart.length) {
-    return [];
-  }
+  config.hooks.SessionStart = [...ssCleaned, buildClaudeRouterEntry()];
 
-  if (filtered.length > 0) {
-    config.hooks.SessionStart = filtered;
-  } else {
-    delete config.hooks.SessionStart;
+  // UserPromptSubmit: install the per-prompt reminder (the strongest always-on trigger).
+  const upCurrent = Array.isArray(config.hooks.UserPromptSubmit) ? config.hooks.UserPromptSubmit : [];
+  const upCleaned = upCurrent.filter(entry => !isManagedClaudeReminderEntry(entry));
+  config.hooks.UserPromptSubmit = [...upCleaned, buildClaudeReminderEntry()];
+
+  if (JSON.stringify(config.hooks) === before) {
+    return [];
   }
 
   if (isEmptyObject(config.hooks)) {
@@ -575,7 +693,8 @@ function isManagedCursorSessionStartEntry(entry, homeDir = homedir()) {
 }
 
 function hasCursorSessionStartScript(homeDir = homedir()) {
-  return existsSync(join(homeDir, '.cursor', 'hooks', 'session-start.js'));
+  return existsSync(join(homeDir, '.cursor', 'hooks', 'session-start.js'))
+    || existsSync(join(homeDir, '.cursor', 'hooks', 'aw-session-start.sh'));
 }
 
 function disableCursorStartup(homeDir = homedir()) {
@@ -641,6 +760,71 @@ function enableCursorStartup(homeDir = homedir()) {
   return [hooksPath];
 }
 
+function isManagedCursorAwRouterEntry(entry) {
+  return entry?.description === CURSOR_AW_ROUTER_DESCRIPTION
+    || String(entry?.command || '') === CURSOR_AW_ROUTER_COMMAND;
+}
+
+function enableCursorAwRouting(homeDir = homedir()) {
+  const updated = [];
+
+  // 1. Write the managed AW router hook script (idempotent).
+  const scriptPath = join(homeDir, '.cursor', 'hooks', 'aw-session-start.sh');
+  const existing = existsSync(scriptPath) ? readFileSync(scriptPath, 'utf8') : null;
+  if (existing !== CURSOR_AW_HOOK_SCRIPT) {
+    mkdirSync(dirname(scriptPath), { recursive: true });
+    writeFileSync(scriptPath, CURSOR_AW_HOOK_SCRIPT);
+    try { chmodSync(scriptPath, 0o755); } catch { /* best effort */ }
+    updated.push(scriptPath);
+  }
+
+  // 2. Wire it into ~/.cursor/hooks.json sessionStart, additive and idempotent — preserve
+  // Cursor's native session-start hook and any unrelated entries.
+  const hooksPath = join(homeDir, '.cursor', 'hooks.json');
+  const config = readJson(hooksPath, {});
+  if (!isObject(config.hooks)) config.hooks = {};
+  config.version = Number.isInteger(config.version) ? config.version : 1;
+  const current = Array.isArray(config.hooks.sessionStart) ? config.hooks.sessionStart : [];
+  if (!current.some(isManagedCursorAwRouterEntry)) {
+    config.hooks.sessionStart = [
+      ...current,
+      { command: CURSOR_AW_ROUTER_COMMAND, event: 'sessionStart', description: CURSOR_AW_ROUTER_DESCRIPTION },
+    ];
+    writeJson(hooksPath, config);
+    updated.push(hooksPath);
+  }
+
+  return updated;
+}
+
+export function disableCursorAwRouting(homeDir = homedir()) {
+  const updated = [];
+
+  const hooksPath = join(homeDir, '.cursor', 'hooks.json');
+  if (existsSync(hooksPath)) {
+    const config = readJson(hooksPath, {});
+    if (isObject(config.hooks) && Array.isArray(config.hooks.sessionStart)) {
+      const filtered = config.hooks.sessionStart.filter(entry => !isManagedCursorAwRouterEntry(entry));
+      if (filtered.length !== config.hooks.sessionStart.length) {
+        if (filtered.length > 0) config.hooks.sessionStart = filtered;
+        else delete config.hooks.sessionStart;
+        if (isEmptyObject(config.hooks)) delete config.hooks;
+        if (config.version === undefined) config.version = 1;
+        if (!pruneEmptySettingsFile(hooksPath, config)) writeJson(hooksPath, config);
+        updated.push(hooksPath);
+      }
+    }
+  }
+
+  const scriptPath = join(homeDir, '.cursor', 'hooks', 'aw-session-start.sh');
+  if (existsSync(scriptPath) && readFileSync(scriptPath, 'utf8').includes(CURSOR_AW_HOOK_MARKER)) {
+    rmSync(scriptPath, { force: true });
+    updated.push(scriptPath);
+  }
+
+  return updated;
+}
+
 export function loadStartupPreferences(homeDir = homedir()) {
   const prefs = readJson(startupPrefsPath(homeDir), {});
   return {
@@ -685,11 +869,13 @@ export function applyGlobalStartupMode(mode, homeDir = homedir()) {
     updatedFiles.push(...disableClaudeTelemetryHooks(homeDir));
     updatedFiles.push(...disableCodexStartup(homeDir));
     updatedFiles.push(...disableCursorStartup(homeDir));
+    updatedFiles.push(...disableCursorAwRouting(homeDir));
   } else {
     updatedFiles.push(...enableClaudeStartup(homeDir));
     updatedFiles.push(...enableClaudeTelemetryHooks(homeDir));
     updatedFiles.push(...enableCodexStartup(homeDir));
     updatedFiles.push(...enableCursorStartup(homeDir));
+    updatedFiles.push(...enableCursorAwRouting(homeDir));
   }
 
   return [...new Set(updatedFiles)];
@@ -719,6 +905,8 @@ export function getStartupStatus(homeDir = homedir(), env = process.env) {
     preferencesPath: startupPrefsPath(homeDir),
     claudePluginEnabled: claudeSettings?.enabledPlugins?.['aw@aw-marketplace'] === true,
     claudePluginInstalled: hasClaudePluginCache(homeDir),
+    claudeRouterPresent: Array.isArray(claudeSettings?.hooks?.SessionStart) &&
+      claudeSettings.hooks.SessionStart.some(isManagedClaudeRouterEntry),
     claudeDisabled: Array.isArray(claudeSettings?.hooks?.SessionStart) &&
       claudeSettings.hooks.SessionStart.some(isManagedClaudeSessionStartOverride),
     claudeLegacySessionStartPresent: Array.isArray(claudeSettings?.hooks?.SessionStart) &&
@@ -728,7 +916,7 @@ export function getStartupStatus(homeDir = homedir(), env = process.env) {
       codexHooks.hooks.SessionStart.some(isManagedCodexSessionStartEntry),
     codexSessionStartScriptInstalled: hasCodexSessionStartScript(homeDir),
     cursorSessionStartPresent: cursorSessionStartEntries.some(entry =>
-      isManagedCursorSessionStartEntry(entry, homeDir)),
+      isManagedCursorSessionStartEntry(entry, homeDir) || isManagedCursorAwRouterEntry(entry)),
     cursorAnySessionStartPresent: cursorSessionStartEntries.length > 0,
     cursorSessionStartScriptInstalled: hasCursorSessionStartScript(homeDir),
   };