@davesheffer/hunch 1.31.0 → 1.32.0

package/dist/core/taskReportEvidence.js

@@ -0,0 +1,268 @@
+import { createHash } from "node:crypto";
+import { execFile, execFileSync, spawn } from "node:child_process";
+import { lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { analyzeDiff } from "../extractors/diff.js";
+import { workingDiff, workingFiles } from "../extractors/git.js";
+import { assertCompleteRepoScan, scanRepo } from "../extractors/indexer.js";
+import { checkConformance } from "./conformance.js";
+import { effectiveForbids, matchForbids } from "./constraintmatch.js";
+import { ReportCheckSchema, ReportRecordSchema, beginReportCheck, readTaskReport, recordReportCheck, recordReportConformance, reportHash } from "./taskReport.js";
+export function snapshotDeliveredRecords(store, envelope) {
+    const records = [];
+    for (const item of envelope.delivered) {
+        const record = store.recs(item.kind === "relationships" ? "edges" : item.kind).find(r => r.id === item.record_id);
+        if (!record)
+            continue;
+        const raw = record;
+        const text = (...keys) => keys.map(k => raw[k]).find(v => typeof v === "string");
+        const candidate = ReportRecordSchema.safeParse({
+            record_id: item.record_id, kind: item.kind, content_hash: reportHash(record),
+            title: (text("title", "statement", "name", "reason") ?? item.record_id).slice(0, 500),
+            lesson: (text("decision", "statement", "description", "root_cause", "reason", "title", "name") ?? item.record_id).slice(0, 12_000),
+            recorded_at: text("date", "created_at", "observed_at", "valid_from") ?? null,
+        });
+        if (candidate.success)
+            records.push(candidate.data);
+    }
+    return records;
+}
+/** Bounded source snapshot, not a committed change proof. Ignored files and
+ * Hunch's own memory/cache are excluded and explicitly disclosed. */
+export function reportSourceSnapshot(root) {
+    const limitations = ["Git-ignored files, Hunch memory/cache, and external dependencies are outside this source snapshot."];
+    try {
+        const base = realpathSync(root);
+        const env = { ...process.env, GIT_OPTIONAL_LOCKS: "0" };
+        for (const key of Object.keys(env))
+            if (key.startsWith("GIT_") && key !== "GIT_OPTIONAL_LOCKS")
+                delete env[key];
+        const paths = execFileSync("git", ["-C", base, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], { env, timeout: 5_000, maxBuffer: 4_000_000 }).toString("utf8").split("\0").filter(Boolean);
+        const sorted = [...new Set(paths)].sort();
+        if (sorted.length > 20_000)
+            throw new Error("source file count exceeds snapshot limit");
+        const entries = [];
+        let bytes = 0;
+        for (const path of sorted) {
+            if (path.split("/").some(p => p === ".hunch" || p === ".hunch-cache" || p === ".git"))
+                continue;
+            const file = resolve(base, path);
+            const rel = relative(base, file);
+            if (isAbsolute(rel) || rel === ".." || rel.startsWith("../") || rel.startsWith("..\\"))
+                throw new Error("source path escapes repository");
+            let stat;
+            try {
+                stat = lstatSync(file);
+            }
+            catch (e) {
+                if (e.code === "ENOENT") {
+                    entries.push([path, null, 0]);
+                    continue;
+                }
+                throw e;
+            }
+            const parent = relative(base, realpathSync(dirname(file)));
+            if (isAbsolute(parent) || parent === ".." || parent.startsWith("../") || parent.startsWith("..\\"))
+                throw new Error("source parent escapes repository");
+            if (stat.isSymbolicLink()) {
+                entries.push([path, reportHash(readlinkSync(file)), 0o120000]);
+                continue;
+            }
+            if (!stat.isFile())
+                throw new Error("submodules or non-file sources require separate verification");
+            bytes += stat.size;
+            if (bytes > 64_000_000 || stat.size > 8_000_000)
+                throw new Error("source bytes exceed snapshot limit");
+            const content = readFileSync(file);
+            const after = lstatSync(file);
+            if (stat.mtimeMs !== after.mtimeMs || stat.ctimeMs !== after.ctimeMs || stat.size !== after.size || content.length !== stat.size)
+                throw new Error("source changed during snapshot");
+            entries.push([path, `sha256:${createHash("sha256").update(content).digest("hex")}`, stat.mode & 0o111]);
+        }
+        return { hash: reportHash(entries), limitations };
+    }
+    catch {
+        return { hash: null, limitations: [...limitations, "A complete bounded source snapshot was unavailable; no current-change verification is claimed."] };
+    }
+}
+/** Evaluate every delivered lesson's DECLARED rule against the files this task
+ * changed (working tree vs HEAD). Deterministic and Hunch-owned: the agent
+ * neither chooses the rule nor submits the verdict. A constraint is judged by its
+ * forbids matcher over the added lines of its scoped changed files; a decision by
+ * its conformance predicates over the current working graph, and only when a
+ * predicate's subject lives in a changed file. Everything else stays
+ * `not-exercised` or `unavailable` — never "satisfied" by file overlap. */
+export function runReportConformance(root, store, taskId) {
+    const report = readTaskReport(root, taskId);
+    if (report.task.state !== "open")
+        throw new Error("cannot evaluate rules for a closed task");
+    const delivered = [...new Map(report.deliveries.flatMap(d => d.records).filter(r => r.kind === "constraints" || r.kind === "decisions").map(r => [`${r.kind}:${r.record_id}:${r.content_hash}`, r])).values()];
+    if (!delivered.length)
+        return [];
+    const before = reportSourceSnapshot(root).hash;
+    const files = workingFiles(root);
+    const changed = new Set(files);
+    const diff = workingDiff(root);
+    const analysis = analyzeDiff(diff);
+    const truncated = diff.endsWith("…(diff truncated)…");
+    let graph;
+    const workingGraph = () => {
+        if (graph !== undefined)
+            return graph;
+        try {
+            const scan = scanRepo(store, root, { churn: false, source: { kind: "working" } });
+            assertCompleteRepoScan(scan);
+            graph = { symbols: scan.symbols, edges: scan.edges };
+        }
+        catch {
+            graph = null;
+        }
+        return graph;
+    };
+    const results = [];
+    for (const record of delivered) {
+        const base = { source: "local-rule-check", record_id: record.record_id, kind: record.kind, content_hash: record.content_hash, snapshot: null };
+        const note = (rule, outcome, detail, scoped = []) => results.push({ ...base, rule, outcome, files: scoped.slice(0, 64), detail: detail.slice(0, 1000) });
+        if (record.kind === "constraints") {
+            const constraint = store.recs("constraints").find(c => c.id === record.record_id);
+            if (!constraint || reportHash(constraint) !== record.content_hash) {
+                note("constraint-forbids", "unavailable", "The delivered record revision is no longer the stored revision; the rule of a different revision is not evaluated.");
+                continue;
+            }
+            const forbids = effectiveForbids(constraint);
+            if (!forbids) {
+                note("constraint-forbids", "unavailable", "This constraint declares no forbids matcher; a scope-only rule cannot be verified deterministically.");
+                continue;
+            }
+            const scoped = files.filter(f => store.checkConstraints(f).some(c => c.id === constraint.id));
+            if (!scoped.length) {
+                note("constraint-forbids", "not-exercised", "No changed file falls in this constraint's scope.");
+                continue;
+            }
+            if (truncated) {
+                note("constraint-forbids", "unavailable", "The working diff exceeds the bounded analysis budget; added lines were not fully inspected.", scoped);
+                continue;
+            }
+            const match = matchForbids(forbids, new Set(analysis.addedDeps), scoped.flatMap(f => analysis.addedLinesByFile.get(f) ?? []));
+            if (match)
+                note("constraint-forbids", "violated", `Added code trips the ${match.tier} rule: ${match.evidence.slice(0, 3).join("; ")}`, scoped);
+            else
+                note("constraint-forbids", "satisfied", `Added lines in ${scoped.length} scoped file(s) trip none of the forbidden ${[forbids.deps.length && "dependencies", forbids.symbols.length && "symbols", forbids.patterns.length && "patterns"].filter(Boolean).join("/")}.`, scoped);
+            continue;
+        }
+        const decision = store.recs("decisions").find(d => d.id === record.record_id);
+        if (!decision || reportHash(decision) !== record.content_hash) {
+            note("decision-conformance", "unavailable", "The delivered record revision is no longer the stored revision; the predicates of a different revision are not evaluated.");
+            continue;
+        }
+        if (!decision.conformance?.length) {
+            note("decision-conformance", "unavailable", "This decision declares no conformance predicate; its intent cannot be verified deterministically.");
+            continue;
+        }
+        const current = workingGraph();
+        if (!current) {
+            note("decision-conformance", "unavailable", "The working source graph could not be scanned completely; no predicate result is claimed.");
+            continue;
+        }
+        const subjects = decision.conformance.map(p => p.subject);
+        const exercised = current.symbols.filter(s => changed.has(s.file) && subjects.some(ref => ref === s.id || ref === s.name || (ref.includes(":") && s.name === ref.slice(ref.lastIndexOf(":") + 1) && (s.file === ref.slice(0, ref.lastIndexOf(":")) || s.file.endsWith("/" + ref.slice(0, ref.lastIndexOf(":")))))));
+        if (!exercised.length) {
+            note("decision-conformance", "not-exercised", "No predicate subject is defined in a changed file.");
+            continue;
+        }
+        const verdicts = checkConformance(store, { graph: current }).filter(r => r.decision === decision.id);
+        if (!verdicts.length) {
+            note("decision-conformance", "unavailable", "The decision is not in force; its predicates are not evaluated.");
+            continue;
+        }
+        const scoped = [...new Set(exercised.map(s => s.file))].sort();
+        const failed = verdicts.filter(v => !v.satisfied);
+        if (failed.length)
+            note("decision-conformance", "violated", failed.map(v => v.detail).join("; "), scoped);
+        else
+            note("decision-conformance", "satisfied", verdicts.map(v => v.detail).join("; "), scoped);
+    }
+    const after = reportSourceSnapshot(root).hash;
+    const snapshot = before !== null && before === after ? before : null;
+    return results.map(result => {
+        const value = { ...result, snapshot, ...(snapshot === null ? { detail: `${result.detail} Source changed during evaluation, so this result is not bound to a current snapshot.`.slice(0, 1000) } : {}) };
+        recordReportConformance(root, taskId, value);
+        return value;
+    });
+}
+/** A deliberately explicit command wrapper. The caller chooses the command;
+ * reports never execute commands automatically to validate submitted claims. */
+export async function runReportCheck(root, taskId, command, label, timeoutMs = 120_000, options = {}) {
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 600_000)
+        throw new Error("verification timeout must be between 1 and 600000 ms");
+    options.signal?.throwIfAborted();
+    const task = readTaskReport(root, taskId).task;
+    if (task.state !== "open")
+        throw new Error("cannot verify a closed task");
+    const before = reportSourceSnapshot(root);
+    // Validate sensitive arguments before executing or writing anything.
+    ReportCheckSchema.parse({ label, command, exit_code: null, output_hash: reportHash(""), before_snapshot: before.hash, after_snapshot: null, snapshot_limitations: before.limitations, timed_out: false, source: "local-command-runner" });
+    const checkId = beginReportCheck(root, taskId, label);
+    const result = await new Promise((resolveResult) => {
+        const child = spawn(command[0], command.slice(1), { cwd: root, shell: false, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, detached: process.platform !== "win32" });
+        const stdout = createHash("sha256"), stderr = createHash("sha256");
+        let timedOut = false, cancelled = false, settled = false;
+        let cleanupTimer;
+        const settle = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", cancel);
+            if (cleanupTimer)
+                clearTimeout(cleanupTimer);
+            child.stdout.destroy();
+            child.stderr.destroy();
+            resolveResult({ code, timedOut, cancelled, hash: reportHash({ stdout: stdout.digest("hex"), stderr: stderr.digest("hex") }) });
+        };
+        const stopTree = () => {
+            if (settled || cleanupTimer)
+                return;
+            if (child.pid) {
+                if (process.platform === "win32")
+                    execFile("taskkill", ["/pid", String(child.pid), "/T", "/F"], { timeout: 1_000, windowsHide: true }, () => { });
+                else {
+                    try {
+                        process.kill(-child.pid, "SIGKILL");
+                    }
+                    catch {
+                        child.kill("SIGKILL");
+                    }
+                }
+            }
+            // A descendant can detach or inherit pipes. Always bound settlement even
+            // if the OS cannot confirm process-tree cleanup; timed-out is never pass.
+            cleanupTimer = setTimeout(() => settle(null), 1_200);
+        };
+        const cancel = () => { cancelled = true; stopTree(); };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            stopTree();
+        }, timeoutMs);
+        // Separate streaming digests are stable across stdout/stderr chunk ordering.
+        child.stdout.on("data", chunk => { if (!settled) {
+            stdout.update(chunk);
+            options.onStdout?.(chunk);
+        } });
+        child.stderr.on("data", chunk => { if (!settled) {
+            stderr.update(chunk);
+            options.onStderr?.(chunk);
+        } });
+        child.once("error", () => settle(null));
+        child.once("close", code => settle(code));
+        options.signal?.addEventListener("abort", cancel, { once: true });
+        if (options.signal?.aborted)
+            cancel();
+    });
+    const after = reportSourceSnapshot(root);
+    const check = { check_id: checkId, label, command, exit_code: result.code, output_hash: result.hash, before_snapshot: before.hash, after_snapshot: after.hash,
+        snapshot_limitations: [...new Set([...before.limitations, ...after.limitations])], timed_out: result.timedOut, cancelled: result.cancelled, source: "local-command-runner" };
+    recordReportCheck(root, taskId, check);
+    return check;
+}
+//# sourceMappingURL=taskReportEvidence.js.map

