crewhaus 0.1.8 → 0.2.0

package/dist/security-digest.js

@@ -0,0 +1,650 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+/**
+ * Item 48 — `crewhaus security digest` plumbing, factored out of the entry
+ * file `index.ts` (which runs a top-level argv switch and so cannot be
+ * imported by a test without executing the CLI). Side-effect-free on import
+ * and directly unit-testable, mirroring `audit-verify.ts` / `retention.ts`.
+ *
+ * The problem this closes: warn-tier egress verdicts, boundary redactions,
+ * injection hits, justification denials and circuit events all accumulate in
+ * `.crewhaus/audit` JSONL and on the TraceEventBus, but nothing triages them
+ * — answering "are we being probed, or over-blocking?" meant hand-grepping.
+ * This module walks the durable stores and emits a ranked rollup; the live
+ * per-run tally lives in `@crewhaus/runtime-core`'s observability module
+ * (CREWHAUS_SECURITY_DIGEST=1).
+ *
+ * WHAT THE AUDIT KINDS ACTUALLY CARRY TODAY (verified by grepping for
+ * writers, 2026-07 — the digest reports on what has writers and keeps the
+ * declared-but-writerless kinds visible instead of fabricating sections):
+ *
+ *   kinds WITH writers:
+ *     - permission_justification_evaluated  runtime-core's intent gate
+ *       (payload { toolName, justification, verdict, reason, judgeModel,
+ *       confidence? }) — powers the top-denied-tools + judge-deny-rate rollup.
+ *     - policy_decision   policy-engine's auditPolicyDecision (payload
+ *       { toolName, sideEffect, decision, reason, tenantId, matchedRule }) —
+ *       deny/audit-and-allow rows only by default.
+ *     - model_call, gateway_request, secrets_rotation, secrets_access,
+ *       deployment_action, retention_enforcement, alert_raised (item-31
+ *       alert watchdog's `AlertAuditSink`, see alert-sink.ts; payload
+ *       { sessionId, metric, observed, threshold, baselineSessions, detail })
+ *       — operational kinds; the digest counts them per-kind (countsByKind)
+ *       but builds no verdict rollup from them.
+ *
+ *   kinds DECLARED in @crewhaus/audit-log but with NO writer anywhere in the
+ *   tree today: `egress_decision`, `tool_classification`, `session_fork`,
+ *   `tenancy_context`. Egress verdicts currently surface ONLY as ephemeral
+ *   `permission_decision` trace events (outcome: egress-*) — runtime-core
+ *   never appends the documented `egress_decision` audit record. The digest
+ *   still aggregates `egress_decision` records by the payload shape the
+ *   audit-log header documents ({ sinkId, sinkScope, verdict, originsFound,
+ *   matchCount }) so the rollup lights up the day a writer lands, and it
+ *   reports these kinds under `absentDeclaredKinds` so "0 egress rows"
+ *   reads as "no durable writer yet", not "no egress happened".
+ *
+ * Because block-tier verdicts DO leave durable residue in the session event
+ * logs (`.crewhaus/sessions/<id>.jsonl` `tool_result` events carry the
+ * `[justification denied]` / `[egress denied]` / `[blocked by hook]` notices,
+ * and injection redactions replace the tool output with
+ * `[tool output redacted: prompt injection detected: <rule-ids>]`), the
+ * digest ALSO scans session JSONLs in the window — that is where injection
+ * rule-id hit counts come from today.
+ *
+ * TRUST BOUNDARY (adversarial-review F1): everything parsed out of session
+ * `tool_result` content is attacker-reachable — any tool that returns
+ * malicious output can start it with a forged denial/redaction notice, so
+ * the session-derived counters are HEURISTIC (best-effort), never
+ * authoritative; the report says so explicitly and keeps them in their own
+ * section, separate from the audit-derived rollups. And because a forged
+ * notice can carry terminal escape codes or newlines aimed at the
+ * operator's terminal, every content-derived string is neutralized at PARSE
+ * time ({@link sanitizeContentString}: C0+C1 controls incl. ESC/newlines
+ * stripped, length clamped) so every renderer — text, JSON, HTML, --notify
+ * payload — sees only sanitized values. Audit-record strings get the same
+ * treatment as defense in depth (judge reasons can embed model-generated
+ * text). The HTML renderer additionally HTML-escapes, as before.
+ *
+ * HTML output: apps/cli already depends on `@crewhaus/eval-report`, but its
+ * render.ts keeps `shell`/`escapeHtml` private to the eval-report shapes.
+ * Rather than widen that package's public API for a CLI-side concern, the
+ * digest ships a small local renderer following the same dependency-free
+ * style (inline CSS variables, no external assets).
+ *
+ * Webhook notify: `--notify <url>` POSTs the JSON digest with plain `fetch`
+ * — deliberately NOT via `@crewhaus/channel-adapter-slack`, to keep the CLI
+ * dependency graph clean (the adapter pulls in channel-runtime concerns the
+ * digest doesn't need). Slack incoming webhooks reject arbitrary JSON, so
+ * point `--notify` at a receiver that accepts the digest shape, or wrap it:
+ * a one-line proxy that forwards `{ text: renderSecurityDigestText(...) }`
+ * satisfies Slack.
+ */
+const MS_PER_DAY = 86_400_000;
+const AUDIT_RELPATH = ".crewhaus/audit";
+const SESSIONS_RELPATH = ".crewhaus/sessions";
+const AUDIT_DAY_FILE_REGEX = /^(\d{4})-(\d{2})-(\d{2})\.jsonl$/;
+const SESSION_EVENT_LOG_REGEX = /^sess_[0-9a-f]{16}\.jsonl$/;
+/** How many entries each ranked "top …" list carries. */
+const TOP_N = 10;
+/**
+ * Every kind declared by `@crewhaus/audit-log`. Kept as a local literal list
+ * (rather than importing a value — the package only exports the TYPE) so the
+ * digest can report declared kinds that produced zero records in the window.
+ *
+ * `satisfies ReadonlyArray<AuditKind>` only checks that every entry HERE is a
+ * valid `AuditKind` — it is a subset check, not an exhaustiveness check. It
+ * does NOT catch a NEW kind added to the `AuditKind` union that this list
+ * forgets to list (F7: `alert_raised`, added by the item-31 alert watchdog,
+ * compiled cleanly for a while despite being absent here). Keep this list in
+ * sync BY HAND whenever `AuditKind` gains a member.
+ */
+export const DECLARED_AUDIT_KINDS = [
+    "policy_decision",
+    "model_call",
+    "tool_classification",
+    "gateway_request",
+    "session_fork",
+    "tenancy_context",
+    "secrets_rotation",
+    "secrets_access",
+    "deployment_action",
+    "egress_decision",
+    "permission_justification_evaluated",
+    "retention_enforcement",
+    "governance_approval",
+    "governance_proposal",
+    "alert_raised",
+    "slo_mitigation",
+];
+/** Thrown by `parseSinceFlag` on an unparseable `--since`. The CLI entry
+ *  file catches it and routes the message through `die()`; tests assert on
+ *  `.message` without the process exiting. */
+export class InvalidSinceFlagError extends Error {
+    value;
+    name = "InvalidSinceFlagError";
+    constructor(value) {
+        super(`invalid --since "${value}" — expected a day window like 7d or 30d, or an ISO date/datetime (e.g. 2026-06-01 or 2026-06-01T00:00:00Z)`);
+        this.value = value;
+    }
+}
+/**
+ * Parse the `--since` flag: `<N>d` (a trailing day window, default `7d`) or
+ * an ISO date/datetime (bare dates are UTC midnight per `Date.parse`).
+ */
+export function parseSinceFlag(value, now = () => Date.now()) {
+    const raw = value ?? "7d";
+    const dayMatch = /^(\d+)d$/.exec(raw);
+    if (dayMatch !== null) {
+        const days = Number(dayMatch[1]);
+        if (days <= 0)
+            throw new InvalidSinceFlagError(raw);
+        return { sinceMs: now() - days * MS_PER_DAY, label: raw };
+    }
+    const ms = Date.parse(raw);
+    if (Number.isNaN(ms))
+        throw new InvalidSinceFlagError(raw);
+    return { sinceMs: ms, label: raw };
+}
+function asObject(payload) {
+    return payload !== null && typeof payload === "object" && !Array.isArray(payload)
+        ? payload
+        : undefined;
+}
+/** Length clamp for content-derived strings in the digest (reasons, names). */
+const MAX_CONTENT_STRING_LENGTH = 256;
+/** Tighter clamp for injection rule ids — real ids are short slugs. */
+const MAX_RULE_ID_LENGTH = 64;
+// Matches C0 controls (U+0000–U+001F, incl. ESC/newline/CR), DEL (U+007F)
+// and C1 controls (U+0080–U+009F, incl. CSI/OSC single-byte forms).
+// eslint-disable-next-line no-control-regex
+// biome-ignore lint/suspicious/noControlCharactersInRegex: intentional control-character detection/sanitization
+const CONTROL_CHAR_PATTERN = /[\u0000-\u001f\u007f-\u009f]/g;
+/**
+ * Neutralize a string parsed out of stored session/audit content before it
+ * enters the digest (adversarial-review F1). Session `tool_result` content
+ * is attacker-reachable — a malicious tool output can embed ANSI escape
+ * sequences (rewrite the operator's terminal, forge "ALL CLEAR" lines) or
+ * newlines (inject whole fake report lines) into anything the text renderer
+ * prints raw. Applied at PARSE time so text, JSON, HTML and the --notify
+ * payload all carry only sanitized values: strips C0/C1 control characters
+ * (including ESC and line breaks) and clamps the length.
+ */
+export function sanitizeContentString(value, maxLength = MAX_CONTENT_STRING_LENGTH) {
+    const stripped = value.replace(CONTROL_CHAR_PATTERN, "");
+    return stripped.length > maxLength ? `${stripped.slice(0, maxLength)}…` : stripped;
+}
+/** `YYYY-MM-DD` day file → epoch ms of the LAST instant of that UTC day
+ *  (mirrors retention.ts): a day overlaps the window when its newest
+ *  possible record does. Undefined for labels that don't round-trip. */
+function endOfUtcDayMs(y, m, d) {
+    const startMs = Date.UTC(Number(y), Number(m) - 1, Number(d));
+    const roundTrip = new Date(startMs).toISOString().slice(0, 10);
+    if (roundTrip !== `${y}-${m}-${d}`)
+        return undefined;
+    return startMs + MS_PER_DAY - 1;
+}
+function rankEntries(map, score, build) {
+    return [...map.entries()]
+        .sort((a, b) => score(b[1]) - score(a[1]) || a[0].localeCompare(b[0]))
+        .slice(0, TOP_N)
+        .map(([name, v]) => build(name, v));
+}
+/**
+ * Walk `<rootDir>/.crewhaus/audit` + `<rootDir>/.crewhaus/sessions` and
+ * build the windowed rollup. Missing stores yield an empty (but complete)
+ * digest — the command is a report, not a gate, so it never throws on an
+ * absent or partially-corrupt store; malformed lines are counted instead.
+ */
+export function buildSecurityDigest(opts) {
+    const rootDir = resolve(opts.rootDir);
+    const now = opts.now ?? (() => Date.now());
+    const auditDir = join(rootDir, AUDIT_RELPATH);
+    const { sinceMs } = opts.window;
+    let recordsScanned = 0;
+    let recordsInWindow = 0;
+    let malformedLines = 0;
+    const countsByKind = new Map();
+    // Justification rollup accumulators.
+    let jEvaluated = 0;
+    let jAllowed = 0;
+    let jDenied = 0;
+    const deniedTools = new Map();
+    const judges = new Map();
+    // Egress rollup accumulators (no writer today — see module header).
+    let ePassed = 0;
+    let eWarned = 0;
+    let eBlocked = 0;
+    const sinks = new Map();
+    const origins = new Map();
+    // Policy rollup accumulators.
+    let pDenied = 0;
+    let pAuditAndAllow = 0;
+    let pOther = 0;
+    const policyDeniedTools = new Map();
+    if (existsSync(auditDir)) {
+        const dayFiles = readdirSync(auditDir)
+            .filter((f) => {
+            const m = AUDIT_DAY_FILE_REGEX.exec(f);
+            if (m === null)
+                return false;
+            const end = endOfUtcDayMs(m[1], m[2], m[3]);
+            return end !== undefined && end >= sinceMs;
+        })
+            .sort();
+        for (const file of dayFiles) {
+            for (const raw of readFileSync(join(auditDir, file), "utf8").split("\n")) {
+                if (raw === "")
+                    continue;
+                let record;
+                try {
+                    record = JSON.parse(raw);
+                }
+                catch {
+                    malformedLines += 1;
+                    continue;
+                }
+                recordsScanned += 1;
+                if (typeof record.ts !== "number" || record.ts < sinceMs)
+                    continue;
+                recordsInWindow += 1;
+                const kind = typeof record.kind === "string" ? record.kind : "(unknown)";
+                countsByKind.set(kind, (countsByKind.get(kind) ?? 0) + 1);
+                if (kind === "permission_justification_evaluated") {
+                    const p = (asObject(record.payload) ?? {});
+                    const toolName = typeof p.toolName === "string" ? sanitizeContentString(p.toolName) : "(unknown tool)";
+                    const judgeModel = typeof p.judgeModel === "string"
+                        ? sanitizeContentString(p.judgeModel)
+                        : "(unknown judge)";
+                    const denied = p.verdict === "deny";
+                    jEvaluated += 1;
+                    if (denied)
+                        jDenied += 1;
+                    else
+                        jAllowed += 1;
+                    const judge = judges.get(judgeModel) ?? { evaluated: 0, denied: 0 };
+                    judge.evaluated += 1;
+                    if (denied)
+                        judge.denied += 1;
+                    judges.set(judgeModel, judge);
+                    if (denied) {
+                        const t = deniedTools.get(toolName) ?? {
+                            denials: 0,
+                            judges: new Set(),
+                            confidences: [],
+                        };
+                        t.denials += 1;
+                        t.judges.add(judgeModel);
+                        if (typeof p.confidence === "number")
+                            t.confidences.push(p.confidence);
+                        if (typeof p.reason === "string")
+                            t.lastReason = sanitizeContentString(p.reason);
+                        deniedTools.set(toolName, t);
+                    }
+                }
+                else if (kind === "egress_decision") {
+                    const p = (asObject(record.payload) ?? {});
+                    const sinkId = typeof p.sinkId === "string" ? sanitizeContentString(p.sinkId) : "(unknown sink)";
+                    const verdict = p.verdict;
+                    if (verdict === "warn")
+                        eWarned += 1;
+                    else if (verdict === "block")
+                        eBlocked += 1;
+                    else
+                        ePassed += 1;
+                    if (verdict === "warn" || verdict === "block") {
+                        const s = sinks.get(sinkId) ?? { warned: 0, blocked: 0, origins: new Set() };
+                        if (verdict === "warn")
+                            s.warned += 1;
+                        else
+                            s.blocked += 1;
+                        if (Array.isArray(p.originsFound)) {
+                            for (const o of p.originsFound) {
+                                if (typeof o === "string") {
+                                    const origin = sanitizeContentString(o);
+                                    s.origins.add(origin);
+                                    origins.set(origin, (origins.get(origin) ?? 0) + 1);
+                                }
+                            }
+                        }
+                        sinks.set(sinkId, s);
+                    }
+                }
+                else if (kind === "policy_decision") {
+                    const p = (asObject(record.payload) ?? {});
+                    if (p.decision === "deny") {
+                        pDenied += 1;
+                        const toolName = typeof p.toolName === "string" ? sanitizeContentString(p.toolName) : "(unknown tool)";
+                        policyDeniedTools.set(toolName, (policyDeniedTools.get(toolName) ?? 0) + 1);
+                    }
+                    else if (p.decision === "audit-and-allow") {
+                        pAuditAndAllow += 1;
+                    }
+                    else {
+                        pOther += 1;
+                    }
+                }
+            }
+        }
+    }
+    const sessions = scanSessionDenials(join(rootDir, SESSIONS_RELPATH), sinceMs);
+    const absentDeclaredKinds = DECLARED_AUDIT_KINDS.filter((k) => !countsByKind.has(k));
+    return {
+        version: 1,
+        generatedAt: new Date(now()).toISOString(),
+        since: new Date(sinceMs).toISOString(),
+        windowLabel: opts.window.label,
+        rootDir,
+        audit: {
+            dir: auditDir,
+            recordsScanned,
+            recordsInWindow,
+            malformedLines,
+            countsByKind: Object.fromEntries([...countsByKind.entries()].sort()),
+            absentDeclaredKinds,
+        },
+        justification: {
+            evaluated: jEvaluated,
+            allowed: jAllowed,
+            denied: jDenied,
+            denyRate: jEvaluated > 0 ? jDenied / jEvaluated : null,
+            topDeniedTools: rankEntries(deniedTools, (t) => t.denials, (toolName, t) => ({
+                toolName,
+                denials: t.denials,
+                judges: [...t.judges].sort(),
+                meanConfidence: t.confidences.length > 0
+                    ? t.confidences.reduce((a, b) => a + b, 0) / t.confidences.length
+                    : null,
+                ...(t.lastReason !== undefined ? { lastReason: t.lastReason } : {}),
+            })),
+            byJudge: [...judges.entries()]
+                .sort((a, b) => b[1].evaluated - a[1].evaluated || a[0].localeCompare(b[0]))
+                .map(([judgeModel, j]) => ({ judgeModel, evaluated: j.evaluated, denied: j.denied })),
+        },
+        egress: {
+            decisions: ePassed + eWarned + eBlocked,
+            passed: ePassed,
+            warned: eWarned,
+            blocked: eBlocked,
+            topSinks: rankEntries(sinks, (s) => s.blocked * 2 + s.warned, (sinkId, s) => ({
+                sinkId,
+                warned: s.warned,
+                blocked: s.blocked,
+                origins: [...s.origins].sort(),
+            })),
+            topOrigins: rankEntries(origins, (c) => c, (name, count) => ({ name, count })),
+        },
+        policy: {
+            decisions: pDenied + pAuditAndAllow + pOther,
+            denied: pDenied,
+            auditAndAllow: pAuditAndAllow,
+            topDeniedTools: rankEntries(policyDeniedTools, (c) => c, (name, count) => ({ name, count })),
+        },
+        sessions,
+    };
+}
+/** Prefixes the runtime writes into `tool_result` event contents on the
+ *  block tier — the durable residue the session scan keys on. Kept in one
+ *  place so the digest and its tests cite the same literals as
+ *  `@crewhaus/runtime-core`'s denial messages. */
+export const SESSION_DENIAL_MARKERS = {
+    justification: "[justification denied]",
+    egress: "[egress denied]",
+    hook: "[blocked by hook]",
+};
+/** The runtime's redaction notice is a single line; excluding `\n`/`\r` from
+ *  the rule-id capture keeps a forged notice from smuggling multi-line
+ *  content into the parse (the ids are additionally sanitized + clamped). */
+const REDACTION_NOTICE_REGEX = /^\[tool output redacted: prompt injection detected: ([^\]\n\r]*)\]/;
+function scanSessionDenials(sessionsDir, sinceMs) {
+    let scanned = 0;
+    let justificationDenials = 0;
+    let egressBlocks = 0;
+    let hookBlocks = 0;
+    let injectionRedactions = 0;
+    const ruleHits = new Map();
+    if (existsSync(sessionsDir)) {
+        for (const file of readdirSync(sessionsDir).sort()) {
+            if (!SESSION_EVENT_LOG_REGEX.test(file))
+                continue;
+            scanned += 1;
+            for (const raw of readFileSync(join(sessionsDir, file), "utf8").split("\n")) {
+                if (raw === "")
+                    continue;
+                let event;
+                try {
+                    event = JSON.parse(raw);
+                }
+                catch {
+                    continue; // the digest triages; event-log integrity is not its job
+                }
+                if (event.kind !== "tool_result")
+                    continue;
+                if (typeof event.ts !== "number" || event.ts < sinceMs)
+                    continue;
+                const payload = asObject(event.payload);
+                const content = payload?.["content"];
+                if (typeof content !== "string")
+                    continue;
+                if (content.startsWith(SESSION_DENIAL_MARKERS.justification))
+                    justificationDenials += 1;
+                else if (content.startsWith(SESSION_DENIAL_MARKERS.egress))
+                    egressBlocks += 1;
+                else if (content.startsWith(SESSION_DENIAL_MARKERS.hook))
+                    hookBlocks += 1;
+                else {
+                    const m = REDACTION_NOTICE_REGEX.exec(content);
+                    if (m !== null) {
+                        injectionRedactions += 1;
+                        for (const rule of m[1].split(",")) {
+                            // Rule ids come from attacker-reachable tool_result content —
+                            // neutralize before they can reach a renderer (F1).
+                            const id = sanitizeContentString(rule.trim(), MAX_RULE_ID_LENGTH);
+                            if (id !== "")
+                                ruleHits.set(id, (ruleHits.get(id) ?? 0) + 1);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return {
+        scanned,
+        justificationDenials,
+        egressBlocks,
+        hookBlocks,
+        injectionRedactions,
+        injectionRuleHits: [...ruleHits.entries()]
+            .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+            .slice(0, TOP_N)
+            .map(([name, count]) => ({ name, count })),
+    };
+}
+/** Render the digest as the CLI's indented text summary lines. */
+export function renderSecurityDigestText(d) {
+    const lines = [];
+    const pct = (r) => (r === null ? "n/a" : `${(r * 100).toFixed(1)}%`);
+    lines.push(`window: ${d.windowLabel} (since ${d.since}) — ${d.audit.recordsInWindow} audit record(s) in window (${d.audit.recordsScanned} scanned${d.audit.malformedLines > 0 ? `, ${d.audit.malformedLines} malformed line(s) skipped` : ""})`);
+    lines.push(`justification gate: ${d.justification.evaluated} evaluated, ${d.justification.denied} denied (deny rate ${pct(d.justification.denyRate)})`);
+    for (const t of d.justification.topDeniedTools) {
+        lines.push(`  ✗ ${t.toolName} — ${t.denials} denial(s) [judge=${t.judges.join(", ")}${t.meanConfidence !== null ? `, mean confidence ${t.meanConfidence.toFixed(2)}` : ""}]${t.lastReason !== undefined ? ` — last: ${t.lastReason}` : ""}`);
+    }
+    for (const j of d.justification.byJudge) {
+        lines.push(`  • judge ${j.judgeModel}: ${j.evaluated} evaluated, ${j.denied} denied`);
+    }
+    if (d.egress.decisions > 0) {
+        lines.push(`egress: ${d.egress.decisions} decision(s) — ${d.egress.warned} warned, ${d.egress.blocked} blocked`);
+        for (const s of d.egress.topSinks) {
+            lines.push(`  ✗ sink ${s.sinkId} — ${s.warned} warned / ${s.blocked} blocked (origins: ${s.origins.join(", ") || "n/a"})`);
+        }
+        for (const o of d.egress.topOrigins)
+            lines.push(`  • origin ${o.name}: ${o.count} hit(s)`);
+    }
+    else {
+        lines.push("egress: no durable egress_decision records — the kind is declared but has no writer yet; live verdicts surface per-run via CREWHAUS_SECURITY_DIGEST=1");
+    }
+    lines.push(`policy engine: ${d.policy.decisions} audited decision(s) — ${d.policy.denied} denied, ${d.policy.auditAndAllow} audit-and-allow`);
+    for (const t of d.policy.topDeniedTools)
+        lines.push(`  ✗ ${t.name} — ${t.count} denial(s)`);
+    // Content-derived section — kept apart from the audit-derived rollups
+    // above: these markers live in tool_result content, which any malicious
+    // tool output can forge (adversarial-review F1).
+    lines.push(`sessions — content-derived, heuristic (${d.sessions.scanned} event log(s)): ${d.sessions.justificationDenials} justification denial notice(s), ${d.sessions.egressBlocks} egress block(s), ${d.sessions.hookBlocks} hook block(s), ${d.sessions.injectionRedactions} injection redaction(s)`);
+    for (const r of d.sessions.injectionRuleHits) {
+        lines.push(`  ✗ injection rule ${r.name}: ${r.count} hit(s)`);
+    }
+    lines.push("  ~ session-derived counts are heuristic (parsed from tool_result content, which tool output can forge); audit-derived counts above are authoritative");
+    const kindCounts = Object.entries(d.audit.countsByKind)
+        .map(([k, n]) => `${k}=${n}`)
+        .join(", ");
+    lines.push(`audit kinds in window: ${kindCounts === "" ? "none" : kindCounts}`);
+    if (d.audit.absentDeclaredKinds.length > 0) {
+        lines.push(`  ~ declared kinds with no records: ${d.audit.absentDeclaredKinds.join(", ")}`);
+    }
+    return lines;
+}
+// ---------------------------------------------------------------------------
+// HTML rendering — local, dependency-free, following the visual style of
+// packages/eval-report/src/render.ts (whose shell/escapeHtml are private to
+// the eval-report shapes; see the module header for why we don't widen them).
+// ---------------------------------------------------------------------------
+const STYLE = `
+:root {
+  --bg: #0f1115; --fg: #e6e6e6; --muted: #999; --pass: #4caf50; --fail: #ef5350;
+  --card: #1a1d23; --border: #333; --link: #61dafb;
+}
+* { box-sizing: border-box; }
+body { font-family: ui-sans-serif, system-ui, sans-serif; background: var(--bg); color: var(--fg); margin: 0; padding: 24px; line-height: 1.5; }
+h1 { margin: 0 0 16px; }
+h2 { margin: 24px 0 12px; }
+.meta { color: var(--muted); font-size: 13px; margin-bottom: 24px; }
+.aggregate { display: grid; grid-template-columns: repeat(auto-fit, minmax(140px, 1fr)); gap: 8px; margin-bottom: 24px; }
+.aggregate .card { background: var(--card); border: 1px solid var(--border); border-radius: 6px; padding: 12px; }
+.aggregate .label { color: var(--muted); font-size: 12px; text-transform: uppercase; }
+.aggregate .value { font-size: 22px; font-weight: 600; margin-top: 4px; }
+table { width: 100%; border-collapse: collapse; background: var(--card); border-radius: 6px; overflow: hidden; margin-bottom: 16px; }
+th, td { padding: 10px 14px; text-align: left; border-bottom: 1px solid var(--border); font-size: 14px; }
+th { background: #14171c; }
+tr:last-child td { border-bottom: none; }
+.fail { color: var(--fail); font-weight: 600; }
+.note { color: var(--muted); font-size: 13px; }
+`;
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+function card(label, value) {
+    return `<div class="card"><div class="label">${escapeHtml(label)}</div><div class="value">${escapeHtml(value)}</div></div>`;
+}
+function tableOf(headers, rows) {
+    if (rows.length === 0)
+        return '<p class="note">none</p>';
+    return `<table>
+  <thead><tr>${headers.map((h) => `<th>${escapeHtml(h)}</th>`).join("")}</tr></thead>
+  <tbody>${rows
+        .map((r) => `<tr>${r.map((c) => `<td>${escapeHtml(c)}</td>`).join("")}</tr>`)
+        .join("")}</tbody>
+</table>`;
+}
+/** Render the digest as a self-contained HTML page (no external assets). */
+export function renderSecurityDigestHtml(d) {
+    const pct = (r) => (r === null ? "n/a" : `${(r * 100).toFixed(1)}%`);
+    const body = `
+<h1>Security digest</h1>
+<p class="meta">Window ${escapeHtml(d.windowLabel)} (since ${escapeHtml(d.since)}) · generated ${escapeHtml(d.generatedAt)} · ${escapeHtml(d.rootDir)}</p>
+<section class="aggregate">
+${card("Audit records", String(d.audit.recordsInWindow))}
+${card("Justification denials", String(d.justification.denied))}
+${card("Judge deny rate", pct(d.justification.denyRate))}
+${card("Egress warned", String(d.egress.warned))}
+${card("Egress blocked", String(d.egress.blocked))}
+${card("Policy denials", String(d.policy.denied))}
+${card("Injection redactions", String(d.sessions.injectionRedactions))}
+</section>
+<h2>Top denied tools (justification gate)</h2>
+${tableOf(["Tool", "Denials", "Judges", "Mean confidence", "Last reason"], d.justification.topDeniedTools.map((t) => [
+        t.toolName,
+        String(t.denials),
+        t.judges.join(", "),
+        t.meanConfidence !== null ? t.meanConfidence.toFixed(2) : "n/a",
+        t.lastReason ?? "",
+    ]))}
+<h2>Judges</h2>
+${tableOf(["Judge", "Evaluated", "Denied"], d.justification.byJudge.map((j) => [j.judgeModel, String(j.evaluated), String(j.denied)]))}
+<h2>Egress sinks (warn/block)</h2>
+${d.egress.decisions === 0
+        ? '<p class="note">no durable egress_decision records — the kind is declared but has no writer yet; live verdicts surface per-run via CREWHAUS_SECURITY_DIGEST=1</p>'
+        : tableOf(["Sink", "Warned", "Blocked", "Origins"], d.egress.topSinks.map((s) => [
+            s.sinkId,
+            String(s.warned),
+            String(s.blocked),
+            s.origins.join(", "),
+        ]))}
+<h2>Policy denials</h2>
+${tableOf(["Tool", "Denials"], d.policy.topDeniedTools.map((t) => [t.name, String(t.count)]))}
+<h2>Injection rule hits (session redaction notices)</h2>
+${tableOf(["Rule", "Hits"], d.sessions.injectionRuleHits.map((r) => [r.name, String(r.count)]))}
+<p class="note">Session-derived counts are heuristic — parsed from tool_result content, which tool output can forge; audit-derived counts are authoritative.</p>
+<h2>Audit kinds in window</h2>
+${tableOf(["Kind", "Records"], Object.entries(d.audit.countsByKind).map(([k, n]) => [k, String(n)]))}
+<p class="note">Declared kinds with no records in window: ${escapeHtml(d.audit.absentDeclaredKinds.join(", ") || "none")}</p>
+`;
+    return `<!doctype html>
+<html><head>
+<meta charset="utf-8">
+<title>Security digest ${escapeHtml(d.windowLabel)}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+${body}
+</body></html>`;
+}
+/** Thrown by `notifySecurityDigest` on a malformed URL or non-2xx response.
+ *  The CLI routes it through `die()` — a scheduled digest whose notification
+ *  silently failed would fabricate assurance, so it exits 1 loudly
+ *  (mirroring audit-verify's requested-but-unconsulted-anchor stance). */
+export class NotifyError extends Error {
+    name = "NotifyError";
+}
+/**
+ * POST the JSON digest to a webhook. Plain `fetch`, no channel-adapter
+ * dependency (see module header); Slack users wrap the payload — incoming
+ * webhooks accept `{ text }`, not arbitrary JSON.
+ *
+ * A plain-http URL is allowed (local tunnels/dev receivers) but warned about
+ * on stderr (adversarial-review F3): the digest is security telemetry —
+ * denial counts, tool names, judge reasons — and posting it cleartext leaks
+ * it to every on-path observer. `warn` is injectable for tests.
+ */
+export async function notifySecurityDigest(url, digest, fetchImpl = fetch, warn = (line) => process.stderr.write(`${line}\n`)) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new NotifyError(`invalid --notify URL "${url}"`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new NotifyError(`--notify only supports http(s) URLs (got "${parsed.protocol}//")`);
+    }
+    if (parsed.protocol === "http:") {
+        warn(`warning: --notify ${url} uses plain http — the digest is security telemetry and will transit unencrypted; prefer an https webhook`);
+    }
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(digest),
+        });
+    }
+    catch (err) {
+        throw new NotifyError(`--notify POST to ${url} failed: ${err.message}`);
+    }
+    if (!res.ok) {
+        throw new NotifyError(`--notify POST to ${url} returned ${res.status} ${res.statusText}`);
+    }
+}

package/dist/sessions-index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Item #57 — durable sessions index. Before a session JSONL is evicted (30-day
+ * TTL), it is summarized into a compact index entry under
+ * `.crewhaus/sessions-index/<id>.json` so the harness retains long-term
+ * knowledge (outcome, tools used, ratings, key facts) past raw-transcript
+ * retention. These entries feed the memory-store / few-shot / FAQ features.
+ *
+ * The summary logic lives in `@crewhaus/session-store` (`summarizeSession`, a
+ * deterministic no-model reducer). This module is the CLI-side glue: read a
+ * session's JSONL, summarize it, and write the index entry idempotently. Kept
+ * thin + separately testable, mirroring `feedback.ts` / `dataset-mine.ts`.
+ */
+import { type SessionSummary } from "@crewhaus/session-store";
+/** The index directory, relative to a session root's PARENT `.crewhaus`. */
+export declare const SESSIONS_INDEX_DIRNAME = "sessions-index";
+/** Parse a JSONL blob into `{ kind, payload }` events, skipping bad lines. */
+export declare function parseSessionLog(text: string): Array<{
+    kind?: string;
+    payload?: unknown;
+}>;
+/**
+ * Summarize the session whose `.jsonl` lives at `logPath` into `indexDir`,
+ * returning the written summary (or undefined when the log is missing/empty).
+ * Idempotent: re-writing the same session overwrites its entry rather than
+ * duplicating. `now` is injectable for deterministic tests.
+ */
+export declare function summarizeSessionIntoIndex(sessionId: string, logPath: string, indexDir: string, now?: () => Date): SessionSummary | undefined;