@0xmaxma/claude-gateway 1.3.25 → 1.3.31

package/README.md

@@ -293,6 +293,52 @@ Controls the Claude subprocess backend for all non-app agents.
 
 This setting is hot-reloadable — new sessions pick it up without a restart.
 
+### `gateway.selfHealing.autoRecover`
+
+Opt-in self-healing for the turn-trace watchdog (Epic #195). When a turn stalls, the gateway always detects it, logs a scrubbed incident, and notifies the affected chat. This flag additionally controls whether the gateway may *act* on a stall.
+
+| Value | Behaviour |
+|-------|-----------|
+| `false` *(default)* | Detection + incident logging + notification only — no automatic action |
+| `true` | The watchdog may run a whitelisted recovery for a stalled turn: a keystroke into the TUI (esc / enter / arrow / menu selection), a session restart, a reversible safe-mode fallback to the headless backend, and — after a successful unblock — a guarded resend of the last message (only if the turn produced no output, so it is never double-submitted) |
+
+Recovery actions are clamped to a per-stage whitelist and a per-turn budget, and any local triage treats the on-screen text as untrusted data validated against a closed schema. Safe-mode auto-fallback on a hard PTY failure is independent of this flag (it is always reversible and never presses keys). In-memory only — a gateway restart re-reads your real config.
+
+```json
+{
+  "gateway": {
+    "selfHealing": {
+      "autoRecover": true
+    }
+  }
+}
+```
+
+### `gateway.bind`
+
+Network interface the HTTP/WebSocket server binds to. Defaults to `127.0.0.1` (localhost-only), so the dashboard and API are **not** exposed to the local network out of the box. Set to `0.0.0.0` to listen on all interfaces (for example when a containerized reverse proxy needs to reach the gateway). The `GATEWAY_BIND` environment variable, when set, takes precedence over this field.
+
+```json
+{
+  "gateway": {
+    "bind": "127.0.0.1"
+  }
+}
+```
+
+> **⚠️ Upgrade note:** the default bind changed from `0.0.0.0` to `127.0.0.1` (configVersion 1.0.13). To avoid silently cutting off external access, the config migrator is **behavior-preserving**: whenever it upgrades a config that never set `gateway.bind`, it pins `bind` to `0.0.0.0` and logs a one-time warning, so a deployment that was reachable from another host stays reachable. This applies to *any* upgraded config with no `bind` key — including one already stamped `1.0.13` that never received a bind (an earlier version gated this on `< 1.0.13` and left such configs stuck on the `127.0.0.1` default). New installs (no prior config, so no migration runs) keep the secure `127.0.0.1` default. If you *want* localhost-only after upgrading, set `gateway.bind` to `127.0.0.1` explicitly (or the `GATEWAY_BIND` env var).
+
+### Terminal Viewer — interactive terminal mode
+
+The dashboard's **Terminal Viewer** opens read-only (a live mirror of the PTY). A toggle in the top-right of the viewer switches it into an **interactive terminal**: keystrokes typed into the panel — printable characters, Enter, arrows, Ctrl-combos, Esc — are streamed into the live PTY, and the panel title changes to reflect the active mode. This is a per-browser client-side choice (Issue #201); there is no server config flag to enable it.
+
+Because interactive mode turns a read-only view into a remote-write surface, access is protected upstream rather than by a feature flag:
+
+- **Authentication** — the WebSocket requires a valid dashboard ticket or API key.
+- **`gateway.bind`** — the gateway binds to `127.0.0.1` (localhost) by default, so the dashboard is not reachable from the network out of the box. Expose a non-loopback bind (`0.0.0.0`) **only** behind a trusted authenticating reverse proxy.
+
+Inbound frames are always bounded (text-only, size-capped) and are dropped for headless sessions (no PTY).
+
 ### `gateway.api.keys`
 
 Each key has a `key` string (supports `${ENV_VAR}` interpolation), an optional `description`, and an `agents` field — either an array of agent IDs or `"*"` for full access. Keys support both `Authorization: Bearer` and `X-Api-Key` headers.
@@ -485,7 +531,7 @@ The gateway proxies `/app/:name/:portName/*` to the app containers. Two env vars
 
 | Env var | Default | Description |
 |---------|---------|-------------|
-| `GATEWAY_BIND` | `0.0.0.0` | Gateway HTTP listen address. Must be `0.0.0.0` (default) when a **containerized** reverse proxy (Caddy, nginx in Docker) needs to reach the gateway. Set to `127.0.0.1` only if using a **host-network** proxy (Traefik on host) — loopback is not reachable across container boundaries. |
+| `GATEWAY_BIND` | `127.0.0.1` | Gateway HTTP listen address. Overrides the `gateway.bind` config field when set. Defaults to localhost-only; set to `0.0.0.0` when a **containerized** reverse proxy (Caddy, nginx in Docker) needs to reach the gateway across container boundaries. A **host-network** proxy (Traefik on host) can keep the localhost default. |
 | `DOCKER_HOST` | _(system default)_ | Docker socket/TCP address. When set to `tcp://host:port` (e.g. DinD), the gateway automatically uses the host extracted from `DOCKER_HOST` to proxy to app containers instead of `127.0.0.1`. |
 
 Example Caddyfile for apps behind Caddy in Docker:

package/config.template.json

@@ -10,10 +10,11 @@
       "claude.dangerouslySkipPermissions"
     ]
   },
