auxilo-mcp 0.9.27 → 0.9.29

package/bin/auxilo-cli.js

@@ -19,7 +19,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const readline = require('readline');
-const { exec } = require('child_process');
+const { exec, spawnSync } = require('child_process');
 const installer = require('../lib/installer.js');
 const review = require('../lib/review.js');
 const runnerAutoupdate = require('../lib/runner-autoupdate.js');
@@ -244,7 +244,15 @@ async function cmdSetup(flags) {
   console.log('');
   for (const client of chosen.filter((c) => c.mcp)) {
     try {
-      const result = installer.registerMcp(client);
+      const result = installer.registerMcp(client, undefined, { commandRunner: spawnSync });
+      if (client.id === 'claude-code') {
+        if (result.failed) {
+          console.log('Setup could not add Auxilo to Claude Code, so run this command to add it yourself.');
+          console.log(installer.claudeMcpCommand());
+        }
+        console.log(installer.claudeMcpStatusLine(result));
+        continue;
+      }
       console.log(result.changed
         ? `  ✓ ${client.name}: registered Auxilo MCP server (${result.configPath})`
         : `  ✓ ${client.name}: already registered (no changes)`);
@@ -283,7 +291,7 @@ async function cmdSetup(flags) {
       });
       creds = installer.readCredentials(HOME);
       console.log(`  ✓ Logged in as ${result.email || result.account_id}`);
-      console.log(`  ✓ Credentials saved to ~/.auxilo/credentials.json (mode 0600)`);
+      console.log(`  ✓ Credentials saved to ~/.auxilo/credentials.json${process.platform === 'win32' ? '' : ' (mode 0600)'}`);
     } catch (err) {
       console.error(`  ✗ Login failed: ${err.message}`);
       console.error('    MCP registration (above) is still in place. Re-run `auxilo setup` to retry login.');
@@ -505,7 +513,7 @@ async function cmdInit(flags) {
     try {
       const w = installer.writeEnvFile(envPath, { api_key: result.api_key, base_url: baseUrl });
       if (!flags.json) {
-        console.log(`  ✓ ${w.created ? 'Created' : 'Updated'} ${w.path} (AUXILO_API_KEY, mode 0600)`);
+        console.log(`  ✓ ${w.created ? 'Created' : 'Updated'} ${w.path} (AUXILO_API_KEY${process.platform === 'win32' ? '' : ', mode 0600'})`);
       }
     } catch (err) {
       // The key was already minted — surface it rather than losing it.
@@ -523,7 +531,7 @@ async function cmdInit(flags) {
       email: result.email,
       account_id: result.account_id,
     });
-    if (!flags.json) console.log('  ✓ Saved to ~/.auxilo/credentials.json (mode 0600) — this machine now uses this key.');
+    if (!flags.json) console.log(`  ✓ Saved to ~/.auxilo/credentials.json${process.platform === 'win32' ? '' : ' (mode 0600)'} — this machine now uses this key.`);
   }
 
   if (flags.json) {
@@ -553,7 +561,7 @@ async function cmdInit(flags) {
 // ─── auxilo status ──────────────────────────────────────────────────────────
 
 async function cmdStatus() {
-  const s = await installer.getStatus(HOME);
+  const s = await installer.getStatus(HOME, { commandRunner: spawnSync });
 
   console.log('\nAuxilo status');
   console.log('=============');
@@ -561,6 +569,10 @@ async function cmdStatus() {
   console.log('Clients:');
   if (s.clients.length === 0) console.log('  (none detected)');
   for (const c of s.clients) {
+    if (c.id === 'claude-code') {
+      console.log(`  ${installer.claudeMcpStatusLine(c)}`);
+      continue;
+    }
     const reg = c.mcp
       ? (c.registered ? 'MCP registered' : 'detected, MCP NOT registered')
       : 'poll-based source (no MCP config)';
@@ -1121,6 +1133,10 @@ const CLEAN_LANE_AFFIRMATION = 'I understand and choose auto-publish for qualify
  * "readable only by your user account" claim below is never printed false.
  */
 const PROVIDER_KEY_CONSENT_SENTENCE = 'This key is yours. It stays on this machine in ~/.auxilo/providers.json, readable only by your user account, and Auxilo never receives it. It is used for one thing, drafting learnings from your own scrubbed sessions. Drafting sends those sessions to that provider under your own account, and any use is charged to that account, never to Auxilo. Run auxilo provider clear to remove it.';
+const WINDOWS_PROVIDER_KEY_CONSENT_SENTENCE = 'This key is yours. It stays on this machine in your user profile folder, at .auxilo\\providers.json, and Auxilo never receives it. It is used for one thing, drafting learnings from your own scrubbed sessions. Drafting sends those sessions to that provider under your own account, and any use is charged to that account, never to Auxilo. Run auxilo provider clear to remove it.';
+function providerKeyConsentSentence(platform = process.platform) {
+  return platform === 'win32' ? WINDOWS_PROVIDER_KEY_CONSENT_SENTENCE : PROVIDER_KEY_CONSENT_SENTENCE;
+}
 const CLEAN_LANE_UNAVAILABLE = 'Auto-publish for clean learnings is not yet available on this account.';
 // CLEAN-LANE-FLIP Phase B (legal; DRAFT pending Tyler): the full text of ToS
 // §5.9.3(g) (plus its ratchet paragraph) prints ABOVE the affirmation prompt —
@@ -1371,6 +1387,7 @@ const PROVIDER_VENDORS = ['openai', 'anthropic', 'gemini'];
  * reason. Never throws now.
  */
 function providersFileModeUnsafe(target) {
+  if (process.platform === 'win32') return !byoKeyProvider.providersFileInsideProfile(target);
   let stat;
   try {
     stat = fs.statSync(target);
@@ -1382,6 +1399,7 @@ function providersFileModeUnsafe(target) {
 }
 
 async function cmdProvider(flags) {
+  const PROVIDER_KEY_CONSENT_SENTENCE = providerKeyConsentSentence();
   const sub = process.argv[3];
   if (!['status', 'set', 'clear'].includes(sub)) {
     if (sub) console.error(`Unknown provider subcommand: ${sub}`);
@@ -1430,7 +1448,7 @@ async function cmdProvider(flags) {
   // existing providers.json that is not owner-read-only would make the
   // sentence's "readable only by your user account" claim false.
   if (providersFileModeUnsafe(byoKeyProvider.DEFAULT_PROVIDERS_STATE_PATH)) {
-    console.error('auxilo provider set refuses to continue: ~/.auxilo/providers.json exists and is not owner-read-only, so this build cannot truthfully make the consent promise (reasonCode: providers-file-mode-unsafe). Fix its permissions (chmod 600 ~/.auxilo/providers.json) or remove the file, then try again.');
+    console.error(process.platform === 'win32' ? 'The provider key file must be inside your Windows user profile folder. (reasonCode: providers-file-mode-unsafe)' : 'auxilo provider set refuses to continue: ~/.auxilo/providers.json exists and is not owner-read-only, so this build cannot truthfully make the consent promise (reasonCode: providers-file-mode-unsafe). Fix its permissions (chmod 600 ~/.auxilo/providers.json) or remove the file, then try again.');
     process.exit(1);
   }
 
@@ -1515,7 +1533,7 @@ async function cmdProvider(flags) {
     }
     throw err;
   }
-  console.log(`\n✓ Saved to ${written} (mode 0600). This machine drafts through Claude Code first when you are signed in to it; your ${vendor} key only takes over when Claude Code is not usable, and once it does, it keeps drafting even after Claude Code becomes usable again.`);
+  console.log(`\n✓ Saved to ${written}${process.platform === 'win32' ? '' : ' (mode 0600)' }. This machine drafts through Claude Code first when you are signed in to it; your ${vendor} key only takes over when Claude Code is not usable, and once it does, it keeps drafting even after Claude Code becomes usable again.`);
 }
 
 // ─── Entry point ────────────────────────────────────────────────────────────
@@ -1708,6 +1726,7 @@ module.exports = {
   CLEAN_LANE_NO_EMAIL_LINE,
   wrapForTerminal,
   PROVIDER_KEY_CONSENT_SENTENCE,
+  providerKeyConsentSentence,
   CLI_CLEAN_LANE_CALIBRATED_PROVIDERS,
   STATUS_WORTHY_SKIP_REASON_CODES,
   extractionSkipReasonLine,

package/lib/hook-status.js

@@ -1,5 +1,16 @@
 'use strict';
 
+/** Recognize only the generated node command under Auxilo's scripts directory. */
+function isAuxiloNodeHook(command, script, source = null) {
+  if (typeof command !== 'string') return false;
+  const match = /^node "([^"\r\n]+)"(?: --source ([a-z0-9-]+))?$/.exec(command);
+  if (!match) return false;
+  const windows = process.platform === 'win32' || /^[a-z]:[\\/]/i.test(match[1]) || match[1].includes('\\');
+  const target = windows ? match[1].replace(/\\/g, '/').toLowerCase() : match[1];
+  if (!target.endsWith(`/.auxilo/bin/scripts/${script}`)) return false;
+  return source === true ? Boolean(match[2]) : (match[2] || null) === source;
+}
+
 /**
  * True when a Claude Code SessionEnd collection contains an Auxilo extraction
  * hook. Accepts both the legacy bare-command string and the current matcher
@@ -9,16 +20,17 @@
  * @returns {boolean}
  */
 function hasAuxiloSessionEndHook(sessionEnd) {
+  const ours = command => command.includes('auxilo-extract') || isAuxiloNodeHook(command, 'capture-core.js', 'claude-code');
   if (!Array.isArray(sessionEnd)) return false;
 
   return sessionEnd.some((entry) => {
-    if (typeof entry === 'string') return entry.includes('auxilo-extract');
+    if (typeof entry === 'string') return ours(entry);
     if (!entry || typeof entry !== 'object' || !Array.isArray(entry.hooks)) return false;
     return entry.hooks.some((hook) =>
       hook && typeof hook === 'object' &&
       typeof hook.command === 'string' &&
-      hook.command.includes('auxilo-extract'));
+      ours(hook.command));
   });
 }
 
-module.exports = { hasAuxiloSessionEndHook };
+module.exports = { hasAuxiloSessionEndHook, isAuxiloNodeHook };

package/lib/installer.js

@@ -25,7 +25,7 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
-const { hasAuxiloSessionEndHook } = require('./hook-status.js');
+const { hasAuxiloSessionEndHook, isAuxiloNodeHook } = require('./hook-status.js');
 
 // ─── Constants ──────────────────────────────────────────────────────────────
 
@@ -47,6 +47,7 @@ const MCP_PACKAGE_NAME = MCP_ENTRY.args[0];
 
 /** True when `args` is shaped like an Auxilo-owned MCP entry (pinned or not). */
 function isOwnedMcpArgs(args) {
+  if (Array.isArray(args) && args.length === 3 && args[0] === '/c' && args[1] === 'npx') args = args.slice(2);
   return Array.isArray(args) && args.length === 1 && typeof args[0] === 'string' &&
     (args[0] === MCP_PACKAGE_NAME || args[0].startsWith(`${MCP_PACKAGE_NAME}@`));
 }
@@ -57,6 +58,7 @@ function isOwnedMcpArgs(args) {
  */
 function parseMcpPin(args) {
   if (!isOwnedMcpArgs(args)) return null;
+  if (args.length === 3) args = args.slice(2);
   return args[0] === MCP_PACKAGE_NAME ? 'unpinned' : args[0].slice(MCP_PACKAGE_NAME.length + 1);
 }
 
@@ -235,8 +237,11 @@ function clientRegistry(homeDir, opts = {}) {
       id: 'claude-code',
       name: 'Claude Code',
       detectDir: path.join(homeDir, '.claude'),
-      configPath: path.join(homeDir, '.claude', 'settings.json'),
-      format: 'json-mcpServers',
+      configPath: path.join(homeDir, '.claude.json'),
+      legacyConfigPath: path.join(homeDir, '.claude', 'settings.json'),
+      homeDir,
+      platform,
+      format: 'claude-cli',
       mcp: true,
       hooks: true, // SessionEnd hook (background extraction)
     },
@@ -466,7 +471,7 @@ function clientRegistry(homeDir, opts = {}) {
       mcp: true,
       hooks: false,
     },
-  ];
+  ].map(client => ({ ...client, platform }));
 }
 
 /** True when p exists and is a directory (detection probe). */
@@ -601,10 +606,103 @@ function readClientConfig(configPath) {
  * unpinned shape (only used by parity checks below — every real writer call
  * always passes a version, defaulting to packageVersion() in registerMcp).
  */
-function mcpEntry(version) {
+function mcpEntry(version, platform) {
+  if (platform === 'win32') return { command: 'cmd', args: ['/c', 'npx', version ? `${MCP_PACKAGE_NAME}@${version}` : MCP_PACKAGE_NAME] };
   return { command: MCP_ENTRY.command, args: [version ? `${MCP_PACKAGE_NAME}@${version}` : MCP_PACKAGE_NAME] };
 }
 
+/** The binding layer supplies the runner; omission is deliberately inert. */
+function claudeMcpCommand(platform = process.platform) {
+  return `claude mcp add --scope user auxilo -- ${platform === 'win32' ? 'cmd /c ' : ''}npx auxilo-mcp`;
+}
+
+function claudeMcpStatusLine(state, platform = process.platform) {
+  if (state.connection === 'connected') return `Claude Code: connected (${state.mcpPin || 'unpinned'})`;
+  if (state.connection === 'added') return 'Claude Code: added, not responding yet. Restart Claude Code, then run npx auxilo status';
+  return `Claude Code: not connected. Run ${claudeMcpCommand(platform)}`;
+}
+
+function claudeRunnerBin(client, opts) {
+  if (opts.claudeBin) return opts.claudeBin;
+  const recorded = readRunnerConfig(client.homeDir).claude_bin;
+  if (typeof recorded === 'string' && fs.existsSync(recorded)) return recorded;
+  return findExecutableOnPath('claude', (opts.env || process.env).PATH, fs, { platform: client.platform, env: opts.env || process.env }) ||
+    [path.join(client.homeDir, '.local', 'bin', 'claude.exe'), path.join((opts.env || process.env).APPDATA || path.join(client.homeDir, 'AppData', 'Roaming'), 'npm', 'claude.cmd')].find(candidate => client.platform === 'win32' && fs.existsSync(candidate)) || null;
+}
+
+function runClaudeMcp(client, args, opts) {
+  if (typeof opts.commandRunner !== 'function') return null;
+  const bin = claudeRunnerBin(client, opts);
+  if (!bin) return null;
+  try {
+    if (client.platform === 'win32' && /\.cmd$/i.test(bin)) {
+      const cli = path.join(path.dirname(bin), 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js');
+      if (!fs.existsSync(cli)) return null;
+      return opts.commandRunner(process.execPath, [cli, ...args], { encoding: 'utf8', timeout: 20000, windowsHide: true });
+    }
+    return opts.commandRunner(bin, args, { encoding: 'utf8', timeout: 20000, windowsHide: true });
+  } catch (error) { return { error, status: null }; }
+}
+
+function claudeMcpState(client, opts = {}, added = false) {
+  const result = runClaudeMcp(client, ['mcp', 'get', 'auxilo'], opts);
+  if (!result) return { connection: 'not-connected', registered: false, mcpPin: null };
+  const output = String(result.stdout || '') + String(result.stderr || '');
+  const absent = output.includes('No MCP server named');
+  const present = !absent && (added || mcpRegistrationPresent(client) || /Command:\s*\S/.test(output));
+  const connected = !absent && /\bConnected\b/.test(output);
+  const pinMatch = output.match(/\bauxilo-mcp@([^\s"']+)/);
+  return {
+    connection: connected ? 'connected' : present ? 'added' : 'not-connected',
+    registered: connected || present,
+    mcpPin: pinMatch ? pinMatch[1] : (present ? mcpPinnedVersion(client) || 'unpinned' : null),
+  };
+}
+
+function claudeAddArgs(entry) {
+  const envArgs = Object.entries(entry.env || {}).flatMap(([key, value]) => ['--env', `${key}=${value}`]);
+  return ['mcp', 'add', '--scope', 'user', ...envArgs, 'auxilo', '--', entry.command, ...entry.args];
+}
+
+function registerClaudeMcp(client, version, opts = {}) {
+  const target = client.platform === 'win32'
+    ? { command: 'cmd', args: ['/c', 'npx', `auxilo-mcp@${version}`] }
+    : mcpEntry(version);
+  const result = runClaudeMcp(client, claudeAddArgs({ ...(opts.previousEntry || {}), ...target }), opts);
+  if (!result || result.error || result.status !== 0) {
+    return { changed: false, status: 'not-connected', failed: true, ...claudeMcpState(client, opts), configPath: client.configPath };
+  }
+  const state = claudeMcpState(client, opts, true);
+  if (state.registered && client.legacyConfigPath && fs.existsSync(client.legacyConfigPath)) {
+    const legacy = readClientConfig(client.legacyConfigPath);
+    const old = legacy.mcpServers && legacy.mcpServers.auxilo;
+    if (old && (old.command === 'npx' || old.command === 'cmd') && isOwnedMcpArgs(old.args)) {
+      delete legacy.mcpServers.auxilo;
+      writeJsonAtomic(client.legacyConfigPath, legacy);
+    }
+  }
+  return { changed: true, status: state.connection, ...state, configPath: client.configPath };
+}
+
+function rewriteClaudeMcpPin(client, version, opts) {
+  const previous = readClientConfig(client.configPath).mcpServers?.auxilo;
+  if (!previous || !['npx', 'cmd'].includes(previous.command) || !isOwnedMcpArgs(previous.args)) return unchangedResult(client.configPath);
+  if (parseMcpPin(previous.args) === version) return unchangedResult(client.configPath);
+  if (!claudeMcpState(client, opts).registered) return unchangedResult(client.configPath);
+  const removed = runClaudeMcp(client, ['mcp', 'remove', '--scope', 'user', 'auxilo'], opts);
+  if (!removed || removed.error || removed.status !== 0) return unchangedResult(client.configPath);
+  const result = registerClaudeMcp(client, version, { ...opts, previousEntry: previous });
+  if (result.failed) {
+    const restored = runClaudeMcp(client, claudeAddArgs(previous), opts);
+    const state = claudeMcpState(client, opts);
+    const preserved = Boolean(restored && !restored.error && restored.status === 0 && state.registered && state.mcpPin === parseMcpPin(previous.args));
+    return preserved
+      ? { ...unchangedResult(client.configPath), ...state, restored: true }
+      : { changed: true, status: 'error', failed: true, restored: false, ...state, configPath: client.configPath };
+  }
+  return result;
+}
+
 /** Result helpers shared by every registerMcp format writer. */
 function unchangedResult(configPath) {
   return { changed: false, status: 'already-registered', configPath };
@@ -633,10 +731,10 @@ function registeredResult(configPath) {
 function registerJsonMcpServers(client, version) {
   const config = readClientConfig(client.configPath);
   const existing = config.mcpServers && config.mcpServers.auxilo;
-  if (existing && !(existing.command === MCP_ENTRY.command && isOwnedMcpArgs(existing.args))) {
+  if (existing && !(['npx', 'cmd'].includes(existing.command) && isOwnedMcpArgs(existing.args))) {
     return unchangedResult(client.configPath); // foreign entry — never touch
   }
-  const target = mcpEntry(version);
+  const target = mcpEntry(version, client.platform);
   if (existing && existing.command === target.command &&
       JSON.stringify(existing.args) === JSON.stringify(target.args)) {
     return unchangedResult(client.configPath); // already pinned correctly
@@ -850,10 +948,11 @@ const MCP_WRITERS = Object.freeze({
  * @returns {{ changed: boolean, status: 'registered'|'already-registered', configPath: string }}
  * @throws on malformed existing JSON (B15 — caller skips that client loudly)
  */
-function registerMcp(client, version) {
+function registerMcp(client, version, opts = {}) {
   if (!client || !client.configPath) {
     throw new Error(`registerMcp: client ${client && client.id} has no MCP config path`);
   }
+  if (client.id === 'claude-code') return registerClaudeMcp(client, version || packageVersion(), opts);
   const writer = MCP_WRITERS[client.format || 'json-mcpServers'];
   if (!writer) {
     throw new Error(`registerMcp: client ${client.id} has unknown config format "${client.format}"`);
@@ -956,7 +1055,7 @@ function rewriteMcpPins(homeDir, version, opts = {}) {
   for (const client of detectClients(homeDir, opts).filter((c) => c.mcp)) {
     if (!mcpRegistrationPresent(client)) continue; // not already registered — never first-register here
     try {
-      const result = registerMcp(client, version);
+      const result = client.id === 'claude-code' ? rewriteClaudeMcpPin(client, version, opts) : registerMcp(client, version, opts);
       results.push({ id: client.id, name: client.name, ...result });
     } catch (err) {
       // B15 discipline: malformed config — skip loudly, never overwrite,
@@ -1062,23 +1161,30 @@ function writeRunnerConfig(homeDir, patch) {
 }
 
 /** Find the first regular executable in PATH, preserving its symlink path. */
-function findExecutableOnPath(name, envPath, fsImpl = fs) {
+function findExecutableOnPath(name, envPath, fsImpl = fs, opts = {}) {
   if (typeof envPath !== 'string' || !envPath) return null;
-  for (const dir of envPath.split(path.delimiter)) {
+  const windows = (opts.platform || process.platform) === 'win32';
+  const pathImpl = windows ? path.win32 : path;
+  const extensions = windows && !pathImpl.extname(name)
+    ? ((opts.env || process.env).PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+    : [''];
+  for (const dir of envPath.split(windows ? ';' : path.delimiter)) {
     if (!dir) continue;
-    const candidate = path.resolve(dir, name);
-    try {
-      if (!fsImpl.statSync(candidate).isFile()) continue;
-      fsImpl.accessSync(candidate, fs.constants.X_OK);
-      return candidate;
-    } catch (_) { /* missing, inaccessible or non-executable — try the next entry */ }
+    for (const extension of extensions) {
+      const candidate = pathImpl.resolve(dir, name + extension.toLowerCase());
+      try {
+        if (!fsImpl.statSync(candidate).isFile()) continue;
+        fsImpl.accessSync(candidate, windows ? fs.constants.F_OK : fs.constants.X_OK);
+        return candidate;
+      } catch (_) { /* try the next candidate */ }
+    }
   }
   return null;
 }
 
 /** Setup only: record the user's CLI and confirm the best-effort write persisted. */
-function recordClaudeBin(homeDir, envPath, fsImpl = fs) {
-  const bin = findExecutableOnPath('claude', envPath, fsImpl);
+function recordClaudeBin(homeDir, envPath, fsImpl = fs, opts = {}) {
+  const bin = findExecutableOnPath('claude', envPath, fsImpl, opts);
   if (bin === null) return null;
   writeRunnerConfig(homeDir, { claude_bin: bin });
   return readRunnerConfig(homeDir).claude_bin === bin ? bin : null;
@@ -1331,10 +1437,13 @@ function installRunner(homeDir, opts = {}) {
   // the WRITE TARGET (hookPath/versionPath below) follows binRoot, so a
   // staged build never touches the real bin root until the caller renames
   // the whole staged directory into place.
-  const hookPath = path.join(binRoot, path.basename(hookScriptPathFor(homeDir)));
-  fs.writeFileSync(hookPath, renderHookScript(homeDir));
-  fs.chmodSync(hookPath, 0o755);
-  installed.push(hookPath);
+  const hookPath = (opts.platform || process.platform) === 'win32'
+    ? path.join(binRoot, 'scripts', 'capture-core.js') : path.join(binRoot, path.basename(hookScriptPathFor(homeDir)));
+  if ((opts.platform || process.platform) !== 'win32') {
+    fs.writeFileSync(hookPath, renderHookScript(homeDir));
+    fs.chmodSync(hookPath, 0o755);
+    installed.push(hookPath);
+  }
 
   const version = packageVersion(packageRoot);
   const versionPath = path.join(binRoot, path.basename(runnerVersionPath(homeDir)));
@@ -1478,9 +1587,12 @@ function installRunnerAtomic(homeDir, opts = {}) {
   // pruneStaleStackFiles's doc comment.
   pruneStaleStackFiles(binRoot, installed);
 
-  const hookPath = path.join(binRoot, path.basename(hookScriptPathFor(homeDir)));
-  atomicWrite(hookPath, (tmp) => fs.writeFileSync(tmp, renderHookScript(homeDir)), 0o755);
-  installed.push(hookPath);
+  const hookPath = (opts.platform || process.platform) === 'win32'
+    ? path.join(binRoot, 'scripts', 'capture-core.js') : path.join(binRoot, path.basename(hookScriptPathFor(homeDir)));
+  if ((opts.platform || process.platform) !== 'win32') {
+    atomicWrite(hookPath, (tmp) => fs.writeFileSync(tmp, renderHookScript(homeDir)), 0o755);
+    installed.push(hookPath);
+  }
 
   const version = packageVersion(packageRoot);
   const versionPath = path.join(binRoot, path.basename(runnerVersionPath(homeDir)));
@@ -1534,10 +1646,15 @@ function runnerVersionSkew(homeDir, opts = {}) {
 
 // ─── Claude Code hook registration (spec §LW-12 step 4) ─────────────────────
 
+function nodeHookCommand(homeDir, script, source) {
+  const target = path.join(binRootFor(homeDir), 'scripts', script).replace(/\\/g, '/');
+  return `node "${target}"${source ? ` --source ${source}` : ''}`;
+}
+
 /** True when an inner hook object is an Auxilo extraction command. */
 function isAuxiloCommandHook(h) {
   return h && typeof h === 'object' && typeof h.command === 'string' &&
-    h.command.includes('auxilo-extract');
+    (h.command.includes('auxilo-extract') || isAuxiloNodeHook(h.command, 'capture-core.js', 'claude-code'));
 }
 
 /**
@@ -1558,10 +1675,10 @@ function isAuxiloCommandHook(h) {
  *
  * @returns {{ changed: boolean, hookCmd: string, removedLegacy: string[] }}
  */
-function registerClaudeCodeHook(homeDir) {
+function registerClaudeCodeHook(homeDir, opts = {}) {
   if (!homeDir) throw new Error('registerClaudeCodeHook: homeDir is required');
   const settingsPath = path.join(homeDir, '.claude', 'settings.json');
-  const hookCmd = hookScriptPathFor(homeDir);
+  const hookCmd = (opts.platform || process.platform) === 'win32' ? nodeHookCommand(homeDir, 'capture-core.js', 'claude-code') : hookScriptPathFor(homeDir);
 
   const settings = readClientConfig(settingsPath);
   if (!settings.hooks) settings.hooks = {};
@@ -1572,7 +1689,7 @@ function registerClaudeCodeHook(homeDir) {
   const kept = [];
 
   for (const entry of before) {
-    if (typeof entry === 'string' && entry.includes('auxilo-extract')) {
+    if (typeof entry === 'string' && isAuxiloCommandHook({ command: entry })) {
       removedLegacy.push(entry); // includes 0.8.1's dead bare-string entry
       continue;
     }
@@ -1632,7 +1749,7 @@ function removeClaudeCodeHook(homeDir) {
   const removed = [];
   const kept = [];
   for (const entry of settings.hooks.SessionEnd) {
-    if (typeof entry === 'string' && entry.includes('auxilo-extract')) {
+    if (typeof entry === 'string' && isAuxiloCommandHook({ command: entry })) {
       removed.push(entry);
       continue;
     }
@@ -1711,7 +1828,7 @@ function writeCaptureShim(homeDir, sourceId) {
 
 /** True when an entry's command string references an Auxilo capture shim. */
 function isAuxiloCaptureCommand(cmd) {
-  return typeof cmd === 'string' && cmd.includes('auxilo-capture');
+  return typeof cmd === 'string' && (cmd.includes('auxilo-capture') || isAuxiloNodeHook(cmd, 'capture-core.js', true));
 }
 
 /**
@@ -1870,7 +1987,7 @@ const CAPTURE_WRITERS = Object.freeze({
  * @returns {{ changed: boolean, hookPath: string, configPath: string, notes?: string }}
  * @throws on malformed existing hook config JSON (B15 — caller skips loudly)
  */
-function registerCaptureHook(client, homeDir) {
+function registerCaptureHook(client, homeDir, opts = {}) {
   if (!homeDir) throw new Error('registerCaptureHook: homeDir is required');
   if (!client || !client.captureHook || !client.captureConfigPath) {
     throw new Error(`registerCaptureHook: client ${client && client.id} has no capture-hook support`);
@@ -1880,13 +1997,14 @@ function registerCaptureHook(client, homeDir) {
     throw new Error(`registerCaptureHook: no capture writer for client "${client.id}"`);
   }
   const sourceId = client.sourceId || client.id;
-  const shimPath = captureShimPath(homeDir, sourceId);
+  const windows = (opts.platform || client.platform || process.platform) === 'win32';
+  const shimPath = windows ? nodeHookCommand(homeDir, 'capture-core.js', sourceId) : captureShimPath(homeDir, sourceId);
 
   // Codex skip-gotcha must not leave a dangling shim behind — let the writer
   // decide first, then write the shim only when the hook is actually wired.
   const result = writer(client, homeDir, shimPath);
   let shimChanged = false;
-  if (!(client.id === 'codex' && result.changed === false &&
+  if (!windows && !(client.id === 'codex' && result.changed === false &&
         result.notes && result.notes.includes('config.toml already defines hooks'))) {
     shimChanged = writeCaptureShim(homeDir, sourceId);
   }
@@ -1904,15 +2022,18 @@ function registerCaptureHook(client, homeDir) {
  * registered when the shim file exists AND the hook config references it.
  * Never throws (missing/malformed config reads as "not registered").
  */
-function captureHookRegistered(client, homeDir) {
+function captureHookRegistered(client, homeDir, opts = {}) {
   if (!client || !client.captureHook || !client.captureConfigPath) return false;
-  const shimPath = captureShimPath(homeDir, client.sourceId || client.id);
+  const source = client.sourceId || client.id;
+  const shimPath = captureShimPath(homeDir, source);
+  const nodeCommand = nodeHookCommand(homeDir, 'capture-core.js', source);
+  const includes = (value, target) => typeof value === 'string' ? value === target :
+    value && typeof value === 'object' && Object.values(value).some(child => includes(child, target));
   try {
-    return fs.existsSync(shimPath) &&
-      fs.readFileSync(client.captureConfigPath, 'utf-8').includes(shimPath);
-  } catch {
-    return false;
-  }
+    const config = JSON.parse(fs.readFileSync(client.captureConfigPath, 'utf8'));
+    return (fs.existsSync(shimPath) && includes(config, shimPath)) ||
+      (fs.existsSync(path.join(binRootFor(homeDir), 'scripts', 'capture-core.js')) && includes(config, nodeCommand));
+  } catch { return false; }
 }
 
 /**
@@ -1949,7 +2070,7 @@ function installCaptureHooks(homeDir, clients, opts = {}) {
 
   for (const client of targets) {
     try {
-      const r = registerCaptureHook(client, homeDir);
+      const r = registerCaptureHook(client, homeDir, opts);
       results.push({ id: client.id, name: client.name, event: client.captureEvent, ...r });
     } catch (err) {
       // B15 skip-loudly: collect the error, keep going for the other clients.
@@ -2071,7 +2192,7 @@ function noticeShimPath(homeDir) {
 
 /** Marker every notice entry carries (registration + removal + status probe). */
 function isAuxiloNoticeCommand(cmd) {
-  return typeof cmd === 'string' && cmd.includes('auxilo-review-notice');
+  return typeof cmd === 'string' && (cmd.includes('auxilo-review-notice') || isAuxiloNodeHook(cmd, 'review-notice.js'));
 }
 
 /** Generate the notice shim body (fail-silent: always exits 0). */
@@ -2096,15 +2217,16 @@ exit 0
  *
  * @returns {{ changed: boolean, hookCmd: string }}
  */
-function registerClaudeCodeSessionStartNotice(homeDir) {
+function registerClaudeCodeSessionStartNotice(homeDir, opts = {}) {
   if (!homeDir) throw new Error('registerClaudeCodeSessionStartNotice: homeDir is required');
   const settingsPath = path.join(homeDir, '.claude', 'settings.json');
-  const hookCmd = noticeShimPath(homeDir);
+  const windows = (opts.platform || process.platform) === 'win32';
+  const hookCmd = windows ? nodeHookCommand(homeDir, 'review-notice.js') : noticeShimPath(homeDir);
 
   // Shim first (its own idempotency: rewritten only when stale).
   const body = renderNoticeShim(homeDir);
   let shimChanged = false;
-  if (!fs.existsSync(hookCmd) || fs.readFileSync(hookCmd, 'utf-8') !== body) {
+  if (!windows && (!fs.existsSync(hookCmd) || fs.readFileSync(hookCmd, 'utf-8') !== body)) {
     fs.mkdirSync(path.dirname(hookCmd), { recursive: true });
     fs.writeFileSync(hookCmd, body);
     fs.chmodSync(hookCmd, 0o755);
@@ -2146,9 +2268,9 @@ function registerClaudeCodeSessionStartNotice(homeDir) {
  * Read-only probe for `auxilo status`: notice counts as registered when the
  * shim exists AND a STRUCTURED SessionStart entry references it. Never throws.
  */
-function sessionStartNoticeRegistered(homeDir) {
+function sessionStartNoticeRegistered(homeDir, opts = {}) {
   try {
-    if (!fs.existsSync(noticeShimPath(homeDir))) return false;
+    if (!fs.existsSync(noticeShimPath(homeDir)) && !fs.existsSync(path.join(binRootFor(homeDir), 'scripts', 'review-notice.js'))) return false;
     const settings = JSON.parse(
       fs.readFileSync(path.join(homeDir, '.claude', 'settings.json'), 'utf-8')
     );
@@ -2244,10 +2366,11 @@ async function getStatus(homeDir, opts = {}) {
   // 1. Clients: detected + whether MCP registration is present
   const clients = detectClients(homeDir, opts).map((c) => {
     // null = not applicable (no MCP config); per-format probe otherwise (UC-0).
-    const registered = c.mcp ? mcpRegistrationPresent(c) : null;
-    const base = { id: c.id, name: c.name, mcp: c.mcp, registered };
+    const cc = c.id === 'claude-code' ? claudeMcpState(c, opts) : null;
+    const registered = cc ? cc.registered : c.mcp ? mcpRegistrationPresent(c) : null;
+    const base = { id: c.id, name: c.name, mcp: c.mcp, registered, ...(cc || {}) };
     if (c.mcp && registered) {
-      const pin = mcpPinnedVersion(c);
+      const pin = cc ? cc.mcpPin : mcpPinnedVersion(c);
       base.mcpPin = pin; // exact version string, 'unpinned' (legacy), or null (foreign entry)
       base.mcpPinStale = Boolean(pin && pin !== 'unpinned' && runnerVersion && pin !== runnerVersion);
     }
@@ -2284,7 +2407,7 @@ async function getStatus(homeDir, opts = {}) {
   }
 
   // 4. Sentinel + runner + hook install state
-  const hookPath = hookScriptPathFor(homeDir);
+  const hookPath = (opts.platform || process.platform) === 'win32' ? path.join(binRootFor(homeDir), 'scripts', 'capture-core.js') : hookScriptPathFor(homeDir);
   const runnerInstalled = fs.existsSync(path.join(binRootFor(homeDir), 'scripts', 'runner.js'));
   let hookInstalled = false;
   let hookRegistered = false;
@@ -2416,6 +2539,10 @@ module.exports = {
   detectClients,
   clientHasCaptureHookMode,
   registerMcp,
+  nodeHookCommand,
+  claudeMcpState,
+  claudeMcpCommand,
+  claudeMcpStatusLine,
   mcpRegistrationPresent,
   mcpPinnedVersion,
   rewriteMcpPins,

package/lib/review.js

@@ -48,7 +48,7 @@ async function fetchPending(opts = {}) {
 
   const res = await fetchImpl(`${baseUrl}/account/pending${suffix}`, {
     method: 'GET',
-    headers: { 'X-API-Key': apiKey },
+    headers: { 'X-API-Key': apiKey, 'X-Auxilo-Client': `cli/${require('../package.json').version}` },
   });
   let body = {};
   try { body = await res.json(); } catch { /* non-JSON error body */ }
@@ -82,7 +82,7 @@ async function submitDecision(opts = {}) {
 
   const init = {
     method: 'POST',
-    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
+    headers: { 'X-API-Key': apiKey, 'X-Auxilo-Client': `cli/${require('../package.json').version}`, 'Content-Type': 'application/json' },
   };
   // reject accepts an optional reason; approve takes no body.
   if (decision === 'reject') {
@@ -154,7 +154,7 @@ async function fetchPendingSummary(opts = {}) {
 
   const res = await fetchImpl(`${baseUrl}/account/pending/summary`, {
     method: 'GET',
-    headers: { 'X-API-Key': apiKey },
+    headers: { 'X-API-Key': apiKey, 'X-Auxilo-Client': `cli/${require('../package.json').version}` },
   });
   let body = {};
   try { body = await res.json(); } catch { /* non-JSON error body */ }
@@ -188,7 +188,7 @@ async function submitBulk(opts = {}) {
 
   const res = await fetchImpl(`${baseUrl}/account/pending/bulk`, {
     method: 'POST',
-    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
+    headers: { 'X-API-Key': apiKey, 'X-Auxilo-Client': `cli/${require('../package.json').version}`, 'Content-Type': 'application/json' },
     body: JSON.stringify({ decisions, confirm_count: decisions.length }),
   });
   let body = {};

package/lib/runner-autoupdate.js

@@ -626,7 +626,7 @@ function stageAndSwap(homeDir, extractedPackageDir, installer) {
   // fixture's minimal installer stub) simply skips the rewrite.
   if (typeof extractedInstaller.rewriteMcpPins === 'function') {
     try {
-      extractedInstaller.rewriteMcpPins(homeDir, result.version);
+      extractedInstaller.rewriteMcpPins(homeDir, result.version, { commandRunner: require('child_process').spawnSync });
     } catch { /* best-effort — the runner swap itself already succeeded */ }
   }
 

package/mcp-server.js

@@ -198,7 +198,7 @@ async function postBulkChunks(headers, decisions) {
 }
 
 const server = new Server(
-  { name: 'auxilo', version: '0.9.27' },
+  { name: 'auxilo', version: '0.9.29' },
   {
     capabilities: { tools: {} },
     instructions: `You are connected to Auxilo, a knowledge marketplace where AI agents buy and sell operational learnings.
@@ -687,6 +687,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const headers = baseHeaders(
           args.session_token ? { 'Authorization': `Bearer ${args.session_token}` } : {}
         );
+        headers['X-Auxilo-Client'] = `mcp/${require('./package.json').version}`;
 
         if (args.action === 'list') {
           const resp = await fetch(`${AUXILO_BASE}/account/pending/summary`, { headers });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auxilo-mcp",
-  "version": "0.9.27",
+  "version": "0.9.29",
   "mcpName": "io.github.silent-architects/auxilo",
   "description": "MCP server for Auxilo. Your agent stops solving the same problem twice: auto-extracted learnings, free self-unlocks, and earnings when other agents unlock yours.",
   "main": "mcp-server.js",

package/scripts/capture-core.js

@@ -99,12 +99,17 @@ function transcriptRoots(homeDir) {
 /** True iff realPath sits under a known transcript root AND has a text extension.
  *  Roots are symlink-resolved too, so the comparison is realpath-vs-realpath
  *  (macOS /var → /private/var would otherwise defeat a correct path). */
-function transcriptPathAllowed(realPath, homeDir) {
+function transcriptPathAllowed(realPath, homeDir, opts = {}) {
+  const windows = (opts.platform || process.platform) === 'win32';
+  const normalize = value => windows ? value.replace(/\\/g, '/').toLowerCase() : value;
+  const realpath = opts.realpathSync || (windows ? fs.realpathSync.native : fs.realpathSync);
+  const candidate = normalize(realPath);
   if (!TRANSCRIPT_EXTS.includes(path.extname(realPath).toLowerCase())) return false;
   return transcriptRoots(homeDir).some((root) => {
     let realRoot = root;
-    try { realRoot = fs.realpathSync(root); } catch { /* root may not exist yet */ }
-    return realPath === realRoot || realPath.startsWith(realRoot + path.sep);
+    try { realRoot = realpath(root); } catch { /* root may not exist yet */ }
+    realRoot = normalize(realRoot);
+    return candidate === realRoot || candidate.startsWith(realRoot + (windows ? '/' : path.sep));
   });
 }
 
@@ -146,9 +151,13 @@ function readStdin() {
   });
 }
 
+function captureHome(platform = process.platform, env = process.env, homedir = os.homedir) {
+  return platform === 'win32' ? homedir() : env.HOME || homedir();
+}
+
 async function main() {
   const args = parseArgs(process.argv);
-  const homeDir = args.home || process.env.HOME || os.homedir();
+  const homeDir = args.home || captureHome();
   const auxiloDir = path.join(homeDir, '.auxilo');
 
   // 1. Consent sentinel — kill-switch shared by every capture class (UC §6).
@@ -167,7 +176,7 @@ async function main() {
   // GOV-3 M4: resolve symlinks BEFORE validating, and use the resolved path
   // from here on — a symlink under an allowed root must not reach outside it.
   let transcriptPath;
-  try { transcriptPath = fs.realpathSync(namedPath); } catch { return; }
+  try { transcriptPath = (process.platform === 'win32' ? fs.realpathSync.native : fs.realpathSync)(namedPath); } catch { return; }
   if (!transcriptPathAllowed(transcriptPath, homeDir)) return;
 
   let stat;
@@ -193,7 +202,7 @@ async function main() {
 
   const child = spawn(process.execPath,
     [runnerPath, '--transcript', transcriptPath, '--source', args.source],
-    { detached: true, stdio: ['ignore', 'ignore', stderrFd], env });
+    { detached: true, stdio: ['ignore', 'ignore', stderrFd], env, ...(process.platform === 'win32' ? { windowsHide: true } : {}) });
   child.on('error', () => { /* fail-silent */ });
   child.unref();
 
@@ -204,6 +213,7 @@ async function main() {
 
 module.exports = {
   parseArgs,
+  captureHome,
   extractTranscriptPath,
   transcriptPathAllowed,
   transcriptRoots,

package/scripts/providers/byo-key.js

@@ -314,11 +314,33 @@ function baseUrlFor(vendor, configured) {
  * than silently trusting a permission state it could not verify. Never
  * throws.
  */
+function providersFileInsideProfile(target, opts = {}) {
+  const profile = opts.homeDir || (opts.env || process.env).USERPROFILE || os.homedir();
+  const realpath = opts.realpathSyncImpl || fs.realpathSync.native;
+  try {
+    let current = target;
+    const suffix = [];
+    let realTarget;
+    for (;;) {
+      try { realTarget = path.join(realpath(current), ...suffix); break; }
+      catch (error) {
+        if (error.code !== 'ENOENT' || path.dirname(current) === current) return false;
+        suffix.unshift(path.basename(current));
+        current = path.dirname(current);
+      }
+    }
+    const root = realpath(profile).replace(/\\/g, '/').replace(/\/$/, '').toLowerCase();
+    const file = realTarget.replace(/\\/g, '/').toLowerCase();
+    return file.startsWith(root + '/');
+  } catch { return false; }
+}
+
 function isProvidersFileModeUnsafe(opts = {}) {
   // EXTRACTION-LOW-FOLLOWUPS item 2 (TOCTOU, accepted on the record): a
   // window exists between this check and readByoConfig()'s read below; only the same uid could win that race, and that uid already owns the key on disk, so it is accepted rather than replaced with an fd-based check-then-read.
   const target = statePath(opts);
   if (isHomeUnresolved(target)) return true; // can't even name the file — fail closed
+  if ((opts.platform || process.platform) === 'win32') return !providersFileInsideProfile(target, opts);
   const statSyncImpl = typeof opts.statSyncImpl === 'function' ? opts.statSyncImpl : fs.statSync;
   let stat;
   try {
@@ -551,7 +573,7 @@ async function runModel(opts = {}) {
       ok: false,
       text: '',
       usage: null,
-      reason: '~/.auxilo/providers.json is not owner-read-only; refusing to use the stored key until its permissions are fixed (chmod 600 ~/.auxilo/providers.json) or the file is removed (`auxilo provider clear`)',
+      reason: (opts.platform || process.platform) === 'win32' ? 'The provider key file must be inside your Windows user profile folder.' : '~/.auxilo/providers.json is not owner-read-only; refusing to use the stored key until its permissions are fixed (chmod 600 ~/.auxilo/providers.json) or the file is removed (`auxilo provider clear`)',
       reasonCode: 'providers-file-mode-unsafe',
       refusal: 'pre-invocation',
       authStatus: 'unknown',
@@ -712,6 +734,7 @@ module.exports = {
   // isProvidersFileModeUnsafe before trusting a persisted `selected` value
   // it reads (GOV-3 item 2, "read too, not just write").
   isProvidersFileModeUnsafe,
+  providersFileInsideProfile,
   isHomeUnresolved,
   isBaseUrlInsecure,
   writeProvidersStateAtomic,

package/scripts/providers/claude-code.js

@@ -41,7 +41,13 @@ function resolveClaudeBin(opts = {}) {
   const homeDir = typeof opts.homeDir === 'string' ? opts.homeDir : os.homedir();
   const existsSync = typeof opts.existsSync === 'function' ? opts.existsSync : fs.existsSync;
   const readFileSyncImpl = typeof opts.readFileSyncImpl === 'function' ? opts.readFileSyncImpl : fs.readFileSync;
-  const candidates = [
+  const windows = (opts.platform || process.platform) === 'win32';
+  const env = opts.env || process.env;
+  const candidates = windows ? [
+    path.join(homeDir, '.local', 'bin', 'claude.exe'),
+    path.join(env.APPDATA || path.join(homeDir, 'AppData', 'Roaming'), 'npm', 'claude.cmd'),
+    ...(env.PATH || '').split(';').filter(Boolean).flatMap(dir => (env.PATHEXT || '.EXE;.CMD').split(';').filter(Boolean).map(ext => path.join(dir, 'claude' + ext.toLowerCase()))),
+  ] : [
     path.join(homeDir, '.claude', 'local', 'claude'),
     '/usr/local/bin/claude',
     '/opt/homebrew/bin/claude',
@@ -52,7 +58,7 @@ function resolveClaudeBin(opts = {}) {
   try {
     const config = JSON.parse(readFileSyncImpl(path.join(homeDir, '.auxilo', 'runner-config.json'), 'utf8'));
     const recorded = config && config.claude_bin;
-    if (typeof recorded === 'string' && path.isAbsolute(recorded) && path.basename(recorded) === 'claude') {
+    if (typeof recorded === 'string' && path.isAbsolute(recorded) && (windows ? /^claude\.(exe|cmd)$/i.test(path.basename(recorded)) : path.basename(recorded) === 'claude')) {
       candidates.unshift(recorded);
     }
   } catch (_) { /* missing/malformed config means no recorded candidate */ }
@@ -75,6 +81,14 @@ function resolveClaudeBin(opts = {}) {
   return newest || firstExisting || 'claude';
 }
 
+/** Resolve npm command shims without invoking a shell or the shim itself. */
+function claudeSpawnTarget(bin, opts = {}) {
+  if ((opts.platform || process.platform) !== 'win32' || !/\.cmd$/i.test(bin)) return { command: bin, prefix: [] };
+  const cli = path.join(path.dirname(bin), 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js');
+  const exists = opts.existsSync || fs.existsSync;
+  return exists(cli) ? { command: process.execPath, prefix: [cli] } : null;
+}
+
 // ─── Child settings/hooks isolation (EXTRACTION-CHILD-HOOKS, PUNCH-LIST P1,
 // 0.9.15) ────────────────────────────────────────────────────────────────
 //
@@ -154,7 +168,9 @@ function getClaudeCliVersion(bin, opts = {}) {
   const realpathSyncImpl = typeof opts.realpathSyncImpl === 'function' ? opts.realpathSyncImpl : fs.realpathSync;
   const readFileSyncImpl = typeof opts.readFileSyncImpl === 'function' ? opts.readFileSyncImpl : fs.readFileSync;
   try {
-    const real = realpathSyncImpl(bin);
+    const target = claudeSpawnTarget(bin, opts);
+    if (!target) return null;
+    const real = realpathSyncImpl(target.prefix[0] || target.command);
     const dir = path.dirname(real);
     for (const [pkgDir, requireName] of [[dir, false], [path.dirname(dir), true]]) {
       try {
@@ -402,12 +418,15 @@ function detectBillingHelperConfigured(opts = {}) {
 function checkAuthStatus(opts = {}) {
   const spawnSyncImpl = typeof opts.spawnSyncImpl === 'function' ? opts.spawnSyncImpl : spawnSync;
   const bin = typeof opts.claudeBin === 'string' ? opts.claudeBin : resolveClaudeBin(opts);
+  const target = claudeSpawnTarget(bin, opts);
+  if (!target) return 'unknown';
   const version = versionParts(getClaudeCliVersion(bin, opts));
   // Unknown and old versions can interpret this probe as a model prompt.
   if (!version || compareVersions(version, [2, 1, 41]) < 0) return 'unknown';
   let res;
   try {
-    res = spawnSyncImpl(bin, ['auth', 'status'], {
+    res = spawnSyncImpl(target.command, [...target.prefix, 'auth', 'status'], {
+      ...((opts.platform || process.platform) === 'win32' ? { windowsHide: true } : {}),
       encoding: 'utf-8',
       env: claudeChildEnv(),
       timeout: 5000,
@@ -446,6 +465,7 @@ function checkAuthStatus(opts = {}) {
 function detect(opts = {}) {
   if (detectBillingHelperConfigured(opts)) return false;
   const bin = resolveClaudeBin(opts);
+  if (!claudeSpawnTarget(bin, opts)) return false;
   const status = checkAuthStatus({ ...opts, claudeBin: bin });
   return status === 'logged-in' || status === 'unknown';
 }
@@ -516,9 +536,15 @@ function wrapperIdentity(wrapper, cliVersion) {
     ...(observed === null && { identity_unresolved: models.length ? 'ambiguous' : 'missing' }) };
 }
 
+// Exact production CLI wording (verified 2026-09-27..10-01). Add another alternative only for
+// another CONFIRMED real CLI message, never a guessed synonym.
+const OAUTH_EXPIRED_PATTERN = /Failed to authenticate:\s*OAuth session expired and could not be refreshed/i;
+
 function runCliMode(opts, mode) {
   const spawn = typeof opts.spawnSyncImpl === 'function' ? opts.spawnSyncImpl : spawnSync;
   const bin = typeof opts.claudeBin === 'string' ? opts.claudeBin : resolveClaudeBin(opts);
+  const target = claudeSpawnTarget(bin, opts);
+  if (!target) return { ok: false, text: '', usage: null, reasonCode: 'cli-not-installed', reason: 'local model invocation failed', refusal: 'pre-invocation', authStatus: 'unknown' };
   if (cachedSettingSourcesUnsupported) return { ...settingSourcesIsolationUnsupportedResult('unknown'), refusal: 'pre-invocation' };
   const authStatus = mode === 'extract' ? checkAuthStatus({ ...opts, claudeBin: bin }) : 'unknown';
   const authReason = 'local model not authenticated in this context (run `claude auth login` once); skipping deterministic extraction';
@@ -532,7 +558,8 @@ function runCliMode(opts, mode) {
   if (gate) return { ...gate, ...meta };
   let res;
   try {
-    res = spawn(bin, argv, {
+    res = spawn(target.command, [...target.prefix, ...argv], {
+      ...((opts.platform || process.platform) === 'win32' ? { windowsHide: true } : {}),
       input: (typeof opts.prompt === 'string' ? opts.prompt : '') + (mode === 'extract' ? String(opts.input || '').slice(0, 200000) : ''),
       encoding: 'utf-8', env: claudeChildEnv(), timeout: opts.timeoutMs || 120000, maxBuffer: 20 * 1024 * 1024,
     });
@@ -552,6 +579,14 @@ function runCliMode(opts, mode) {
   if ((!decoded.wrapper && authPattern.test(stdout)) || authPattern.test(String(res.stderr || ''))) {
     return { ...fail('cli-unauthenticated', authReason), ...(authStatus === 'logged-in' && { authDiscrepancy: true }) };
   }
+  // EXT-0806c: an expired, unrefreshable OAuth session exits nonzero with this exact CLI
+  // message on either stream. Nonzero exit only, and stdout only when no result wrapper
+  // decoded, so a successful run whose own text discusses an auth bug never matches. Like
+  // the check above it is a post-spawn outcome: no `refusal`, so it never permits fallback.
+  if (Number.isInteger(res.status) && res.status !== 0
+    && ((!decoded.wrapper && OAUTH_EXPIRED_PATTERN.test(stdout)) || OAUTH_EXPIRED_PATTERN.test(String(res.stderr || '')))) {
+    return { ...fail('cli-unauthenticated', authReason), ...(authStatus === 'logged-in' && { authDiscrepancy: true }) };
+  }
   if (res.status !== 0) return fail('model-error', 'local model exited unsuccessfully');
   if (decoded.malformed) return fail('model-error', mode === 'judge' ? 'local judge returned malformed JSON wrapper' : 'local model returned malformed JSON wrapper');
   if (decoded.unsuccessful) return fail('model-error', 'local model returned no successful result');
@@ -654,6 +689,7 @@ module.exports = {
   extractWithClaudeCode,
   checkClaudeAuthStatus,
   resolveClaudeBin,
+  claudeSpawnTarget,
   // Exported for direct unit coverage (test/claude-code-provider.test.js) and for
   // bin/auxilo-cli.js's cmdStatus provider line.
   claudeChildEnv,
@@ -676,4 +712,5 @@ module.exports = {
   getClaudeCliVersion,
   looksLikeUnsupportedSettingSourcesFlag,
   _resetSettingSourcesCacheForTests,
+  OAUTH_EXPIRED_PATTERN,
 };

package/scripts/providers/index.js

@@ -366,6 +366,7 @@ async function runModel(opts = {}) {
   const order = [record.route, ...AUTOMATIC_PROVIDER_ORDER.filter(id =>
     (id !== record.route || record.route === 'byo-key') && (id !== 'byo-key' || configuredByo))];
   const attempts = [];
+  let firstFailure = null;
   for (const id of order) {
     if (id !== store.record.route) {
       const updated = store.mutate(routeMetadata(id, opts, 'auto'));
@@ -394,6 +395,7 @@ async function runModel(opts = {}) {
       if (standalone) result = { ...result, ...finishJob(context) };
       return result;
     }
+    if (!attempts.length) firstFailure = result;
     attempts.push(id + '=' + (NON_RETRYABLE_FOR_THIS_PROVIDER.has(result.reasonCode) ? result.reasonCode : 'unavailable'));
     if (result.refusal !== 'pre-invocation' || !store.canFallback()) {
       const release = store.hold('pinned-route-unusable');
@@ -405,7 +407,13 @@ async function runModel(opts = {}) {
   const released = store.hold('pinned-route-unusable');
   context.hold = released.hold || 'pinned-route-unusable';
   if (!configuredByo && !attempts.some(attempt => attempt.startsWith('byo-key='))) attempts.push('byo-key=provider-not-configured');
-  return { ok: false, text: '', usage: null, authStatus: 'unknown', reasonCode: 'no-usable-provider',
+  // EXT-0806c: a generic 'no-usable-provider' reads as UNKNOWN downstream and never alerts. When the
+  // first-choice provider was refused for an unauthenticated CLI, the chain already knows the
+  // actionable cause, so surface it; the attempts list stays in `reason`. Read from the first
+  // attempt's result object, never from the attempts strings.
+  const unauthenticated = Boolean(firstFailure) && firstFailure.reasonCode === 'cli-unauthenticated';
+  return { ok: false, text: '', usage: null, authStatus: unauthenticated ? 'logged-out' : 'unknown',
+    reasonCode: unauthenticated ? 'cli-unauthenticated' : 'no-usable-provider',
     reason: 'no usable extraction provider (tried: ' + attempts.join('; ') + ')', hold: context.hold };
 }
 

package/scripts/review-notice.js

@@ -90,7 +90,7 @@ function writeState(homeDir, now = Date.now()) {
 
 /** The one line. Count only — see the header contract. */
 function renderNotice(count) {
-  return `Auxilo: ${count} learning(s) held for your review — run auxilo_review (MCP) or \`npx auxilo review\`.`;
+  return `Auxilo: ${count} ${count === 1 ? 'learning is' : 'learnings are'} waiting for your review. Run auxilo_review (MCP) or \`npx auxilo review\`.`;
 }
 
 /**

package/scripts/runner.js

@@ -364,10 +364,11 @@ async function finalizeExtractionRun(outcomes, opts = {}) {
     : loadExtractionSkipState(opts);
   if (rows.length === 0) return state;
 
-  // A completed real result or a concrete model/API failure proves the local
-  // model was attempted. Either resets both visibility streaks.
-  const resetsAuthStreak = rows.some((row) => !isSkippedExtraction(row)
-    || row.reasonCode === 'model-error');
+  // Only a completed real extraction (a row that is not a skipped extraction)
+  // resets both visibility streaks. A 'model-error' skip is counted as an
+  // unknown skip, never a reset: an expired-OAuth outage once classified as
+  // model-error reset its own alarm on every sweep (EXT-0806c).
+  const resetsAuthStreak = rows.some((row) => !isSkippedExtraction(row));
   if (resetsAuthStreak) {
     const reset = {
       ...zeroExtractionSkipState(),
@@ -383,8 +384,7 @@ async function finalizeExtractionRun(outcomes, opts = {}) {
   const hasUnauthenticated = rows.some((row) => isSkippedExtraction(row)
     && row.reasonCode === 'cli-unauthenticated');
   if (!hasUnauthenticated) {
-    const hasUnknown = rows.some((row) => isSkippedExtraction(row)
-      && row.reasonCode !== 'model-error');
+    const hasUnknown = rows.some((row) => isSkippedExtraction(row));
     if (!hasUnknown) return state;
     const unknown = {
       ...state,
@@ -764,17 +764,21 @@ function renderExtractionResult(detailed, opts = {}) {
  * swallowed; a broken notifier must never fail the run. AUXILO_NO_NOTIFY=1
  * disables (tests, headless CI).
  */
-function notifyHeld(count) {
+function notifyHeld(count, opts = {}) {
   try {
-    if (!count || count <= 0) return;
-    if (process.platform !== 'darwin') return;
-    if (process.env.AUXILO_NO_NOTIFY === '1') return;
-    const msg = `${count} learning(s) held for your review — run npx auxilo review`;
-    const child = spawn('/usr/bin/osascript', [
-      '-e', `display notification ${JSON.stringify(msg)} with title "Auxilo"`,
-    ], { stdio: 'ignore', detached: true });
-    child.unref();
+    if (!Number.isSafeInteger(count) || count <= 0) return;
+    const platform = opts.platform || process.platform;
+    if (!['darwin', 'win32'].includes(platform)) return;
+    if ((opts.env || process.env).AUXILO_NO_NOTIFY === '1') return;
+    const msg = `${count} ${count === 1 ? 'learning is' : 'learnings are'} waiting for your review. Run npx auxilo review`;
+    const spawnImpl = opts.spawnImpl || spawn;
+    const child = platform === 'win32'
+      ? spawnImpl('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command',
+        `Add-Type -AssemblyName System.Windows.Forms; $n = New-Object System.Windows.Forms.NotifyIcon; $n.Icon = [System.Drawing.SystemIcons]::Information; $n.Visible = $true; $n.ShowBalloonTip(10000, 'Auxilo', '${msg}', [System.Windows.Forms.ToolTipIcon]::Info); Start-Sleep -Seconds 10; $n.Dispose()`],
+      { stdio: 'ignore', detached: true, windowsHide: true })
+      : spawnImpl('/usr/bin/osascript', ['-e', `display notification ${JSON.stringify(msg)} with title "Auxilo"`], { stdio: 'ignore', detached: true });
     child.on('error', () => { /* fail-silent */ });
+    child.unref();
   } catch { /* fail-silent */ }
 }
 
@@ -1066,6 +1070,8 @@ function installDigest() {
 
 // ─── Status (B14) ───────────────────────────────────────────────────────────
 
+const EXTRACTION_STALE_MS = 48 * 60 * 60 * 1000;
+
 function renderExtractionStatus(opts = {}) {
   const state = normalizeExtractionSkipState(opts.state) || zeroExtractionSkipState();
   const ledger = opts.ledger && typeof opts.ledger === 'object' ? opts.ledger : {};
@@ -1086,19 +1092,28 @@ function renderExtractionStatus(opts = {}) {
 
   const timestamp = ledger.lastRealExtractionAt;
   if (typeof timestamp === 'string' && isCanonicalIsoTimestamp(timestamp)) {
+    const rawNow = typeof opts.now === 'function' ? opts.now() : opts.now;
+    const nowMs = rawNow === undefined ? Date.now()
+      : rawNow instanceof Date ? rawNow.getTime()
+        : typeof rawNow === 'string' ? Date.parse(rawNow) : Number(rawNow);
+    const ageMs = nowMs - Date.parse(timestamp);
+    if (Number.isFinite(ageMs) && ageMs > EXTRACTION_STALE_MS) {
+      return `Extraction: STALE (no real extraction for ${Math.floor(ageMs / 3600000)}h, last ${timestamp}). ` +
+        'Run `claude auth login` and check extract.log';
+    }
     return `Extraction: OK (last real extraction ${timestamp})`;
   }
   return 'Extraction: OK (last real extraction unavailable)';
 }
 
-function currentExtractionStatusLine(ledger) {
+function currentExtractionStatusLine(ledger, now) {
   const state = loadExtractionSkipState();
   let authStatus = 'unknown';
   try {
     const { checkClaudeAuthStatus } = require('./extract-local.js');
     authStatus = checkClaudeAuthStatus();
   } catch { /* missing/broken local CLI state is UNKNOWN, never authenticated */ }
-  return renderExtractionStatus({ state, ledger, authStatus });
+  return renderExtractionStatus({ state, ledger, authStatus, now });
 }
 
 async function printStatus() {
@@ -1146,7 +1161,7 @@ async function printStatus() {
   console.log(`Pending queue: ${pendingCount} file(s)`);
 
   // 7. Extraction health — durable skip state plus the authoritative CLI auth probe.
-  console.log(currentExtractionStatusLine(ledger));
+  console.log(currentExtractionStatusLine(ledger, Date.now()));
 }
 
 // ─── Scrub + Verify ─────────────────────────────────────────────────────────