package/dist/core/taskReportHook.d.ts

@@ -0,0 +1,20 @@
+import type { HookProvider, HunchHookInput } from "./agenthook.js";
+export declare function hookReportTaskId(root: string, provider: HookProvider, event: HunchHookInput): string | null;
+/** Every prompt receives its exact ID, even when ambient reminders were deduped.
+ * No raw prompt, host session identifier, or transcript is retained. */
+export declare function startHookReport(root: string, provider: HookProvider, event: HunchHookInput): string | null;
+/** A presentation notice never denies Stop or injects another model turn. Stop
+ * can precede another hook's continuation, so it does not close an open task. */
+export declare function stopHookReport(root: string, provider: HookProvider, event: HunchHookInput): {
+    systemMessage: string;
+} | null;
+/** Call only after emitting the native denial. Evidence failures must never
+ * suppress the gate response or attach it to a guessed task. */
+export declare function observeHookDenial(root: string, provider: HookProvider, event: HunchHookInput, target: string, denial: {
+    reason: string;
+    event: {
+        kind: "constraint" | "veto";
+        constraint?: string;
+        decision?: string;
+    };
+}): void;

package/dist/core/taskReportHook.js

@@ -0,0 +1,76 @@
+/** Native lifecycle coverage is independent of whether a model follows reporting
+ * instructions. Only an authoritative prompt identity may join its evidence. */
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { findRoot } from "./paths.js";
+import { readTaskReport, recordReportRefusal, reportHash, reportPresentationEnabled, startReportTask } from "./taskReport.js";
+import { reportSourceSnapshot } from "./taskReportEvidence.js";
+import { renderTaskReport, writeTaskReportHtml } from "./taskReportRender.js";
+function identity(root, provider, event) {
+    if (provider !== "claude" || !event.cwd || realpathSync(findRoot(event.cwd)) !== realpathSync(root))
+        return null;
+    for (const value of [event.session_id, event.prompt_id, event.agent_id]) {
+        if (value !== undefined && (!value.length || value.length > 1024 || /[\u0000-\u001f\u007f]/.test(value)))
+            return null;
+    }
+    if (!event.session_id)
+        return null;
+    if (!event.prompt_id)
+        return "legacy";
+    return `htask_${reportHash([realpathSync(root), provider, event.session_id, event.prompt_id, event.agent_id ?? null]).slice(7, 31)}`;
+}
+export function hookReportTaskId(root, provider, event) {
+    try {
+        const id = identity(root, provider, event);
+        return id === "legacy" ? null : id;
+    }
+    catch {
+        return null;
+    }
+}
+/** Every prompt receives its exact ID, even when ambient reminders were deduped.
+ * No raw prompt, host session identifier, or transcript is retained. */
+export function startHookReport(root, provider, event) {
+    const id = identity(root, provider, event);
+    if (!id || id === "legacy")
+        return null;
+    const task = startReportTask(root, "Claude task", id);
+    return `Hunch has opened this prompt's report: ${task.task_id}. Reuse this exact ID for this prompt. Call hunch_task(action: "start", task_id: "${task.task_id}", title: "Claude task") to obtain verification_argv; do not create another report. Pass this task_id to hunch_context and decision/correction/finding captures, and finish with hunch_task before responding. A host Stop notice will show the evidence even if no task-linked memory was observed.`;
+}
+/** A presentation notice never denies Stop or injects another model turn. Stop
+ * can precede another hook's continuation, so it does not close an open task. */
+export function stopHookReport(root, provider, event) {
+    if (!reportPresentationEnabled(root))
+        return null;
+    const id = identity(root, provider, event);
+    if (!id)
+        return null;
+    if (id === "legacy")
+        return { systemMessage: "Hunch hook active. This Claude version does not provide an exact prompt identifier, so contribution for this response is unverified. Explicit task reports remain available with hunch report." };
+    try {
+        const report = readTaskReport(root, id, reportSourceSnapshot(root).hash);
+        let card = renderTaskReport(report);
+        try {
+            const file = writeTaskReportHtml(root, id);
+            card = card.replace(/^Evidence .*$/m, `Evidence  ${pathToFileURL(file).href}`);
+        }
+        catch { /* exact CLI evidence link remains available */ }
+        return { systemMessage: card };
+    }
+    catch {
+        return { systemMessage: `Hunch report unavailable for ${id}. Contribution is unverified; inspect with hunch report ${id}.` };
+    }
+}
+/** Call only after emitting the native denial. Evidence failures must never
+ * suppress the gate response or attach it to a guessed task. */
+export function observeHookDenial(root, provider, event, target, denial) {
+    try {
+        const taskId = hookReportTaskId(root, provider, event);
+        const recordId = denial.event.kind === "constraint" ? denial.event.constraint : denial.event.decision;
+        if (!taskId || !recordId)
+            return;
+        recordReportRefusal(root, taskId, { source: "native-edit-gate", outcome: "denial-emitted", kind: denial.event.kind, record_id: recordId, target, reason_hash: reportHash(denial.reason) });
+    }
+    catch { /* the already emitted gate response remains authoritative */ }
+}
+//# sourceMappingURL=taskReportHook.js.map

