agent-tank 0.9.1 → 0.9.3

package/bin/agent-tank.js

@@ -3,6 +3,8 @@
 
 const { parseArgs } = require('node:util');
 const { AgentTank } = require('../src/index.js');
+const { installShutdownHandlers } = require('../src/shutdown-handler.js');
+const pkg = require('../package.json');
 
 const options = {
   claude: { type: 'boolean', default: false },
@@ -17,6 +19,7 @@ const options = {
   'fresh-process': { type: 'boolean', default: false },
   config: { type: 'string', short: 'c' },
   help: { type: 'boolean', short: 'h', default: false },
+  version: { type: 'boolean', short: 'v', default: false },
   'auto-discover': { type: 'boolean', default: true },
   'auto-refresh': { type: 'boolean', default: true },
   'auto-refresh-interval': { type: 'string', default: '60' },
@@ -56,6 +59,7 @@ Options:
   --auth-token <token>  API key for Bearer token auth
   --fresh-process       Spawn a new process per refresh (default: false)
   --config, -c          Path to config file (JSON)
+  --version, -v         Show version
   --auto-discover       Auto-discover available agents (default: true)
   --auto-refresh        Enable/disable background auto-refresh (default: true)
   --auto-refresh-mode <mode>         Refresh mode: none, interval, activity (default: activity)
@@ -127,6 +131,12 @@ async function main() {
     return;
   }
 
+  if (values.version) {
+    process.stdout.write(`${pkg.version}\n`);
+    process.exitCode = 0;
+    return;
+  }
+
   // Load config file if specified
   let config = {};
   if (values.config) {
@@ -255,15 +265,19 @@ async function main() {
   });
 
   // Graceful shutdown
-  const shutdown = () => {
+  let shuttingDown = false;
+  let cleanupShutdownHandlers = () => {};
+  const shutdown = (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    cleanupShutdownHandlers();
     if (!jsonMode) {
-      originalLog('\nShutting down...');
+      originalLog(`\nShutting down${signal ? ` (${signal})` : ''}...`);
     }
     watcher.stop();
-    process.exitCode = 0;
+    process.exit(0);
   };
-  process.on('SIGINT', shutdown);
-  process.on('SIGTERM', shutdown);
+  cleanupShutdownHandlers = installShutdownHandlers({ shutdown });
 
   try {
     if (onceMode) {
@@ -281,6 +295,7 @@ async function main() {
           originalLog(JSON.stringify(agentStatus, null, 2));
         }
       }
+      cleanupShutdownHandlers();
       watcher.stop();
       process.exitCode = 0;
       return;
@@ -288,6 +303,7 @@ async function main() {
 
     await watcher.start();
   } catch (err) {
+    cleanupShutdownHandlers();
     if (jsonMode) {
       console.log = originalLog;
       console.log(JSON.stringify({ error: err.message }, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-tank",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Monitor and query usage limits for LLM CLI tools (Claude, Gemini, Codex) via HTTP API",
   "main": "src/index.js",
   "bin": {

package/src/agents/base.js

@@ -1,4 +1,5 @@
 const pty = require('node-pty');
+const process = require('node:process');
 const logger = require('../logger.js');
 
 class BaseAgent {
@@ -11,6 +12,7 @@ class BaseAgent {
     this._metadataFetched = false;
     this.lastUpdated = null;
     this.error = null;
+    this.auth = null;
     this.isRefreshing = false;
     this.refreshInterval = null;    // Per-agent override (seconds), null = use global
     this.minRefreshInterval = null; // Per-agent minimum (seconds), null = no minimum
@@ -23,6 +25,22 @@ class BaseAgent {
     this._onDataCallback = null;
     this._commandInFlight = false;
     this._disposables = [];
+    this._stopRequested = false;
+  }
+
+  _createStopError() {
+    return new Error('Agent stopping');
+  }
+
+  isStopping() {
+    return this._stopRequested;
+  }
+
+  requestStop() {
+    this._stopRequested = true;
+    this.isRefreshing = false;
+    this._commandInFlight = false;
+    this._onDataCallback = null;
   }
 
   getStatus() {
@@ -32,11 +50,17 @@ class BaseAgent {
       metadata: this.metadata,
       lastUpdated: this.lastUpdated,
       error: this.error,
+      auth: this.auth,
       isRefreshing: this.isRefreshing,
     };
   }
 
   async refresh() {
+    if (this.isStopping()) {
+      logger.agent(this.name, 'Skipping refresh while stopping');
+      return;
+    }
+
     if (this.isRefreshing) {
       logger.agent(this.name, 'Already refreshing, skipping...');
       return;
@@ -45,6 +69,7 @@ class BaseAgent {
     logger.agent(this.name, 'Starting refresh...');
     this.isRefreshing = true;
     this.error = null;
+    this.auth = null;
 
     try {
       // Fetch metadata once on first refresh (if agent supports it)
@@ -65,12 +90,25 @@ class BaseAgent {
         }
       }
 
+      if (this.isStopping()) {
+        throw this._createStopError();
+      }
+
       const output = await this.runCommand();
       logger.agent(this.name, 'Got output, length:', logger.dim(`${output.length} chars`));
 
       // Check for rate limit and session errors before parsing
       // Match actual error messages, not incidental mentions like "rate limits and credits"
       const cleanOutput = this.stripAnsi(output);
+      const authState = this.detectAuthenticationState ? this.detectAuthenticationState(cleanOutput) : null;
+      if (authState) {
+        logger.agent(this.name, 'Authentication issue detected:', logger.json(authState));
+        this.auth = authState;
+        this.error = this.usage ? `${authState.message} — using cached data` : authState.message;
+        this.lastUpdated = new Date().toISOString();
+        return;
+      }
+
       if (/rate.?limited|rate_limit_error/i.test(cleanOutput)) {
         logger.agent(this.name, 'Rate limited, preserving last known usage data');
         this.error = 'Rate limited — using cached data';
@@ -96,6 +134,10 @@ class BaseAgent {
       if (hasData) { this.usage = parsed; this.lastUpdated = new Date().toISOString(); } else if (this.usage) { logger.agent(this.name, 'Parse returned no data, preserving last known usage'); this.error = 'Failed to parse — using cached data'; } else { this.usage = parsed; this.lastUpdated = new Date().toISOString(); }
       logger.agent(this.name, 'Parsed usage:', logger.json(this.usage));
     } catch (err) {
+      if (this.isStopping() && err.message === 'Agent stopping') {
+        logger.agent(this.name, 'Refresh cancelled during shutdown');
+        return;
+      }
       logger.error(`[${this.name}] Error during refresh:`, err.message);
       this.error = err.message;
     } finally {
@@ -105,6 +147,10 @@ class BaseAgent {
   }
 
   async runCommand() {
+    if (this.isStopping()) {
+      throw this._createStopError();
+    }
+
     if (this.freshProcess) {
       return this._runCommandFresh();
     }
@@ -118,6 +164,10 @@ class BaseAgent {
   }
 
   async spawnProcess() {
+    if (this.isStopping()) {
+      throw this._createStopError();
+    }
+
     return new Promise((resolve, reject) => {
       let trustHandled = false;
       let spawnOutput = '';
@@ -133,6 +183,9 @@ class BaseAgent {
           cwd: '/tmp',
           env,
         });
+        if (typeof this.shell.pid === 'number') {
+          logger.agent(this.name, 'Persistent process pid:', logger.dim(String(this.shell.pid)));
+        }
       } catch (spawnErr) {
         logger.error(`[${this.name}] Failed to spawn:`, spawnErr.message);
         reject(new Error(`Failed to spawn ${this.command}: ${spawnErr.message}`));
@@ -140,6 +193,10 @@ class BaseAgent {
       }
 
       const timer = setTimeout(() => {
+        if (this.isStopping()) {
+          reject(this._createStopError());
+          return;
+        }
         logger.error(`[${this.name}] Spawn timeout after ${this.getTimeout()}ms`);
         this.killProcess();
         reject(new Error('Timeout waiting for process to become ready'));
@@ -147,6 +204,15 @@ class BaseAgent {
 
       let trustCooldownUntil = 0;
       const spawnDataHandler = this.shell.onData((data) => {
+        if (this.isStopping()) {
+          clearTimeout(timer);
+          spawnDataHandler.dispose();
+          spawnExitHandler.dispose();
+          this.killProcess();
+          reject(this._createStopError());
+          return;
+        }
+
         spawnOutput += data;
 
         // Handle trust/update prompts during spawn (only once each)
@@ -159,6 +225,20 @@ class BaseAgent {
         this._handleAdditionalPrompts(this.shell, data, spawnOutput);
         this._respondToTerminalQueries(data);
 
+        const authState = this.detectAuthenticationState ? this.detectAuthenticationState(spawnOutput) : null;
+        if (authState) {
+          logger.agent(this.name, 'Authentication issue detected during spawn');
+          clearTimeout(timer);
+          spawnDataHandler.dispose();
+          spawnExitHandler.dispose();
+          this.processReady = true;
+          this.output = spawnOutput;
+          this._setupPersistentDataHandler();
+          this._setupPersistentExitHandler();
+          resolve();
+          return;
+        }
+
         if (Date.now() >= trustCooldownUntil && this.isReadyForCommands(spawnOutput)) {
           logger.agent(this.name, 'Process ready for commands');
           clearTimeout(timer);
@@ -176,13 +256,29 @@ class BaseAgent {
         spawnExitHandler.dispose();
         this.shell = null;
         this.processReady = false;
+        if (this.isStopping()) {
+          reject(this._createStopError());
+          return;
+        }
         reject(new Error(`Process exited during spawn with code ${exitCode}`));
       });
     });
   }
 
   async sendCommandAndWait() {
+    if (this.isStopping()) {
+      throw this._createStopError();
+    }
+
     return new Promise((resolve, reject) => {
+      const existingOutput = this.output;
+      const existingAuthState = this.detectAuthenticationState ? this.detectAuthenticationState(existingOutput) : null;
+      if (existingAuthState) {
+        logger.agent(this.name, 'Using existing authentication output without sending commands');
+        resolve(existingOutput);
+        return;
+      }
+
       this.output = '';
       this._commandInFlight = true;
 
@@ -194,6 +290,12 @@ class BaseAgent {
       };
 
       const timer = setTimeout(() => {
+        if (this.isStopping()) {
+          this._commandInFlight = false;
+          this._onDataCallback = null;
+          reject(this._createStopError());
+          return;
+        }
         logger.agent(this.name, 'Command timeout after', logger.dim(`${this.getTimeout()}ms`), ', output length:', logger.dim(`${this.output.length}`));
         if (this.output.length > 0) {
           logger.agent(this.name, 'Partial output:', logger.dim(this.stripAnsi(this.output).substring(0, 500)));
@@ -211,6 +313,13 @@ class BaseAgent {
       }, this.getTimeout());
 
       this._onDataCallback = () => {
+        if (this.isStopping()) {
+          this._commandInFlight = false;
+          this._onDataCallback = null;
+          clearTimeout(timer);
+          reject(this._createStopError());
+          return;
+        }
         if (this.hasCompleteOutput(this.output)) {
           logger.agent(this.name, 'Complete output detected');
           // Small delay to capture any remaining output
@@ -264,15 +373,27 @@ class BaseAgent {
   _handleAdditionalPrompts(_s, _d, _o) { } // Hook for subclasses; killProcess: see below
   killProcess() { // Terminates the persistent PTY process
     if (this.shell) {
-      logger.agent(this.name, 'Killing persistent process');
+      const pidText = typeof this.shell.pid === 'number' ? ` (pid ${this.shell.pid})` : '';
+      logger.agent(this.name, `Killing persistent process${pidText}`);
+      const shell = this.shell;
       for (const d of this._disposables) { d.dispose(); }
       this._disposables = []; this._onDataCallback = null; this.processReady = false;
-      try { this.shell.kill(); } catch (_e) { /* Process may already be dead */ }
+      try {
+        // PTY-backed CLIs may spawn descendants; kill the whole process group when available.
+        if (typeof shell.pid === 'number' && shell.pid > 0) {
+          try { process.kill(-shell.pid, 'SIGTERM'); } catch (_e) { /* Group may not exist */ }
+        }
+        shell.kill();
+      } catch (_e) { /* Process may already be dead */ }
       this.shell = null;
     }
   }
 
   async _runCommandFresh() {
+    if (this.isStopping()) {
+      throw this._createStopError();
+    }
+
     return new Promise((resolve, reject) => {
       const timeout = this.getTimeout();
       let output = '';
@@ -300,6 +421,12 @@ class BaseAgent {
 
       const timer = setTimeout(() => {
         if (!completed) {
+          if (this.isStopping()) {
+            completed = true;
+            shell.kill();
+            reject(this._createStopError());
+            return;
+          }
           completed = true;
           logger.agent(this.name, 'Timeout after', logger.dim(`${timeout}ms`), ', output length:', logger.dim(`${output.length}`));
           if (output.length > 0) {
@@ -318,6 +445,16 @@ class BaseAgent {
 
       let trustCooldownUntil = 0;
       shell.onData((data) => {
+        if (this.isStopping()) {
+          if (!completed) {
+            completed = true;
+            clearTimeout(timer);
+            shell.kill();
+            reject(this._createStopError());
+          }
+          return;
+        }
+
         output += data;
 
         if (output.length <= data.length) {
@@ -361,6 +498,10 @@ class BaseAgent {
         if (!completed) {
           completed = true;
           clearTimeout(timer);
+          if (this.isStopping()) {
+            reject(this._createStopError());
+            return;
+          }
           logger.agent(this.name, 'Process exited with code', logger.dim(exitCode), ', output length:', logger.dim(`${output.length}`));
           if (output) {
             resolve(output);
@@ -380,6 +521,7 @@ class BaseAgent {
 
   /** Lightweight keepalive method to prevent session expiration. Subclasses can override. @returns {Promise<boolean>} True if keepalive succeeded */
   async keepalive() {
+    if (this.isStopping()) { return false; }
     if (this.freshProcess) { console.log(`[${this.name}] Keepalive skipped (fresh process mode)`); return true; }
     if (!this.shell || !this.processReady) { console.log(`[${this.name}] Keepalive: spawning process...`); await this.spawnProcess(); }
     if (this.shell) { console.log(`[${this.name}] Keepalive: sending ping...`); this.shell.write('\x1b'); return true; }

package/src/agents/codex.js

@@ -156,6 +156,9 @@ class CodexAgent extends BaseAgent {
           cwd: '/tmp',
           env: { ...process.env, TERM: 'xterm-256color' },
         });
+        if (typeof this.shell.pid === 'number') {
+          logger.agent(this.name, 'Persistent process pid:', logger.dim(String(this.shell.pid)));
+        }
       } catch (spawnErr) {
         logger.error(`[${this.name}] Failed to spawn:`, spawnErr.message);
         reject(new Error(`Failed to spawn ${this.command}: ${spawnErr.message}`));

package/src/agents/gemini.js

@@ -10,10 +10,24 @@ class GeminiAgent extends BaseAgent {
   }
 
   getTimeout() {
-    return 25000; // 25 seconds
+    return 35000; // 35 seconds - Gemini can take 10+ seconds to start
+  }
+
+  getEnv() {
+    // Use xterm-256color for proper terminal support
+    // Gemini CLI needs good terminal emulation for its TUI
+    return {
+      ...process.env,
+      TERM: 'xterm-256color',
+      COLORTERM: 'truecolor',
+    };
   }
 
   isReadyForCommands(output) {
+    // Don't consider ready if authentication is in progress
+    if (this._isAuthenticating(output)) {
+      return false;
+    }
     // v0.24: "Type your message" prompt
     // v0.35+: "Ready" in terminal title + visible prompt area (no "Type your message")
     // Also check for terminal title sequence containing "Ready"
@@ -22,6 +36,52 @@ class GeminiAgent extends BaseAgent {
       || /Ready\s*\(/.test(output);
   }
 
+  _isAuthenticating(output) {
+    // Detect OAuth/authentication screens where Escape would cancel the flow
+    const clean = this.stripAnsi(output);
+
+    // If we see the ready prompt, auth is complete (even if auth text still in buffer)
+    if (clean.includes('Type your message') || clean.includes('? for shortcuts')) {
+      return false;
+    }
+
+    // Only consider authenticating if we see auth-specific text
+    return /waiting for authentication/i.test(clean)
+      || /press esc.*to cancel/i.test(clean)
+      || /authenticating\.\.\./i.test(clean);
+  }
+
+  detectAuthenticationState(output) {
+    const clean = this.stripAnsi(output);
+    if (!clean) return null;
+
+    const hasAuthMenu = /how would you like to authenticate for this project\?/i.test(clean)
+      || /get started/i.test(clean);
+    const hasAuthFailure = /failed to sign in\.\s*message:\s*([^\n]+)/i.test(clean)
+      || /please run gemini cli in an interactive terminal to authenticate/i.test(clean)
+      || /authentication consent could not be obtained/i.test(clean);
+
+    if (!hasAuthMenu && !hasAuthFailure) {
+      return null;
+    }
+
+    const failureMatch = clean.match(/failed to sign in\.\s*message:\s*([^\n]+)/i);
+    const detail = failureMatch
+      ? `Failed to sign in: ${failureMatch[1].trim()}`
+      : 'Gemini CLI is waiting for authentication.';
+    const action = /NO_BROWSER=true/i.test(clean)
+      ? 'Run Gemini CLI in an interactive terminal to authenticate, or use NO_BROWSER=true for manual authentication.'
+      : 'Run Gemini CLI in an interactive terminal to authenticate.';
+
+    return {
+      authenticated: false,
+      status: 'unauthenticated',
+      message: 'Authentication required',
+      detail,
+      action,
+    };
+  }
+
   handleTrustPrompt(shell, output) {
     // Check for trust prompt with various wordings
     const trustPatterns = [
@@ -42,6 +102,7 @@ class GeminiAgent extends BaseAgent {
       // v0.35+ does an internal restart after trust — send Escape after a delay
       // to dismiss any transitional UI before the process becomes ready again
       setTimeout(() => {
+        if (!shell) return;
         logger.agent(this.name, 'Post-trust: sending Escape to clear restart UI...');
         shell.write('\x1b');
       }, 3000);
@@ -55,6 +116,7 @@ class GeminiAgent extends BaseAgent {
     // Gemini shows "Usage limits" after the model usage table (v0.24.x)
     if (output.includes('Usage limits span all sessions')) return true;
     const clean = this.stripAnsi(output);
+    if (this.detectAuthenticationState(clean)) return true;
     const hasModel = /gemini-[\w.-]+/i.test(clean);
     const hasPercent = /\d+(?:\.\d+)?%/i.test(clean);
     // v0.24: "Resets in 3h 26m", v0.35+: "(23h 21m)" after time
@@ -89,10 +151,16 @@ class GeminiAgent extends BaseAgent {
     return totalSeconds > 0 ? totalSeconds : null;
   }
 
-  sendCommands(shell, _output) {
+  sendCommands(shell, output) {
+    // Check if authentication is still in progress - don't send commands that could interfere
+    if (this._isAuthenticating(output) || this.detectAuthenticationState(output)) {
+      logger.agent(this.name, 'Authentication required or in progress, cannot send /stats command');
+      // Don't retry - let the timeout handle it. Sending Escape would cancel auth.
+      return;
+    }
     logger.agent(this.name, 'Sending /stats command...');
     // v0.35+: typing /stats triggers autocomplete dropdown.
-    // Escape dismisses autocomplete, then Enter submits the command.
+    // Escape clears any pending state, then send command, Escape again to dismiss autocomplete
     setTimeout(() => shell.write('\x1b'), 50);
     setTimeout(() => shell.write('/stats'), 500);
     setTimeout(() => shell.write('\x1b'), 1000);
@@ -161,6 +229,10 @@ class GeminiAgent extends BaseAgent {
       await this.spawnProcess();
     }
 
+    if (this.detectAuthenticationState(this.output)) {
+      return null;
+    }
+
     return new Promise((resolve, _reject) => {
       let aboutOutput = '';
       let completed = false;
@@ -181,8 +253,16 @@ class GeminiAgent extends BaseAgent {
       }, 10000); // 10 second timeout for /about
 
       this._commandInFlight = true;
+      let trustHandled = false;
       this._onDataCallback = () => {
         aboutOutput = this.output;
+        // Handle trust prompts that appear during command execution
+        if (!trustHandled && this.handleTrustPrompt(this.shell, aboutOutput)) {
+          trustHandled = true;
+          aboutOutput = '';
+          this.output = '';
+          return;
+        }
         // Check if we have complete /about output
         if (this._hasCompleteAboutOutput(aboutOutput)) {
           logger.agent(this.name, 'Complete /about output detected');
@@ -192,11 +272,39 @@ class GeminiAgent extends BaseAgent {
 
       logger.agent(this.name, 'Sending /about command for metadata...');
       this.output = '';
-      // Escape clears pending state, delay for CLI to be fully interactive,
-      // second Enter in case /about has an autocomplete menu in newer versions
-      setTimeout(() => this.shell.write('\x1b'), 100);
-      setTimeout(() => this.shell.write('/about\r'), 2000);
-      setTimeout(() => this.shell.write('\r'), 2500);
+
+      // Wait for authentication to complete before sending commands
+      // Auth can start after spawn if token refresh is needed
+      // Gemini can take 10+ seconds to fully start up
+      let authWaitCount = 0;
+      const maxAuthWait = 15; // Max 15 seconds waiting for auth
+
+      const waitForAuth = () => {
+        if (this.detectAuthenticationState(this.output)) {
+          logger.agent(this.name, 'Authentication required, skipping /about metadata fetch');
+          finish(null);
+          return;
+        }
+        if (this._isAuthenticating(this.output)) {
+          authWaitCount++;
+          if (authWaitCount >= maxAuthWait) {
+            logger.agent(this.name, 'Authentication timeout - Gemini may be stuck in auth flow');
+            // Don't send commands that would interfere with stuck auth
+            // Let the overall timeout handle this
+            return;
+          }
+          logger.agent(this.name, 'Authentication in progress, waiting...');
+          setTimeout(waitForAuth, 1000);
+          return;
+        }
+        // Auth complete (or not happening), send commands
+        // Guard against shell being nullified if process exits during setTimeout delays
+        // Don't send Escape first - it can cancel auth flows that started between checks
+        setTimeout(() => this.shell?.write('/about\r'), 500);
+        setTimeout(() => this.shell?.write('\r'), 1000);
+      };
+
+      setTimeout(waitForAuth, 100);
     });
   }
 

package/src/index.js

@@ -23,6 +23,24 @@ const pkg = require(path.join(__dirname, '..', 'package.json'));
  */
 const AUTO_REFRESH_MODES = ['none', 'interval', 'activity'];
 
+function describeAgentShutdown(agent) {
+  const parts = [];
+
+  if (agent.shell && typeof agent.shell.pid === 'number') {
+    parts.push(`pty pid ${agent.shell.pid}`);
+  }
+
+  if (agent._rpcClient) {
+    parts.push('json-rpc client');
+  }
+
+  if (parts.length === 0) {
+    parts.push('no active child process');
+  }
+
+  return parts.join(', ');
+}
+
 class AgentTank {
   constructor(options = {}) {
     this.port = options.port || 3456;
@@ -37,6 +55,7 @@ class AgentTank {
     this.publicStatus = {}; // Public API status from upstream providers
     this.skipServer = options.skipServer || false; // Skip HTTP server in one-shot mode
     this.lastRefreshedAt = null;
+    this.stopping = false;
 
     // Auto-refresh configuration (backend periodic refresh)
     // Determine the mode: 'none', 'interval', or 'activity' (default: 'activity')
@@ -121,6 +140,10 @@ class AgentTank {
   }
 
   async start() {
+    if (this.stopping) {
+      return;
+    }
+
     // Display startup banner with website URL, version, and copyright
     this.displayStartupBanner();
 
@@ -169,18 +192,24 @@ class AgentTank {
       await Promise.all(
         Array.from(this.agents.values()).map(agent =>
           agent.spawnProcess().catch(err =>
-            logger.error(`Error spawning ${agent.name}:`, err.message)
+            this.stopping || err.message === 'Agent stopping'
+              ? null
+              : logger.error(`Error spawning ${agent.name}:`, err.message)
           )
         )
       );
     }
 
+    if (this.stopping) {
+      return;
+    }
+
     // Initial fetch
     logger.info('📊 Fetching initial usage data...');
     await this.refreshAll();
 
     // Start backend auto-refresh if enabled (skip in one-shot mode)
-    if (!this.skipServer) {
+    if (!this.skipServer && !this.stopping) {
       this.startAutoRefresh();
       this.startKeepalive();
     }
@@ -231,6 +260,10 @@ class AgentTank {
   }
 
   async refreshAll() {
+    if (this.stopping) {
+      return;
+    }
+
     logger.info('🔄 Refreshing all agents...');
     const agentNames = Array.from(this.agents.keys());
 
@@ -240,7 +273,9 @@ class AgentTank {
       Promise.all(
         Array.from(this.agents.values()).map(agent =>
           agent.refresh().catch(err => {
-            logger.error(`Error refreshing ${agent.name}:`, err.message);
+            if (!this.stopping && err.message !== 'Agent stopping') {
+              logger.error(`Error refreshing ${agent.name}:`, err.message);
+            }
           })
         )
       ),
@@ -276,6 +311,10 @@ class AgentTank {
   }
 
   async refreshAgent(name) {
+    if (this.stopping) {
+      return;
+    }
+
     const agent = this.agents.get(name);
     if (!agent) {
       throw new Error(`Agent not found: ${name}`);
@@ -345,12 +384,19 @@ class AgentTank {
   }
 
   stop() {
+    this.stopping = true;
+    console.log('[Shutdown] Stopping Agent Tank...');
     this.stopAutoRefresh();
     this.stopKeepalive();
-    for (const agent of this.agents.values()) {
+    for (const [name, agent] of this.agents) {
+      console.log(`[Shutdown] ${name}: ${describeAgentShutdown(agent)}`);
+      if (typeof agent.requestStop === 'function') {
+        agent.requestStop();
+      }
       agent.killProcess();
     }
     if (this.server) {
+      console.log('[Shutdown] Closing HTTP server');
       this.server.close();
     }
   }

package/src/json-rpc-client.js

@@ -44,6 +44,9 @@ class JsonRpcClient extends EventEmitter {
           env: this.options.env,
           stdio: ['pipe', 'pipe', 'pipe'],
         });
+        if (typeof this.process.pid === 'number') {
+          console.log(`[JsonRpcClient] Started ${this.command} (pid ${this.process.pid})`);
+        }
 
         this.process.on('error', (err) => {
           this.isConnected = false;

package/src/shutdown-handler.js

@@ -0,0 +1,32 @@
+function installShutdownHandlers({ shutdown, processObj = process, stdin = process.stdin }) {
+  const onSigterm = () => shutdown('SIGTERM');
+  const onStdinData = (chunk) => {
+    const data = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk || ''));
+    if (data.includes(0x03)) {
+      shutdown('CTRL+C');
+    }
+  };
+
+  processObj.on('SIGTERM', onSigterm);
+
+  const shouldWatchStdin = stdin && stdin.isTTY && typeof stdin.on === 'function';
+  if (shouldWatchStdin) {
+    stdin.on('data', onStdinData);
+    if (typeof stdin.resume === 'function') {
+      stdin.resume();
+    }
+  }
+
+  return () => {
+    processObj.off('SIGTERM', onSigterm);
+
+    if (shouldWatchStdin) {
+      stdin.off('data', onStdinData);
+      if (typeof stdin.pause === 'function') {
+        stdin.pause();
+      }
+    }
+  };
+}
+
+module.exports = { installShutdownHandlers };

package/src/status-page.css

@@ -516,6 +516,21 @@ body.light-mode .progress-bar {
   font-size: 13px;
 }
 
+.auth-notice {
+  font-size: 13px;
+  color: #f6ad55;
+  padding: 8px 10px;
+  margin-bottom: 10px;
+  background: rgba(246, 173, 85, 0.08);
+  border: 1px solid rgba(246, 173, 85, 0.2);
+  border-radius: 4px;
+}
+
+.auth-detail {
+  margin-top: 4px;
+  color: var(--text-secondary);
+}
+
 /* Version update notice below agent cards */
 .version-update-notice {
   font-family: var(--font-mono);
@@ -533,6 +548,12 @@ body.light-mode .version-update-notice {
   border-color: rgba(183, 121, 31, 0.2);
 }
 
+body.light-mode .auth-notice {
+  color: #b7791f;
+  background: rgba(246, 173, 85, 0.12);
+  border-color: rgba(183, 121, 31, 0.2);
+}
+
 button {
   width: 100%;
   padding: 10px;

package/src/status-page.js

@@ -9,6 +9,15 @@ const { getStatusBadgeClass, getStatusText } = require('./public-status');
 
 const styles = fs.readFileSync(path.join(__dirname, 'status-page.css'), 'utf8');
 
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
 function statusPage(status) {
   const agents = Object.entries(status);
 
@@ -36,7 +45,7 @@ function statusPage(status) {
     const publicStatus = data.publicStatus;
     const badgeClass = publicStatus ? getStatusBadgeClass(publicStatus.status) : 'status-badge-grey';
     const badgeText = publicStatus ? getStatusText(publicStatus.status) : 'Unknown';
-    const badgeTitle = publicStatus?.description || 'Unable to fetch status';
+    const badgeTitle = escapeHtml(publicStatus?.description || 'Unable to fetch status');
     const statusBadgeHtml = `<span class="status-badge ${badgeClass}" title="${badgeTitle}">${badgeText}</span>`;
 
     // Version update notice - check usage.version (Codex) or metadata.updateAvailable (Gemini)
@@ -45,10 +54,15 @@ function statusPage(status) {
       ? `<div class="version-update-notice">Update available: v${version.current} → v${version.latest}</div>`
       : '';
 
+    const authHtml = data.auth
+      ? `<div class="auth-notice">${escapeHtml(data.auth.action || 'Please log in via the CLI.')}</div>`
+      : '';
+    const errorHtml = data.error && !data.auth ? `<span class="error-msg">${escapeHtml(data.error)}</span>` : '';
+
     // Only show card-footer if there's an error or update notice
-    const hasFooterContent = data.error || updateHtml;
+    const hasFooterContent = errorHtml || authHtml || updateHtml;
     const footerHtml = hasFooterContent
-      ? `<div class="card-footer">${data.error ? `<span class="error-msg">${data.error}</span>` : ''}${updateHtml}</div>`
+      ? `<div class="card-footer">${errorHtml}${authHtml}${updateHtml}</div>`
       : '';
 
     return `