@nocville/npc 0.2.2 → 0.2.3

package/dist/core/polling-npc.js

@@ -1,14 +1,31 @@
 import { BaseNPC } from './base-npc.js';
+/**
+ * Lower bound for any poll interval, so a typo can't exhaust the API's
+ * per-service rate limit (60 pushes/min) or hammer the watched source.
+ */
+export const MIN_POLL_INTERVAL_MS = 5000;
+/** How long `stop()` waits for an in-flight collection before pushing offline anyway. */
+const STOP_DRAIN_TIMEOUT_MS = 10_000;
 function clamp(n, min, max) {
     return Math.min(max, Math.max(min, n));
 }
 export class PollingNPC extends BaseNPC {
     timer = null;
-    collecting = false;
+    keepaliveTimer = null;
+    /** The running collection + push, if any (awaited by `onStop`). */
+    inflight = null;
+    /** A `collectNow()` arrived while a collection was in flight: run once more after it. */
+    rerunRequested = false;
+    /** The last successfully pushed cycle, replayed (without its screen) by the keepalive. */
+    lastPushed = null;
+    lastPushAt = 0;
     pollInterval;
     constructor(config) {
         super(config);
-        this.pollInterval = config.pollInterval ?? 15000;
+        const requested = config.pollInterval ?? 15000;
+        this.pollInterval = Number.isFinite(requested)
+            ? Math.max(MIN_POLL_INTERVAL_MS, requested)
+            : 15000;
     }
     /** Scale staleness to the poll cadence: the server marks unknown at ~2x the interval. */
     get heartbeatSeconds() {
@@ -17,14 +34,22 @@ export class PollingNPC extends BaseNPC {
     async onStart() {
         // Collect immediately on start
         await this.runCollection();
+        // Stopped while the first collection ran: don't arm timers nobody will clear.
+        if (this.state !== 'running')
+            return;
         // Then on interval
         this.timer = setInterval(() => {
             void this.runCollection();
         }, this.pollInterval);
-        // For slow pollers, keep the NPC alive with a lightweight heartbeat between
-        // collections so it never falsely goes stale mid-interval.
-        if (this.pollInterval > 60_000) {
-            this.client.startHeartbeat(30_000);
+        // Only very slow pollers (> heartbeatSeconds, i.e. > 30 min given the clamp)
+        // could go stale between collections. Keep them alive by replaying the
+        // last cycle. The SDK's own heartbeat is not used: it omits `map`, `name`
+        // and `alertConfig`, so it would spawn a twin on the team's default map.
+        const heartbeatMs = this.heartbeatSeconds * 1000;
+        if (this.pollInterval > heartbeatMs) {
+            this.keepaliveTimer = setInterval(() => {
+                void this.keepalive(heartbeatMs);
+            }, heartbeatMs);
         }
     }
     async onStop() {
@@ -32,29 +57,89 @@ export class PollingNPC extends BaseNPC {
             clearInterval(this.timer);
             this.timer = null;
         }
-        this.client.stopHeartbeat();
+        if (this.keepaliveTimer) {
+            clearInterval(this.keepaliveTimer);
+            this.keepaliveTimer = null;
+        }
+        this.rerunRequested = false;
+        // Let an in-flight push land before the offline push, so it can't arrive
+        // afterwards and respawn the NPC. Bounded: a hung collector never blocks exit.
+        if (this.inflight) {
+            let timeout;
+            await Promise.race([
+                this.inflight,
+                new Promise((resolve) => {
+                    timeout = setTimeout(resolve, STOP_DRAIN_TIMEOUT_MS);
+                }),
+            ]);
+            clearTimeout(timeout);
+        }
     }
-    async runCollection() {
+    /**
+     * Collect and push now instead of waiting for the next tick — for NPCs that
+     * also react to events (e.g. a fresh error line). Coalesces: if a collection
+     * is already running, exactly one more runs after it.
+     */
+    collectNow() {
         if (this.state !== 'running')
             return;
+        if (this.inflight) {
+            this.rerunRequested = true;
+            return;
+        }
+        void this.runCollection();
+    }
+    runCollection() {
+        if (this.state !== 'running')
+            return Promise.resolve();
         // Overlap guard: if a slow collector is still running, skip this tick rather
         // than stacking collections (load-bearing for screenshot/render collectors).
-        if (this.collecting) {
+        if (this.inflight) {
             this.logger.debug('Previous collection still in flight, skipping this tick');
-            return;
+            return this.inflight;
         }
-        this.collecting = true;
+        const run = this.collectAndPush().finally(() => {
+            this.inflight = null;
+            if (this.rerunRequested && this.state === 'running') {
+                this.rerunRequested = false;
+                void this.runCollection();
+            }
+        });
+        this.inflight = run;
+        return run;
+    }
+    async collectAndPush() {
         try {
             const metrics = await this.collect();
+            // Stopped mid-collection: never push after (or race) the offline push.
+            if (this.state !== 'running')
+                return;
             await this.pushMetrics(metrics);
+            this.lastPushed = metrics;
+            this.lastPushAt = Date.now();
         }
         catch (err) {
+            if (this.state !== 'running')
+                return; // teardown aborted the collector
             this.logger.error('Collection failed', {
                 error: err instanceof Error ? err.message : String(err),
             });
         }
-        finally {
-            this.collecting = false;
+    }
+    /** Replay the last cycle (minus its screen, which the server keeps) if nothing was pushed recently. */
+    async keepalive(heartbeatMs) {
+        if (this.state !== 'running' || this.inflight || !this.lastPushed)
+            return;
+        if (Date.now() - this.lastPushAt < heartbeatMs / 2)
+            return;
+        try {
+            await this.pushMetrics({ ...this.lastPushed, screenData: undefined });
+            this.lastPushAt = Date.now();
+        }
+        catch (err) {
+            this.logger.debug('Keepalive push failed', {
+                error: err instanceof Error ? err.message : String(err),
+            });
         }
     }
 }

package/dist/core/text.d.ts

@@ -3,4 +3,10 @@
  * Used to keep messages and screen lines within API limits.
  */
 export declare function truncate(s: string, max?: number): string;
+/**
+ * Make untrusted remote text (commit messages, page titles, log lines) safe to
+ * display: drop control and bidi-override characters, collapse whitespace
+ * (including newlines and tabs) to single spaces, trim, and truncate.
+ */
+export declare function sanitizeText(s: string, max?: number): string;
 //# sourceMappingURL=text.d.ts.map

package/dist/core/text.js

@@ -9,4 +9,16 @@ export function truncate(s, max = 200) {
         return s.slice(0, Math.max(0, max));
     return s.slice(0, max - 1) + '…';
 }
+// C0/C1 controls (incl. ESC, so no terminal escapes) plus the bidi overrides,
+// isolates and marks that can visually reorder text on a banner.
+// eslint-disable-next-line no-control-regex
+const UNSAFE_CHARS = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F؜‎‏‪-‮⁦-⁩]/g;
+/**
+ * Make untrusted remote text (commit messages, page titles, log lines) safe to
+ * display: drop control and bidi-override characters, collapse whitespace
+ * (including newlines and tabs) to single spaces, trim, and truncate.
+ */
+export function sanitizeText(s, max = 200) {
+    return truncate(s.replace(UNSAFE_CHARS, '').replace(/\s+/g, ' ').trim(), max);
+}
 //# sourceMappingURL=text.js.map

package/dist/core/thresholds.d.ts

@@ -1,4 +1,4 @@
-import type { Status, ThresholdConfig } from './types.js';
+import type { Mood, Status, ThresholdConfig } from './types.js';
 /**
  * Evaluate a numeric value against thresholds to determine status.
  */
@@ -7,4 +7,12 @@ export declare function evaluateThreshold(value: number, config: ThresholdConfig
  * Returns the worst (most severe) status from an array.
  */
 export declare function worstStatus(statuses: Status[]): Status;
+/** The NPC mood that matches a status (drives the NPC's demeanour and emotes). */
+export declare function moodForStatus(status: Status): Mood;
+/**
+ * Validate a warning/critical pair from user flags: both finite, and critical
+ * at least as severe as warning for the threshold's direction. Returns an error
+ * message, or null when the pair is usable.
+ */
+export declare function thresholdProblem(label: string, t: ThresholdConfig): string | null;
 //# sourceMappingURL=thresholds.d.ts.map

package/dist/core/thresholds.js

@@ -41,4 +41,31 @@ export function worstStatus(statuses) {
     }
     return worst;
 }
+/** The NPC mood that matches a status (drives the NPC's demeanour and emotes). */
+export function moodForStatus(status) {
+    switch (status) {
+        case 'healthy':
+            return 'happy';
+        case 'warning':
+            return 'concerned';
+        case 'critical':
+            return 'stressed';
+        default:
+            return 'idle';
+    }
+}
+/**
+ * Validate a warning/critical pair from user flags: both finite, and critical
+ * at least as severe as warning for the threshold's direction. Returns an error
+ * message, or null when the pair is usable.
+ */
+export function thresholdProblem(label, t) {
+    if (!Number.isFinite(t.warning) || !Number.isFinite(t.critical)) {
+        return `${label}: thresholds must be numbers`;
+    }
+    const inverted = (t.direction ?? 'above') === 'above' ? t.critical < t.warning : t.critical > t.warning;
+    return inverted
+        ? `${label}: critical (${t.critical}) must be at least as severe as warning (${t.warning})`
+        : null;
+}
 //# sourceMappingURL=thresholds.js.map

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';

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';

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/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;