package/dist/core/taskReportPaths.d.ts

@@ -0,0 +1,3 @@
+/** Report paths are local to this physical worktree. Existing symlinks and
+ * hard-linked files are refused; never follow a cache pointer into another scope. */
+export declare function assertReportPath(root: string, ...parts: string[]): string;

package/dist/core/taskReportPaths.js

@@ -0,0 +1,23 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+/** Report paths are local to this physical worktree. Existing symlinks and
+ * hard-linked files are refused; never follow a cache pointer into another scope. */
+export function assertReportPath(root, ...parts) {
+    let path = realpathSync(root);
+    for (const part of parts) {
+        if (!/^[A-Za-z0-9._-]+$/.test(part) || part === "." || part === "..")
+            throw new Error("invalid local report path component");
+        path = join(path, part);
+        try {
+            const stat = lstatSync(path);
+            if (stat.isSymbolicLink() || (stat.isFile() && stat.nlink > 1))
+                throw new Error("report path must not follow symlinks or hard links");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    return path;
+}
+//# sourceMappingURL=taskReportPaths.js.map

package/dist/core/taskReportPublic.d.ts

@@ -0,0 +1,31 @@
+export declare function publicTaskReport(root: string, taskId: string): {
+    content_hash: string;
+    schema: "hunch.public-task-report/1";
+    title: string;
+    state: "open" | "completed" | "interrupted";
+    records: {
+        record_id: string;
+        kind: string;
+        content_hash: string;
+        title: string;
+        lesson: string;
+        recorded_at: string | null;
+    }[];
+    deliveries: {
+        occurrence_id: string;
+        receipt_id: string;
+        envelope_hash: string;
+        record_id: string;
+        record_hash: string;
+    }[];
+    applications: {
+        occurrence_id: string;
+        record_id: string;
+        content_hash: string;
+        attribution: "agent-reported";
+        detail: string;
+    }[];
+    limitations: string[];
+};
+export type PublicTaskReport = ReturnType<typeof publicTaskReport>;
+export declare function renderPublicTaskReportHtml(report: PublicTaskReport): string;

package/dist/core/taskReportPublic.js

@@ -0,0 +1,45 @@
+/** Publication is a fresh public-store projection, never redaction of a local
+ * report's prose. Task titles, actions, commands and native envelope text are private. */
+import { JsonStore } from "../store/jsonStore.js";
+import { hunchPaths } from "./paths.js";
+import { readTaskReport, reportHash } from "./taskReport.js";
+import { reportSourceSnapshot } from "./taskReportEvidence.js";
+export function publicTaskReport(root, taskId) {
+    const report = readTaskReport(root, taskId, reportSourceSnapshot(root).hash);
+    const publicStore = new JsonStore(hunchPaths(root));
+    const records = new Map();
+    const deliveries = [];
+    for (const delivery of report.deliveries) {
+        for (const snapshot of delivery.records) {
+            const item = delivery.envelope.delivered.find(r => r.record_id === snapshot.record_id && r.kind === snapshot.kind);
+            if (!item)
+                continue;
+            const record = publicStore.loadAll(item.kind === "relationships" ? "edges" : item.kind).find(r => r.id === item.record_id);
+            if (!record || reportHash(record) !== snapshot.content_hash)
+                continue;
+            // Reconstruct human-readable content from public records, not caller-supplied snapshots.
+            const raw = record;
+            const text = (...keys) => keys.map(k => raw[k]).find(v => typeof v === "string");
+            const safe = { record_id: record.id, kind: item.kind, content_hash: snapshot.content_hash,
+                title: (text("title", "statement", "name", "reason") ?? record.id).slice(0, 500),
+                lesson: (text("decision", "statement", "description", "root_cause", "reason", "title", "name") ?? record.id).slice(0, 12_000),
+                recorded_at: text("date", "created_at", "observed_at", "valid_from") ?? null };
+            records.set(`${item.kind}:${record.id}:${snapshot.content_hash}`, safe);
+            deliveries.push({ occurrence_id: delivery.occurrence_id, receipt_id: delivery.receipt_id, envelope_hash: delivery.envelope_hash, record_id: record.id, record_hash: snapshot.content_hash });
+        }
+    }
+    const allowed = new Set(deliveries.map(d => `${d.occurrence_id}:${d.record_id}:${d.record_hash}`));
+    const applications = report.claims.filter(c => allowed.has(`${c.occurrence_id}:${c.record_id}:${c.content_hash}`)).map(c => ({ occurrence_id: c.occurrence_id, record_id: c.record_id, content_hash: c.content_hash, attribution: "agent-reported", detail: "Action details withheld from public export." }));
+    const unsigned = {
+        schema: "hunch.public-task-report/1",
+        title: "Hunch contribution · public evidence", state: report.task.state,
+        records: [...records.values()], deliveries, applications,
+        limitations: ["Only exact record revisions currently present in the public store are included.", "Task identity, task prose, private memory, command results and native delivery payloads are omitted. Receipt hashes identify local evidence; their full payloads are not published.", "Agent-reported application does not establish causal impact."],
+    };
+    return { ...unsigned, content_hash: reportHash(unsigned) };
+}
+export function renderPublicTaskReportHtml(report) {
+    const esc = (x) => String(x ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'"><title>${esc(report.title)}</title><style>body{margin:40px auto;padding:0 24px;max-width:850px;font:16px/1.6 system-ui,sans-serif;color:#193725;background:#f6f8f5}article{padding:24px;border:1px solid #b9cbbd;border-radius:12px;background:white;margin:18px 0}h1{font-size:36px}code{overflow-wrap:anywhere}pre{white-space:pre-wrap}summary{cursor:pointer;padding:8px 0}:focus-visible{outline:3px solid #276540}</style></head><body><h1>${esc(report.title)}</h1><p>${report.records.length} public lesson(s) · ${esc(report.state)}</p>${report.records.map(r => `<article><h2>${esc(r.title)}</h2><p>${esc(r.lesson)}</p><p>${esc(r.record_id)}</p><code>${esc(r.content_hash)}</code><details><summary>Inspect public delivery references</summary><pre>${esc(JSON.stringify(report.deliveries.filter(d => d.record_id === r.record_id && d.record_hash === r.content_hash), null, 2))}</pre></details></article>`).join("")}<h2>Limits of this export</h2><ul>${report.limitations.map(l => `<li>${esc(l)}</li>`).join("")}</ul><p>${report.applications.length} agent-reported application(s); action details withheld.</p><footer><code>${esc(report.content_hash)}</code></footer></body></html>`;
+}
+//# sourceMappingURL=taskReportPublic.js.map

package/dist/core/taskReportRender.d.ts

@@ -0,0 +1,6 @@
+import { type LessonHistory, type TaskReport } from "./taskReport.js";
+export declare function writeTaskReportHtml(root: string, taskId: string, publicOnly?: boolean): string;
+export declare function renderTaskReport(report: TaskReport): string;
+/** Standalone, local-only projection. No active content, external assets or
+ * untrusted outbound URLs; evidence references are internal anchors. */
+export declare function renderTaskReportHtml(report: TaskReport, generatedAt?: string, histories?: LessonHistory[] | null): string;

package/dist/core/taskReportRender.js

@@ -0,0 +1,97 @@
+import { mkdirSync } from "node:fs";
+import { writeFileAtomic } from "./io.js";
+import { readTaskReport, readLessonHistory } from "./taskReport.js";
+import { reportSourceSnapshot } from "./taskReportEvidence.js";
+import { assertReportPath } from "./taskReportPaths.js";
+import { publicTaskReport, renderPublicTaskReportHtml } from "./taskReportPublic.js";
+export function writeTaskReportHtml(root, taskId, publicOnly = false) {
+    const report = readTaskReport(root, taskId, reportSourceSnapshot(root).hash);
+    const directory = assertReportPath(root, ".hunch-cache", "reports");
+    mkdirSync(directory, { recursive: true });
+    const file = assertReportPath(root, ".hunch-cache", "reports", `${report.task.task_id}${publicOnly ? ".public" : ""}.html`);
+    let histories = [];
+    if (!publicOnly) {
+        try {
+            histories = historyRecords(report).slice(0, 3).map(record => readLessonHistory(root, { kind: record.kind, record_id: record.record_id, content_hash: record.content_hash }, { limit: 8 }));
+        }
+        catch {
+            histories = null;
+        } // History is optional; retain the primary task evidence if unavailable.
+    }
+    writeFileAtomic(file, publicOnly ? renderPublicTaskReportHtml(publicTaskReport(root, taskId)) : renderTaskReportHtml(report, undefined, histories));
+    return file;
+}
+function plain(value) { return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").replace(/\s+/g, " ").trim(); }
+function clip(value, size = 66) { const chars = [...plain(value)]; return chars.length > size ? chars.slice(0, size - 1).join("") + "…" : chars.join(""); }
+function uniqueRecords(report) {
+    return [...new Map(report.deliveries.flatMap(d => d.records).map(r => [`${r.kind}:${r.record_id}:${r.content_hash}`, r])).values()];
+}
+function historyRecords(report) {
+    return [...new Map([...uniqueRecords(report), ...report.saves.map(s => s.record)].map(r => [`${r.kind}:${r.record_id}:${r.content_hash}`, r])).values()];
+}
+/** The last evaluation of each delivered record revision is its standing. */
+function ruleStanding(report) {
+    return [...new Map(report.conformance.map(r => [`${r.kind}:${r.record_id}:${r.content_hash}`, r])).values()];
+}
+function recordTitle(report, rule) {
+    return uniqueRecords(report).find(r => r.kind === rule.kind && r.record_id === rule.record_id && r.content_hash === rule.content_hash)?.title ?? rule.record_id;
+}
+export function renderTaskReport(report) {
+    const records = uniqueRecords(report);
+    const lines = [`Hunch · ${clip(report.task.title)}`, `Task ${report.task.task_id} · ${report.task.state}`];
+    if (!report.deliveries.length)
+        lines.push("No task-linked delivery observed; connection/use is unverified.");
+    else if (!records.length)
+        lines.push(report.coverage === "no-relevant-memory" ? "No relevant memory returned for this task." : "Memory delivered; exact record snapshots unavailable.");
+    else {
+        lines.push(`Recalled  ${clip(records[0].title, 65)}`);
+        if (records.length > 1)
+            lines.push(`          ${records.length - 1} more lesson(s) in the evidence view`);
+    }
+    const standing = ruleStanding(report);
+    const violated = standing.find(r => r.outcome === "violated");
+    const held = standing.find(r => r.outcome === "satisfied" && r.current);
+    if (report.claims.length) {
+        const claim = report.claims.find(c => c.supported_by) ?? report.claims[0];
+        lines.push(`Applied   ${clip(claim.action, 42)} · ${claim.supported_by ? "rule-supported" : "agent-reported"}`);
+    }
+    else if (held)
+        lines.push(`Conformed ${clip(recordTitle(report, held), 34)} · rule held on ${held.files.length} changed file(s)`);
+    else if (records.length)
+        lines.push("Impact    Memory delivered; contribution unverified.");
+    if (violated)
+        lines.push(`Violated  ${clip(recordTitle(report, violated), 34)} · rule broken on changed files`);
+    if (report.saves.length)
+        lines.push(`Saved     ${clip(report.saves[0].record.title, 38)} · ${report.saves[0].durability}`);
+    if (report.refusals.length)
+        lines.push(`Guarded   Denial emitted · ${clip(report.refusals[0].record_id, 40)}`);
+    const check = report.checks.at(-1);
+    if (check) {
+        const state = check.cancelled ? "cancelled" : check.timed_out ? "timed out" : check.exit_code === 0 ? "passed" : "failed";
+        lines.push(`Checked   ${clip(check.label, 28)} · ${state}${check.current ? " · current source snapshot" : " · current source unverified"}`);
+    }
+    else
+        lines.push("Checked   No independent command result recorded.");
+    lines.push(`Evidence  hunch report ${report.task.task_id} --html`);
+    return lines.join("\n");
+}
+function esc(value) { return String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]); }
+/** Standalone, local-only projection. No active content, external assets or
+ * untrusted outbound URLs; evidence references are internal anchors. */
+export function renderTaskReportHtml(report, generatedAt = new Date().toISOString(), histories = []) {
+    const records = uniqueRecords(report);
+    const section = (title, body) => `<section><h2>${title}</h2>${body}</section>`;
+    const empty = (message) => `<p class="muted">${esc(message)}</p>`;
+    const deliveries = report.deliveries.map((d, index) => `<article id="delivery-${index}"><div class="eyebrow">DELIVERED · ${esc(d.at)}</div><h3>${d.records.length ? esc(d.records.map(r => r.title).join(" · ")) : "No retained lesson snapshot"}</h3><p>${d.envelope.delivered.length} record(s) returned. ${d.envelope.abstention.active ? "Some memory withheld for insufficient relevance or confidence." : ""}</p><details><summary>Inspect exact delivery</summary><dl><dt>Receipt</dt><dd>${esc(d.receipt_id)}</dd><dt>Occurrence</dt><dd>${esc(d.occurrence_id)}</dd><dt>Envelope hash</dt><dd>${esc(d.envelope_hash)}</dd></dl><pre>${esc(d.envelope.text)}</pre></details></article>`).join("");
+    const lessons = records.map(r => `<article><div class="eyebrow">${esc(r.kind)} · ${esc(r.recorded_at ?? "creation date unavailable")}</div><h3>${esc(r.title)}</h3><p class="lesson">${esc(r.lesson)}</p><details><summary>Original record identity</summary><p>${esc(r.record_id)}</p><code>${esc(r.content_hash)}</code></details></article>`).join("");
+    const claims = report.claims.map(c => { const index = report.deliveries.findIndex(d => d.occurrence_id === c.occurrence_id); return `<article><span class="badge">${c.supported_by ? "RULE-SUPPORTED · AGENT-REPORTED" : "AGENT-REPORTED"}</span><h3>${esc(c.action)}</h3><p>${c.supported_by ? `This is the agent's attribution. Hunch separately evaluated the lesson's declared rule against the changed files and it held on the current source (<a href="#rule-${esc(c.supported_by)}">open the rule evaluation</a>).` : "This is the agent's attribution. No current, satisfied rule evaluation supports it; verification below establishes only the recorded command result."}</p><a href="#delivery-${index}">Open the lesson's delivery</a></article>`; }).join("");
+    const rules = ruleStanding(report).map(r => { const label = r.outcome === "satisfied" ? (r.current ? "RULE HELD" : "RULE HELD · SOURCE CHANGED SINCE") : r.outcome === "violated" ? "RULE VIOLATED" : r.outcome === "not-exercised" ? "NOT EXERCISED" : "NO CHECKABLE RULE"; return `<article id="rule-${esc(r.event_id)}"><span class="badge">${label}</span><h3>${esc(recordTitle(report, r))}</h3><p>${esc(r.detail)}</p>${r.files.length ? `<p class="muted">Changed files in scope: ${esc(r.files.join(", "))}</p>` : ""}<details><summary>Inspect rule evaluation</summary><dl><dt>Rule</dt><dd>${esc(r.rule)}</dd><dt>Evaluated</dt><dd>${esc(r.at)}</dd><dt>Record revision</dt><dd>${esc(r.content_hash)}</dd><dt>Source snapshot</dt><dd>${esc(r.snapshot ?? "unavailable")}</dd></dl><p>Hunch evaluated the lesson's own declared rule on the files this task changed. A held rule shows the change conforms to that lesson; it is not proof the agent read it.</p></details></article>`; }).join("");
+    const checks = report.checks.map(c => `<article><span class="badge">${c.cancelled ? "CANCELLED" : c.timed_out ? "TIMED OUT" : c.exit_code === 0 ? "COMMAND PASSED" : "COMMAND FAILED"}</span><h3>${esc(c.label)}</h3><p>${c.current ? "When this report was generated, source matched the snapshots observed before and after this command." : "At report generation, source verification was unavailable or the source had changed."}</p><pre>${esc(c.command.map(x => JSON.stringify(x)).join(" "))}</pre><details><summary>Inspect verification evidence</summary><dl><dt>Observed</dt><dd>${esc(c.at)}</dd><dt>Exit code</dt><dd>${esc(c.exit_code ?? "unavailable")}</dd><dt>Output digest (raw output not retained)</dt><dd>${esc(c.output_hash)}</dd><dt>Before snapshot</dt><dd>${esc(c.before_snapshot ?? "unavailable")}</dd><dt>After snapshot</dt><dd>${esc(c.after_snapshot ?? "unavailable")}</dd></dl>${c.snapshot_limitations.map(x => `<p>${esc(x)}</p>`).join("")}</details></article>`).join("");
+    const saves = report.saves.map(s => `<article><span class="badge">${esc(s.durability.toUpperCase())}</span><h3>${esc(s.record.title)}</h3><p>${esc(s.operation)} in ${esc(s.home)} memory. Exact saved revision: <code>${esc(s.record.content_hash)}</code>.</p><p>${s.durability === "local" ? "No exact commit or push proof is retained for this revision." : "Git proof applies to this revision at the observed time, not the current remote state."}</p><details><summary>Inspect save evidence</summary><p>${esc(s.event_id)} · ${esc(s.at)}</p>${s.proofs.map(p => `<p>${esc(p.durability)} · ${esc(p.at)} · <code>${esc(p.commit)}</code>${p.publication ? ` · ${esc(p.publication.ref)} · ${esc(p.publication.basis)}` : ""}</p>`).join("")}</details></article>`).join("");
+    const refusals = report.refusals.map(r => `<article><span class="badge">DENIAL EMITTED</span><h3>${esc(r.record_id)}</h3><p>Hunch emitted a ${esc(r.kind)} denial for ${esc(r.target)}.</p><p>This does not establish that the host honored the denial or that a bug was prevented.</p><details><summary>Inspect gate evidence</summary><dl><dt>Observed</dt><dd>${esc(r.at)}</dd><dt>Event</dt><dd>${esc(r.event_id)}</dd><dt>Exact response reason digest</dt><dd>${esc(r.reason_hash)}</dd></dl></details></article>`).join("");
+    const history = histories === null ? empty("Lesson history is unavailable. The task evidence above is retained.") : histories.map(h => `<article><h3>${esc(h.entries[0]?.record.title ?? h.reference.record_id)}</h3><p>Save and delivery observations show where a lesson appeared; they do not prove use or additional impact.</p>${h.entries.map(e => `<details><summary>${esc(e.task.title)} · ${esc(e.task.state)}</summary><p>${e.event === "save" ? "Saved" : "Delivered"} ${esc(e.at)}</p><p class="lesson">${esc(e.record.lesson)}</p><dl><dt>Exact revision</dt><dd>${esc(e.record.content_hash)}</dd><dt>Evidence reference</dt><dd>${esc(e.receipt_id ?? e.event_id)}</dd></dl><p>Inspect this task: <code>hunch report ${esc(e.task.task_id)} --html</code></p></details>`).join("")}${!h.index_complete ? empty("History indexing is incomplete. Refresh for additional retained evidence.") : ""}${h.truncated ? empty("Additional deliveries are available through the lesson history command.") : ""}</article>`).join("");
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'"><title>Hunch · ${esc(report.task.title)}</title><style>
+:root{color-scheme:light dark;--bg:#f4f7f4;--paper:#fff;--ink:#162e24;--muted:#53685b;--line:#d5e1d8;--accent:#276540}*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.65 system-ui,sans-serif}main{max-width:920px;margin:auto;padding:48px 24px 80px}header{border-top:5px solid var(--accent);padding-top:24px;margin-bottom:40px}.eyebrow{font-size:12px;letter-spacing:.09em;color:var(--muted);font-weight:650}h1{font-size:clamp(28px,5vw,46px);line-height:1.15;letter-spacing:-.035em;margin:16px 0}h2{font-size:22px;margin:32px 0 12px}h3{font-size:18px;margin:12px 0 6px}p{margin:8px 0}article{background:var(--paper);border:1px solid var(--line);border-radius:12px;padding:22px;margin:12px 0}.muted,dt{color:var(--muted)}.badge{font-size:11px;letter-spacing:.06em;border:1px solid var(--line);border-radius:30px;padding:5px 10px}.lesson{white-space:pre-wrap}a{color:var(--accent);text-underline-offset:3px}a:focus-visible,summary:focus-visible{outline:3px solid var(--accent);outline-offset:5px}summary{cursor:pointer;font-weight:600;padding:8px 0}details{margin-top:16px}pre,code,dd{overflow-wrap:anywhere;word-break:break-word}pre{white-space:pre-wrap;font:13px/1.6 ui-monospace,monospace;padding:14px;background:var(--bg);border-radius:8px}dd{margin:0 0 12px}footer{border-top:1px solid var(--line);margin-top:36px;padding-top:20px;font-size:12px;color:var(--muted)}@media(prefers-color-scheme:dark){:root{--bg:#101b16;--paper:#17271e;--ink:#e3eee6;--muted:#a7b9ac;--line:#365041;--accent:#9cdbb0}}@media print{details>*{display:block}body{background:white;color:black}article{break-inside:avoid}}
+</style></head><body><main><header><div class="eyebrow">HUNCH · TASK EVIDENCE · LOCAL REPORT</div><h1>${esc(report.task.title)}</h1><p>${records.length ? "Project experience carried into this task." : "What Hunch could observe in this task."}</p><p class="muted">${esc(report.task.state)} · ${esc(report.task.started_at)} · ${esc(report.task.task_id)}</p></header>${section("1. What the project remembered", lessons || empty("No lesson snapshot is available for this task."))}${section("2. What reached the agent", deliveries || empty("No task-linked delivery was observed. This does not prove the agent was disconnected."))}${section("3. How the agent says it applied", claims || empty("Contribution is unverified. A context delivery alone does not establish use."))}${section("4. What was checked", checks || empty("No independent command result was recorded."))}${section("5. How the change conforms to delivered rules", rules || empty("No delivered rule was evaluated. Finishing a task, or hunch task conform, evaluates each delivered lesson's declared rule against the changed files."))}${saves ? section("What was saved for future tasks", saves) : ""}${refusals ? section("When Hunch intervened", refusals) : ""}${section("Where this lesson appeared", (history || empty("No lesson history is included in this view.")) + (histories && historyRecords(report).length > histories.length ? empty(`History shown for ${histories.length} of ${historyRecords(report).length} lesson revisions. Inspect another revision with hunch report --lesson <record-id> --kind <kind> --revision <content-hash>.`) : ""))}${section("What remains unknown", report.unknowns.length ? `<ul>${report.unknowns.map(x => `<li>${esc(x)}</li>`).join("")}</ul>` : empty("The report makes no additional causal claim."))}<footer>Generated ${esc(generatedAt)}. This is a saved snapshot, not a live source check.<br>After editing source, refresh with <code>hunch report ${esc(report.task.task_id)} --html</code>.<br>Observed evidence, not a score or an estimate of bugs prevented.<br>Report ${esc(report.content_hash)}<br>Local report may contain private project memory. Keep it within the project's authorized audience.</footer></main></body></html>`;
+}
+//# sourceMappingURL=taskReportRender.js.map