@nocville/npc 0.2.2 → 0.3.0

package/dist/index.d.ts

@@ -5,8 +5,9 @@ export { EventNPC } from './core/event-npc.js';
 export { Logger } from './core/logger.js';
 export { parseArgs, resolveConfig, stringFlag, boolFlag, numberFlag } from './core/config.js';
 export type { ParsedArgs } from './core/config.js';
-export { evaluateThreshold, worstStatus } from './core/thresholds.js';
-export { truncate } from './core/text.js';
+export { evaluateThreshold, worstStatus, moodForStatus } from './core/thresholds.js';
+export { truncate, sanitizeText } from './core/text.js';
+export { NpcConfigError } from './core/errors.js';
 export { statusColor, pushHistory } from './core/screen.js';
 export type { ScreenColor } from './core/screen.js';
 export type { Status, Mood, NpcConfig, CollectedMetrics, ThresholdConfig, NpcState, LogLevelName, Archetype, BehaviorHints, CompanionSpec, CompanionDecl, ScreenData, ScreenValue, } from './core/types.js';
@@ -18,6 +19,8 @@ export { handleCodexCommand, handleCodexHookEvent, codexTransition, setupCodexHo
 export type { CodexSetupOptions, CodexWatcherOptions, RolloutSignal } from './npcs/codex/index.js';
 export { describeToolUse, shortCommand, shortPath, redactSecrets, } from './npcs/agent-common/activity.js';
 export { loadUserConfig, saveUserConfig, userConfigPath } from './core/user-config.js';
+export { encodePixelArt, pixelArtFromPng, pixelDevice } from './core/pixel-art.js';
+export type { PixelArtFrames } from './core/pixel-art.js';
 export { loadSessionFilter, sessionFilterPath, sessionPublishDecision, ensureSessionFilterTemplate, } from './core/session-filter.js';
 export type { SessionFilter, SessionRules, PublishDecision } from './core/session-filter.js';
 export type { UserConfig } from './core/user-config.js';
@@ -38,4 +41,6 @@ export type { GeminiSetupOptions } from './npcs/gemini/index.js';
 export { CURSOR_DEFAULTS, CURSOR_ADAPTER, cursorServiceId, handleCursorHookEvent, setupCursorHooks, uninstallCursorHooks, installCursorHooksInto, CURSOR_HOOK_EVENTS, } from './npcs/cursor/index.js';
 export type { CursorSetupOptions } from './npcs/cursor/index.js';
 export { isCursorInvocation, normalizeCursorEvent } from './npcs/cursor/normalize.js';
+export { SecurityNPC } from './npcs/security/index.js';
+export { JanitorNPC, BaristaNPC, OfficeCatNPC, OfficeDogNPC, PlantCaretakerNPC, ITTechnicianNPC, OutOfTouchExecutiveNPC, OFFICE_CHARACTER_NPCS, } from './npcs/office-characters/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -4,8 +4,9 @@ export { PollingNPC } from './core/polling-npc.js';
 export { EventNPC } from './core/event-npc.js';
 export { Logger } from './core/logger.js';
 export { parseArgs, resolveConfig, stringFlag, boolFlag, numberFlag } from './core/config.js';
-export { evaluateThreshold, worstStatus } from './core/thresholds.js';
-export { truncate } from './core/text.js';
+export { evaluateThreshold, worstStatus, moodForStatus } from './core/thresholds.js';
+export { truncate, sanitizeText } from './core/text.js';
+export { NpcConfigError } from './core/errors.js';
 export { statusColor, pushHistory } from './core/screen.js';
 // NPCs
 export { SystemMonitorNPC } from './npcs/system-monitor/index.js';
@@ -13,6 +14,7 @@ export { ClaudeCodeNPC, handleClaudeCodeCommand, handleHookEvent, setupHooks, un
 export { handleCodexCommand, handleCodexHookEvent, codexTransition, setupCodexHooks, uninstallCodexHooks, parseRolloutLine, CodexWatcher, } from './npcs/codex/index.js';
 export { describeToolUse, shortCommand, shortPath, redactSecrets, } from './npcs/agent-common/activity.js';
 export { loadUserConfig, saveUserConfig, userConfigPath } from './core/user-config.js';
+export { encodePixelArt, pixelArtFromPng, pixelDevice } from './core/pixel-art.js';
 export { loadSessionFilter, sessionFilterPath, sessionPublishDecision, ensureSessionFilterTemplate, } from './core/session-filter.js';
 export { InternetConnectivityNPC } from './npcs/internet-connectivity/index.js';
 export { ProcessWatcherNPC } from './npcs/process-watcher/index.js';
@@ -23,4 +25,6 @@ export { WebPageWatcherNPC } from './npcs/web-page-watcher/index.js';
 export { GEMINI_DEFAULTS, GEMINI_ADAPTER, geminiTransition, geminiServiceId, handleGeminiHookEvent, setupGeminiHooks, uninstallGeminiHooks, installGeminiHooksInto, GEMINI_HOOK_EVENTS, } from './npcs/gemini/index.js';
 export { CURSOR_DEFAULTS, CURSOR_ADAPTER, cursorServiceId, handleCursorHookEvent, setupCursorHooks, uninstallCursorHooks, installCursorHooksInto, CURSOR_HOOK_EVENTS, } from './npcs/cursor/index.js';
 export { isCursorInvocation, normalizeCursorEvent } from './npcs/cursor/normalize.js';
+export { SecurityNPC } from './npcs/security/index.js';
+export { JanitorNPC, BaristaNPC, OfficeCatNPC, OfficeDogNPC, PlantCaretakerNPC, ITTechnicianNPC, OutOfTouchExecutiveNPC, OFFICE_CHARACTER_NPCS, } from './npcs/office-characters/index.js';
 //# sourceMappingURL=index.js.map

package/dist/npcs/agent-common/session.js

@@ -222,6 +222,7 @@ export function buildAgentPayload(adapter, state, config) {
         name,
         message: current ? truncate(current, 120) : undefined,
         archetype: 'ai-agent',
+        kind: adapter.command,
         metrics: { sessionStartedAt: state.startedAt ?? state.lastUpdate },
         appearance: { family: adapter.family },
         agentStats: state.agentStats,

package/dist/npcs/agent-common/shim.js

@@ -77,13 +77,19 @@ try {
 if (neutral) process.stdout.write('{}\\n');
 `;
 export function installHookShim(nodePath, cliPath) {
+    // Desktop ships this same CLI with Electron's Node runtime. Keep the flag in
+    // the launcher (never globally), inherited by flush/watchdog child processes.
+    const electron = !!process.versions['electron'];
     writeChanged(RUNTIME_POINTER(), JSON.stringify({ node: nodePath, cli: cliPath }, null, 2) + '\n', 0o600);
     writeChanged(join(dirname(RUNTIME_POINTER()), 'node-path'), nodePath + '\n', 0o600);
     writeChanged(join(dirname(SHIM_PATH()), 'launch.cjs'), LAUNCHER, 0o600);
-    writeChanged(SHIM_PATH(), SHIM, 0o755);
+    writeChanged(SHIM_PATH(), electron ? SHIM.replace('exec "$NODE"', 'export ELECTRON_RUN_AS_NODE=1\nexec "$NODE"') : SHIM, 0o755);
     chmodSync(SHIM_PATH(), 0o755);
     // Both launchers use the same bootstrap, including imported-Cursor detection.
-    writeChanged(SHIM_PATH() + '.cmd', WINDOWS_SHIM.replace(/\n/g, '\r\n'), 0o755);
+    const windowsShim = electron
+        ? WINDOWS_SHIM.replace(':launch\n', ':launch\nset "ELECTRON_RUN_AS_NODE=1"\n')
+        : WINDOWS_SHIM;
+    writeChanged(SHIM_PATH() + '.cmd', windowsShim.replace(/\n/g, '\r\n'), 0o755);
     pruneOldRuntimes(dirname(RUNTIME_POINTER()));
     return SHIM_PATH();
 }

package/dist/npcs/github-watcher/defaults.d.ts

@@ -1,8 +1,14 @@
 export declare const DEFAULTS: {
     pollInterval: number;
+    /** Without a token GitHub allows 60 requests/hour (304s included): poll every 90s. */
+    unauthenticatedPollInterval: number;
     fetchTimeoutMs: number;
     perPage: number;
+    /** Commit rows on the board (plus a header row). */
+    boardRows: number;
     /** Polls to keep the 'new-commit' sub-status active after a fresh commit. */
     newCommitPolls: number;
+    /** Consecutive network/5xx failures tolerated (board kept, healthy) before warning. */
+    failuresBeforeWarning: number;
 };
 //# sourceMappingURL=defaults.d.ts.map

package/dist/npcs/github-watcher/defaults.js

@@ -1,8 +1,14 @@
 export const DEFAULTS = {
-    pollInterval: 60000, // 60s
+    pollInterval: 60000, // 60s with a token
+    /** Without a token GitHub allows 60 requests/hour (304s included): poll every 90s. */
+    unauthenticatedPollInterval: 90000,
     fetchTimeoutMs: 5000,
     perPage: 10,
+    /** Commit rows on the board (plus a header row). */
+    boardRows: 8,
     /** Polls to keep the 'new-commit' sub-status active after a fresh commit. */
     newCommitPolls: 2,
+    /** Consecutive network/5xx failures tolerated (board kept, healthy) before warning. */
+    failuresBeforeWarning: 3,
 };
 //# sourceMappingURL=defaults.js.map

package/dist/npcs/github-watcher/github-api.d.ts

@@ -1,3 +1,4 @@
+import type { ReadableResponse } from '../../core/http.js';
 export interface CommitInfo {
     sha: string;
     author: string;
@@ -5,25 +6,26 @@ export interface CommitInfo {
     date: string;
 }
 export interface FetchCommitsResult {
-    /** 304 Not Modified — the ETag matched, nothing changed, no rate-limit cost. */
+    /** 304 Not Modified — the ETag matched, nothing changed. */
     notModified: boolean;
     commits: CommitInfo[];
     etag: string | null;
     rateRemaining: number | null;
+    /** When the rate-limit window resets (epoch ms), if GitHub said. */
+    rateResetAt: number | null;
+    /** HTTP status, or 0 for a network error/timeout/unreadable body. */
     status: number;
 }
 /** Minimal fetch signature so tests can inject a stub. */
 export type FetchFn = (url: string, init?: {
     headers?: Record<string, string>;
     signal?: AbortSignal;
-}) => Promise<{
+}) => Promise<ReadableResponse & {
     ok: boolean;
     status: number;
     headers: {
         get(name: string): string | null;
     };
-    json(): Promise<unknown>;
-    text(): Promise<string>;
 }>;
 export interface FetchOptions {
     token?: string;
@@ -34,15 +36,27 @@ export interface FetchOptions {
     /** Injectable fetch (defaults to the global fetch). */
     fetchFn?: FetchFn;
 }
+/**
+ * Validate an "owner/name" repository slug. It is interpolated into the API
+ * URL path, so anything else (`../`, extra segments, query characters) is
+ * rejected rather than letting it — and the token — reach another endpoint.
+ */
+export declare function isValidRepo(repo: string): boolean;
 /** Look up a repo's default branch (one call at startup). Null on failure. */
 export declare function fetchDefaultBranch(repo: string, opts?: FetchOptions): Promise<string | null>;
 /**
  * Fetch recent commits from the GitHub REST API using conditional requests.
- * Passing the previous ETag yields a 304 (which does not count against the
- * unauthenticated 60/hour limit) when nothing has changed. Never throws —
- * network errors surface as `status: 0`.
+ * Passing the previous ETag yields a cheap 304 when nothing has changed (free
+ * of the rate limit for authenticated requests). Never throws — network
+ * errors and unreadable bodies surface as `status: 0`.
  */
 export declare function fetchCommits(repo: string, opts?: FetchOptions): Promise<FetchCommitsResult>;
+/**
+ * Extract the displayed fields from one (untrusted) commit object: a hex sha,
+ * the subject line and author name with control/bidi characters removed and
+ * lengths capped. Null for anything without a valid sha.
+ */
+export declare function parseCommit(raw: unknown): CommitInfo | null;
 /** Count how many commits landed within the last `hours`. */
 export declare function commitsWithin(commits: CommitInfo[], hours: number, now?: number): number;
 /**

package/dist/npcs/github-watcher/github-api.js

@@ -1,96 +1,131 @@
+import { NPC_USER_AGENT, asRecord, readTextCapped } from '../../core/http.js';
+import { sanitizeText } from '../../core/text.js';
+/** Largest GitHub API response we read (10 commits are ~30-60 KB). */
+const MAX_BODY_BYTES = 512 * 1024;
+// GitHub owner and repository names: letters, digits, '-', '_' and '.'.
+const REPO_RE = /^([A-Za-z0-9-]{1,39})\/([A-Za-z0-9._-]{1,100})$/;
+/**
+ * Validate an "owner/name" repository slug. It is interpolated into the API
+ * URL path, so anything else (`../`, extra segments, query characters) is
+ * rejected rather than letting it — and the token — reach another endpoint.
+ */
+export function isValidRepo(repo) {
+    const m = repo.match(REPO_RE);
+    return !!m && m[2] !== '.' && m[2] !== '..';
+}
 function toNum(v) {
-    if (v === null)
+    if (v === null || v.trim() === '')
         return null;
     const n = Number(v);
-    return Number.isNaN(n) ? null : n;
+    return Number.isFinite(n) ? n : null;
 }
 function ghHeaders(opts) {
     const headers = {
         Accept: 'application/vnd.github+json',
-        'User-Agent': 'nocville-npc',
+        'User-Agent': NPC_USER_AGENT,
         'X-GitHub-Api-Version': '2022-11-28',
     };
     if (opts.token)
         headers['Authorization'] = `Bearer ${opts.token}`;
     return headers;
 }
+function doFetchFn(opts) {
+    return opts.fetchFn ?? globalThis.fetch;
+}
+async function readJson(res) {
+    const { text, truncated } = await readTextCapped(res, MAX_BODY_BYTES);
+    if (truncated)
+        throw new Error('response too large');
+    return JSON.parse(text);
+}
 /** Look up a repo's default branch (one call at startup). Null on failure. */
 export async function fetchDefaultBranch(repo, opts = {}) {
-    const doFetch = opts.fetchFn ?? globalThis.fetch;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 5000);
     try {
-        const res = await doFetch(`https://api.github.com/repos/${repo}`, {
+        const res = await doFetchFn(opts)(`https://api.github.com/repos/${repo}`, {
             headers: ghHeaders(opts),
-            signal: controller.signal,
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 5000),
         });
         if (!res.ok)
             return null;
-        const body = (await res.json());
-        return body.default_branch ?? null;
+        const branch = asRecord(await readJson(res))?.['default_branch'];
+        return typeof branch === 'string' && branch.length > 0 && branch.length <= 255
+            ? sanitizeText(branch, 255)
+            : null;
     }
     catch {
         return null;
     }
-    finally {
-        clearTimeout(timer);
-    }
 }
 /**
  * Fetch recent commits from the GitHub REST API using conditional requests.
- * Passing the previous ETag yields a 304 (which does not count against the
- * unauthenticated 60/hour limit) when nothing has changed. Never throws —
- * network errors surface as `status: 0`.
+ * Passing the previous ETag yields a cheap 304 when nothing has changed (free
+ * of the rate limit for authenticated requests). Never throws — network
+ * errors and unreadable bodies surface as `status: 0`.
  */
 export async function fetchCommits(repo, opts = {}) {
     const perPage = opts.perPage ?? 10;
-    const doFetch = opts.fetchFn ?? globalThis.fetch;
     let url = `https://api.github.com/repos/${repo}/commits?per_page=${perPage}`;
     if (opts.branch)
         url += `&sha=${encodeURIComponent(opts.branch)}`;
     const headers = ghHeaders(opts);
     if (opts.etag)
         headers['If-None-Match'] = opts.etag;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 5000);
+    const failed = {
+        notModified: false,
+        commits: [],
+        etag: null,
+        rateRemaining: null,
+        rateResetAt: null,
+        status: 0,
+    };
     try {
-        const res = await doFetch(url, { headers, signal: controller.signal });
+        const res = await doFetchFn(opts)(url, {
+            headers,
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 5000),
+        });
         const rateRemaining = toNum(res.headers.get('x-ratelimit-remaining'));
+        const resetSecs = toNum(res.headers.get('x-ratelimit-reset'));
+        const rateResetAt = resetSecs === null ? null : resetSecs * 1000;
         const etag = res.headers.get('etag');
+        const meta = { rateRemaining, rateResetAt, status: res.status };
         if (res.status === 304) {
-            return {
-                notModified: true,
-                commits: [],
-                etag: opts.etag ?? null,
-                rateRemaining,
-                status: 304,
-            };
+            return { ...meta, notModified: true, commits: [], etag: opts.etag ?? null };
         }
         if (!res.ok) {
-            await res.text().catch(() => undefined);
-            return { notModified: false, commits: [], etag, rateRemaining, status: res.status };
+            await res.body?.cancel().catch(() => undefined);
+            return { ...meta, notModified: false, commits: [], etag };
         }
-        const body = (await res.json());
-        const commits = body.map((c) => parseCommit(c));
-        return { notModified: false, commits, etag, rateRemaining, status: res.status };
+        const body = await readJson(res);
+        if (!Array.isArray(body))
+            return failed;
+        const commits = body.map(parseCommit).filter((c) => c !== null);
+        return { ...meta, notModified: false, commits, etag };
     }
     catch {
-        return { notModified: false, commits: [], etag: null, rateRemaining: null, status: 0 };
-    }
-    finally {
-        clearTimeout(timer);
+        return failed;
     }
 }
