nightytidy 0.2.13 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nightytidy",
-  "version": "0.2.13",
+  "version": "0.3.1",
   "description": "Automated overnight codebase improvement through Claude Code",
   "license": "MIT",
   "author": "Dorian Spitz",

package/src/agent/firebase-auth.js

@@ -1,3 +1,5 @@
+import fs from 'node:fs';
+import path from 'node:path';
 import { debug, info, warn } from '../logger.js';
 
 const REFRESH_BUFFER_MS = 15 * 60_000; // Request refresh 15 min before expiry
@@ -58,6 +60,7 @@ export class FirebaseAuth {
     }
     const remainMin = Math.round((this.expiresAt - Date.now()) / 60_000);
     debug(`Firebase auth token updated (expires in ${remainMin}m)`);
+    this.saveTokenToDisk(token);
     this._replayQueue();
   }
 
@@ -128,6 +131,60 @@ export class FirebaseAuth {
     this._replayCallback(queue);
   }
 
+  /**
+   * Persist the raw JWT token to `{configDir}/firebase-token.json`.
+   * Atomic write (temp file + rename). Best-effort — logs a warning on failure.
+   */
+  saveTokenToDisk(token) {
+    try {
+      const tokenPath = path.join(this.configDir, 'firebase-token.json');
+      const tmpPath = tokenPath + '.tmp';
+      const data = JSON.stringify({ token, savedAt: Date.now() });
+      fs.writeFileSync(tmpPath, data, 'utf-8');
+      fs.renameSync(tmpPath, tokenPath);
+      debug('Firebase token saved to disk');
+    } catch (err) {
+      warn(`Failed to save Firebase token to disk: ${err.message}`);
+    }
+  }
+
+  /**
+   * Load a previously saved Firebase token from `{configDir}/firebase-token.json`.
+   * Returns the token string, or null if missing, corrupt, or expired.
+   * Deletes the file if the token is expired.
+   */
+  loadTokenFromDisk() {
+    const tokenPath = path.join(this.configDir, 'firebase-token.json');
+    try {
+      const raw = fs.readFileSync(tokenPath, 'utf-8');
+      const { token } = JSON.parse(raw);
+      if (!token || typeof token !== 'string') return null;
+
+      const expiry = FirebaseAuth.parseJwtExpiry(token);
+      if (expiry !== null && expiry <= Date.now()) {
+        // Token is expired — clean up the file
+        try { fs.unlinkSync(tokenPath); } catch { /* ignore */ }
+        debug('Stored Firebase token is expired — removed from disk');
+        return null;
+      }
+      return token;
+    } catch {
+      // File missing or corrupt — not an error
+      return null;
+    }
+  }
+
+  /**
+   * Attempt to restore Firebase auth state from the on-disk token.
+   * Returns true if a valid token was found and restored, false otherwise.
+   */
+  restoreToken() {
+    const token = this.loadTokenFromDisk();
+    if (!token) return false;
+    this.setToken(token);
+    return true;
+  }
+
   // Full OAuth flow will be implemented in integration phase
   // For now, this is a placeholder that stores/retrieves tokens
   async authenticate() {

package/src/agent/firestore-poller.js

@@ -0,0 +1,191 @@
+import { debug, warn } from '../logger.js';
+
+/**
+ * FirestorePoller — polls Firestore REST API for queued runs.
+ *
+ * This is a SECONDARY trigger alongside the existing WebSocket command path.
+ * It allows the agent to pick up runs queued by the web app even when no
+ * browser is connected.
+ *
+ * Never throws — all errors are logged and swallowed.
+ */
+export class FirestorePoller {
+  /**
+   * @param {object} opts
+   * @param {import('./firebase-auth.js').FirebaseAuth} opts.firebaseAuth
+   * @param {string} opts.projectId  Firebase project ID (e.g. 'nightytidy-web')
+   * @param {(run: object) => void} opts.onQueuedRunFound  Callback when a run is found
+   */
+  constructor({ firebaseAuth, projectId, onQueuedRunFound }) {
+    this._firebaseAuth = firebaseAuth;
+    this._projectId = projectId;
+    this._onQueuedRunFound = onQueuedRunFound;
+    this._intervalId = null;
+  }
+
+  /**
+   * Start polling on a fixed interval.
+   * @param {number} intervalMs  Polling interval (default 30 s)
+   */
+  start(intervalMs = 30_000) {
+    if (this._intervalId !== null) return; // already running
+    debug(`FirestorePoller: starting (interval ${intervalMs}ms)`);
+    this._intervalId = setInterval(() => { this.poll(); }, intervalMs);
+  }
+
+  /** Stop polling. */
+  stop() {
+    if (this._intervalId !== null) {
+      clearInterval(this._intervalId);
+      this._intervalId = null;
+      debug('FirestorePoller: stopped');
+    }
+  }
+
+  /**
+   * Run a single poll cycle.
+   * Exported so tests can call it directly without timers.
+   */
+  async poll() {
+    if (!this._firebaseAuth.isAuthenticated()) {
+      debug('FirestorePoller: skipping poll — not authenticated');
+      return;
+    }
+
+    const token = this._firebaseAuth.getToken();
+    if (!token) {
+      debug('FirestorePoller: skipping poll — no token');
+      return;
+    }
+
+    const uid = FirestorePoller.extractUidFromToken(token);
+    if (!uid) {
+      warn('FirestorePoller: could not extract UID from token — skipping poll');
+      return;
+    }
+
+    const url = `https://firestore.googleapis.com/v1/projects/${this._projectId}/databases/(default)/documents/users/${uid}:runQuery`;
+
+    const body = JSON.stringify({
+      structuredQuery: {
+        from: [{ collectionId: 'runs' }],
+        where: {
+          fieldFilter: {
+            field: { fieldPath: 'status' },
+            op: 'EQUAL',
+            value: { stringValue: 'queued' },
+          },
+        },
+        orderBy: [{ field: { fieldPath: 'startedAt' }, direction: 'ASCENDING' }],
+        limit: 1,
+      },
+    });
+
+    let response;
+    try {
+      response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${token}`,
+          'Content-Type': 'application/json',
+        },
+        body,
+      });
+    } catch (err) {
+      warn(`FirestorePoller: network error during poll — ${err.message}`);
+      return;
+    }
+
+    if (!response.ok) {
+      warn(`FirestorePoller: poll returned HTTP ${response.status} — skipping`);
+      return;
+    }
+
+    let results;
+    try {
+      results = await response.json();
+    } catch (err) {
+      warn(`FirestorePoller: failed to parse Firestore response — ${err.message}`);
+      return;
+    }
+
+    // Firestore REST runQuery returns an array of { document } objects.
+    // An empty result set is returned as [{}] (object with no document field).
+    if (!Array.isArray(results) || results.length === 0) {
+      return;
+    }
+
+    const first = results[0];
+    if (!first || !first.document) {
+      // No queued runs found
+      return;
+    }
+
+    let run;
+    try {
+      run = FirestorePoller._parseRunDocument(first.document);
+    } catch (err) {
+      warn(`FirestorePoller: failed to parse run document — ${err.message}`);
+      return;
+    }
+
+    debug(`FirestorePoller: found queued run ${run.runId} for project ${run.projectId}`);
+    this._onQueuedRunFound(run);
+  }
+
+  /**
+   * Extract UID from a Firebase ID token (JWT).
+   * Reads `user_id` or `sub` from the unverified payload — no crypto needed.
+   * Returns null on any parse failure.
+   *
+   * @param {string} token
+   * @returns {string|null}
+   */
+  static extractUidFromToken(token) {
+    try {
+      const parts = token.split('.');
+      if (parts.length !== 3) return null;
+      const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+      return payload.user_id || payload.sub || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Parse a Firestore document object into a plain run object.
+   * Throws on missing required fields so callers can log and skip.
+   *
+   * @param {{ name: string, fields: object }} doc
+   * @returns {{ runId, projectId, projectName, selectedSteps, timeout }}
+   */
+  static _parseRunDocument(doc) {
+    // Document name format:
+    // projects/{project}/databases/(default)/documents/users/{uid}/runs/{runId}
+    const nameParts = doc.name.split('/');
+    const runId = nameParts[nameParts.length - 1];
+
+    const fields = doc.fields || {};
+
+    const projectId = fields.projectId?.stringValue ?? null;
+    const projectName = fields.projectName?.stringValue ?? null;
+
+    // selectedSteps can be an arrayValue of integerValue/stringValue entries
+    let selectedSteps = [];
+    if (fields.selectedSteps?.arrayValue?.values) {
+      selectedSteps = fields.selectedSteps.arrayValue.values.map((v) => {
+        if (v.integerValue !== undefined) return Number(v.integerValue);
+        if (v.stringValue !== undefined) return Number(v.stringValue);
+        return null;
+      }).filter((n) => n !== null && !isNaN(n));
+    }
+
+    const timeoutRaw = fields.timeout?.integerValue ?? fields.timeout?.stringValue ?? null;
+    const timeout = timeoutRaw !== null ? Number(timeoutRaw) : 45;
+
+    if (!runId) throw new Error('missing runId in document name');
+    if (!projectId) throw new Error('missing projectId field');
+
+    return { runId, projectId, projectName, selectedSteps, timeout };
+  }
+}

package/src/agent/index.js

@@ -12,9 +12,11 @@ import { WebhookDispatcher } from './webhook-dispatcher.js';
 import { CliBridge } from './cli-bridge.js';
 import { AgentGit } from './git-integration.js';
 import { FirebaseAuth } from './firebase-auth.js';
+import { FirestorePoller } from './firestore-poller.js';
 import { acquireKeepAwake, releaseKeepAwake } from './keep-awake.js';
 
 const FIREBASE_WEBHOOK_URL = 'https://webhookingest-24h6taciuq-uc.a.run.app';
+const FIREBASE_PROJECT_ID = process.env.NIGHTYTIDY_FIREBASE_PROJECT_ID || 'nightytidy-web';
 
 // Read version from package.json so it stays in sync with npm
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -26,6 +28,10 @@ export async function startAgent() {
   ensureConfigDir(configDir);
   const config = readConfig(configDir);
 
+  // Write PID file so stop/status subcommands can find this process
+  const pidPath = path.join(configDir, 'agent.pid');
+  fs.writeFileSync(pidPath, String(process.pid));
+
   info(`NightyTidy Agent starting on ${config.machine}`);
 
   // Initialize components
@@ -34,6 +40,14 @@ export async function startAgent() {
 
   const runQueue = new RunQueue(configDir);
   const firebaseAuth = new FirebaseAuth(configDir);
+
+  // Restore Firebase token from disk (survives reboots)
+  if (firebaseAuth.restoreToken()) {
+    debug('Restored Firebase token from disk');
+  } else {
+    debug('No stored Firebase token — waiting for web app to provide one');
+  }
+
   const webhookDispatcher = new WebhookDispatcher({
     machine: config.machine,
     version: AGENT_VERSION,
@@ -464,6 +478,37 @@ export async function startAgent() {
     }
   }
 
+  // Start Firestore polling — secondary trigger for queued runs when no browser is connected.
+  // The poller is additive; WebSocket commands still work as the primary path.
+  const poller = new FirestorePoller({
+    firebaseAuth,
+    projectId: FIREBASE_PROJECT_ID,
+    onQueuedRunFound: (run) => {
+      // Check if this run's project is registered locally
+      const project = projectManager.getProject(run.projectId);
+      if (!project) {
+        debug(`Polled run ${run.runId} for unknown project ${run.projectId} — skipping`);
+        return;
+      }
+      // Check if already in local queue or currently running
+      const queue = runQueue.getQueue();
+      const isAlreadyQueued = queue.some(q => q.id === run.runId) ||
+                              (runQueue.getCurrent()?.id === run.runId);
+      if (isAlreadyQueued) return;
+
+      // Enqueue locally and process
+      debug(`Polled queued run ${run.runId} for ${project.name}`);
+      runQueue.enqueue({
+        projectId: run.projectId,
+        steps: run.selectedSteps,
+        timeout: run.timeout,
+      });
+      wsServer.broadcast({ type: 'queue-updated', queue: runQueue.getQueue() });
+      if (!runQueue.getCurrent()) processQueue();
+    },
+  });
+  poller.start(30_000);
+
   // Run execution handler
   async function handleStartRun(msg, reply) {
     const project = projectManager.getProject(msg.projectId);
@@ -1066,8 +1111,11 @@ export async function startAgent() {
     info('Agent shutting down...');
     releaseKeepAwake();
     saveInterruptedState();
+    poller.stop();
     scheduler.stopAll();
     await wsServer.stop();
+    // Remove PID file on clean exit
+    try { fs.unlinkSync(pidPath); } catch { /* ignore — may already be gone */ }
     info('Agent stopped');
     process.exit(0);
   };

package/src/agent/service.js

@@ -0,0 +1,196 @@
+/**
+ * OS service registration for the NightyTidy agent.
+ *
+ * Registers the agent to start on login/boot using the platform-native
+ * service mechanism (Windows Task Scheduler, macOS LaunchAgent, Linux systemd).
+ *
+ * Never throws — all functions return result objects.
+ */
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { debug } from '../logger.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// package root is two levels up from src/agent/
+const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
+const BIN_PATH = path.join(PACKAGE_ROOT, 'bin', 'nightytidy.js');
+
+const SERVICE_NAME = 'NightyTidy Agent';
+const PLIST_ID = 'com.nightytidy.agent';
+const PLIST_PATH = path.join(os.homedir(), 'Library', 'LaunchAgents', `${PLIST_ID}.plist`);
+const SYSTEMD_DIR = path.join(os.homedir(), '.config', 'systemd', 'user');
+const SYSTEMD_PATH = path.join(SYSTEMD_DIR, 'nightytidy.service');
+
+/**
+ * Returns the command string used to start the agent.
+ * Format: `"<node>" "<nightytidy bin>" agent`
+ */
+export function getAgentStartCommand() {
+  return `"${process.execPath}" "${BIN_PATH}" agent`;
+}
+
+/**
+ * Registers the agent as an OS service (run on login).
+ * @returns {{ success: true } | { success: false, error: string, fallbackInstructions: string }}
+ */
+export function registerService() {
+  const cmd = getAgentStartCommand();
+  debug(`Registering service with command: ${cmd}`);
+
+  try {
+    if (process.platform === 'win32') {
+      _registerWindows(cmd);
+    } else if (process.platform === 'darwin') {
+      _registerMacOS(cmd);
+    } else {
+      _registerLinux(cmd);
+    }
+    debug('Service registered successfully');
+    return { success: true };
+  } catch (err) {
+    const error = err.message || String(err);
+    debug(`Service registration failed: ${error}`);
+    return {
+      success: false,
+      error,
+      fallbackInstructions: `To start manually on login, add this to your startup: ${cmd}`,
+    };
+  }
+}
+
+/**
+ * Unregisters the OS service.
+ * @returns {{ success: true } | { success: false, error: string }}
+ */
+export function unregisterService() {
+  debug('Unregistering service');
+
+  try {
+    if (process.platform === 'win32') {
+      _unregisterWindows();
+    } else if (process.platform === 'darwin') {
+      _unregisterMacOS();
+    } else {
+      _unregisterLinux();
+    }
+    debug('Service unregistered successfully');
+    return { success: true };
+  } catch (err) {
+    const error = err.message || String(err);
+    debug(`Service unregistration failed: ${error}`);
+    return { success: false, error };
+  }
+}
+
+// --- Platform implementations ---
+
+/**
+ * Windows: Use the Startup folder (no admin needed).
+ * Writes a .vbs wrapper script that launches the agent hidden (no console window).
+ * Falls back to schtasks if Startup folder isn't writable.
+ */
+const STARTUP_DIR = process.platform === 'win32'
+  ? path.join(os.homedir(), 'AppData', 'Roaming', 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup')
+  : '';
+const STARTUP_VBS = path.join(STARTUP_DIR, 'NightyTidy Agent.vbs');
+
+function _registerWindows(cmd) {
+  // Primary: Startup folder (no admin required)
+  try {
+    // VBS wrapper runs the agent without showing a console window
+    const vbs = `' NightyTidy Agent — auto-start on login\r\nSet ws = CreateObject("WScript.Shell")\r\nws.Run ${JSON.stringify(cmd)}, 0, False\r\n`;
+    fs.mkdirSync(STARTUP_DIR, { recursive: true });
+    fs.writeFileSync(STARTUP_VBS, vbs, 'utf-8');
+    debug('Registered via Windows Startup folder');
+    return;
+  } catch (err) {
+    debug(`Startup folder failed: ${err.message}, trying schtasks`);
+  }
+
+  // Fallback: Task Scheduler (needs admin on some systems)
+  execSync(
+    `schtasks /create /tn "${SERVICE_NAME}" /tr "${cmd}" /sc onlogon /rl LIMITED /f`,
+    { stdio: 'pipe' },
+  );
+}
+
+function _unregisterWindows() {
+  // Remove Startup folder entry
+  try {
+    if (fs.existsSync(STARTUP_VBS)) {
+      fs.unlinkSync(STARTUP_VBS);
+      debug('Removed Startup folder entry');
+    }
+  } catch { /* ignore */ }
+
+  // Also try removing schtasks entry (may not exist)
+  try {
+    execSync(`schtasks /delete /tn "${SERVICE_NAME}" /f`, { stdio: 'pipe' });
+    debug('Removed Task Scheduler entry');
+  } catch { /* ignore — may not have been registered via schtasks */ }
+}
+
+function _registerMacOS(cmd) {
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${PLIST_ID}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${process.execPath}</string>
+    <string>${BIN_PATH}</string>
+    <string>agent</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${path.join(os.homedir(), '.nightytidy', 'agent-stdout.log')}</string>
+  <key>StandardErrorPath</key>
+  <string>${path.join(os.homedir(), '.nightytidy', 'agent-stderr.log')}</string>
+</dict>
+</plist>
+`;
+  const launchAgentsDir = path.join(os.homedir(), 'Library', 'LaunchAgents');
+  fs.mkdirSync(launchAgentsDir, { recursive: true });
+  fs.writeFileSync(PLIST_PATH, plist, 'utf-8');
+  execSync(`launchctl load "${PLIST_PATH}"`, { stdio: 'pipe' });
+}
+
+function _unregisterMacOS() {
+  if (fs.existsSync(PLIST_PATH)) {
+    execSync(`launchctl unload "${PLIST_PATH}"`, { stdio: 'pipe' });
+    fs.unlinkSync(PLIST_PATH);
+  }
+}
+
+function _registerLinux(cmd) {
+  const unit = `[Unit]
+Description=NightyTidy Agent
+After=network.target
+
+[Service]
+ExecStart=${process.execPath} "${BIN_PATH}" agent
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+`;
+  fs.mkdirSync(SYSTEMD_DIR, { recursive: true });
+  fs.writeFileSync(SYSTEMD_PATH, unit, 'utf-8');
+  execSync('systemctl --user enable --now nightytidy.service', { stdio: 'pipe' });
+}
+
+function _unregisterLinux() {
+  execSync('systemctl --user disable --now nightytidy.service', { stdio: 'pipe' });
+  if (fs.existsSync(SYSTEMD_PATH)) {
+    fs.unlinkSync(SYSTEMD_PATH);
+  }
+}

package/src/agent/setup-flow.js

@@ -0,0 +1,190 @@
+/**
+ * @fileoverview One-liner setup command for the NightyTidy agent.
+ *
+ * Orchestrates: browser OAuth → token save → service registration → agent start.
+ *
+ * Error contract: Never throws. Prints errors and calls process.exit(1) on failure.
+ *
+ * @module agent/setup-flow
+ */
+
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import chalk from 'chalk';
+import { getConfigDir, ensureConfigDir } from './config.js';
+import { registerService } from './service.js';
+import { FirebaseAuth } from './firebase-auth.js';
+import { debug } from '../logger.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// package root is two levels up from src/agent/
+const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
+const BIN_PATH = path.join(PACKAGE_ROOT, 'bin', 'nightytidy.js');
+
+const AUTH_BASE_URL = 'https://nightytidy.com/auth/agent';
+
+/**
+ * Open a URL in the default system browser.
+ * Fire-and-forget — detached, stdio ignored.
+ * @param {string} url
+ */
+function openBrowser(url) {
+  const platform = process.platform;
+  if (platform === 'darwin') {
+    spawn('open', [url], { detached: true, stdio: 'ignore' }).unref();
+  } else if (platform === 'win32') {
+    spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref();
+  } else {
+    spawn('xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
+  }
+}
+
+/**
+ * Start a temporary HTTP server on 127.0.0.1 and wait for a POST /callback.
+ * Resolves with the parsed JSON body, or rejects after a timeout.
+ * @returns {{ server: import('node:http').Server, port: number, waitForCallback: () => Promise<object> }}
+ */
+function createCallbackServer() {
+  let resolvePayload;
+  let rejectPayload;
+
+  const waitForCallback = () =>
+    new Promise((resolve, reject) => {
+      resolvePayload = resolve;
+      rejectPayload = reject;
+    });
+
+  const server = createServer((req, res) => {
+    // CORS preflight — the web app may send OPTIONS first
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, {
+        'Access-Control-Allow-Origin': 'https://nightytidy.com',
+        'Access-Control-Allow-Methods': 'POST, OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type',
+      });
+      res.end();
+      return;
+    }
+
+    if (req.method !== 'POST' || req.url !== '/callback') {
+      res.writeHead(404);
+      res.end('Not found');
+      return;
+    }
+
+    let body = '';
+    req.on('data', (chunk) => { body += chunk; });
+    req.on('end', () => {
+      try {
+        const payload = JSON.parse(body);
+        res.writeHead(200, {
+          'Content-Type': 'application/json',
+          'Access-Control-Allow-Origin': 'https://nightytidy.com',
+        });
+        res.end(JSON.stringify({ ok: true }));
+        debug('OAuth callback received');
+        resolvePayload(payload);
+      } catch (err) {
+        res.writeHead(400);
+        res.end('Bad request');
+        rejectPayload(new Error(`Invalid callback body: ${err.message}`));
+      }
+    });
+  });
+
+  // Bind to random port on localhost
+  server.listen(0, '127.0.0.1');
+
+  return { server, waitForCallback };
+}
+
+/**
+ * Main setup flow. Runs all four steps sequentially.
+ * Never throws — prints errors and calls process.exit(1).
+ */
+export async function setupAgent() {
+  console.log(chalk.bold.cyan('\nNightyTidy Agent Setup'));
+  console.log(chalk.dim('────────────────────────────────────────'));
+
+  // ── Step 1: Authenticate ──────────────────────────────────────────────────
+
+  console.log(chalk.bold('\nStep 1: Authenticate'));
+
+  const { server, waitForCallback } = createCallbackServer();
+
+  // Wait for the server to be assigned a port
+  await new Promise((resolve) => server.once('listening', resolve));
+  const port = server.address().port;
+  debug(`Callback server listening on 127.0.0.1:${port}`);
+
+  const callbackUrl = `http://127.0.0.1:${port}/callback`;
+  const authUrl = `${AUTH_BASE_URL}?callback=${encodeURIComponent(callbackUrl)}`;
+
+  console.log(chalk.dim(`Opening: ${authUrl}`));
+  openBrowser(authUrl);
+  console.log(chalk.yellow('Waiting for authorization in browser...'));
+
+  let payload;
+  try {
+    payload = await waitForCallback();
+  } catch (err) {
+    server.close();
+    console.error(chalk.red(`\nAuthorization failed: ${err.message}`));
+    process.exit(1);
+  } finally {
+    server.close();
+  }
+
+  if (payload.error) {
+    console.error(chalk.red(`\nAuthorization error: ${payload.error}`));
+    process.exit(1);
+  }
+
+  // ── Step 2: Save credentials ──────────────────────────────────────────────
+
+  console.log(chalk.bold('\nStep 2: Save credentials'));
+
+  const configDir = getConfigDir();
+  ensureConfigDir(configDir);
+
+  const firebaseAuth = new FirebaseAuth(configDir);
+  const token = payload.token || payload.idToken;
+
+  if (!token) {
+    console.error(chalk.red('\nNo token received in callback. Cannot authenticate.'));
+    process.exit(1);
+  }
+
+  firebaseAuth.setToken(token);
+  console.log(chalk.green('  Authenticated'));
+
+  // ── Step 3: Register service ──────────────────────────────────────────────
+
+  console.log(chalk.bold('\nStep 3: Register auto-start service'));
+
+  const serviceResult = registerService();
+  if (serviceResult.success) {
+    console.log(chalk.green('  Service registered — agent will start automatically on login'));
+  } else {
+    console.log(chalk.yellow(`  Warning: Could not register service: ${serviceResult.error}`));
+    console.log(chalk.dim(`  ${serviceResult.fallbackInstructions}`));
+  }
+
+  // ── Step 4: Start agent ───────────────────────────────────────────────────
+
+  console.log(chalk.bold('\nStep 4: Start agent'));
+
+  spawn(process.execPath, [BIN_PATH, 'agent'], { detached: true, stdio: 'ignore' }).unref();
+  console.log(chalk.green('  Agent started'));
+
+  // ── Done ──────────────────────────────────────────────────────────────────
+
+  console.log(chalk.dim('\n────────────────────────────────────────'));
+  console.log(
+    chalk.bold.green('Done!') +
+    ' Your agent is running. Visit nightytidy.com to add projects and configure schedules.',
+  );
+  console.log('');
+}

package/src/cli.js

@@ -814,11 +814,95 @@ export async function run() {
     .option('--skip-dashboard', 'Skip launching the standalone dashboard server (used by GUI)')
     .option('--resume', 'Resume a previously paused run (usage limit / manual restart)');
 
+  // Handle 'setup-agent' before 'agent' — process.argv.includes('agent') would
+  // also match 'setup-agent', so this check must come first.
+  if (process.argv.includes('setup-agent')) {
+    const { initLogger } = await import('./logger.js');
+    initLogger(process.cwd());
+    const { setupAgent } = await import('./agent/setup-flow.js');
+    await setupAgent();
+    return;
+  }
+
   // Handle 'agent' subcommand before Commander parses — avoids breaking
   // Commander's option-only routing when a .command() subcommand is registered.
   if (process.argv.includes('agent')) {
     const { initLogger } = await import('./logger.js');
     initLogger(process.cwd());
+
+    // Determine the subcommand that follows 'agent' in argv
+    const agentIdx = process.argv.indexOf('agent');
+    const agentSub = process.argv[agentIdx + 1];
+
+    if (agentSub === 'stop') {
+      // Send SIGTERM to the running agent via its PID file
+      const { getConfigDir } = await import('./agent/config.js');
+      const fsModule = await import('node:fs');
+      const pathModule = await import('node:path');
+      const pidPath = pathModule.default.join(getConfigDir(), 'agent.pid');
+      try {
+        const pid = parseInt(fsModule.default.readFileSync(pidPath, 'utf-8').trim(), 10);
+        process.kill(pid, 'SIGTERM');
+        console.log(`Agent (PID ${pid}) signalled to stop.`);
+      } catch (err) {
+        console.error(`Could not stop agent: ${err.message}`);
+        console.error(`Is the agent running? Check with: nightytidy agent status`);
+        process.exitCode = 1;
+      }
+      return;
+    }
+
+    if (agentSub === 'status') {
+      const { getConfigDir } = await import('./agent/config.js');
+      const fsModule = await import('node:fs');
+      const pathModule = await import('node:path');
+      const pidPath = pathModule.default.join(getConfigDir(), 'agent.pid');
+      try {
+        const pid = parseInt(fsModule.default.readFileSync(pidPath, 'utf-8').trim(), 10);
+        process.kill(pid, 0); // signal 0 = check existence only
+        console.log(`Agent is running (PID ${pid}).`);
+      } catch {
+        console.log('Agent is not running.');
+      }
+      return;
+    }
+
+    if (agentSub === 'install-service') {
+      const { registerService } = await import('./agent/service.js');
+      const result = registerService();
+      if (result.success) {
+        console.log('NightyTidy Agent service installed. It will start automatically on login.');
+      } else {
+        console.error(`Failed to install service: ${result.error}`);
+        console.error(result.fallbackInstructions);
+        process.exitCode = 1;
+      }
+      return;
+    }
+
+    if (agentSub === 'uninstall-service') {
+      const { unregisterService } = await import('./agent/service.js');
+      // Stop the agent if it is running before removing the service
+      const { getConfigDir } = await import('./agent/config.js');
+      const fsModule = await import('node:fs');
+      const pathModule = await import('node:path');
+      const pidPath = pathModule.default.join(getConfigDir(), 'agent.pid');
+      try {
+        const pid = parseInt(fsModule.default.readFileSync(pidPath, 'utf-8').trim(), 10);
+        process.kill(pid, 'SIGTERM');
+      } catch { /* agent not running — that's fine */ }
+
+      const result = unregisterService();
+      if (result.success) {
+        console.log('NightyTidy Agent service uninstalled.');
+      } else {
+        console.error(`Failed to uninstall service: ${result.error}`);
+        process.exitCode = 1;
+      }
+      return;
+    }
+
+    // Default: no subcommand — start the agent
     const { startAgent } = await import('./agent/index.js');
     await startAgent();
     return;