@nocville/npc 0.2.1 → 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Marshall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,7 +7,7 @@ a hand when it needs you, dozes when idle, and shows what it's doing on its spee
 desk sign: `Editing src/GameScene.ts`, `Running pnpm test`, `Searching for 'reconnect'`,
 `Needs your approval`, `Thinking…`. It leaves the office when the session ends.
 
-Requires Node.js 20+. Your team API key is in your Nocville team settings.
+Requires Node.js 20+. Get an agent key in your Nocville office under **Connect AI coworkers**.
 
 ## Quick start: AI coworkers
 
@@ -16,23 +16,23 @@ npx @nocville/npc setup
 ```
 
 Paste your key at the prompt (input is hidden, so the key never lands in your shell history).
-For scripts, pass `--api-key=<your team key>` or set `NOCVILLE_API_KEY` instead. That's it. The command saves your key to `~/.config/nocville/config.json` (mode 0600), then
-hooks up whichever agents you have installed:
+For scripts, pass `--api-key=<your key>` or set `NOCVILLE_API_KEY` instead. That's it. The
+command saves your key to `~/.config/nocville/config.json` (readable only by you), then hooks
+up whichever agents you have installed:
 
 - **Claude Code**: adds hooks to `~/.claude/settings.json`. New sessions show up right away;
   restart sessions that are already running.
 - **Codex**: adds hooks to `~/.codex/hooks.json`. Codex won't run a new hook until you've
   approved it, so start Codex once and run **`/hooks`** to trust the Nocville hooks.
+- **Gemini CLI**: adds hooks to `~/.gemini/settings.json`, keeping your settings and existing
+  hooks. Start a new session after setup.
+- **Cursor**: adds hooks to `~/.cursor/hooks.json`. Start a new chat after setup.
 
-- **Gemini CLI**: adds eight telemetry hooks to `~/.gemini/settings.json`, preserving your
-  settings and existing hooks. Start a new session after setup. Hooks return only `{}`.
+Your existing hooks are left alone, and Nocville's hooks never answer permission prompts or
+change what your agent does; they only report activity.
 
-- **Cursor**: adds native hooks to `~/.cursor/hooks.json`. Existing Nocville Claude hooks
-  also detect Cursor when its third-party hook imports are enabled. Both installations share
-  one coworker and deduplicate matching events. No permission decisions or model output are sent.
-
-Self-hosting or developing locally? Add `--api-url=http://localhost:3601`. To send sessions to
-a map other than your team's default, add `--map="Trading Floor"`.
+Running your own Nocville server? Add `--api-url=https://your-server`. To send sessions to a
+map other than your team's default, add `--map="Trading Floor"`.
 
 Prefer a global install? Run `npm i -g @nocville/npc`, then `nocville-npc setup --api-key=…`.
 When setup runs through `npx`, it copies itself to `~/.config/nocville/runtime/` so the hooks