-function parseCommit(c) {
-    const commit = c['commit'] ?? {};
-    const commitAuthor = commit['author'] ?? {};
-    const ghAuthor = c['author'] ?? {};
-    const message = String(commit['message'] ?? '').split('\n')[0] ?? '';
+/**
+ * Extract the displayed fields from one (untrusted) commit object: a hex sha,
+ * the subject line and author name with control/bidi characters removed and
+ * lengths capped. Null for anything without a valid sha.
+ */
+export function parseCommit(raw) {
+    const c = asRecord(raw);
+    const sha = c?.['sha'];
+    if (typeof sha !== 'string' || !/^[0-9a-f]{7,64}$/i.test(sha))
+        return null;
+    const commit = asRecord(c['commit']) ?? {};
+    const commitAuthor = asRecord(commit['author']) ?? {};
+    const ghAuthor = asRecord(c['author']) ?? {};
+    const str = (v) => (typeof v === 'string' && v.trim() ? v : null);
+    const message = str(commit['message'])?.split('\n')[0] ?? '';
+    const date = str(commitAuthor['date']) ?? '';
     return {
-        sha: String(c['sha'] ?? ''),
-        author: String(commitAuthor['name'] ?? ghAuthor['login'] ?? 'unknown'),
-        message,
-        date: String(commitAuthor['date'] ?? ''),
+        sha: sha.toLowerCase(),
+        author: sanitizeText(str(commitAuthor['name']) ?? str(ghAuthor['login']) ?? 'unknown', 40),
+        message: sanitizeText(message, 200),
+        date: Number.isFinite(Date.parse(date)) ? date : '',
     };
 }
 /** Count how many commits landed within the last `hours`. */

package/dist/npcs/github-watcher/index.d.ts

@@ -19,6 +19,9 @@ export declare class GitHubWatcherNPC extends PollingNPC {
     private lastSeenSha;
     private commits;
     private rateRemaining;
+    /** While rate-limited, don't call GitHub again before this time (epoch ms). */
+    private rateLimitedUntil;
+    private consecutiveFailures;
     private newCommitPollsLeft;
     constructor(config: GitHubWatcherConfig);
     get name(): string;
@@ -27,6 +30,9 @@ export declare class GitHubWatcherNPC extends PollingNPC {
     get companion(): CompanionDecl;
     protected onStart(): Promise<void>;
     protected collect(): Promise<CollectedMetrics>;
+    /** Map an error response to a report, or null when the fetch succeeded. */
+    private classifyFailure;
+    private rateLimited;
     private reportNewCommits;
     private reportIdle;
     private report;

package/dist/npcs/github-watcher/index.js

@@ -1,7 +1,9 @@
 import { PollingNPC } from '../../core/polling-npc.js';
 import { truncate } from '../../core/text.js';
+import { moodForStatus } from '../../core/thresholds.js';
+import { NpcConfigError } from '../../core/errors.js';
 import { DEFAULTS } from './defaults.js';
-import { fetchCommits, fetchDefaultBranch, newCommitsSince, commitsWithin } from './github-api.js';
+import { fetchCommits, fetchDefaultBranch, newCommitsSince, commitsWithin, isValidRepo, } from './github-api.js';
 import { relativeTime } from './format.js';
 export class GitHubWatcherNPC extends PollingNPC {
     repo;
@@ -12,12 +14,24 @@ export class GitHubWatcherNPC extends PollingNPC {
     lastSeenSha = null;
     commits = [];
     rateRemaining = null;
+    /** While rate-limited, don't call GitHub again before this time (epoch ms). */
+    rateLimitedUntil = 0;
+    consecutiveFailures = 0;
     newCommitPollsLeft = 0;
     constructor(config) {
-        super({ ...config, pollInterval: config.pollInterval ?? DEFAULTS.pollInterval });
+        super({
+            ...config,
+            // Unauthenticated requests get 60/hour and 304s still count against
+            // them, so a 60s poll (plus the branch lookup) would hit the limit.
+            pollInterval: config.pollInterval ??
+                (config.token ? DEFAULTS.pollInterval : DEFAULTS.unauthenticatedPollInterval),
+        });
+        if (!isValidRepo(config.repo)) {
+            throw new NpcConfigError(`--repo must look like owner/name (got "${truncate(config.repo, 80)}")`);
+        }
         this.repo = config.repo;
-        this.token = config.token;
-        this.branch = config.branch;
+        this.token = config.token || undefined;
+        this.branch = config.branch?.trim() || undefined;
         this.fetchFn = config.fetchFn;
     }
     get name() {
@@ -39,7 +53,8 @@ export class GitHubWatcherNPC extends PollingNPC {
         };
     }
     async onStart() {
-        // Resolve the default branch once if the user didn't pin one.
+        // Resolve the default branch once if the user didn't pin one (it only
+        // labels the board; the commits API already defaults to that branch).
         if (!this.branch) {
             const def = await fetchDefaultBranch(this.repo, {
                 token: this.token,
@@ -54,6 +69,8 @@ export class GitHubWatcherNPC extends PollingNPC {
         await super.onStart();
     }
     async collect() {
+        if (Date.now() < this.rateLimitedUntil)
+            return this.rateLimited();
         const result = await fetchCommits(this.repo, {
             token: this.token,
             etag: this.etag,
@@ -64,39 +81,68 @@ export class GitHubWatcherNPC extends PollingNPC {
         });
         if (result.rateRemaining !== null)
             this.rateRemaining = result.rateRemaining;
-        if (result.status === 403) {
-            return this.report('warning', 'concerned', 'GitHub API rate-limited (403)', 'rate-limited');
+        const failure = this.classifyFailure(result);
+        if (failure)
+            return failure;
+        this.consecutiveFailures = 0;
+        if (result.notModified)
+            return this.reportIdle();
+        if (result.status === 409)
+            return this.report('healthy', 'Repository is empty');
+        this.etag = result.etag ?? this.etag;
+        if (result.commits.length === 0)
+            return this.reportIdle();
+        const fresh = newCommitsSince(result.commits, this.lastSeenSha);
+        this.commits = result.commits;
+        const seeded = this.lastSeenSha !== null;
+        this.lastSeenSha = result.commits[0].sha;
+        if (!seeded || fresh.length === 0)
+            return this.reportIdle();
+        this.newCommitPollsLeft = DEFAULTS.newCommitPolls;
+        return this.reportNewCommits(fresh);
+    }
+    /** Map an error response to a report, or null when the fetch succeeded. */
+    classifyFailure(result) {
+        const { status } = result;
+        if (status === 304 || status === 409 || (status >= 200 && status < 300))
+            return null;
+        if (status === 429 || (status === 403 && result.rateRemaining === 0)) {
+            this.rateLimitedUntil = result.rateResetAt ?? Date.now() + 15 * 60_000;
+            if (!this.token) {
+                this.logger.warn('GitHub rate limit reached; set GITHUB_TOKEN for a higher limit');
+            }
+            return this.rateLimited();
         }
-        if (result.status === 404) {
-            return this.report('warning', 'concerned', `Repo not found: ${this.repo}`, 'not-found');
+        if (status === 401) {
+            return this.report('warning', 'GitHub token rejected (401)', 'auth-failed');
         }
-        if (result.status === 0 && this.commits.length === 0) {
-            return this.report('warning', 'concerned', 'GitHub API unreachable', 'unreachable');
+        if (status === 403) {
+            return this.report('warning', `Access to ${this.repo} denied (403)`, 'forbidden');
         }
-        if (result.notModified) {
-            return this.reportIdle();
+        if (status === 404) {
+            const hint = this.token ? '' : ' (private repos need GITHUB_TOKEN)';
+            return this.report('warning', `Repo not found: ${this.repo}${hint}`, 'not-found');
         }
-        if (result.commits.length > 0) {
-            const fresh = newCommitsSince(result.commits, this.lastSeenSha);
-            this.commits = result.commits;
-            this.etag = result.etag ?? this.etag;
-            if (this.lastSeenSha === null) {
-                this.lastSeenSha = result.commits[0].sha;
-                return this.reportIdle();
-            }
-            if (fresh.length > 0) {
-                this.lastSeenSha = result.commits[0].sha;
-                this.newCommitPollsLeft = DEFAULTS.newCommitPolls;
-                return this.reportNewCommits(fresh);
-            }
+        // Network error, timeout or 5xx: ride out blips while there's a board to show.
+        this.consecutiveFailures++;
+        if (this.commits.length > 0 && this.consecutiveFailures < DEFAULTS.failuresBeforeWarning) {
+            return this.reportIdle();
         }
-        return this.reportIdle();
+        const what = status === 0 ? 'unreachable' : `error (HTTP ${status})`;
+        return this.report('warning', `GitHub API ${what}`, 'unreachable');
+    }
+    rateLimited() {
+        const resumes = new Date(this.rateLimitedUntil).toLocaleTimeString([], {
+            hour: '2-digit',
+            minute: '2-digit',
+        });
+        return this.report('warning', `GitHub API rate-limited until ${resumes}`, 'rate-limited');
     }
     reportNewCommits(fresh) {
         const newest = fresh[0];
         const latest = `${newest.author}: ${truncate(newest.message, 120)} (${newest.sha.slice(0, 7)})`;
         const message = fresh.length > 1 ? `${fresh.length} new commits — latest: ${latest}` : latest;
-        return this.report('healthy', 'happy', message, 'new-commit');
+        return this.report('healthy', message, 'new-commit');
     }
     reportIdle() {
         if (this.newCommitPollsLeft > 0)
@@ -106,16 +152,16 @@ export class GitHubWatcherNPC extends PollingNPC {
         const message = newest
             ? `Last: ${truncate(newest.message, 80)} (${relativeTime(newest.date)})`
             : `Watching ${this.repo}`;
-        return this.report('healthy', 'happy', message, subStatus);
+        return this.report('healthy', message, subStatus);
     }
-    report(status, mood, message, subStatus) {
-        const newest = this.commits[0];
-        const secondsSinceLast = newest && newest.date
-            ? Math.max(0, Math.round((Date.now() - Date.parse(newest.date)) / 1000))
+    report(status, message, subStatus) {
+        const newestAt = Date.parse(this.commits[0]?.date ?? '');
+        const secondsSinceLast = Number.isFinite(newestAt)
+            ? Math.max(0, Math.round((Date.now() - newestAt) / 1000))
             : 0;
         return {
             status,
-            mood,
+            mood: moodForStatus(status),
             message,
             subStatus,
             screenData: this.buildBoard(),
@@ -129,9 +175,9 @@ export class GitHubWatcherNPC extends PollingNPC {
     buildBoard() {
         const now = Date.now();
         const header = this.branch ? `${this.repo}@${this.branch}` : this.repo;
-        const values = [{ label: 'repo', value: header }];
-        for (const c of this.commits.slice(0, 8)) {
-            const recent = c.date && now - Date.parse(c.date) < 3600_000;
+        const values = [{ label: 'repo', value: truncate(header, 60) }];
+        for (const c of this.commits.slice(0, DEFAULTS.boardRows)) {
+            const recent = now - Date.parse(c.date) < 3600_000;
             values.push({
                 label: c.sha.slice(0, 7),
                 value: truncate(`${c.author}: ${c.message}`, 60),

package/dist/npcs/internet-connectivity/checks.d.ts

@@ -1,24 +1,21 @@
 import type { LatencyHost } from './defaults.js';
-export interface DnsCheckResult {
-    host: string;
+/** One probe's outcome. `timeMs` is only meaningful when `ok`. */
+export interface CheckResult {
+    target: string;
     ok: boolean;
     timeMs: number;
     error?: string;
 }
-export declare function checkDns(hosts: string[]): Promise<DnsCheckResult[]>;
-export interface HttpCheckResult {
-    url: string;
-    ok: boolean;
-    timeMs: number;
-    statusCode?: number;
-    error?: string;
-}
-export declare function checkHttp(urls: string[], timeout: number): Promise<HttpCheckResult[]>;
-export interface LatencyCheckResult {
-    host: string;
-    ok: boolean;
-    timeMs: number;
-    error?: string;
-}
-export declare function checkLatency(hosts: LatencyHost[]): Promise<LatencyCheckResult[]>;
+/**
+ * Resolve each host's A records through a dedicated resolver with a bounded
+ * timeout (the default resolver retries for tens of seconds when DNS is down).
+ */
+export declare function checkDns(hosts: string[], timeoutMs: number): Promise<CheckResult[]>;
+/**
+ * Time to response headers for each URL. The body is discarded unread, so a
+ * large or endless response costs nothing. Only 2xx counts as reachable.
+ */
+export declare function checkHttp(urls: string[], timeoutMs: number): Promise<CheckResult[]>;
+/** Time to establish a TCP connection to each host:port. */
+export declare function checkLatency(hosts: LatencyHost[], timeoutMs: number): Promise<CheckResult[]>;
 //# sourceMappingURL=checks.d.ts.map