-  "configVersion": "1.0.11",
+  "configVersion": "1.0.14",
   "gateway": {
     "logDir": "~/.claude-gateway/logs",
     "timezone": "Asia/Bangkok",
+    "bind": "127.0.0.1",
     "models": [
       { "id": "claude-fable-5[1m]",        "label": "Fable 5 (1M)",     "alias": "fable[1m]",   "contextWindow": 1000000 },
       { "id": "claude-opus-4-8[1m]",       "label": "Opus 4.8 (1M)",    "alias": "opus[1m]",    "contextWindow": 1000000 },
@@ -44,7 +45,10 @@
       "cleanupHour": 0,
       "cleanupTimezone": "UTC"
     },
-    "headless": true
+    "headless": true,
+    "selfHealing": {
+      "autoRecover": false
+    }
   },
   "agents": [
     {

package/dist/agent/incident-store.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Incident store (Epic #195, Phase 2).
+ *
+ * Persists turn-trace stall incidents as on-disk bundles under
+ * `<dir>/<id>/`, deduplicates repeats by fingerprint within a rolling window,
+ * escalates according to the pure rules in incident.ts, and prunes old bundles.
+ *
+ * All IO is funnelled through an injected `fs` and `now()` so the store is
+ * fully unit-testable against an in-memory filesystem (no real disk, no real
+ * clock). The pure decision logic (fingerprint, escalation, scrub, digest)
+ * lives in incident.ts; this file only orchestrates it and touches disk.
+ *
+ * A bundle is captured BEFORE any recovery mutates state (Phase 3 recovery runs
+ * after record() returns), so evidence reflects the wedged turn, not its
+ * aftermath. Every text artifact is scrubbed on the way in.
+ */
+import type { TurnIncident, TurnIncidentEvidence } from './turn-trace';
+import { type EscalationConfig, type EscalationDecision, type EscalationLevel, type IncidentManifest, type DigestSummary, type RecoveryOutcome } from './incident';
+/** Minimal filesystem surface the store needs. Node's `fs` satisfies it. */
+export interface IncidentFsApi {
+    mkdirSync(path: string, opts: {
+        recursive: boolean;
+    }): void;
+    writeFileSync(path: string, data: string): void;
+    readFileSync(path: string, enc: 'utf8'): string;
+    existsSync(path: string): boolean;
+    readdirSync(path: string): string[];
+    rmSync(path: string, opts: {
+        recursive: boolean;
+        force: boolean;
+    }): void;
+}
+export interface IncidentStoreDeps {
+    /** Base directory for incident bundles (e.g. ~/.claude-gateway/incidents). */
+    dir: string;
+    fs: IncidentFsApi;
+    /** Clock injection — epoch ms. */
+    now: () => number;
+    /** Transport name recorded on each incident ('telegram' | 'discord' | ...). */
+    channel: string;
+    /** Gateway version, recorded for context (not part of the fingerprint). */
+    gatewayVersion: string;
+    /** Lazily resolves the Claude CLI version (part of the fingerprint). */
+    getCliVersion: () => string;
+    /** Retention: bundles whose lastAt is older than this are pruned (ms). */
+    retentionMs?: number;
+    /** Retention: hard cap on bundle count (oldest pruned first). */
+    maxIncidents?: number;
+    /** Escalation thresholds. */
+    escalation?: EscalationConfig;
+    /** Max occurrence samples retained per incident. */
+    maxSamples?: number;
+}
+/** Outcome of recording one stall occurrence. */
+export interface RecordResult {
+    id: string;
+    fingerprint: string;
+    occurrences: number;
+    escalation: EscalationDecision;
+    /** True when this created a fresh bundle (vs. folding into an existing one). */
+    isNew: boolean;
+    manifest: IncidentManifest;
+}
+export interface IncidentStore {
+    record(incident: TurnIncident, evidence?: TurnIncidentEvidence): RecordResult;
+    /** Load a manifest by id, or null if absent/corrupt. */
+    get(id: string): IncidentManifest | null;
+    /** Record that the user was notified at a level (dedupes re-notifying). */
+    markNotified(id: string, level: EscalationLevel, at?: number): void;
+    /**
+     * Append a recovery outcome to an incident bundle (Phase 3b). The runner
+     * executes recovery and returns the outcome; the receiver persists it here so
+     * the bundle records what was attempted and whether it worked. Capped like
+     * samples so a flapping stall cannot grow the manifest unbounded.
+     */
+    appendRecovery(id: string, outcome: RecoveryOutcome): void;
+    /** Link a filed GitHub issue to an incident fingerprint. */
+    linkIssue(id: string, issueNumber: number): void;
+    /** Mark an incident resolved (stops it folding new occurrences). */
+    resolve(id: string): void;
+    /** Prune bundles past retention / over the count cap. Returns pruned ids. */
+    prune(): string[];
+    /** Digest summary over the last `sinceMs`. */
+    digest(sinceMs: number): DigestSummary;
+    /** All manifests currently on disk (unsorted). */
+    list(): IncidentManifest[];
+}
+export declare function createIncidentStore(deps: IncidentStoreDeps): IncidentStore;
+//# sourceMappingURL=incident-store.d.ts.map

package/dist/agent/incident-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"incident-store.d.ts","sourceRoot":"","sources":["../../src/agent/incident-store.ts"],"names":[],"mappings":"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"}

package/dist/agent/incident-store.js

@@ -0,0 +1,299 @@
+"use strict";
+/**
+ * Incident store (Epic #195, Phase 2).
+ *
+ * Persists turn-trace stall incidents as on-disk bundles under
+ * `<dir>/<id>/`, deduplicates repeats by fingerprint within a rolling window,
+ * escalates according to the pure rules in incident.ts, and prunes old bundles.
+ *
+ * All IO is funnelled through an injected `fs` and `now()` so the store is
+ * fully unit-testable against an in-memory filesystem (no real disk, no real
+ * clock). The pure decision logic (fingerprint, escalation, scrub, digest)
+ * lives in incident.ts; this file only orchestrates it and touches disk.
+ *
+ * A bundle is captured BEFORE any recovery mutates state (Phase 3 recovery runs
+ * after record() returns), so evidence reflects the wedged turn, not its
+ * aftermath. Every text artifact is scrubbed on the way in.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createIncidentStore = createIncidentStore;
+const incident_1 = require("./incident");
+const DEFAULT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+const DEFAULT_MAX_INCIDENTS = 500;
+const DEFAULT_MAX_SAMPLES = 20;
+const MANIFEST = 'manifest.json';
+function createIncidentStore(deps) {
+    const { dir, fs, now, channel, gatewayVersion, getCliVersion, retentionMs = DEFAULT_RETENTION_MS, maxIncidents = DEFAULT_MAX_INCIDENTS, escalation = incident_1.DEFAULT_ESCALATION, maxSamples = DEFAULT_MAX_SAMPLES, } = deps;
+    // In-memory index of currently-open incidents by fingerprint, so dedup does
+    // not rescan every bundle on each stall. Rebuilt from disk on construction so
+    // dedup survives a process restart.
+    const openByFingerprint = new Map(); // fingerprint → id
+    function bundleDir(id) {
+        return join(dir, id);
+    }
+    function manifestPath(id) {
+        return join(bundleDir(id), MANIFEST);
+    }
+    function ensureBaseDir() {
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        catch {
+            // Best-effort; a subsequent write will surface a real failure.
+        }
+    }
+    function readManifest(id) {
+        try {
+            const raw = fs.readFileSync(manifestPath(id), 'utf8');
+            const m = JSON.parse(raw);
+            // Defensive: a manifest missing its id is treated as corrupt.
+            if (!m || typeof m.id !== 'string' || typeof m.fingerprint !== 'string') {
+                return null;
+            }
+            return m;
+        }
+        catch {
+            return null;
+        }
+    }
+    function writeManifest(m) {
+        fs.mkdirSync(bundleDir(m.id), { recursive: true });
+        fs.writeFileSync(manifestPath(m.id), JSON.stringify(m, null, 2));
+    }
+    function listIds() {
+        try {
+            return fs.readdirSync(dir).filter((name) => {
+                // Only directories that contain a manifest count as bundles.
+                return fs.existsSync(manifestPath(name));
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    // ── Rebuild the open-fingerprint index from disk on construction. ──────────
+    ensureBaseDir();
+    for (const id of listIds()) {
+        const m = readManifest(id);
+        if (m && m.status === 'open') {
+            // If two open bundles share a fingerprint (shouldn't happen), keep the
+            // most recent so folding continues on the freshest episode.
+            const existing = openByFingerprint.get(m.fingerprint);
+            if (!existing) {
+                openByFingerprint.set(m.fingerprint, m.id);
+            }
+            else {
+                const prev = readManifest(existing);
+                if (!prev || m.lastAt >= prev.lastAt) {
+                    openByFingerprint.set(m.fingerprint, m.id);
+                }
+            }
+        }
+    }
+    function scrubEvidence(evidence, redactions) {
+        const files = {};
+        if (!evidence)
+            return files;
+        if (evidence.artifacts && evidence.artifacts.length > 0) {
+            files['typing-artifacts.txt'] = (0, incident_1.scrubText)(evidence.artifacts.join('\n'), redactions);
+        }
+        if (evidence.statusText) {
+            files['status.txt'] = (0, incident_1.scrubText)(evidence.statusText, redactions);
+        }
+        if (evidence.errorText) {
+            files['error.txt'] = (0, incident_1.scrubText)(evidence.errorText, redactions);
+        }
+        return files;
+    }
+    function record(incident, evidence) {
+        const at = incident.at || now();
+        const cliVersion = safe(getCliVersion) || 'unknown';
+        const fingerprint = (0, incident_1.computeFingerprint)({
+            stage: incident.stage,
+            failureClass: incident.failureClass,
+            cliVersion,
+        });
+        const sample = {
+            at,
+            sinceMs: incident.sinceMs,
+            budgetMs: incident.budgetMs,
+            midTurn: incident.midTurn,
+        };
+        // Try to fold into an existing open incident within the dedup window.
+        const existingId = openByFingerprint.get(fingerprint);
+        if (existingId) {
+            const existing = readManifest(existingId);
+            if (existing &&
+                existing.status === 'open' &&
+                at - existing.lastAt <= escalation.windowMs) {
+                existing.occurrences += 1;
+                existing.lastAt = at;
+                existing.samples = pushCapped(existing.samples, sample, maxSamples);
+                const escalated = (0, incident_1.decideEscalation)(existing.occurrences, existing.notifiedLevel === 'investigate', escalation);
+                existing.escalationLevel = (0, incident_1.maxEscalationLevel)(existing.escalationLevel, escalated.level);
+                writeManifest(existing);
+                return {
+                    id: existing.id,
+                    fingerprint,
+                    occurrences: existing.occurrences,
+                    escalation: escalated,
+                    isNew: false,
+                    manifest: existing,
+                };
+            }
+            // Stale or resolved → drop the stale index entry and fall through to new.
+            openByFingerprint.delete(fingerprint);
+        }
+        // Fresh incident bundle.
+        const id = `${(0, incident_1.fingerprintHash)(fingerprint)}-${at}`;
+        const escalated = (0, incident_1.decideEscalation)(1, false, escalation);
+        const manifest = {
+            id,
+            fingerprint,
+            stage: incident.stage,
+            failureClass: incident.failureClass,
+            cliVersion,
+            gatewayVersion,
+            channel,
+            firstAt: at,
+            lastAt: at,
+            occurrences: 1,
+            escalationLevel: escalated.level,
+            status: 'open',
+            notifiedAt: null,
+            notifiedLevel: null,
+            githubIssue: null,
+            recovery: [],
+            samples: [sample],
+        };
+        // Redact the chat id and any known handle from all exported text.
+        const redactions = [incident.chatId];
+        writeManifest(manifest);
+        const files = scrubEvidence(evidence, redactions);
+        for (const [name, content] of Object.entries(files)) {
+            try {
+                fs.writeFileSync(join(bundleDir(id), name), content);
+            }
+            catch {
+                // A failed artifact write must not lose the incident itself.
+            }
+        }
+        openByFingerprint.set(fingerprint, id);
+        // Enforce the count cap opportunistically on creation.
+        prune();
+        return { id, fingerprint, occurrences: 1, escalation: escalated, isNew: true, manifest };
+    }
+    function get(id) {
+        return readManifest(id);
+    }
+    function markNotified(id, level, atArg) {
+        const m = readManifest(id);
+        if (!m)
+            return;
+        m.notifiedAt = atArg ?? now();
+        m.notifiedLevel = m.notifiedLevel
+            ? (0, incident_1.maxEscalationLevel)(m.notifiedLevel, level)
+            : level;
+        writeManifest(m);
+    }
+    function appendRecovery(id, outcome) {
+        const m = readManifest(id);
+        if (!m)
+            return;
+        m.recovery = pushCapped(m.recovery ?? [], outcome, maxSamples);
+        writeManifest(m);
+    }
+    function linkIssue(id, issueNumber) {
+        const m = readManifest(id);
+        if (!m)
+            return;
+        m.githubIssue = issueNumber;
+        writeManifest(m);
+    }
+    function resolve(id) {
+        const m = readManifest(id);
+        if (!m)
+            return;
+        m.status = 'resolved';
+        writeManifest(m);
+        if (openByFingerprint.get(m.fingerprint) === id) {
+            openByFingerprint.delete(m.fingerprint);
+        }
+    }
+    function list() {
+        const out = [];
+        for (const id of listIds()) {
+            const m = readManifest(id);
+            if (m)
+                out.push(m);
+        }
+        return out;
+    }
+    function prune() {
+        const manifests = list();
+        const cutoff = now() - retentionMs;
+        const pruned = [];
+        // Age-based prune.
+        const survivors = [];
+        for (const m of manifests) {
+            if (m.lastAt < cutoff) {
+                removeBundle(m.id);
+                pruned.push(m.id);
+            }
+            else {
+                survivors.push(m);
+            }
+        }
+        // Count-cap prune: drop oldest (by lastAt) beyond the cap.
+        if (survivors.length > maxIncidents) {
+            survivors.sort((a, b) => a.lastAt - b.lastAt); // oldest first
+            const overflow = survivors.length - maxIncidents;
+            for (let i = 0; i < overflow; i++) {
+                removeBundle(survivors[i].id);
+                pruned.push(survivors[i].id);
+            }
+        }
+        // Keep the open-fingerprint index consistent with what remains.
+        for (const id of pruned) {
+            for (const [fp, mapped] of openByFingerprint) {
+                if (mapped === id)
+                    openByFingerprint.delete(fp);
+            }
+        }
+        return pruned;
+    }
+    function removeBundle(id) {
+        try {
+            fs.rmSync(bundleDir(id), { recursive: true, force: true });
+        }
+        catch {
+            // Best-effort.
+        }
+    }
+    function digest(sinceMs) {
+        return (0, incident_1.summarizeIncidents)(list(), sinceMs, now());
+    }
+    return { record, get, markNotified, appendRecovery, linkIssue, resolve, prune, digest, list };
+}
+/** Path join without importing `path` (keeps the module dependency-light). */
+function join(...parts) {
+    return parts
+        .map((p, i) => (i === 0 ? p.replace(/\/+$/, '') : p.replace(/^\/+|\/+$/g, '')))
+        .filter((p) => p.length > 0)
+        .join('/');
+}
+/** Push onto a capped ring, dropping the oldest when full. */
+function pushCapped(arr, item, cap) {
+    const next = [...arr, item];
+    return next.length > cap ? next.slice(next.length - cap) : next;
+}
+/** Call a provider defensively; any throw collapses to ''. */
+function safe(fn) {
+    try {
+        return fn();
+    }
+    catch {
+        return '';
+    }
+}
+//# sourceMappingURL=incident-store.js.map

package/dist/agent/incident-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"incident-store.js","sourceRoot":"","sources":["../../src/agent/incident-store.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;AA6FH,kDAsSC;AAhYD,yCAemB;AA6CnB,MAAM,oBAAoB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA,CAAC,UAAU;AAChE,MAAM,qBAAqB,GAAG,GAAG,CAAA;AACjC,MAAM,mBAAmB,GAAG,EAAE,CAAA;AAC9B,MAAM,QAAQ,GAAG,eAAe,CAAA;AA2BhC,SAAgB,mBAAmB,CAAC,IAAuB;IACzD,MAAM,EACJ,GAAG,EACH,EAAE,EACF,GAAG,EACH,OAAO,EACP,cAAc,EACd,aAAa,EACb,WAAW,GAAG,oBAAoB,EAClC,YAAY,GAAG,qBAAqB,EACpC,UAAU,GAAG,6BAAkB,EAC/B,UAAU,GAAG,mBAAmB,GACjC,GAAG,IAAI,CAAA;IAER,4EAA4E;IAC5E,8EAA8E;IAC9E,oCAAoC;IACpC,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAkB,CAAA,CAAC,mBAAmB;IAEvE,SAAS,SAAS,CAAC,EAAU;QAC3B,OAAO,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;IACtB,CAAC;IACD,SAAS,YAAY,CAAC,EAAU;QAC9B,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAA;IACtC,CAAC;IAED,SAAS,aAAa;QACpB,IAAI,CAAC;YACH,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,+DAA+D;QACjE,CAAC;IACH,CAAC;IAED,SAAS,YAAY,CAAC,EAAU;QAC9B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAA;YACrD,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAqB,CAAA;YAC7C,8DAA8D;YAC9D,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;gBACxE,OAAO,IAAI,CAAA;YACb,CAAC;YACD,OAAO,CAAC,CAAA;QACV,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC;IAED,SAAS,aAAa,CAAC,CAAmB;QACxC,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QAClD,EAAE,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;IAClE,CAAC;IAED,SAAS,OAAO;QACd,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;gBACzC,6DAA6D;gBAC7D,OAAO,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAA;YAC1C,CAAC,CAAC,CAAA;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAA;QACX,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,aAAa,EAAE,CAAA;IACf,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,YAAY,CAAC,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC7B,uEAAuE;YACvE,4DAA4D;YAC5D,MAAM,QAAQ,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;YACrD,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,CAAA;YAC5C,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;gBACnC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;oBACrC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,CAAA;gBAC5C,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,SAAS,aAAa,CACpB,QAA0C,EAC1C,UAAoB;QAEpB,MAAM,KAAK,GAA2B,EAAE,CAAA;QACxC,IAAI,CAAC,QAAQ;YAAE,OAAO,KAAK,CAAA;QAC3B,IAAI,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxD,KAAK,CAAC,sBAAsB,CAAC,GAAG,IAAA,oBAAS,EACvC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAC7B,UAAU,CACX,CAAA;QACH,CAAC;QACD,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;YACxB,KAAK,CAAC,YAAY,CAAC,GAAG,IAAA,oBAAS,EAAC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;QAClE,CAAC;QACD,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;YACvB,KAAK,CAAC,WAAW,CAAC,GAAG,IAAA,oBAAS,EAAC,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC,CAAA;QAChE,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;IAED,SAAS,MAAM,CACb,QAAsB,EACtB,QAA+B;QAE/B,MAAM,EAAE,GAAG,QAAQ,CAAC,EAAE,IAAI,GAAG,EAAE,CAAA;QAC/B,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,SAAS,CAAA;QACnD,MAAM,WAAW,GAAG,IAAA,6BAAkB,EAAC;YACrC,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,YAAY,EAAE,QAAQ,CAAC,YAAY;YACnC,UAAU;SACX,CAAC,CAAA;QAEF,MAAM,MAAM,GAAmB;YAC7B,EAAE;YACF,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,OAAO,EAAE,QAAQ,CAAC,OAAO;SAC1B,CAAA;QAED,sEAAsE;QACtE,MAAM,UAAU,GAAG,iBAAiB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;QACrD,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,QAAQ,GAAG,YAAY,CAAC,UAAU,CAAC,CAAA;YACzC,IACE,QAAQ;gBACR,QAAQ,CAAC,MAAM,KAAK,MAAM;gBAC1B,EAAE,GAAG,QAAQ,CAAC,MAAM,IAAI,UAAU,CAAC,QAAQ,EAC3C,CAAC;gBACD,QAAQ,CAAC,WAAW,IAAI,CAAC,CAAA;gBACzB,QAAQ,CAAC,MAAM,GAAG,EAAE,CAAA;gBACpB,QAAQ,CAAC,OAAO,GAAG,UAAU,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,CAAA;gBACnE,MAAM,SAAS,GAAG,IAAA,2BAAgB,EAChC,QAAQ,CAAC,WAAW,EACpB,QAAQ,CAAC,aAAa,KAAK,aAAa,EACxC,UAAU,CACX,CAAA;gBACD,QAAQ,CAAC,eAAe,GAAG,IAAA,6BAAkB,EAC3C,QAAQ,CAAC,eAAe,EACxB,SAAS,CAAC,KAAK,CAChB,CAAA;gBACD,aAAa,CAAC,QAAQ,CAAC,CAAA;gBACvB,OAAO;oBACL,EAAE,EAAE,QAAQ,CAAC,EAAE;oBACf,WAAW;oBACX,WAAW,EAAE,QAAQ,CAAC,WAAW;oBACjC,UAAU,EAAE,SAAS;oBACrB,KAAK,EAAE,KAAK;oBACZ,QAAQ,EAAE,QAAQ;iBACnB,CAAA;YACH,CAAC;YACD,0EAA0E;YAC1E,iBAAiB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;QACvC,CAAC;QAED,yBAAyB;QACzB,MAAM,EAAE,GAAG,GAAG,IAAA,0BAAe,EAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAA;QAClD,MAAM,SAAS,GAAG,IAAA,2BAAgB,EAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,CAAA;QACxD,MAAM,QAAQ,GAAqB;YACjC,EAAE;YACF,WAAW;YACX,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,YAAY,EAAE,QAAQ,CAAC,YAAY;YACnC,UAAU;YACV,cAAc;YACd,OAAO;YACP,OAAO,EAAE,EAAE;YACX,MAAM,EAAE,EAAE;YACV,WAAW,EAAE,CAAC;YACd,eAAe,EAAE,SAAS,CAAC,KAAK;YAChC,MAAM,EAAE,MAAM;YACd,UAAU,EAAE,IAAI;YAChB,aAAa,EAAE,IAAI;YACnB,WAAW,EAAE,IAAI;YACjB,QAAQ,EAAE,EAAE;YACZ,OAAO,EAAE,CAAC,MAAM,CAAC;SAClB,CAAA;QAED,kEAAkE;QAClE,MAAM,UAAU,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;QACpC,aAAa,CAAC,QAAQ,CAAC,CAAA;QACvB,MAAM,KAAK,GAAG,aAAa,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;QACjD,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACpD,IAAI,CAAC;gBACH,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAA;YACtD,CAAC;YAAC,MAAM,CAAC;gBACP,6DAA6D;YAC/D,CAAC;QACH,CAAC;QAED,iBAAiB,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC,CAAA;QACtC,uDAAuD;QACvD,KAAK,EAAE,CAAA;QACP,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;IAC1F,CAAC;IAED,SAAS,GAAG,CAAC,EAAU;QACrB,OAAO,YAAY,CAAC,EAAE,CAAC,CAAA;IACzB,CAAC;IAED,SAAS,YAAY,CAAC,EAAU,EAAE,KAAsB,EAAE,KAAc;QACtE,MAAM,CAAC,GAAG,YAAY,CAAC,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,CAAC;YAAE,OAAM;QACd,CAAC,CAAC,UAAU,GAAG,KAAK,IAAI,GAAG,EAAE,CAAA;QAC7B,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,aAAa;YAC/B,CAAC,CAAC,IAAA,6BAAkB,EAAC,CAAC,CAAC,aAAa,EAAE,KAAK,CAAC;YAC5C,CAAC,CAAC,KAAK,CAAA;QACT,aAAa,CAAC,CAAC,CAAC,CAAA;IAClB,CAAC;IAED,SAAS,cAAc,CAAC,EAAU,EAAE,OAAwB;QAC1D,MAAM,CAAC,GAAG,YAAY,CAAC,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,CAAC;YAAE,OAAM;QACd,CAAC,CAAC,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,EAAE,OAAO,EAAE,UAAU,CAAC,CAAA;QAC9D,aAAa,CAAC,CAAC,CAAC,CAAA;IAClB,CAAC;IAED,SAAS,SAAS,CAAC,EAAU,EAAE,WAAmB;QAChD,MAAM,CAAC,GAAG,YAAY,CAAC,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,CAAC;YAAE,OAAM;QACd,CAAC,CAAC,WAAW,GAAG,WAAW,CAAA;QAC3B,aAAa,CAAC,CAAC,CAAC,CAAA;IAClB,CAAC;IAED,SAAS,OAAO,CAAC,EAAU;QACzB,MAAM,CAAC,GAAG,YAAY,CAAC,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,CAAC;YAAE,OAAM;QACd,CAAC,CAAC,MAAM,GAAG,UAAU,CAAA;QACrB,aAAa,CAAC,CAAC,CAAC,CAAA;QAChB,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,EAAE,EAAE,CAAC;YAChD,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAA;QACzC,CAAC;IACH,CAAC;IAED,SAAS,IAAI;QACX,MAAM,GAAG,GAAuB,EAAE,CAAA;QAClC,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,EAAE,CAAC;YAC3B,MAAM,CAAC,GAAG,YAAY,CAAC,EAAE,CAAC,CAAA;YAC1B,IAAI,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACpB,CAAC;QACD,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,SAAS,KAAK;QACZ,MAAM,SAAS,GAAG,IAAI,EAAE,CAAA;QACxB,MAAM,MAAM,GAAG,GAAG,EAAE,GAAG,WAAW,CAAA;QAClC,MAAM,MAAM,GAAa,EAAE,CAAA;QAE3B,mBAAmB;QACnB,MAAM,SAAS,GAAuB,EAAE,CAAA;QACxC,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;YAC1B,IAAI,CAAC,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC;gBACtB,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;gBAClB,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;YACnB,CAAC;iBAAM,CAAC;gBACN,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACnB,CAAC;QACH,CAAC;QAED,2DAA2D;QAC3D,IAAI,SAAS,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;YACpC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAA,CAAC,eAAe;YAC7D,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,GAAG,YAAY,CAAA;YAChD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;gBAClC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;gBAC7B,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;YAC9B,CAAC;QACH,CAAC;QAED,gEAAgE;QAChE,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;YACxB,KAAK,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,iBAAiB,EAAE,CAAC;gBAC7C,IAAI,MAAM,KAAK,EAAE;oBAAE,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;YACjD,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC;IAED,SAAS,YAAY,CAAC,EAAU;QAC9B,IAAI,CAAC;YACH,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;QAC5D,CAAC;QAAC,MAAM,CAAC;YACP,eAAe;QACjB,CAAC;IACH,CAAC;IAED,SAAS,MAAM,CAAC,OAAe;QAC7B,OAAO,IAAA,6BAAkB,EAAC,IAAI,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAA;IACnD,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;AAC/F,CAAC;AAED,8EAA8E;AAC9E,SAAS,IAAI,CAAC,GAAG,KAAe;IAC9B,OAAO,KAAK;SACT,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,CAAC;SAC9E,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;SAC3B,IAAI,CAAC,GAAG,CAAC,CAAA;AACd,CAAC;AAED,8DAA8D;AAC9D,SAAS,UAAU,CAAI,GAAQ,EAAE,IAAO,EAAE,GAAW;IACnD,MAAM,IAAI,GAAG,CAAC,GAAG,GAAG,EAAE,IAAI,CAAC,CAAA;IAC3B,OAAO,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AACjE,CAAC;AAED,8DAA8D;AAC9D,SAAS,IAAI,CAAC,EAAgB;IAC5B,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,CAAA;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAA;IACX,CAAC;AACH,CAAC"}

package/dist/agent/incident.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Incident core (Epic #195, Phase 2).
+ *
+ * Pure decision logic for the incident-reporting layer that sits on top of the
+ * turn-trace watchdog (Phase 1). Given a stall incident, this module decides:
+ *   - its fingerprint (what makes two stalls "the same problem"),
+ *   - whether/how to escalate a repeat (quiet → repeat → recommend-investigate),
+ *   - how to scrub evidence before any of it can leave the machine,
+ *   - how to summarise a set of incidents into a digest line/report.
+ *
+ * Like turn-trace.ts and orphan-wake.ts, this file performs NO IO and imports
+ * no runtime code (only types, which are erased), so every rule here is
+ * unit-testable without a filesystem, a clock, or a live session. The store
+ * (incident-store.ts) owns persistence and calls into these functions.
+ */
+import type { TurnStage, TurnFailureClass } from './turn-trace';
+/** Placeholder substituted for any redacted span in a scrubbed export. */
+export declare const REDACTION = "\u2039redacted\u203A";
+/** Escalation level reached for an incident fingerprint. */
+export type EscalationLevel = 'quiet' | 'repeat' | 'investigate';
+/** Lifecycle status of a persisted incident. */
+export type IncidentStatus = 'open' | 'resolved';
+/**
+ * A single occurrence of a stall, captured each time the watchdog re-raises the
+ * same fingerprint. Kept small — the store retains only a capped tail of these.
+ */
+export interface IncidentSample {
+    /** When this occurrence was raised (epoch ms). */
+    at: number;
+    /** How long the turn had sat in the stalled stage (ms). */
+    sinceMs: number;
+    /** The stage's timeout budget at the time (ms). */
+    budgetMs: number;
+    /** Whether a fresh `.processing` sentinel showed the turn was mid-work. */
+    midTurn: boolean;
+}
+/**
+ * The persisted record for one incident fingerprint. Written to
+ * `<dir>/<id>/manifest.json`. Fields are deliberately free of chat content;
+ * `channel` is the transport name only (never a chat id), and evidence with
+ * potentially sensitive text lives in scrubbed sibling artifact files.
+ */
+export interface IncidentManifest {
+    /** Filesystem-safe unique id: `<fingerprintHash>-<firstAt>`. */
+    id: string;
+    /** Stable dedup key: stage + failure class + CLI version. */
+    fingerprint: string;
+    stage: TurnStage;
+    failureClass: TurnFailureClass | null;
+    /** Claude CLI version at capture time, or 'unknown'. Part of the fingerprint. */
+    cliVersion: string;
+    /** Gateway version at capture time, or 'unknown'. Context only. */
+    gatewayVersion: string;
+    /** Transport name only: 'telegram' | 'discord' | 'line' | 'api'. */
+    channel: string;
+    /** First and most-recent occurrence (epoch ms). */
+    firstAt: number;
+    lastAt: number;
+    /** Total occurrences folded into this incident. */
+    occurrences: number;
+    /** Highest escalation level reached. */
+    escalationLevel: EscalationLevel;
+    status: IncidentStatus;
+    /** Last time the user was notified, and at what level (dedupes re-notifying). */
+    notifiedAt: number | null;
+    notifiedLevel: EscalationLevel | null;
+    /** Linked GitHub issue number, if one was filed for this fingerprint. */
+    githubIssue: number | null;
+    /** Recovery actions + outcomes — populated in Phase 3; [] in Phase 2. */
+    recovery: RecoveryOutcome[];
+    /** Capped tail of recent occurrences. */
+    samples: IncidentSample[];
+}
+/** A recovery action and its result (Phase 3 fills these; typed here for the schema). */
+export interface RecoveryOutcome {
+    action: string;
+    at: number;
+    ok: boolean;
+    detail?: string;
+}
+/**
+ * Compute the dedup fingerprint. Two stalls are "the same problem" when they
+ * hit the same pipeline stage with the same failure attribution on the same CLI
+ * version — a new CLI version is treated as a distinct problem so a regression
+ * introduced by an upgrade does not silently fold into an old fingerprint.
+ */
+export declare function computeFingerprint(input: {
+    stage: TurnStage;
+    failureClass: TurnFailureClass | null;
+    cliVersion: string | null | undefined;
+}): string;
+/**
+ * Deterministic, dependency-free hash (FNV-1a → base36). Used to derive a short
+ * filesystem-safe prefix for an incident id from its fingerprint. Not used for
+ * anything security-sensitive — only stable naming/dedup.
+ */
+export declare function fingerprintHash(fingerprint: string): string;
+/** Configurable thresholds for escalation. */
+export interface EscalationConfig {
+    /** Dedup window — repeats within this of the last occurrence fold in (ms). */
+    windowMs: number;
+    /** Occurrence count at/after which we recommend investigation. */
+    investigateThreshold: number;
+}
+export declare const DEFAULT_ESCALATION: EscalationConfig;
+/** The escalation verdict for a single (folded) occurrence. */
+export interface EscalationDecision {
+    level: EscalationLevel;
+    /** Whether the user should be notified for this occurrence. */
+    notify: boolean;
+}
+/**
+ * Decide how to escalate given the running occurrence count for a fingerprint
+ * and whether the user was already notified at 'investigate' level.
+ *
+ *   - 1st occurrence            → quiet notify (one short heads-up)
+ *   - repeats below threshold   → silent increment (no re-notify)
+ *   - Nth (N ≥ threshold), once → recommend investigation (louder notify)
+ *   - after that                → silent (already recommended)
+ *
+ * Pure: the caller supplies the count and prior-notify state.
+ */
+export declare function decideEscalation(occurrences: number, alreadyInvestigateNotified: boolean, cfg?: EscalationConfig): EscalationDecision;
+/** The maximum of two escalation levels (for tracking the highest reached). */
+export declare function maxEscalationLevel(a: EscalationLevel, b: EscalationLevel): EscalationLevel;
+/**
+ * Scrub text destined for an exported/persisted artifact. Removes:
+ *   1. every caller-supplied literal (chat ids, usernames) — matched verbatim,
+ *   2. recognisable secret/PII shapes (tokens, keys, emails).
+ *
+ * Literals are escaped before use so a value like `a.b` cannot act as a regex.
+ * Pure and idempotent enough for repeated application (placeholder is inert).
+ */
+export declare function scrubText(text: string, redactions?: string[]): string;
+/** A roll-up of incidents over a period, for the digest line / trend report. */
+export interface DigestSummary {
+    /** Incidents (folded fingerprints) whose lastAt falls in the window. */
+    total: number;
+    /** Sum of occurrences across those incidents. */
+    occurrences: number;
+    openCount: number;
+    byStage: Record<string, number>;
+    byFailureClass: Record<string, number>;
+    byCliVersion: Record<string, number>;
+}
+/**
+ * Summarise the incidents whose most-recent occurrence lands in
+ * `[now - sinceMs, now]`. Pure — the store supplies the manifests it read.
+ */
+export declare function summarizeIncidents(manifests: IncidentManifest[], sinceMs: number, now: number): DigestSummary;
+/**
+ * One-line, human-friendly digest. Zero-incident periods produce a short "all
+ * clear" line rather than nothing, so the digest itself is a liveness signal.
+ */
+export declare function formatDigestLine(summary: DigestSummary, label?: string): string;
+//# sourceMappingURL=incident.d.ts.map

package/dist/agent/incident.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"incident.d.ts","sourceRoot":"","sources":["../../src/agent/incident.ts"],"names":[],"mappings":"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"}