@@ -71,26 +71,8 @@ checks the current folder (`--project=<dir>`, `--name=<session name>` to test ot
 | `nocville-npc claude-code uninstall` | `nocville-npc codex uninstall`                 |
 |                                      | `nocville-npc codex watch` (no-hooks fallback) |
 
-`nocville-npc gemini setup` and `nocville-npc gemini uninstall` manage Gemini alone.
-Gemini uses a 5000 ms hook timeout; pushes and end-of-turn git summaries are detached.
-Its Node process is identified by the Gemini executable path, not an unrelated Node parent.
-
-`nocville-npc cursor setup` and `nocville-npc cursor uninstall` manage native Cursor hooks.
-Native commands use 10-second timeouts. Setup installs only sessionStart/sessionEnd,
-beforeSubmitPrompt, postToolUse/postToolUseFailure, afterFileEdit, stop, subagentStop and
-preCompact; it removes older Nocville permission hooks while preserving other hooks.
-Activity comes from completed tools. Native and imported Cursor invocations return exactly
-`{}` with no decision fields. Payload fields identify imported Cursor; `CURSOR_VERSION`
-alone never reclassifies Claude launched inside its terminal. The launcher suppresses child
-stdout for every agent, including debug logs, and emits only the appropriate neutral response.
-Cursor does not watch the editor process or start a watchdog: an abandoned conversation uses
-the one-hour fallback heartbeat interval (unknown after two hours, despawn ten minutes later).
-Uninstall intentionally leaves `{"version":1}` when no other settings remain.
-
-Cursor's [documented tool names](https://cursor.com/docs/hooks#configuration) include Grep,
-Delete, Task and MCP tools. Their summaries use the shared redaction/path handling; MCP names
-are normalized to the shared MCP format. Real Cursor Shell/Read/Write verification with both
-Claude-imported-only and native hooks is still required before a public support claim.
+`nocville-npc gemini setup|uninstall` and `nocville-npc cursor setup|uninstall` manage
+Gemini CLI and Cursor on their own. For Cursor, start a new chat after setup.
 
 `nocville-npc uninstall` removes every Nocville hook. `nocville-npc init` only saves
 credentials. Every setup command takes the key from `--api-key`, then `NOCVILLE_API_KEY`, then
@@ -111,58 +93,22 @@ are shortened to their first line, and anything that looks like a secret is reda
 env assignments, `--token=`/`--password` flags, bearer headers, URL credentials, and long
 key-like strings. Paths are shown relative to the project.
 
-**Lifecycle and overhead:** normal hooks run asynchronously, update a locked local state file,
-and hand HTTP delivery to a detached process. Same-phase bursts coalesce at 1.5 seconds.
-SessionEnd stays synchronous with a short timeout to deliver the offline update; failures
-remain pending for retry. Hooks never output instructions or permission decisions.
-
-A watchdog checks a known agent process every 15 seconds and heartbeats once a minute.
-A killed process leaves the office on the next check. If the machine sleeps or loses power,
-the NPC becomes unknown after three minutes and disappears after thirteen. Hosts where
-process liveness cannot be established retain the legacy one-hour heartbeat fallback.
-Claude subagent activity appears below the parent's current activity and disappears when
-the subagent stops (or after ten minutes without activity).
-
-Setup installs a stable `~/.config/nocville/bin/nocville-hook` launcher (respecting
-`XDG_CONFIG_HOME` and `NOCVILLE_CONFIG`) and an immutable runtime copy when needed.
-Re-running setup updates the runtime pointer without changing the hook command or Codex's
-command trust. Old snapshots remain available to running watchdogs. Windows uses the sibling
-`nocville-hook.cmd` launcher, which resolves the saved Node path and runs the same bootstrap.
-Windows setup writes plain commands, never `-EncodedCommand` or an execution-policy override.
-Re-running setup replaces the former encoded commands; uninstall still recognizes them.
-
-| Agent       | Windows command host and verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Claude Code | Explicit per-hook `shell: "powershell"`; invokes `& '<shim>.cmd' claude-code hook`. Claude selects PowerShell 7 or falls back to 5.1. CI exercises both. [Claude hook shell reference](https://code.claude.com/docs/en/hooks#windows-powershell-tool).                                                                                                                                                                                                                                                   |
-| Gemini      | Its hook runner selects PowerShell 7 or 5.1. The saved `cmd.exe /d /s /c --% ...` preserves cmd quoting, with a terminating newline before Gemini's appended exit check. CI exercises both hosts with that check. [Hook reference](https://geminicli.com/docs/hooks/reference/), [runner](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/hooks/hookRunner.ts), [shell selection](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/utils/shell-utils.ts). |
-| Cursor      | Explicit `cmd.exe /d /s /c` launcher; CI executes the saved string under cmd. The [published hook contract](https://cursor.com/docs/hooks) does not specify the Windows outer shell; real Windows Cursor verification remains required.                                                                                                                                                                                                                                                                  |
-| Codex       | Explicit `cmd.exe /d /s /c` launcher; CI executes the saved string under cmd. The [published hook contract](https://learn.chatgpt.com/docs/hooks) does not identify the Windows outer shell; real Windows Codex verification remains required.                                                                                                                                                                                                                                                           |
-
-PowerShell's [stop-parsing token](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing#the-stop-parsing-token)
-ends at a newline, not a semicolon. Keep Gemini's saved newline: its runner appends PowerShell
-code to the command. No event input is interpolated into shell commands. Windows support remains
-unverified until the Windows CI job and real-agent checks pass; macOS tests cannot establish it.
-**Windows Cursor users:** install native hooks with `nocville-npc cursor setup`; do not rely on
-Cursor importing Claude Code hooks. Claude's saved hook uses PowerShell syntax and an explicit
-`shell` field. If Cursor's import path ignores that field and uses cmd, the imported command can
-fail before the shim runs and produce hook errors. Nocville cannot control Cursor's import path.
-
-Windows real-agent owner checklist (required before support claims):
-
-- Run the native Windows CI job, including PowerShell 5.1/7 and a spaced `O’Neil` profile path.
-- Verify native Cursor Shell/Read/Write events after `nocville-npc cursor setup`.
-- With Claude hooks also installed, check whether Cursor imports them and honors their `shell`
-  field. Record agent versions and any duplicate/error events; verify native Cursor hooks work
-  independently. Do not count an imported Claude hook as proof of native Cursor support.
-- Verify the actual Claude, Gemini and Codex hosts using their installed saved commands.
-
-Claude's single-quoted path doubles straight and curly apostrophes according to
-[PowerShell quoting rules](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules#including-quote-characters-in-a-string).
-
-Both launchers discard child stdout and preserve stderr; all SDK logger levels use stderr.
-If Node is unavailable, the shim drains stdin and returns neutral `{}` for Cursor/Gemini
-and Claude hooks (which may have been imported by Cursor); Codex stays silent. Session records are local, including terminal
-records that prevent late events from reviving an ended NPC; `cleanup` removes old records.
+**Overhead:** hooks return immediately and send updates from a background process, so your
+agent never waits on the network. Rapid bursts of activity are combined into one update.
+
+If an agent is killed, its coworker leaves the office within about 15 seconds. If your machine
+sleeps or goes offline, the coworker greys out after a few minutes and leaves after about
+thirteen. Claude subagent activity appears below the parent's current activity.
+
+### Windows
+
+Setup works the same way on Windows; it writes a small `nocville-hook.cmd` launcher to
+`~/.config/nocville/bin/` and points each agent's hooks at it. **Cursor users on Windows:**
+install Cursor's own hooks with `nocville-npc cursor setup` rather than relying on Cursor
+importing your Claude Code hooks.
+
+Re-running `setup` (for example after upgrading with `npx @nocville/npc@latest setup`) keeps
+your hooks in place and switches them to the new version; running sessions are not interrupted.
 
 ### How the Codex integration works
 
@@ -175,9 +121,8 @@ hooks, makes a one-time `hooks.json.nocville-backup`, and is safe to run again.
 reads the rollout logs Codex writes to `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`. It
 shows one NPC per interactive session (subagent and reviewer threads are skipped; add
 `--include-exec` to include `codex exec` runs). A session leaves the office after 30 minutes
-without log activity (`--idle-timeout=<minutes>`) or when you press Ctrl-C. If hooks are
-installed for a session (any hook state file, including an old terminal record), the watcher
-leaves that session to them. `doctor` warns when both modes are running.
+without log activity (`--idle-timeout=<minutes>`) or when you press Ctrl-C. Sessions that
+hooks already report are left to the hooks.
 
 ## Monitoring NPCs
 
@@ -205,16 +150,34 @@ on your map automatically and despawns when you press Ctrl-C. Once you've run
 | `github-watcher`        | New commits on a commit board                      | `nocville-npc github-watcher --repo=owner/name`        |
 | `web-page-watcher`      | A web page rendered as a pixel-art TV              | `nocville-npc web-page-watcher --url=https://…`        |
 
-Run `nocville-npc --help` to see every flag. A few notes:
-
+Run `nocville-npc --help` to see every flag. Poll intervals below 5 seconds are raised to 5
+seconds. A few notes:
+
+- **system-monitor**: `--disk-path=/data` picks the volume; thresholds are percentages
+  (`--cpu-warn`/`--cpu-crit`, `--mem-…`, `--disk-…`). On macOS, memory counts the file cache as
+  available, like Activity Monitor.
+- **internet-connectivity**: `--dns-hosts`, `--http-urls` (http/https only) and
+  `--latency-hosts` take comma-separated lists; latency targets accept `host:port` or
+  `[ipv6]:port`. `--timeout=<ms>` bounds each check (default 5000).
+- **process-watcher**: matches executable names, so `--processes=python` also finds `python3.11`
+  but `sh` does not match `bash`. Use a full path to match one binary exactly. macOS and Linux
+  only.
 - **log-watcher**: `--error-pattern="ERROR|FATAL" --window=300 --error-warn=5 --error-crit=20`.
+  Files are followed across log rotation and may be created after the watcher starts. Lines
+  shown in the office have anything that looks like a secret (tokens, passwords, keys, URL
+  credentials) redacted, but treat the screen as visible to your whole team.
 - **receptionist**: weather comes from the keyless open-meteo API. Set the place with
-  `--lat=52.5 --lon=13.4` or `--location=…` (otherwise it uses IP geolocation). Add
+  `--lat=52.5 --lon=13.4` or `--location=…`. Without either, it estimates your location from
+  your public IP via ipapi.co; pass `--no-ip-geo` to turn that off and show only the time. Add
   `--fahrenheit` for °F.
-- **github-watcher**: uses ETag polling. Pass `--token=$GITHUB_TOKEN` for a higher rate limit.
+- **github-watcher**: uses ETag polling. Set `GITHUB_TOKEN` for private repos and a higher rate
+  limit (`--token` also works, but flags are visible to other users in the process list).
+  Without a token it polls every 90 seconds to stay within GitHub's 60 requests per hour.
 - **web-page-watcher**: the pixel-art TV needs `npm i puppeteer-core` and a local
   Chrome/Chromium (`--chrome-path` or `CHROME_PATH`). Without them it falls back to a
-  title/status ticker. Other options: `--mode=auto|screenshot|basic` and `--screen=160x120`.
+  title/status ticker. Other options: `--mode=auto|screenshot|basic` and `--screen=160x120`
+  (up to 320x240). Only `http(s)` URLs are accepted. Chrome runs with its sandbox unless you're
+  root or pass `--no-chrome-sandbox`; only disable it for pages you trust.
 
 ## Programmatic use
 
@@ -224,7 +187,7 @@ import type { CollectedMetrics } from '@nocville/npc';
 
 await new SystemMonitorNPC({
   apiUrl: 'https://nocville.com',
-  apiKey: 'noc_…',
+  apiKey: 'nvk_…',
   serviceId: 'web-1',
 }).start();
 
@@ -238,32 +201,7 @@ class MyNPC extends PollingNPC {
 }
 ```
 
-## Developing in the monorepo
-
-```bash
-pnpm install
-pnpm --filter @nocville/npc build
-pnpm --filter @nocville/npc test
-node libs/nocville-npc-library/dist/cli.js --help
-SMOKE_STUB=1 pnpm --filter @nocville/npc smoke   # every payload shape, no server needed
-```
-
-**Watch an AI-coworker NPC without running an agent.** `simulate` plays a scripted session
-(start → prompt → Read → Edit → `pnpm test` → approval wait → idle → end) through the real
-built hook handlers. It works in a throwaway HOME, so your `~/.claude` and `~/.codex` are
-untouched, and the NPC appears as "Claude · demo" (or "Codex · demo"):
-
-```bash
-pnpm --filter @nocville/npc simulate claude --api-key=<key> --api-url=http://localhost:3601
-pnpm --filter @nocville/npc simulate codex --api-key=<key> --project=gridbreak --fast
-#   --hold   stay idle after Stop until Ctrl-C, then end the session
-#   --fast   5x shorter pauses (CI)
-```
-
-**Real hooks against your local checkout.** This writes real hooks into `~/.claude` and
-`~/.codex` that run your working copy's `dist/cli.js`:
+## Help
 
-```bash
-node libs/nocville-npc-library/dist/cli.js setup --api-key=<key> --api-url=http://localhost:3601
-node libs/nocville-npc-library/dist/cli.js uninstall   # remove them again
-```
+`nocville-npc --help` lists every command and flag, and `nocville-npc doctor` checks that your
+key and connection work. More at [nocville.com](https://nocville.com).

package/dist/cjs/cli.js

@@ -38,6 +38,7 @@ const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const config_js_1 = require("./core/config.js");
+const errors_js_1 = require("./core/errors.js");
 const logger_js_1 = require("./core/logger.js");
 const session_filter_js_1 = require("./core/session-filter.js");
 // NPC modules are imported lazily per command: `claude-code hook` / `codex hook`
@@ -112,17 +113,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)
@@ -133,23 +140,30 @@ Log Watcher Options:
 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)
+  --location=<name>       Place name to geocode (open-meteo)
+  --no-ip-geo             Without --lat/--lon or --location, don't look up
+                          this machine's IP location (ipapi.co); show time only
   --fahrenheit            Show temperature in °F (default: °C)
 
 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() {
@@ -310,18 +324,10 @@ async function main() {
             if (!config.serviceId) {
                 config.serviceId = 'internet-connectivity';
             }
-            const dnsHosts = (0, config_js_1.stringFlag)(parsed.flags, 'dns-hosts')?.split(',');
-            const httpUrls = (0, config_js_1.stringFlag)(parsed.flags, 'http-urls')?.split(',');
-            const latencyHostsRaw = (0, config_js_1.stringFlag)(parsed.flags, 'latency-hosts')?.split(',');
-            const latencyHosts = latencyHostsRaw?.map((h) => ({ host: h.trim(), port: 80 }));
             const { InternetConnectivityNPC } = await Promise.resolve().then(() => __importStar(require('./npcs/internet-connectivity/index.js')));
             const npc = new InternetConnectivityNPC({
                 ...config,
-                pollInterval: (0, config_js_1.numberFlag)(parsed.flags, 'poll-interval'),
-                dnsHosts,
-                httpUrls,
-                latencyHosts,
-                slowThreshold: (0, config_js_1.numberFlag)(parsed.flags, 'slow-threshold'),
+                ...InternetConnectivityNPC.configFromFlags(parsed.flags),
             });
             logger.info('Starting internet-connectivity NPC');
             await npc.start();
@@ -331,8 +337,8 @@ async function main() {
             if (!config.serviceId) {
                 config.serviceId = 'process-watcher';
             }
-            const processesStr = (0, config_js_1.stringFlag)(parsed.flags, 'processes');
-            if (!processesStr) {
+            const processes = (0, config_js_1.listFlag)(parsed.flags, 'processes');
+            if (!processes) {
                 console.error('Error: --processes is required (comma-separated list)');
                 process.exit(1);
             }
@@ -340,7 +346,7 @@ async function main() {
             const npc = new ProcessWatcherNPC({
                 ...config,
                 pollInterval: (0, config_js_1.numberFlag)(parsed.flags, 'poll-interval'),
-                processes: processesStr.split(','),
+                processes,
                 cpuWarn: (0, config_js_1.numberFlag)(parsed.flags, 'cpu-warn'),
                 memWarn: (0, config_js_1.numberFlag)(parsed.flags, 'mem-warn'),
             });
@@ -349,8 +355,8 @@ async function main() {
             break;
         }
         case 'log-watcher': {
-            const filesStr = (0, config_js_1.stringFlag)(parsed.flags, 'files');
-            if (!filesStr) {
+            const files = (0, config_js_1.listFlag)(parsed.flags, 'files');
+            if (!files) {
                 console.error('Error: --files is required (comma-separated list)');
                 process.exit(1);
             }
@@ -360,7 +366,7 @@ async function main() {
             const { LogWatcherNPC } = await Promise.resolve().then(() => __importStar(require('./npcs/log-watcher/index.js')));
             const npc = new LogWatcherNPC({
                 ...config,
-                files: filesStr.split(','),
+                files,
                 errorPattern: (0, config_js_1.stringFlag)(parsed.flags, 'error-pattern'),
                 warningPattern: (0, config_js_1.stringFlag)(parsed.flags, 'warning-pattern'),
                 windowSeconds: (0, config_js_1.numberFlag)(parsed.flags, 'window'),
@@ -384,6 +390,7 @@ async function main() {
                 lon: (0, config_js_1.numberFlag)(parsed.flags, 'lon'),
                 location: (0, config_js_1.stringFlag)(parsed.flags, 'location'),
                 fahrenheit: (0, config_js_1.boolFlag)(parsed.flags, 'fahrenheit') ?? false,
+                ipGeo: (0, config_js_1.boolFlag)(parsed.flags, 'no-ip-geo') !== true,
             });
             logger.info('Starting receptionist NPC');
             await npc.start();
@@ -400,11 +407,15 @@ async function main() {
                 config.serviceId = `github-${shortName.replace(/[^a-zA-Z0-9_-]/g, '-')}`.slice(0, 100);
             }
             const { GitHubWatcherNPC } = await Promise.resolve().then(() => __importStar(require('./npcs/github-watcher/index.js')));
+            const tokenFlag = (0, config_js_1.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: (0, config_js_1.stringFlag)(parsed.flags, 'branch'),
-                token: (0, config_js_1.stringFlag)(parsed.flags, 'token') ?? process.env['GITHUB_TOKEN'],
+                token: tokenFlag ?? process.env['GITHUB_TOKEN'],
                 pollInterval: (0, config_js_1.numberFlag)(parsed.flags, 'poll-interval'),
             });
             logger.info('Starting github-watcher NPC');
@@ -420,22 +431,28 @@ async function main() {
             const { hostnameOf } = await Promise.resolve().then(() => __importStar(require('./npcs/web-page-watcher/basic-mode.js')));
             const { parseDimensions } = await Promise.resolve().then(() => __importStar(require('./npcs/web-page-watcher/defaults.js')));
             const { WebPageWatcherNPC } = await Promise.resolve().then(() => __importStar(require('./npcs/web-page-watcher/index.js')));
-            const parseWxH = (v) => v ? (parseDimensions(v) ?? undefined) : undefined;
+            const parseWxH = (flag) => {
+                const v = (0, config_js_1.stringFlag)(parsed.flags, flag);
+                if (v === undefined)
+                    return undefined;
+                const dims = parseDimensions(v);
+                if (!dims)
+                    throw new errors_js_1.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 = (0, config_js_1.stringFlag)(parsed.flags, 'mode');
-            const mode = modeFlag === 'auto' || modeFlag === 'screenshot' || modeFlag === 'basic'
-                ? modeFlag
-                : undefined;
-            const viewport = parseWxH((0, config_js_1.stringFlag)(parsed.flags, 'viewport'));
-            const screen = parseWxH((0, config_js_1.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: (0, config_js_1.stringFlag)(parsed.flags, 'mode'),
+                chromeSandbox: (0, config_js_1.boolFlag)(parsed.flags, 'no-chrome-sandbox') !== true,
                 chromePath: (0, config_js_1.stringFlag)(parsed.flags, 'chrome-path'),
                 waitUntil: (0, config_js_1.stringFlag)(parsed.flags, 'wait-until'),
                 viewportWidth: viewport?.width,
@@ -578,6 +595,10 @@ main().catch((err) => {
         process.stdout.write('{}\n');
         return;
     }
+    if (err instanceof errors_js_1.NpcConfigError) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
     console.error('Fatal error:', err);
     process.exit(1);
 });

package/dist/cjs/core/base-npc.js

@@ -42,6 +42,13 @@ class BaseNPC {
         const name = this.displayName;
         return name ? (0, text_js_1.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';
@@ -116,6 +123,7 @@ class BaseNPC {
             message: metrics.message ? (0, text_js_1.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,

package/dist/cjs/core/config.js

@@ -4,6 +4,7 @@ exports.parseArgs = parseArgs;
 exports.resolveConfig = resolveConfig;
 exports.stringFlag = stringFlag;
 exports.boolFlag = boolFlag;
+exports.listFlag = listFlag;
 exports.numberFlag = numberFlag;
 const user_config_js_1 = require("./user-config.js");
 /**
@@ -96,11 +97,27 @@ function boolFlag(flags, key) {
         return false;
     return undefined;
 }
+/**
+ * A comma-separated list flag (`--processes=nginx,redis`): entries trimmed,
+ * empties dropped, duplicates removed. Undefined when the flag is absent or empty.
+ */
+function listFlag(flags, key) {
+    const raw = stringFlag(flags, key);
+    if (raw === undefined)
+        return undefined;
+    const items = [
+        ...new Set(raw
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean)),
+    ];
+    return items.length > 0 ? items : undefined;
+}
 function numberFlag(flags, key) {
     const val = flags[key];
-    if (typeof val === 'string') {
+    if (typeof val === 'string' && val.trim() !== '') {
         const n = Number(val);
-        if (!Number.isNaN(n))
+        if (Number.isFinite(n))
             return n;
     }
     return undefined;

package/dist/cjs/core/errors.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NpcConfigError = void 0;
+exports.assertPosix = assertPosix;
+/**
+ * A user-facing configuration problem (bad flag value, unsupported platform).
+ * The CLI prints only its message and exits 1 — no stack trace — so throw it
+ * for anything the user can fix by changing how they run the NPC.
+ */
+class NpcConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NpcConfigError';
+    }
+}
+exports.NpcConfigError = NpcConfigError;
+/** Throw an NpcConfigError on Windows, for NPCs that rely on POSIX tools or paths. */
+function assertPosix(npcName, hint) {
+    if (process.platform === 'win32') {
+        throw new NpcConfigError(`${npcName} is not supported on Windows. ${hint}`);
+    }
+}
+//# sourceMappingURL=errors.js.map