agent-tank 0.9.7 → 0.9.9

package/README.md

@@ -62,6 +62,47 @@ Or run it directly:
 npx agent-tank
 ```
 
+### Run from Source
+
+If you want to run the latest code from a checkout instead of the published package:
+
+```bash
+# 1. Clone the repo
+git clone https://github.com/integry/agent-tank.git
+cd agent-tank
+
+# 2. Install dependencies (compiles node-pty natively)
+npm install
+
+# 3. Run it
+npm start          # = node bin/agent-tank.js
+```
+
+By default it auto-discovers installed CLIs and serves the dashboard + API at `http://127.0.0.1:3456`.
+
+To pass flags, call the entry point directly (`npm start` does not forward arguments cleanly):
+
+```bash
+node bin/agent-tank.js --claude --codex --port 8080
+node bin/agent-tank.js --once --json          # one-shot, prints JSON, no server
+node bin/agent-tank.js --no-docker            # localhost only
+node bin/agent-tank.js --help                 # full option list
+```
+
+Prerequisites:
+
+- **Node.js 18+**
+- `node-pty` is a native module, so `npm install` needs **Python 3.8+** and **C/C++ build tools**. See [Installation Notes](#installation-notes) if the build fails.
+- At least one supported CLI installed and authenticated on your `PATH` (`claude`, `agy`, or `codex`).
+
+Other useful scripts:
+
+```bash
+npm test           # run all tests
+npm run lint       # check code style
+npm run rebuild    # rebuild node-pty against a detected Python
+```
+
 ### First Run
 
 ```bash
@@ -92,6 +133,9 @@ agent-tank --claude --agy
 # Use a custom port
 agent-tank --port 8080
 
+# Keep Agent Tank running after closing this terminal
+agent-tank --background
+
 # Fetch once and print JSON
 agent-tank --once --json
 
@@ -150,6 +194,14 @@ agent-tank --claude --codex
 agent-tank --once --json
 ```
 
+### Background Server Mode
+
+```bash
+agent-tank --background
+```
+
+This starts Agent Tank as a detached process, prints the background PID, and exits the parent command.
+
 ### Bind to a Different Host or Port
 
 ```bash
@@ -198,14 +250,15 @@ Options:
   --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)
-  --auto-refresh-interval <seconds>  Auto-refresh interval in seconds (default: 60)
+  --auto-refresh-interval <seconds>  Auto-refresh interval in seconds (default: 60, 0 = disabled)
   --refresh-cooldown <seconds>       Minimum time between refreshes per agent (default: 30, 0 = disabled)
   --activity-debounce <ms>           Activity debounce interval in milliseconds (default: 5000)
   --keepalive           Enable/disable session keepalive (default: true)
-  --keepalive-interval <seconds>     Session keepalive interval in seconds (default: 300)
+  --keepalive-interval <seconds>     Session keepalive interval in seconds (default: 300, 0 = disabled)
   --history-retention-days <days>    Days to retain usage history (default: 14)
   --once                Fetch usage once and exit (no HTTP server)
   --json                Output pure JSON (suppress logging, use with --once)
+  --background          Start Agent Tank as a detached background process
   --help, -h            Show this help message
 ```
 
@@ -213,7 +266,9 @@ Options:
 
 ### Environment Variables
 
-Environment variables override CLI flags and config file values.
+Environment variables override CLI flags and config file values. Background mode has
+three exceptions: `--no-background`, `--once`, and `--json` suppress
+`AGENT_TANK_BACKGROUND=1` for that run.
 
 | Variable | Description |
 |---|---|
@@ -232,6 +287,9 @@ Environment variables override CLI flags and config file values.
 | `AGENT_TANK_KEEPALIVE` | Enable/disable keepalive |
 | `AGENT_TANK_KEEPALIVE_INTERVAL` | Keepalive interval in seconds |
 | `AGENT_TANK_HISTORY_RETENTION_DAYS` | History retention window |
+| `AGENT_TANK_BACKGROUND` | Start as a detached background process (`1`/`true`) |
+| `AGENT_TANK_BACKGROUND_LOG` | Background child stdout/stderr log path (defaults to a temp file) |
+| `AGENT_TANK_BACKGROUND_GRACE_MS` | Parent startup grace period before reporting background success; success means the child survived this period |
 
 ### Config File
 

package/bin/agent-tank.js

@@ -1,9 +1,15 @@
 #!/usr/bin/env node
-/* eslint-disable complexity */
+/* eslint-disable complexity -- CLI option merging is centralized here to preserve precedence behavior. */
+/* eslint-disable max-lines -- Tracked in issue #90; CLI help text and option precedence stay together for now. */
 
 const { parseArgs } = require('node:util');
-const { AgentTank } = require('../src/index.js');
-const { installShutdownHandlers } = require('../src/shutdown-handler.js');
+const {
+  isTruthyEnv,
+} = require('../src/process-utils.js');
+const {
+  spawnBackgroundProcess,
+  warnAboutRunningProcesses,
+} = require('../src/cli-background.js');
 const pkg = require('../package.json');
 
 const options = {
@@ -32,9 +38,15 @@ const options = {
   'keepalive-interval': { type: 'string', default: '300' },
   once: { type: 'boolean', default: false },
   json: { type: 'boolean', default: false },
+  background: { type: 'boolean', default: false },
 };
 
-const { values } = parseArgs({ options, allowPositionals: false, allowNegative: true });
+const { values, tokens } = parseArgs({
+  options,
+  allowPositionals: false,
+  allowNegative: true,
+  tokens: true,
+});
 
 function exitWithCode(code, message, stream = process.stderr) {
   if (message) {
@@ -85,6 +97,7 @@ Options:
   --history-retention-days <days>    Days to retain usage history (default: 14)
   --once                Fetch usage once and exit (no HTTP server)
   --json                Output pure JSON (suppress logging, use with --once)
+  --background          Start Agent Tank as a detached background process
   --help, -h            Show this help message
 
 Auto-Refresh Modes:
@@ -109,9 +122,14 @@ Environment variables:
   AGENT_TANK_KEEPALIVE      Enable/disable session keepalive ("1" or "true" / "0" or "false")
   AGENT_TANK_KEEPALIVE_INTERVAL  Session keepalive interval in seconds
   AGENT_TANK_HISTORY_RETENTION_DAYS  Days to retain usage history
+  AGENT_TANK_BACKGROUND  Start as a detached background process ("1" or "true")
+  AGENT_TANK_BACKGROUND_LOG  Log file for background child stdout/stderr
+  AGENT_TANK_BACKGROUND_GRACE_MS  Parent startup grace period before reporting background success
+                                  (success means the child survived this period)
 
 Examples:
   agent-tank                          # Auto-discover and monitor all available
+  agent-tank --background             # Start in the background and print the PID
   agent-tank --claude --agy           # Monitor specific agents
   agent-tank --port 8080              # Use custom port
   agent-tank --host 0.0.0.0           # Expose on all interfaces
@@ -156,6 +174,37 @@ async function main() {
     return;
   }
 
+  const explicitNoBackground = tokens.some(token =>
+    token.kind === 'option' &&
+    token.name === 'background' &&
+    token.rawName === '--no-background');
+  const explicitBackground = tokens.some(token =>
+    token.kind === 'option' &&
+    token.name === 'background' &&
+    token.rawName === '--background');
+  const envBackgroundRequested = isTruthyEnv(process.env.AGENT_TANK_BACKGROUND) &&
+    !explicitNoBackground &&
+    !values.once &&
+    !values.json;
+  const backgroundRequested = explicitBackground || envBackgroundRequested;
+  const backgroundChild = isTruthyEnv(process.env.AGENT_TANK_BACKGROUND_CHILD);
+
+  if (backgroundRequested && !backgroundChild) {
+    for (const incompatibleFlag of ['once', 'json']) {
+      if (values[incompatibleFlag]) {
+        exitWithCode(1, `Error: --background cannot be combined with --${incompatibleFlag}`);
+        return;
+      }
+    }
+
+    const started = await spawnBackgroundProcess();
+    process.exitCode = started ? 0 : 1;
+    return;
+  }
+
+  const { AgentTank } = require('../src/index.js');
+  const { installShutdownHandlers } = require('../src/shutdown-handler.js');
+
   // Load config file if specified
   let config = {};
   if (values.config) {
@@ -346,7 +395,11 @@ async function main() {
       }
     }
 
+    const runningProcessWarning = (!jsonMode && !backgroundChild) ?
+      warnAboutRunningProcesses() :
+      Promise.resolve();
     await watcher.start();
+    await runningProcessWarning;
   } catch (err) {
     cleanupShutdownHandlers();
     if (jsonMode) {

package/package.json

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

package/src/agents/agy.js

@@ -4,6 +4,10 @@ const { CYCLE_DURATIONS } = require('../usage-formatters.js');
 const logger = require('../logger.js');
 
 class AgyAgent extends BaseAgent {
+  // Matches both the older "Model Quota" screen and the newer grouped
+  // "Models & Quota" screen reported by recent Antigravity CLI builds.
+  static QUOTA_HEADER = /Models?\s*&?\s*Quota/i;
+
   constructor() {
     super('agy', 'agy', ['--dangerously-skip-permissions']);
     this._aboutSent = false;
@@ -128,8 +132,8 @@ class AgyAgent extends BaseAgent {
   hasCompleteOutput(output) {
     const clean = this.stripAnsi(output);
     if (this.detectAuthenticationState(clean)) return true;
-    if (/Model\s+Quota/i.test(clean)) {
-      return /(?:Gemini|Claude|GPT)[\s\S]*\d+(?:\.\d+)?%/i.test(clean);
+    if (AgyAgent.QUOTA_HEADER.test(clean)) {
+      return /(?:Gemini|Claude|GPT|Weekly\s+Limit|Five[\s-]?Hour\s+Limit)[\s\S]*\d+(?:\.\d+)?\s*%/i.test(clean);
     }
     const hasModel = /(?:Gemini|Claude|GPT)[^\n]+/i.test(clean);
     const hasPercent = /\d+(?:\.\d+)?%/i.test(clean);
@@ -171,8 +175,32 @@ class AgyAgent extends BaseAgent {
       return;
     }
     logger.agent(this.name, 'Sending /usage command...');
-    setTimeout(() => shell.write('/usage'), 200);
-    setTimeout(() => shell.write('\r'), 600);
+    // A prior /usage leaves Antigravity's usage modal open. On a reused
+    // persistent process that modal swallows the next /usage (0 bytes back ->
+    // 35s timeout -> kill/respawn, which is why refreshes alternated
+    // success/timeout). Press Escape first to return to the prompt; it is a
+    // no-op at a clean prompt and safe because auth flows are guarded above.
+    setTimeout(() => shell.write('\x1b'), 200);
+    setTimeout(() => shell.write('/usage'), 600);
+    setTimeout(() => shell.write('\r'), 1000);
+  }
+
+  // Convert an ALL-CAPS Antigravity group header (e.g. "CLAUDE AND GPT") into a
+  // readable label ("Claude and GPT"), preserving known acronyms and lowercasing
+  // connective words.
+  _formatGroupName(raw) {
+    const acronyms = new Set(['GPT', 'GPU', 'AI', 'CLI', 'API', 'OSS']);
+    const connectives = new Set(['and', 'or', 'of', 'the', 'for', 'with']);
+    return raw
+      .split(/\s+/)
+      .map((word, idx) => {
+        const upper = word.toUpperCase();
+        if (acronyms.has(upper)) return upper;
+        const lower = word.toLowerCase();
+        if (idx > 0 && connectives.has(lower)) return lower;
+        return lower.charAt(0).toUpperCase() + lower.slice(1);
+      })
+      .join(' ');
   }
 
   // Calculate pace data for a model entry when reset timing is available.
@@ -201,21 +229,40 @@ class AgyAgent extends BaseAgent {
   }
 
   _parseAgyUsage(clean, usage) {
-    if (!/Model\s+Quota/i.test(clean)) return;
+    if (!AgyAgent.QUOTA_HEADER.test(clean)) return;
 
     const lines = clean.split('\n').map(line => line.trim()).filter(Boolean);
     const knownMarkers = new Set([
       'Model Quota',
+      'Models & Quota',
       'Quota available',
       '? for shortcuts',
     ]);
 
+    // Newer Antigravity builds group quotas under section headers such as
+    // "GEMINI MODELS" / "CLAUDE AND GPT MODELS", with each group reporting its
+    // own "Weekly Limit" and "Five Hour Limit". Track the active group so those
+    // generic labels can be qualified and not collapsed into a single entry.
+    let currentGroup = null;
+
     for (let i = 0; i < lines.length; i++) {
-      const modelLine = lines[i];
-      if (knownMarkers.has(modelLine) || /^(?:[>└]|[-─↑/↓]|esc\s+to\s+cancel)/i.test(modelLine)) {
+      const line = lines[i];
+
+      const groupMatch = line.match(/^([A-Z][A-Z0-9 &/-]*?)\s+MODELS$/);
+      if (groupMatch) {
+        currentGroup = this._formatGroupName(groupMatch[1].trim());
         continue;
       }
-      if (!/[A-Za-z]/.test(modelLine) || /\d+\s*%/.test(modelLine)) {
+
+      if (knownMarkers.has(line) || /^(?:[>└│]|[-─↑/↓]|esc\s+to\s+cancel)/i.test(line)) {
+        continue;
+      }
+      // Descriptive lines that are not models (e.g. "Account: ...",
+      // "Models within this group: ...").
+      if (/^(?:Account|Models within this group)\s*:/i.test(line)) {
+        continue;
+      }
+      if (!/[A-Za-z]/.test(line) || /\d+\s*%/.test(line)) {
         continue;
       }
 
@@ -232,8 +279,16 @@ class AgyAgent extends BaseAgent {
       const resetsIn = resetMatch?.[1]?.trim() || null;
       const resetsInSeconds = resetsIn ? this.parseDurationToSeconds(resetsIn) : null;
 
-      if (!usage.models.find(m => m.model === modelLine)) {
-        const modelEntry = { model: modelLine, usageLeft, percentUsed, resetsIn, resetsInSeconds };
+      // Qualify shared limit labels with their group so entries from different
+      // groups stay distinct; per-model labels are already unique on their own.
+      const isSharedLimit = /^(?:weekly|five[\s-]?hour|5[\s-]?hour|daily|hourly)\b/i.test(line);
+      const modelName = (currentGroup && isSharedLimit)
+        ? `${currentGroup} · ${line}`
+        : line;
+
+      if (!usage.models.find(m => m.model === modelName)) {
+        const modelEntry = { model: modelName, usageLeft, percentUsed, resetsIn, resetsInSeconds };
+        if (currentGroup) modelEntry.group = currentGroup;
         this._addPaceData(modelEntry, resetsInSeconds);
         usage.models.push(modelEntry);
       }

package/src/agents/base.js

@@ -1,8 +1,14 @@
+/* eslint-disable max-lines -- Tracked in issue #90; keep this PR scoped to background startup behavior. */
+
 const pty = require('node-pty');
 const process = require('node:process');
 const logger = require('../logger.js');
 
 class BaseAgent {
+  // Grace period before escalating a runtime SIGTERM to SIGKILL for CLIs that
+  // ignore graceful termination. Overridable in tests.
+  static FORCE_KILL_GRACE_MS = 2000;
+
   constructor(name, command, args = []) {
     this.name = name;
     this.command = command;
@@ -32,6 +38,25 @@ class BaseAgent {
     return new Error('Agent stopping');
   }
 
+  /**
+   * Best-effort dump of raw output to a temp file for debugging.
+   * Never throws: the target may be unwritable (e.g. a stale file in
+   * /tmp owned by another user), and these dumps run inside timer
+   * callbacks where an exception would crash the whole process.
+   * @param {string} output Raw output to dump
+   * @returns {string|null} Path written to, or null on failure
+   */
+  writeDebugOutput(output) {
+    const debugPath = require('node:path').join(require('node:os').tmpdir(), `${this.name}-output.txt`);
+    try {
+      require('fs').writeFileSync(debugPath, output);
+      return debugPath;
+    } catch (err) {
+      logger.agent(this.name, 'Could not write debug output:', logger.dim(err.message));
+      return null;
+    }
+  }
+
   isStopping() {
     return this._stopRequested;
   }
@@ -308,7 +333,7 @@ class BaseAgent {
         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)));
-          require('fs').writeFileSync(`/tmp/${this.name}-output.txt`, this.output);
+          this.writeDebugOutput(this.output);
         }
         // Kill the stuck process so it respawns fresh on the next refresh
         logger.agent(this.name, 'Killing stuck process to force respawn');
@@ -388,22 +413,57 @@ class BaseAgent {
   }
 
   _handleAdditionalPrompts(_s, _d, _o) { } // Hook for subclasses; killProcess: see below
-  killProcess() { // Terminates the persistent PTY process
-    if (this.shell) {
-      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 {
-        // 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;
+  // Terminates the persistent PTY process.
+  //
+  // Some CLIs (notably `agy` and `codex`) ignore SIGTERM/SIGHUP and would
+  // otherwise survive as orphaned processes (reparented to init) every time we
+  // respawn them or the server exits. We always attempt a graceful SIGTERM
+  // first, then escalate to SIGKILL:
+  //   - runtime (default): asynchronously, after a short grace period, if the
+  //     process is still alive (the event loop is running, so the timer fires);
+  //   - immediate (shutdown): synchronously, because the process is about to
+  //     call process.exit() and pending timers would never run.
+  killProcess({ immediate = false } = {}) {
+    if (!this.shell) return;
+    const shell = this.shell;
+    const pid = (typeof shell.pid === 'number' && shell.pid > 0) ? shell.pid : null;
+    const pidText = pid != null ? ` (pid ${pid})` : '';
+    logger.agent(this.name, `Killing persistent process${pidText}`);
+    for (const d of this._disposables) { d.dispose(); }
+    this._disposables = []; this._onDataCallback = null; this.processReady = false;
+
+    this._signalProcess(pid, shell, 'SIGTERM');
+
+    if (immediate) {
+      this._signalProcess(pid, shell, 'SIGKILL');
+    } else if (pid != null) {
+      const timer = setTimeout(() => {
+        if (!this._isProcessAlive(pid)) return;
+        logger.agent(this.name, `Process ${pid} ignored SIGTERM; sending SIGKILL`);
+        this._signalProcess(pid, shell, 'SIGKILL');
+      }, BaseAgent.FORCE_KILL_GRACE_MS);
+      // Never let the escalation timer keep the process alive on its own.
+      if (typeof timer.unref === 'function') timer.unref();
     }
+
+    this.shell = null;
+  }
+
+  // Best-effort signal to a PTY process and its process group. PTY-backed CLIs
+  // may spawn descendants, so we signal the whole group when we have a pid.
+  // Never throws: the process or group may already be gone.
+  _signalProcess(pid, shell, signal) {
+    try {
+      if (pid != null) {
+        try { process.kill(-pid, signal); } catch (_e) { /* Group may not exist */ }
+      }
+      shell.kill(signal);
+    } catch (_e) { /* Process may already be dead */ }
+  }
+
+  // Returns true if the process is still alive (signal 0 probes without killing).
+  _isProcessAlive(pid) {
+    try { process.kill(pid, 0); return true; } catch (_e) { return false; }
   }
 
   async _runCommandFresh() {
@@ -448,8 +508,10 @@ class BaseAgent {
           logger.agent(this.name, 'Timeout after', logger.dim(`${timeout}ms`), ', output length:', logger.dim(`${output.length}`));
           if (output.length > 0) {
             logger.agent(this.name, 'Partial output:', logger.dim(this.stripAnsi(output).substring(0, 500)));
-            require('fs').writeFileSync(`/tmp/${this.name}-output.txt`, output);
-            logger.agent(this.name, 'Full output written to', logger.dim(`/tmp/${this.name}-output.txt`));
+            const debugPath = this.writeDebugOutput(output);
+            if (debugPath) {
+              logger.agent(this.name, 'Full output written to', logger.dim(debugPath));
+            }
           }
           shell.kill();
           if (output.length > 100) {

package/src/agents/codex.js

@@ -229,7 +229,7 @@ class CodexAgent extends BaseAgent {
         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)));
-          require('fs').writeFileSync(`/tmp/${this.name}-output.txt`, this.output);
+          this.writeDebugOutput(this.output);
         }
         if (this.output.length > 100) {
           finish(this.output);
@@ -347,12 +347,12 @@ class CodexAgent extends BaseAgent {
     this._rpcSupported = useRpc;
   }
 
-  killProcess() {
+  killProcess(options = {}) {
     if (this._rpcClient) {
       this._rpcClient.stop();
       this._rpcClient = null;
     }
-    super.killProcess();
+    super.killProcess(options);
   }
 
   /** Lightweight keepalive to prevent session expiration. @returns {Promise<boolean>} True if keepalive succeeded */

package/src/cli-background.js

@@ -0,0 +1,198 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const {
+  filterBackgroundArgs,
+  findAgentTankProcessesAsync,
+} = require('./process-utils.js');
+const { ANSI } = require('./logger.js');
+
+const BACKGROUND_STARTUP_GRACE_MS = 750;
+
+function createBackgroundLogPath({
+  env = process.env,
+  tmpdir = os.tmpdir,
+  pid = process.pid,
+  now = Date.now,
+} = {}) {
+  return env.AGENT_TANK_BACKGROUND_LOG ||
+    path.join(tmpdir(), `agent-tank-${pid}-${now()}.log`);
+}
+
+function writeBackgroundStartMessage({ pid, logPath, stdout = process.stdout }) {
+  stdout.write(`Agent Tank started in the background with PID ${pid}\n`);
+  stdout.write(`Background log: ${logPath}\n`);
+}
+
+function writeBackgroundStartFailure({ message, logPath, stderr = process.stderr }) {
+  stderr.write(`Failed to start Agent Tank in the background: ${message}\n`);
+  stderr.write(`Background log: ${logPath}\n`);
+}
+
+function ignoreLateChildError() {}
+
+function openBackgroundLog(logPath, openSync = fs.openSync) {
+  return openSync(logPath, 'a');
+}
+
+function closeBackgroundLog(logFd, closeSync = fs.closeSync) {
+  try {
+    closeSync(logFd);
+  } catch (_err) {
+    // The child owns the duplicated descriptor after spawn; parent close failures are non-fatal.
+  }
+}
+
+function getBackgroundStartupGraceMs(env = process.env) {
+  const parsed = Number.parseInt(env.AGENT_TANK_BACKGROUND_GRACE_MS, 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : BACKGROUND_STARTUP_GRACE_MS;
+}
+
+function waitForBackgroundStartup(child, graceMs, setTimer = setTimeout, clearTimer = clearTimeout) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+
+    const finish = (callback, value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimer(timer);
+      child.off('error', onError);
+      child.off('exit', onExit);
+      callback(value);
+    };
+
+    const onError = (err) => finish(reject, err);
+    const onExit = (code, signal) => {
+      const detail = signal ? `signal ${signal}` : `exit code ${code}`;
+      finish(reject, new Error(`child exited during startup (${detail})`));
+    };
+    const timer = setTimer(() => finish(resolve), graceMs);
+
+    child.once('error', onError);
+    child.once('exit', onExit);
+  });
+}
+
+async function spawnBackgroundProcess({
+  argv = process.argv,
+  env = process.env,
+  execPath = process.execPath,
+  spawnFn = spawn,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  openSync = fs.openSync,
+  closeSync = fs.closeSync,
+  startupGraceMs,
+} = {}) {
+  const resolvedStartupGraceMs = startupGraceMs ?? getBackgroundStartupGraceMs(env);
+  const logPath = createBackgroundLogPath({ env });
+  let logFd;
+
+  try {
+    logFd = openBackgroundLog(logPath, openSync);
+  } catch (err) {
+    writeBackgroundStartFailure({ message: err.message, logPath, stderr });
+    return false;
+  }
+
+  const childArgs = [
+    argv[1],
+    ...filterBackgroundArgs(argv.slice(2)),
+  ];
+  const childEnv = {
+    ...env,
+    AGENT_TANK_BACKGROUND_CHILD: '1',
+  };
+  delete childEnv.AGENT_TANK_BACKGROUND;
+  delete childEnv.AGENT_TANK_BACKGROUND_LOG;
+  delete childEnv.AGENT_TANK_BACKGROUND_GRACE_MS;
+
+  let child;
+  try {
+    child = spawnFn(execPath, childArgs, {
+      detached: true,
+      stdio: ['ignore', logFd, logFd],
+      env: childEnv,
+      windowsHide: true,
+    });
+  } catch (err) {
+    closeBackgroundLog(logFd, closeSync);
+    writeBackgroundStartFailure({ message: err.message, logPath, stderr });
+    return false;
+  }
+
+  closeBackgroundLog(logFd, closeSync);
+  child.on('error', ignoreLateChildError);
+
+  try {
+    await waitForBackgroundStartup(child, resolvedStartupGraceMs);
+  } catch (err) {
+    writeBackgroundStartFailure({ message: err.message, logPath, stderr });
+    return false;
+  }
+
+  if (!child.pid) {
+    // Extremely defensive: normal spawn failures are reported via the error event above.
+    writeBackgroundStartFailure({ message: 'child process PID was not assigned', logPath, stderr });
+    return false;
+  }
+
+  child.unref();
+  writeBackgroundStartMessage({ pid: child.pid, logPath, stdout });
+  return true;
+}
+
+function redactProcessCommand(command) {
+  return command
+    .replace(/(--auth-pass(?:=|\s+))(?:"[^"]*"|'[^']*'|\S+)/g, '$1[redacted]')
+    .replace(/(--auth-token(?:=|\s+))(?:"[^"]*"|'[^']*'|\S+)/g, '$1[redacted]');
+}
+
+async function warnAboutRunningProcesses({
+  findProcesses = findAgentTankProcessesAsync,
+  stderr = process.stderr,
+} = {}) {
+  let running;
+  try {
+    running = await findProcesses();
+  } catch (_err) {
+    return;
+  }
+
+  if (running.length === 0) {
+    return;
+  }
+
+  const lines = running
+    .map(entry => `  PID ${entry.pid}: ${redactProcessCommand(entry.command)}`)
+    .join('\n');
+
+  // Only emit color when writing to an interactive terminal, so redirected
+  // logs stay free of ANSI escape sequences.
+  const header = 'Warning: other Agent Tank process(es) already running:';
+  const coloredHeader = stderr.isTTY
+    ? `${ANSI.bold}${ANSI.red}${header}${ANSI.reset}`
+    : header;
+
+  const pids = running.map(entry => entry.pid).join(' ');
+
+  stderr.write(`${coloredHeader}\n`);
+  stderr.write(`${lines}\n`);
+  stderr.write('If this instance uses the same port, startup will fail; choose a different --port or stop the other process.\n');
+  stderr.write(`To stop the process(es) above, run: kill ${pids}\n`);
+  stderr.write(`If a process does not exit, force it with: kill -9 ${pids}\n`);
+  stderr.write('Tip: start Agent Tank in the background with agent-tank --background\n');
+}
+
+module.exports = {
+  BACKGROUND_STARTUP_GRACE_MS,
+  createBackgroundLogPath,
+  getBackgroundStartupGraceMs,
+  redactProcessCommand,
+  spawnBackgroundProcess,
+  waitForBackgroundStartup,
+  warnAboutRunningProcesses,
+};

package/src/index.js

@@ -1,3 +1,5 @@
+/* eslint-disable max-lines -- Tracked in issue #90; keep this PR scoped to background startup behavior. */
+
 const path = require('node:path');
 const os = require('node:os');
 const { execFileSync } = require('node:child_process');
@@ -569,7 +571,9 @@ class AgentTank {
       if (typeof agent.requestStop === 'function') {
         agent.requestStop();
       }
-      agent.killProcess();
+      // Shutdown is followed by process.exit(), so escalate to SIGKILL
+      // synchronously — a deferred timer would never run.
+      agent.killProcess({ immediate: true });
     }
     if (this.servers.length > 0) {
       console.log('[Shutdown] Closing HTTP server');

package/src/process-utils.js

@@ -0,0 +1,215 @@
+const { execFile } = require('node:child_process');
+const path = require('node:path');
+
+const BACKGROUND_ARG_RE = /^--(?:no-)?background$/;
+const AGENT_TANK_BIN_RE = /(^|[\\/])bin[\\/]agent-tank\.js$/;
+const PROCESS_SCAN_TIMEOUT_MS = 2000;
+const WINDOWS_PROCESS_SCAN_TIMEOUT_MS = 8000;
+const PROCESS_SCAN_MAX_BUFFER = 8 * 1024 * 1024;
+const WINDOWS_PROCESS_SCAN_MAX_BUFFER = 32 * 1024 * 1024;
+// This covers common Node flags that take a separate value; unknown flags may
+// still be heuristic misses, but process warnings are best-effort only.
+const NODE_OPTIONS_WITH_VALUE = new Set([
+  '-C',
+  '--conditions',
+  '-e',
+  '--eval',
+  '--experimental-loader',
+  '--import',
+  '--loader',
+  '-r',
+  '--require',
+]);
+
+function isTruthyEnv(value) {
+  return value === '1' || value === 'true';
+}
+
+function filterBackgroundArgs(args) {
+  return args.filter(arg => !BACKGROUND_ARG_RE.test(arg));
+}
+
+function parseProcessList(output) {
+  return output
+    .split('\n')
+    .map(line => line.trim())
+    .filter(Boolean)
+    .map(line => {
+      const match = line.match(/^(\d+)\s+(.+)$/);
+      if (!match) {
+        return null;
+      }
+      return {
+        pid: Number(match[1]),
+        command: match[2],
+      };
+    })
+    .filter(Boolean);
+}
+
+function parseWindowsProcessList(output) {
+  const parsed = JSON.parse(output || '[]');
+  const entries = Array.isArray(parsed) ? parsed : [parsed];
+
+  return entries
+    .map(entry => ({
+      pid: Number(entry.ProcessId),
+      command: entry.CommandLine || '',
+    }))
+    .filter(entry => Number.isFinite(entry.pid) && entry.command);
+}
+
+function commandTokens(command) {
+  const tokens = [];
+  const tokenRe = /"([^"]*)"|'([^']*)'|[^\s]+/g;
+  let match;
+
+  while ((match = tokenRe.exec(command)) !== null) {
+    tokens.push(match[1] ?? match[2] ?? match[0]);
+  }
+
+  return tokens;
+}
+
+function commandBasename(token) {
+  return path.basename(token.replace(/^"|"$/g, '').replace(/\\/g, '/')).toLowerCase();
+}
+
+function isAgentTankExecutable(token) {
+  const executable = commandBasename(token);
+  return executable === 'agent-tank' ||
+    executable === 'agent-tank.cmd' ||
+    executable === 'agent-tank.ps1';
+}
+
+function isAgentTankNodeScript(token) {
+  const scriptPath = token.replace(/^"|"$/g, '');
+  return AGENT_TANK_BIN_RE.test(scriptPath) || isAgentTankExecutable(scriptPath);
+}
+
+function isNodeInterpreter(token) {
+  return /^(?:node|nodejs|node\d*)(?:\.exe)?$/.test(commandBasename(token));
+}
+
+function findNodeScriptToken(tokens) {
+  for (let index = 1; index < tokens.length; index += 1) {
+    const token = tokens[index];
+
+    if (NODE_OPTIONS_WITH_VALUE.has(token)) {
+      index += 1;
+      continue;
+    }
+
+    if (token.startsWith('--') && NODE_OPTIONS_WITH_VALUE.has(token.split('=')[0])) {
+      continue;
+    }
+
+    if (token.startsWith('-')) {
+      continue;
+    }
+
+    return token;
+  }
+
+  return null;
+}
+
+function isAgentTankCommand(command) {
+  const tokens = commandTokens(command);
+  if (tokens.length === 0) {
+    return false;
+  }
+
+  if (isAgentTankExecutable(tokens[0])) {
+    return true;
+  }
+
+  if (!isNodeInterpreter(tokens[0])) {
+    return false;
+  }
+
+  const scriptToken = findNodeScriptToken(tokens);
+  return Boolean(scriptToken && isAgentTankNodeScript(scriptToken));
+}
+
+function getProcessScanCommand(platform, scanTimeoutMs) {
+  const timeout = scanTimeoutMs ?? (
+    platform === 'win32' ? WINDOWS_PROCESS_SCAN_TIMEOUT_MS : PROCESS_SCAN_TIMEOUT_MS
+  );
+
+  if (platform === 'win32') {
+    return {
+      file: 'powershell.exe',
+      args: [
+        '-NoProfile',
+        '-Command',
+        'Get-CimInstance Win32_Process | Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress',
+      ],
+      options: {
+        encoding: 'utf8',
+        maxBuffer: WINDOWS_PROCESS_SCAN_MAX_BUFFER,
+        timeout,
+      },
+      parse: parseWindowsProcessList,
+    };
+  }
+
+  return {
+    file: 'ps',
+    args: ['-eo', 'pid=,args='],
+    options: {
+      encoding: 'utf8',
+      maxBuffer: PROCESS_SCAN_MAX_BUFFER,
+      timeout,
+    },
+    parse: parseProcessList,
+  };
+}
+
+function filterAgentTankProcesses(processes, currentPid) {
+  return processes
+    .filter(entry => entry.pid !== currentPid)
+    .filter(entry => isAgentTankCommand(entry.command));
+}
+
+function execFilePromise(execFileFn, file, args, options) {
+  return new Promise((resolve, reject) => {
+    execFileFn(file, args, options, (err, stdout) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+
+      resolve(stdout);
+    });
+  });
+}
+
+async function findAgentTankProcessesAsync({
+  currentPid = process.pid,
+  execFileFn = execFile,
+  platform = process.platform,
+  scanTimeoutMs,
+} = {}) {
+  const command = getProcessScanCommand(platform, scanTimeoutMs);
+
+  try {
+    const output = await execFilePromise(execFileFn, command.file, command.args, command.options);
+    return filterAgentTankProcesses(command.parse(output), currentPid);
+  } catch (_err) {
+    return [];
+  }
+}
+
+module.exports = {
+  filterBackgroundArgs,
+  findAgentTankProcessesAsync,
+  isAgentTankCommand,
+  isTruthyEnv,
+  parseProcessList,
+  parseWindowsProcessList,
+  PROCESS_SCAN_MAX_BUFFER,
+  PROCESS_SCAN_TIMEOUT_MS,
+  WINDOWS_PROCESS_SCAN_MAX_BUFFER,
+  WINDOWS_PROCESS_SCAN_TIMEOUT_MS,
+};

package/src/shutdown-handler.js

@@ -1,5 +1,16 @@
+// Signals that should trigger a graceful shutdown so agent PTY processes are
+// cleaned up instead of leaking as orphans. SIGINT and SIGHUP matter for
+// detached/background runs that have no TTY (where the stdin Ctrl+C watcher
+// below does not apply). SIGKILL is intentionally absent — it cannot be caught.
+const SHUTDOWN_SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP'];
+
 function installShutdownHandlers({ shutdown, processObj = process, stdin = process.stdin }) {
-  const onSigterm = () => shutdown('SIGTERM');
+  const signalHandlers = SHUTDOWN_SIGNALS.map(signal => {
+    const handler = () => shutdown(signal);
+    processObj.on(signal, handler);
+    return [signal, handler];
+  });
+
   const onStdinData = (chunk) => {
     const data = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk || ''));
     if (data.includes(0x03)) {
@@ -7,8 +18,6 @@ function installShutdownHandlers({ shutdown, processObj = process, stdin = proce
     }
   };
 
-  processObj.on('SIGTERM', onSigterm);
-
   const shouldWatchStdin = stdin && stdin.isTTY && typeof stdin.on === 'function';
   if (shouldWatchStdin) {
     stdin.on('data', onStdinData);
@@ -18,7 +27,9 @@ function installShutdownHandlers({ shutdown, processObj = process, stdin = proce
   }
 
   return () => {
-    processObj.off('SIGTERM', onSigterm);
+    for (const [signal, handler] of signalHandlers) {
+      processObj.off(signal, handler);
+    }
 
     if (shouldWatchStdin) {
       stdin.off('data', onStdinData);

package/src/status-page.js

@@ -26,10 +26,7 @@ function escapeHtml(value) {
     .replace(/'/g, ''');
 }
 
-function statusPage(status) {
-  const agents = Object.entries(status);
-
-  // Calculate the maximum lastUpdated timestamp across all agents for global display
+function getGlobalLastChecked(agents) {
   const maxLastUpdated = agents.reduce((max, [, data]) => {
     if (data.lastUpdated) {
       const ts = new Date(data.lastUpdated).getTime();
@@ -38,42 +35,50 @@ function statusPage(status) {
     return max;
   }, 0);
 
-  const globalLastChecked = maxLastUpdated > 0
+  return maxLastUpdated > 0
     ? new Date(maxLastUpdated).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
     : null;
+}
+
+function renderPublicStatusBadge(publicStatus) {
+  const badgeClass = publicStatus ? getStatusBadgeClass(publicStatus.status) : 'status-badge-grey';
+  const badgeText = publicStatus ? getStatusText(publicStatus.status) : 'Unknown';
+  const badgeTitle = escapeHtml(publicStatus?.description || 'Unable to fetch status');
 
-  const agentCards = agents.map(([name, data]) => {
-    const usageHtml = formatUsage(name, data.usage);
-    const statusClass = data.error ? 'error' : data.isRefreshing ? 'refreshing' : 'ok';
-
-    const icon = agentIcons[name] || '';
-    const displayName = getAgentDisplayName(name);
-
-    // Public API status badge
-    const publicStatus = data.publicStatus;
-    const badgeClass = publicStatus ? getStatusBadgeClass(publicStatus.status) : 'status-badge-grey';
-    const badgeText = publicStatus ? getStatusText(publicStatus.status) : 'Unknown';
-    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 or metadata.updateAvailable.
-    const version = data.usage?.version || data.metadata?.updateAvailable;
-    const updateHtml = (version && version.current && version.latest && version.current !== version.latest)
-      ? `<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 = errorHtml || authHtml || updateHtml;
-    const footerHtml = hasFooterContent
-      ? `<div class="card-footer">${errorHtml}${authHtml}${updateHtml}</div>`
-      : '';
-
-    return `
+  return `<span class="status-badge ${badgeClass}" title="${badgeTitle}">${badgeText}</span>`;
+}
+
+function renderVersionUpdate(data) {
+  const version = data.usage?.version || data.metadata?.updateAvailable;
+
+  if (!version || !version.current || !version.latest || version.current === version.latest) {
+    return '';
+  }
+
+  return `<div class="version-update-notice">Update available: v${version.current} → v${version.latest}</div>`;
+}
+
+function renderCardFooter(data) {
+  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>` : '';
+  const updateHtml = renderVersionUpdate(data);
+
+  return errorHtml || authHtml || updateHtml
+    ? `<div class="card-footer">${errorHtml}${authHtml}${updateHtml}</div>`
+    : '';
+}
+
+function renderAgentCard([name, data]) {
+  const usageHtml = formatUsage(name, data.usage);
+  const statusClass = data.error ? 'error' : data.isRefreshing ? 'refreshing' : 'ok';
+  const icon = agentIcons[name] || '';
+  const displayName = getAgentDisplayName(name);
+  const statusBadgeHtml = renderPublicStatusBadge(data.publicStatus);
+  const footerHtml = renderCardFooter(data);
+
+  return `
       <div class="agent-card ${statusClass} agent-${name}">
         <h2 class="agent-heading">
           ${icon}
@@ -87,7 +92,12 @@ function statusPage(status) {
         ${footerHtml}
       </div>
     `;
-  }).join('');
+}
+
+function statusPage(status) {
+  const agents = Object.entries(status);
+  const globalLastChecked = getGlobalLastChecked(agents);
+  const agentCards = agents.map(renderAgentCard).join('');
 
   return `<!DOCTYPE html>
 <html>