@nocville/npc 0.2.2 → 0.3.0

package/dist/cjs/npcs/web-page-watcher/index.js

@@ -2,14 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebPageWatcherNPC = void 0;
 const polling_npc_js_1 = require("../../core/polling-npc.js");
+const thresholds_js_1 = require("../../core/thresholds.js");
+const screen_js_1 = require("../../core/screen.js");
+const errors_js_1 = require("../../core/errors.js");
+const http_js_1 = require("../../core/http.js");
 const defaults_js_1 = require("./defaults.js");
 const pixelate_js_1 = require("./pixelate.js");
 const capture_js_1 = require("./capture.js");
 const basic_mode_js_1 = require("./basic-mode.js");
+/** Thrown when a capture exceeds its deadline (the browser is then recycled). */
+class CaptureTimeout extends Error {
+}
 class WebPageWatcherNPC extends polling_npc_js_1.PollingNPC {
     url;
+    host;
     mode;
     chromePath;
+    chromeSandbox;
     viewportW;
     viewportH;
     screenW;
@@ -17,7 +26,10 @@ class WebPageWatcherNPC extends polling_npc_js_1.PollingNPC {
     waitUntil;
     puppeteer = null;
     browser = null;
-    browserUnavailable = false;
+    /** puppeteer-core or Chrome is missing: never retried. */
+    browserMissing = false;
+    /** Chrome failed to launch: retry after this time (epoch ms). */
+    nextLaunchAttempt = 0;
     chromeHintShown = false;
     lastHash = 0;
     changedPollsLeft = 0;
@@ -27,22 +39,41 @@ class WebPageWatcherNPC extends polling_npc_js_1.PollingNPC {
             // Floor the poll interval — screenshots are expensive.
             pollInterval: Math.max(config.pollInterval ?? defaults_js_1.DEFAULTS.pollInterval, defaults_js_1.DEFAULTS.minPollInterval),
         });
+        // The page is rendered and shown to the whole office: http(s) only, never
+        // file:, data:, chrome: or javascript: URLs.
+        if (!(0, http_js_1.isHttpUrl)(config.url)) {
+            throw new errors_js_1.NpcConfigError('--url must be an http(s) URL');
+        }
         this.url = config.url;
-        this.mode = config.mode ?? 'auto';
+        this.host = (0, basic_mode_js_1.hostnameOf)(config.url);
+        const mode = config.mode ?? 'auto';
+        if (!defaults_js_1.WATCH_MODES.includes(mode)) {
+            throw new errors_js_1.NpcConfigError(`--mode must be one of ${defaults_js_1.WATCH_MODES.join(', ')}`);
+        }
+        this.mode = mode;
+        const waitUntil = config.waitUntil ?? defaults_js_1.DEFAULTS.waitUntil;
+        if (!defaults_js_1.WAIT_UNTIL.includes(waitUntil)) {
+            throw new errors_js_1.NpcConfigError(`--wait-until must be one of ${defaults_js_1.WAIT_UNTIL.join(', ')}`);
+        }
+        this.waitUntil = waitUntil;
         this.chromePath = config.chromePath;
+        this.chromeSandbox = config.chromeSandbox ?? true;
         this.screenW = config.screenWidth ?? defaults_js_1.DEFAULTS.screenW;
         this.screenH = config.screenHeight ?? defaults_js_1.DEFAULTS.screenH;
         // Derive the viewport from the screen size for native downscaling unless the
         // user overrides it (in which case pngToPixelImage box-filters to screen).
         this.viewportW = config.viewportWidth ?? this.screenW * defaults_js_1.DEFAULTS.scaleDivisor;
         this.viewportH = config.viewportHeight ?? this.screenH * defaults_js_1.DEFAULTS.scaleDivisor;
-        this.waitUntil = config.waitUntil ?? defaults_js_1.DEFAULTS.waitUntil;
+        const sizeProblem = (0, defaults_js_1.screenSizeProblem)(this.screenW, this.screenH) ??
+            (0, defaults_js_1.viewportProblem)(this.viewportW, this.viewportH);
+        if (sizeProblem)
+            throw new errors_js_1.NpcConfigError(sizeProblem);
     }
     get name() {
         return 'web-page-watcher';
     }
     get defaultDisplayName() {
-        return (0, basic_mode_js_1.hostnameOf)(this.url);
+        return this.host;
     }
     get archetype() {
         return 'custom';
@@ -52,43 +83,58 @@ class WebPageWatcherNPC extends polling_npc_js_1.PollingNPC {
             screenType: 'web-view',
             size: { w: 4, h: 3 },
             placement: 'adjacent-wall',
-            label: (0, basic_mode_js_1.hostnameOf)(this.url),
+            label: this.host,
         };
     }
     async collect() {
         if (this.mode === 'basic')
-            return this.collectBasic();
+            return this.collectBasic(false);
         const browser = await this.ensureBrowser();
         if (!browser) {
-            // 'auto' silently degrades; explicit 'screenshot' warns once.
             this.maybeShowChromeHint();
-            return this.collectBasic();
+            return this.collectBasic(true);
+        }
+        try {
+            return await this.withDeadline(this.collectScreenshot(browser));
+        }
+        catch (err) {
+            if (this.state !== 'running')
+                throw err; // shutting down: nothing to report
+            // A crashed or wedged browser: recycle it and report this cycle from a plain fetch.
+            this.logger.warn('Screenshot failed; using a basic check this cycle', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            await this.closeBrowser();
+            return this.collectBasic(true);
         }
-        return this.collectScreenshot(browser);
     }
     async onStop() {
+        // Close Chrome first: it aborts an in-flight capture, so the base class
+        // doesn't wait out a slow page load before pushing offline.
+        await this.closeBrowser();
         await super.onStop();
-        if (this.browser) {
-            try {
-                await this.browser.close();
-            }
-            catch {
-                // best effort
-            }
-            this.browser = null;
-        }
     }
     // --- Screenshot mode ---
+    withDeadline(work) {
+        const ms = defaults_js_1.DEFAULTS.navTimeoutMs + defaults_js_1.DEFAULTS.captureGraceMs;
+        let timer;
+        const deadline = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new CaptureTimeout(`capture exceeded ${ms}ms`)), ms);
+        });
+        return Promise.race([work, deadline]).finally(() => clearTimeout(timer));
+    }
     async collectScreenshot(browser) {
         const page = await browser.newPage();
         try {
-            // deviceScaleFactor 0.125 makes Chrome rasterize the viewport down to the
-            // screen size natively (e.g. 1280×800 → 160×100); pngToPixelImage
+            // A page that alert()s would block navigation and the screenshot.
+            page.on?.('dialog', (dialog) => void dialog.dismiss().catch(() => undefined));
+            // deviceScaleFactor 1/8 makes Chrome rasterize the viewport down to the
+            // screen size natively (e.g. 1280×960 → 160×120); pngToPixelImage
             // box-filters as a fallback if it doesn't.
             await page.setViewport({
                 width: this.viewportW,
                 height: this.viewportH,
-                deviceScaleFactor: 0.125,
+                deviceScaleFactor: 1 / defaults_js_1.DEFAULTS.scaleDivisor,
             });
             let httpStatus = 0;
             let timedOut = false;
@@ -116,15 +162,14 @@ class WebPageWatcherNPC extends polling_npc_js_1.PollingNPC {
             else if (this.changedPollsLeft > 0)
                 this.changedPollsLeft--;
             const status = (0, basic_mode_js_1.statusFromHttp)(httpStatus, timedOut);
-            const host = (0, basic_mode_js_1.hostnameOf)(this.url);
             const message = changed
                 ? 'Page updated!'
                 : httpStatus
-                    ? `${host} ${httpStatus < 400 ? 'OK' : 'ERR'} (${httpStatus}, ${loadMs}ms)`
-                    : `${host} unreachable`;
+                    ? `${this.host} ${httpStatus < 400 ? 'OK' : 'ERR'} (${httpStatus}, ${loadMs}ms)`
+                    : `${this.host} ${timedOut ? 'timed out' : 'unreachable'}`;
             return {
                 status,
-                mood: moodFor(status),
+                mood: (0, thresholds_js_1.moodForStatus)(status),
                 message,
                 subStatus: this.changedPollsLeft > 0 ? 'changed' : undefined,
                 screenData,
@@ -141,74 +186,92 @@ class WebPageWatcherNPC extends polling_npc_js_1.PollingNPC {
         }
     }
     async ensureBrowser() {
-        if (this.browserUnavailable)
+        if (this.browserMissing || Date.now() < this.nextLaunchAttempt)
             return null;
         if (this.browser && (0, capture_js_1.browserConnected)(this.browser))
             return this.browser;
-        if (this.browser)
-            this.browser = null; // disconnected — relaunch
-        if (!this.puppeteer) {
-            this.puppeteer = await (0, capture_js_1.loadPuppeteer)();
-        }
+        this.browser = null; // absent or disconnected — (re)launch
+        this.puppeteer ??= await (0, capture_js_1.loadPuppeteer)();
         const chromePath = (0, capture_js_1.findChrome)(this.chromePath);
         if (!this.puppeteer || !chromePath) {
-            this.browserUnavailable = true;
+            this.browserMissing = true;
             return null;
         }
+        const { args, sandboxed } = (0, capture_js_1.chromeArgs)({
+            sandbox: this.chromeSandbox,
+            isRoot: (0, capture_js_1.runningAsRoot)(),
+        });
+        if (!sandboxed) {
+            this.logger.warn('Chrome sandbox disabled' +
+                (this.chromeSandbox ? ' (running as root)' : '') +
+                ': only watch pages you trust');
+        }
         try {
-            this.browser = await this.puppeteer.launch({
+            const browser = await this.puppeteer.launch({
                 executablePath: chromePath,
                 headless: true,
-                args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-gpu', '--hide-scrollbars'],
+                args,
             });
-            this.browser.on('disconnected', () => {
-                this.browser = null;
+            browser.on('disconnected', () => {
+                if (this.browser === browser)
+                    this.browser = null;
             });
-            return this.browser;
+            // Stopped while Chrome was starting: don't leave it running.
+            if (this.state !== 'running') {
+                await browser.close().catch(() => undefined);
+                return null;
+            }
+            this.browser = browser;
+            return browser;
         }
         catch (err) {
-            this.logger.warn('Failed to launch Chrome', {
+            this.logger.warn('Failed to launch Chrome; retrying in 10 minutes', {
                 error: err instanceof Error ? err.message : String(err),
             });
-            this.browserUnavailable = true;
+            this.nextLaunchAttempt = Date.now() + defaults_js_1.DEFAULTS.relaunchBackoffMs;
             return null;
         }
     }
+    async closeBrowser() {
+        const browser = this.browser;
+        this.browser = null;
+        if (browser)
+            await browser.close().catch(() => undefined);
+    }
     maybeShowChromeHint() {
-        if (this.chromeHintShown)
+        if (this.chromeHintShown || !this.browserMissing)
             return;
         this.chromeHintShown = true;
         this.logger.warn('Chrome/puppeteer-core unavailable — falling back to basic mode. ' +
             'Install `puppeteer-core` and Google Chrome (or set --chrome-path/CHROME_PATH) for the pixel-art TV.');
     }
     // --- Basic mode ---
-    async collectBasic() {
+    /**
+     * Plain fetch: HTTP status + page title on a ticker. When this is a fallback
+     * from screenshot mode (no Chrome), a healthy page is reported as a warning
+     * to nudge the Chrome setup; an explicit `--mode=basic` reports it healthy.
+     */
+    async collectBasic(fallback) {
         const loadStart = Date.now();
-        const check = await (0, basic_mode_js_1.basicCheck)(this.url);
+        const check = await (0, basic_mode_js_1.basicCheck)(this.url, defaults_js_1.DEFAULTS.navTimeoutMs);
         const loadMs = Date.now() - loadStart;
-        // Basic mode can't render the pixel TV, so it never reports fully healthy —
-        // a healthy HTTP result is downgraded to a warning to nudge Chrome setup.
-        let status = (0, basic_mode_js_1.statusFromHttp)(check.status, check.timedOut);
-        if (status === 'healthy')
-            status = 'warning';
-        const host = (0, basic_mode_js_1.hostnameOf)(this.url);
-        const message = check.title ? `${host}: ${check.title}` : `${host} (${check.status || 'ERR'})`;
+        const httpStatus = (0, basic_mode_js_1.statusFromHttp)(check.status, check.timedOut);
+        const status = fallback && httpStatus === 'healthy' ? 'warning' : httpStatus;
+        const message = check.title
+            ? `${this.host}: ${check.title}`
+            : `${this.host} (${check.status || (check.timedOut ? 'timed out' : 'ERR')})`;
         return {
             status,
-            mood: moodFor(status),
+            mood: (0, thresholds_js_1.moodForStatus)(status),
             message,
             screenData: {
                 layout: 'ticker',
                 values: [
-                    { label: 'URL', value: host },
+                    { label: 'URL', value: this.host },
                     {
                         label: 'HTTP',
                         value: check.status ? String(check.status) : 'ERR',
-                        color: check.status >= 200 && check.status < 400
-                            ? 'green'
-                            : check.status >= 500 || check.status === 0
-                                ? 'red'
-                                : 'amber',
+                        color: (0, screen_js_1.statusColor)(httpStatus),
                     },
                     { label: 'Title', value: check.title || '(no title)' },
                     { label: 'Mode', value: 'basic' },
@@ -219,16 +282,4 @@ class WebPageWatcherNPC extends polling_npc_js_1.PollingNPC {
     }
 }
 exports.WebPageWatcherNPC = WebPageWatcherNPC;
-function moodFor(status) {
-    switch (status) {
-        case 'healthy':
-            return 'happy';
-        case 'warning':
-            return 'concerned';
-        case 'critical':
-            return 'stressed';
-        default:
-            return 'idle';
-    }
-}
 //# sourceMappingURL=index.js.map

package/dist/cjs/npcs/web-page-watcher/pixelate.js

@@ -176,6 +176,7 @@ function pngToPixelImage(pngBuffer, maxColors = 32, targetW = exports.TARGET_W,
     const { palette, indices } = quantize(rgba, w * h, maxColors);
     const screenData = buildPixelImageScreen(w, h, palette, indices);
     const byteSize = screenData.values.reduce((sum, v) => sum + v.value.length, 0);
-    return { screenData, byteSize, hash: fnv1a(indices) };
+    // Hash the palette too: a recolour with the same layout is still a change.
+    return { screenData, byteSize, hash: fnv1a(Buffer.concat([palette, indices])) };
 }
 //# sourceMappingURL=pixelate.js.map

package/dist/cli.js

@@ -2,7 +2,8 @@
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { parseArgs, resolveConfig, stringFlag, numberFlag, boolFlag } from './core/config.js';
+import { parseArgs, resolveConfig, stringFlag, numberFlag, boolFlag, listFlag, } from './core/config.js';
+import { NpcConfigError } from './core/errors.js';
 import { Logger } from './core/logger.js';
 import { ensureSessionFilterTemplate, loadSessionFilter, sessionPublishDecision, } from './core/session-filter.js';
 // NPC modules are imported lazily per command: `claude-code hook` / `codex hook`
@@ -46,7 +47,15 @@ Monitoring NPC types:
   internet-connectivity   Monitor network connectivity
   process-watcher         Watch for running processes
   log-watcher             Watch log files for errors
-  receptionist            Greeter showing time + local weather
+  receptionist            Lobby greeter with office check-ins and jokes
+  security                Indoor/outdoor patrols and exterior door watch
+  janitor                 Mops suspicious spots and hunts office bugs
+  barista                 Takes increasingly absurd coffee orders
+  office-cat              Naps on desks and supervises keyboards
+  office-dog              Naps, barks at coworkers and runs around
+  plant-caretaker         Waters plants and reviews their performance
+  it-technician           Inspects tech gear and recommends reboots
+  out-of-touch-executive  Interrupts coworkers between long lounge breaks
   github-watcher          Call out new commits on a repo
   web-page-watcher        Render a watched web page as a pixel-art TV
 
@@ -77,17 +86,23 @@ Internet Connectivity Options:
   --poll-interval=<ms>    Poll interval in ms (default: 30000)
   --dns-hosts=<list>      Comma-separated DNS hosts (default: google.com,cloudflare.com)
   --http-urls=<list>      Comma-separated HTTP URLs to check
-  --latency-hosts=<list>  Comma-separated hosts for latency checks
+  --latency-hosts=<list>  Comma-separated TCP latency targets: host, host:port or
+                          [ipv6]:port (default: 8.8.8.8:443,1.1.1.1:443;
+                          port 80 when omitted)
   --slow-threshold=<ms>   Slow response threshold in ms (default: 1000)
+  --timeout=<ms>          Per-check timeout in ms (default: 5000)
 
 Process Watcher Options:
   --poll-interval=<ms>    Poll interval in ms (default: 15000)
-  --processes=<list>      Comma-separated process names to watch
+  --processes=<list>      Comma-separated executable names to watch (python
+                          also matches python3.11; a /path matches exactly)
   --cpu-warn=<n>          CPU warning threshold % (default: 80)
   --mem-warn=<n>          Memory warning threshold MB (default: 500)
 
 Log Watcher Options:
-  --files=<list>          Comma-separated log file paths
+  --files=<list>          Comma-separated log file paths (followed across
+                          rotation; files may appear later). Lines shown on
+                          the screen have secrets redacted.
   --error-pattern=<regex> Error pattern (default: ERROR|FATAL)
   --warning-pattern=<regex> Warning pattern (default: WARN)
   --window=<seconds>      Sliding window in seconds (default: 300)
@@ -95,26 +110,28 @@ Log Watcher Options:
   --error-crit=<n>        Error count for critical status (default: 20)
   --report-interval=<ms>  Report interval in ms (default: 15000)
 
-Receptionist Options:
-  --poll-interval=<ms>    Clock tick in ms (default: 60000)
-  --lat=<n> --lon=<n>     Explicit coordinates for weather
-  --location=<name>       Place name to geocode (else IP geo)
-  --fahrenheit            Show temperature in °F (default: °C)
+Office Character Options:
+  --poll-interval=<ms>    Heartbeat interval in ms (default: 60000)
 
 GitHub Watcher Options:
   --repo=<owner/name>     Repository to watch (required)
   --branch=<name>         Branch to watch (default: repo default branch)
-  --token=<token>         GitHub token (or GITHUB_TOKEN env)
-  --poll-interval=<ms>    Poll interval in ms (default: 60000)
+  --token=<token>         GitHub token (prefer the GITHUB_TOKEN env: flags are
+                          visible in the process list)
+  --poll-interval=<ms>    Poll interval in ms (default: 60000 with a token,
+                          90000 without, to stay under GitHub's 60/hour)
 
 Web Page Watcher Options:
-  --url=<url>             Page to watch (required)
+  --url=<url>             http(s) page to watch (required)
   --mode=<auto|screenshot|basic>  Render mode (default: auto)
   --interval=<ms>         Poll interval in ms (default: 60000, floor 15000)
-  --viewport=<WxH>        Browser viewport (default: screen x 8)
-  --screen=<WxH>          TV pixel resolution (default: 160x120; e.g. 160x100)
-  --wait-until=<event>    Puppeteer waitUntil (default: networkidle2)
+  --viewport=<WxH>        Browser viewport (default: screen x 8, max 4096x4096)
+  --screen=<WxH>          TV pixel resolution (default: 160x120, max 320x240)
+  --wait-until=<event>    load, domcontentloaded, networkidle0 or networkidle2
+                          (default: networkidle2)
   --chrome-path=<path>    Chrome executable (or CHROME_PATH env)
+  --no-chrome-sandbox     Run Chrome without its sandbox (only for trusted
+                          pages; automatic when running as root)
   (needs puppeteer-core + Chrome for the pixel-art TV; falls back to basic)
 `.trim();
 async function main() {
@@ -275,18 +292,10 @@ async function main() {
             if (!config.serviceId) {
                 config.serviceId = 'internet-connectivity';
             }
-            const dnsHosts = stringFlag(parsed.flags, 'dns-hosts')?.split(',');
-            const httpUrls = stringFlag(parsed.flags, 'http-urls')?.split(',');
-            const latencyHostsRaw = stringFlag(parsed.flags, 'latency-hosts')?.split(',');
-            const latencyHosts = latencyHostsRaw?.map((h) => ({ host: h.trim(), port: 80 }));
             const { InternetConnectivityNPC } = await import('./npcs/internet-connectivity/index.js');
             const npc = new InternetConnectivityNPC({
                 ...config,
-                pollInterval: numberFlag(parsed.flags, 'poll-interval'),
-                dnsHosts,
-                httpUrls,
-                latencyHosts,
-                slowThreshold: numberFlag(parsed.flags, 'slow-threshold'),
+                ...InternetConnectivityNPC.configFromFlags(parsed.flags),
             });
             logger.info('Starting internet-connectivity NPC');
             await npc.start();
@@ -296,8 +305,8 @@ async function main() {
             if (!config.serviceId) {
                 config.serviceId = 'process-watcher';
             }
-            const processesStr = stringFlag(parsed.flags, 'processes');
-            if (!processesStr) {
+            const processes = listFlag(parsed.flags, 'processes');
+            if (!processes) {
                 console.error('Error: --processes is required (comma-separated list)');
                 process.exit(1);
             }
@@ -305,7 +314,7 @@ async function main() {
             const npc = new ProcessWatcherNPC({
                 ...config,
                 pollInterval: numberFlag(parsed.flags, 'poll-interval'),
-                processes: processesStr.split(','),
+                processes,
                 cpuWarn: numberFlag(parsed.flags, 'cpu-warn'),
                 memWarn: numberFlag(parsed.flags, 'mem-warn'),
             });
@@ -314,8 +323,8 @@ async function main() {
             break;
         }
         case 'log-watcher': {
-            const filesStr = stringFlag(parsed.flags, 'files');
-            if (!filesStr) {
+            const files = listFlag(parsed.flags, 'files');
+            if (!files) {
                 console.error('Error: --files is required (comma-separated list)');
                 process.exit(1);
             }
@@ -325,7 +334,7 @@ async function main() {
             const { LogWatcherNPC } = await import('./npcs/log-watcher/index.js');
             const npc = new LogWatcherNPC({
                 ...config,
-                files: filesStr.split(','),
+                files,
                 errorPattern: stringFlag(parsed.flags, 'error-pattern'),
                 warningPattern: stringFlag(parsed.flags, 'warning-pattern'),
                 windowSeconds: numberFlag(parsed.flags, 'window'),
@@ -349,11 +358,43 @@ async function main() {
                 lon: numberFlag(parsed.flags, 'lon'),
                 location: stringFlag(parsed.flags, 'location'),
                 fahrenheit: boolFlag(parsed.flags, 'fahrenheit') ?? false,
+                ipGeo: boolFlag(parsed.flags, 'no-ip-geo') !== true,
             });
             logger.info('Starting receptionist NPC');
             await npc.start();
             break;
         }
+        case 'security': {
+            if (!config.serviceId)
+                config.serviceId = 'security';
+            const { SecurityNPC } = await import('./npcs/security/index.js');
+            const npc = new SecurityNPC({
+                ...config,
+                pollInterval: numberFlag(parsed.flags, 'poll-interval'),
+            });
+            logger.info('Starting security NPC');
+            await npc.start();
+            break;
+        }
+        case 'janitor':
+        case 'barista':
+        case 'office-cat':
+        case 'office-dog':
+        case 'plant-caretaker':
+        case 'it-technician':
+        case 'out-of-touch-executive': {
+            if (!config.serviceId)
+                config.serviceId = parsed.command;
+            const { OFFICE_CHARACTER_NPCS } = await import('./npcs/office-characters/index.js');
+            const NPCClass = OFFICE_CHARACTER_NPCS[parsed.command];
+            const npc = new NPCClass({
+                ...config,
+                pollInterval: numberFlag(parsed.flags, 'poll-interval'),
+            });
+            logger.info(`Starting ${parsed.command} NPC`);
+            await npc.start();
+            break;
+        }
         case 'github-watcher': {
             const repo = stringFlag(parsed.flags, 'repo');
             if (!repo) {
@@ -365,11 +406,15 @@ async function main() {
                 config.serviceId = `github-${shortName.replace(/[^a-zA-Z0-9_-]/g, '-')}`.slice(0, 100);
             }
             const { GitHubWatcherNPC } = await import('./npcs/github-watcher/index.js');
+            const tokenFlag = stringFlag(parsed.flags, 'token');
+            if (tokenFlag) {
+                logger.warn('--token is visible to other local users in the process list; prefer GITHUB_TOKEN');
+            }
             const npc = new GitHubWatcherNPC({
                 ...config,
                 repo,
                 branch: stringFlag(parsed.flags, 'branch'),
-                token: stringFlag(parsed.flags, 'token') ?? process.env['GITHUB_TOKEN'],
+                token: tokenFlag ?? process.env['GITHUB_TOKEN'],
                 pollInterval: numberFlag(parsed.flags, 'poll-interval'),
             });
             logger.info('Starting github-watcher NPC');
@@ -385,22 +430,28 @@ async function main() {
             const { hostnameOf } = await import('./npcs/web-page-watcher/basic-mode.js');
             const { parseDimensions } = await import('./npcs/web-page-watcher/defaults.js');
             const { WebPageWatcherNPC } = await import('./npcs/web-page-watcher/index.js');
-            const parseWxH = (v) => v ? (parseDimensions(v) ?? undefined) : undefined;
+            const parseWxH = (flag) => {
+                const v = stringFlag(parsed.flags, flag);
+                if (v === undefined)
+                    return undefined;
+                const dims = parseDimensions(v);
+                if (!dims)
+                    throw new NpcConfigError(`--${flag} must look like 160x120`);
+                return dims;
+            };
             if (!config.serviceId) {
                 config.serviceId = `webpage-${hostnameOf(url)}`
                     .replace(/[^a-zA-Z0-9_.-]/g, '-')
                     .slice(0, 100);
             }
-            const modeFlag = stringFlag(parsed.flags, 'mode');
-            const mode = modeFlag === 'auto' || modeFlag === 'screenshot' || modeFlag === 'basic'
-                ? modeFlag
-                : undefined;
-            const viewport = parseWxH(stringFlag(parsed.flags, 'viewport'));
-            const screen = parseWxH(stringFlag(parsed.flags, 'screen'));
+            const viewport = parseWxH('viewport');
+            const screen = parseWxH('screen');
             const npc = new WebPageWatcherNPC({
                 ...config,
                 url,
-                mode,
+                // Validated (with a clear error) by the constructor.
+                mode: stringFlag(parsed.flags, 'mode'),
+                chromeSandbox: boolFlag(parsed.flags, 'no-chrome-sandbox') !== true,
                 chromePath: stringFlag(parsed.flags, 'chrome-path'),
                 waitUntil: stringFlag(parsed.flags, 'wait-until'),
                 viewportWidth: viewport?.width,
@@ -543,6 +594,10 @@ main().catch((err) => {
         process.stdout.write('{}\n');
         return;
     }
+    if (err instanceof NpcConfigError) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
     console.error('Fatal error:', err);
     process.exit(1);
 });

package/dist/core/base-npc.d.ts

@@ -20,6 +20,11 @@ export declare abstract class BaseNPC {
     protected get defaultDisplayName(): string | null;
     /** The banner name to send, clamped to the API's 32-char limit, or undefined. */
     private pushName;
+    /**
+     * NPC type sent as the push `kind` (groups NPCs for per-type rules such as "all process
+     * watchers work in the Server Room"). Defaults to `name` when it is a valid slug.
+     */
+    get kind(): string | undefined;
     /** NPC archetype — steers movement speed and default behavior. Override per NPC. */
     get archetype(): Archetype;
     /** Base behavior hints sent on every push (merged with per-cycle overrides). */

package/dist/core/base-npc.js

@@ -39,6 +39,13 @@ export class BaseNPC {
         const name = this.displayName;
         return name ? truncate(name, 32) : undefined;
     }
+    /**
+     * NPC type sent as the push `kind` (groups NPCs for per-type rules such as "all process
+     * watchers work in the Server Room"). Defaults to `name` when it is a valid slug.
+     */
+    get kind() {
+        return /^[a-z0-9][a-z0-9-]{0,39}$/.test(this.name) ? this.name : undefined;
+    }
     /** NPC archetype — steers movement speed and default behavior. Override per NPC. */
     get archetype() {
         return 'service';
@@ -113,6 +120,7 @@ export class BaseNPC {
             message: metrics.message ? truncate(metrics.message, 500) : undefined,
             metrics: metrics.metrics,
             archetype: this.archetype,
+            kind: this.kind,
             subStatus: metrics.subStatus,
             screenData: metrics.screenData,
             behavior: Object.keys(behavior).length > 0 ? behavior : undefined,
@@ -120,6 +128,13 @@ export class BaseNPC {
             alertConfig: { heartbeatInterval: this.heartbeatSeconds },
             map: this.config.map,
         });
+        // An observer cannot interrupt monitoring or retries.
+        try {
+            this.config.onPushResult?.({ success: result.success, error: result.error });
+        }
+        catch {
+            /* observer only */
+        }
         if (!result.success) {
             this.reportPushFailure(result.error);
         }

package/dist/core/config.d.ts

@@ -18,5 +18,10 @@ export declare function parseArgs(argv: string[]): ParsedArgs;
 export declare function resolveConfig(flags: Record<string, string | boolean>, overrides?: Partial<NpcConfig>): NpcConfig;
 export declare function stringFlag(flags: Record<string, string | boolean>, key: string): string | undefined;
 export declare function boolFlag(flags: Record<string, string | boolean>, key: string): boolean | undefined;
+/**
+ * A comma-separated list flag (`--processes=nginx,redis`): entries trimmed,
+ * empties dropped, duplicates removed. Undefined when the flag is absent or empty.
+ */
+export declare function listFlag(flags: Record<string, string | boolean>, key: string): string[] | undefined;
 export declare function numberFlag(flags: Record<string, string | boolean>, key: string): number | undefined;
 //# sourceMappingURL=config.d.ts.map