@davesheffer/hunch 1.31.1 → 1.32.0

package/dist/core/repairqueue.js

@@ -0,0 +1,133 @@
+/**
+ * Local-only queue of commit-provenance repairs detected opportunistically
+ * (typically by the post-merge hook, src/integrations/hooks.ts) but not yet
+ * applied. `.hunch/pending-commit-repairs.json` is gitignored the same way
+ * `.hunch/local.json` is — never committed, never pushed. It exists because
+ * the opportunistic detection window is narrow: `ORIG_HEAD` gets overwritten
+ * by the next merge, and the matched-away commit can eventually be gc'd —
+ * queuing the exact {id, from, to} triple here lets a human confirm the match
+ * later (`hunch repair-provenance --apply`) without losing it.
+ *
+ * `.hunch/dropped-commit-repairs.json` is the sibling tombstone file: a human
+ * rejecting a queued match via `--drop` records the exact {id, from, to}
+ * triple here, durably, so detection re-deriving the identical match on a
+ * later merge doesn't re-queue what was already rejected — a genuinely
+ * different replacement (`to`) for the same still-orphaned commit is a new
+ * proposal and still surfaces (see commitrepair.ts's withoutDropped). Same
+ * local-only, gitignored discipline as the queue.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "./io.js";
+import { withoutDropped, withheldForUnresolvableTo } from "./commitrepair.js";
+import { commitsExist } from "../extractors/git.js";
+function queuePath(root) {
+    return join(root, ".hunch", "pending-commit-repairs.json");
+}
+function droppedPath(root) {
+    return join(root, ".hunch", "dropped-commit-repairs.json");
+}
+function isCommitRewrite(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const { id, from, to } = value;
+    // Non-empty, and to !== from — an empty target is never a useful rewrite,
+    // and a no-op entry would apply "successfully" while accomplishing nothing.
+    // Deliberately NOT a hex-shape check: from/to are opaque strings elsewhere
+    // in this codebase's test fixtures, and repairDecisionCommit's own
+    // `d.commit === mine.from` guard already makes a garbage `from` inert (it
+    // can never match a real decision). A garbage `to` is caught elsewhere,
+    // not here: `hunch repair-provenance --apply` runs commitsExist against
+    // every `to` it's actually about to act on (the whole queue, or just the
+    // one entry `--only <id>` targets) before repairDecisionCommit ever sees
+    // it, and leaves a non-resolving entry queued rather than applying it
+    // (withheldForUnresolvableTo, src/core/commitrepair.ts) — with the caveat
+    // that commitsExist itself fails OPEN if the check can't run at all (not a
+    // git repo, git missing, timeout), same as drift.ts's own use of it. This
+    // filter stays shape-only on purpose — the existence check needs a
+    // repository to run against, which this read-only queue loader doesn't
+    // have.
+    return typeof id === "string" && !!id
+        && typeof from === "string" && !!from
+        && typeof to === "string" && !!to
+        && to !== from;
+}
+function isDroppedRewrite(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const { id, from, to } = value;
+    return typeof id === "string" && !!id
+        && typeof from === "string" && !!from
+        && typeof to === "string" && !!to;
+}
+/** Tolerant read: a missing or corrupt queue file is treated as empty — this
+ *  is local scratch state, never a source of truth worth failing loudly over. */
+export function readPendingRepairs(root) {
+    const path = queuePath(root);
+    if (!existsSync(path))
+        return [];
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return Array.isArray(parsed) ? parsed.filter(isCommitRewrite) : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function writePendingRepairs(root, rewrites) {
+    writeFileAtomic(queuePath(root), JSON.stringify(rewrites, null, 2) + "\n");
+}
+/** Tolerant read, same discipline as readPendingRepairs. */
+export function readDroppedRepairs(root) {
+    const path = droppedPath(root);
+    if (!existsSync(path))
+        return [];
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return Array.isArray(parsed) ? parsed.filter(isDroppedRewrite) : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function writeDroppedRepairs(root, dropped) {
+    writeFileAtomic(droppedPath(root), JSON.stringify(dropped, null, 2) + "\n");
+}
+/** The queue as every READ-ONLY consumer should see it: raw entries minus
+ *  anything a human already rejected via `--drop`, regardless of how a
+ *  tombstoned entry ended up back in the raw queue file (e.g. the post-merge
+ *  hook's backgrounded detection racing a `--drop`). A read-time filter, not
+ *  a mutation — the raw queue file is untouched.
+ *
+ *  `repair-provenance`'s own action is the one exception: it needs the RAW
+ *  read (via readPendingRepairs) because it diffs raw-vs-swept to report what
+ *  it cleaned up, and it persists the sweep back to disk. Every other
+ *  reader — `hunch escalations`, SessionStart orientation, the `hunch_now`
+ *  and `hunch_escalations` MCP tools — must call this instead, or a
+ *  tombstoned entry that hasn't yet been swept by a `repair-provenance` run
+ *  re-surfaces as if the human never answered it. */
+export function readActivePendingRepairs(root) {
+    return withoutDropped(readPendingRepairs(root), readDroppedRepairs(root));
+}
+/** The `queued` entries whose proposed `to` doesn't resolve to a real commit
+ *  in this repository — the same withheldForUnresolvableTo gate
+ *  `repair-provenance --apply` itself runs before writing, surfaced here so
+ *  a READ-ONLY consumer (hunch escalations, hunch_now/hunch_escalations,
+ *  SessionStart orientation) can tell a permanently-stuck entry apart from
+ *  one `--apply` can still resolve, instead of advertising a
+ *  `--apply --only <id>` that's guaranteed to no-op forever. `null` from
+ *  commitsExist (the check itself failed to run) is treated as fail-open —
+ *  same discipline as the apply path — so nothing is misreported as
+ *  withheld just because the check couldn't run.
+ *
+ *  Returns the OBJECTS, not their ids, and every caller must pass the exact
+ *  same `queued` array into both this function and whatever it hands the
+ *  result to (commitRepairEscalations) — an id-keyed set would collapse a
+ *  corrupted queue's two same-id entries (one resolvable, one not) into one
+ *  unit, exactly the identity confusion withheldForUnresolvableTo's own
+ *  docstring warns about. */
+export function withheldRewrites(root, queued) {
+    const existing = commitsExist(queued.map((r) => r.to), root);
+    return new Set(withheldForUnresolvableTo(queued, existing).withheld);
+}
+//# sourceMappingURL=repairqueue.js.map

package/dist/core/reviewMemory.d.ts

@@ -0,0 +1,40 @@
+/** Review text is evidence, never executable instructions or policy authority. */
+import { z } from "zod";
+import type { Constraint } from "./types.js";
+declare const commentSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    body: z.ZodString;
+    path: z.ZodString;
+    html_url: z.ZodString;
+    commit_id: z.ZodString;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+    in_reply_to_id: z.ZodOptional<z.ZodNumber>;
+    user: z.ZodObject<{
+        login: z.ZodString;
+        type: z.ZodEnum<{
+            User: "User";
+            Bot: "Bot";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type Comment = z.infer<typeof commentSchema>;
+export interface ReviewCandidate {
+    id: string;
+    evidence_hash: string;
+    file: string;
+    comments: Comment[];
+}
+export interface ReviewPacket {
+    schema: "hunch.review-memory/1";
+    repository: string;
+    authority: "none";
+    candidates: ReviewCandidate[];
+    excluded_bots: number;
+}
+/** Accept GitHub REST review-comment exports, including gh --paginate --slurp pages. */
+export declare function prepareReviewMemory(repository: string, input: unknown): ReviewPacket;
+export declare function validateReviewPacket(input: unknown): ReviewPacket;
+/** A separate, explicit selection supplies the actual rule and how to check it. */
+export declare function compileReviewRules(packetInput: unknown, selections: unknown, now: string): Constraint[];
+export {};

package/dist/core/reviewqueue.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Review-queue shaping for `hunch review` (the capture → REVIEW → enforce funnel).
+ *
+ * Pure, deterministic, no I/O — so it's unit-testable away from the store. Reads the
+ * `synth:` telemetry line that syncCommit parks in `provenance.evidence` and splits the
+ * drafts into two groups so a reviewer can blast through the easy confirmations and then
+ * scrutinize the rest:
+ *   - READY      — the Critic AUDITED the draft and found it well-grounded
+ *                  (source includes "verified" AND grounded >= threshold). Best first.
+ *   - SCRUTINY   — everything else (unverified, low-grounded, verify failed/unavailable).
+ *                  Lowest-confidence first, i.e. worst-first triage (unchanged behavior).
+ */
+import type { Decision } from "./types.js";
+/** Parsed view of the `synth:` telemetry line (or {} when absent). */
+export interface SynthInfo {
+    provider?: string;
+    grounded?: number;
+    samples?: number;
+    agreement?: number;
+    pruned?: number;
+    /** "unavailable" | "failed" — present only when verification was requested but didn't apply. */
+    verify?: string;
+    /** the raw telemetry body (the line minus the "synth:" prefix), for display. */
+    raw?: string;
+}
+/** Extract the `synth:` line out of a decision's evidence and parse its `k=v` fields. */
+export declare function parseSynth(evidence: string[] | undefined): SynthInfo;
+/** Grounded-ness at/above which a Critic-verified draft is a "quick yes". */
+export declare const READY_MIN_GROUNDED = 0.7;
+/** Whether a decision is an un-vouched draft still awaiting a human — the ONLY thing
+ *  the review path surfaces under the auto-trust model.
+ *
+ *  Low confidence NO LONGER makes a draft: captured memory is trusted-advisory the
+ *  moment it lands (status `accepted`, source `llm_draft`), so it grounds and ranks
+ *  but never nags. Only a DELIBERATE, not-yet-human-vouched `proposed` record — an
+ *  explicit roadmap/intent entry a human hasn't confirmed — counts as a review draft.
+ *  (Enforcement authority is granted INLINE, not by draining a background queue.) */
+export declare function isReviewDraft(d: Decision): boolean;
+export interface ReviewItem {
+    d: Decision;
+    synth: SynthInfo;
+    verified: boolean;
+}
+export interface ReviewQueue {
+    ready: ReviewItem[];
+    scrutiny: ReviewItem[];
+}
+/** A draft is "ready to confirm" only when the Critic actually audited it (source
+ *  includes "verified") AND judged it well-grounded. A high confidence number alone
+ *  is NOT enough — an un-audited draft always needs human eyes. */
+export declare function isReady(d: Decision, synth: SynthInfo, minGrounded?: number): boolean;
+/** Split review drafts into ready-to-confirm (best-grounded first) and needs-scrutiny
+ *  (lowest-confidence first). A draft is never in both groups. */
+export declare function partitionReview(drafts: Decision[], minGrounded?: number): ReviewQueue;

package/dist/core/safeRepoFile.d.ts

@@ -0,0 +1,20 @@
+export type RepoFileReader = (file: string) => string | null;
+export type RepoFileBufferReader = (file: string) => Buffer | null;
+/** Automatic repository scans are a convenience boundary, not a license to
+ * materialize arbitrarily large tracked blobs in memory. Eight MiB is well
+ * above ordinary source-file sizes while keeping one malicious/generated file
+ * from becoming an unbounded descriptor read. */
+export declare const MAX_REPO_SOURCE_FILE_BYTES: number;
+export interface RepoFileReaderOptions {
+    maxBytes?: number;
+}
+/** Build a no-follow reader for automatic repository scanners. A Git-tracked
+ * symlink still appears in `git ls-files`; following it can copy host data into
+ * generated memory or reports. This reader accepts only one unchanged regular
+ * file beneath the canonical repository root and reads through the descriptor
+ * whose identity was checked. */
+export declare function createRepoFileBufferReader(root: string, options?: RepoFileReaderOptions): RepoFileBufferReader;
+/** Text facade for parsers and legacy callers. Security-sensitive identities
+ * should hash the raw bytes returned by createRepoFileBufferReader first, since
+ * distinct invalid UTF-8 sequences can decode to the same replacement text. */
+export declare function createRepoFileReader(root: string, options?: RepoFileReaderOptions): RepoFileReader;

package/dist/core/served.d.ts

@@ -0,0 +1,57 @@
+type DatabaseSync = import("node:sqlite").DatabaseSync;
+export type ServedEvent = "served" | "refreshed";
+export interface ServedEntry {
+    event: ServedEvent;
+    /** decisions | constraints | bugs | findings */
+    kind: string;
+    record_id: string;
+    /** what the delivery grounded: a repo-relative file, or a moment like "(subagent:Explore)" */
+    target: string;
+    session_id?: string;
+    rank?: number;
+    delivery_reason?: string;
+    provenance_status?: string;
+    token_cost?: number;
+    delivery_profile?: string;
+    ranking_policy?: string;
+}
+export interface ServedRow {
+    record_id: string;
+    kind: string;
+    serves: number;
+    refreshes: number;
+    last_at: string;
+    best_rank: number | null;
+    average_token_cost: number | null;
+}
+export interface ServedReceipt {
+    at: string;
+    session_id: string | null;
+    event: ServedEvent;
+    kind: string;
+    record_id: string;
+    target: string;
+    rank: number | null;
+    delivery_reason: string | null;
+    provenance_status: string | null;
+    token_cost: number | null;
+    delivery_profile: string | null;
+    ranking_policy: string | null;
+}
+export interface ServedSummary {
+    total: number;
+    distinct_records: number;
+    distinct_sessions: number;
+    first_at: string | null;
+    last_at: string | null;
+    rows: ServedRow[];
+    recent: ServedReceipt[];
+}
+/** Shared observation ledger. Explicit report operations surface failures; only
+ * passive delivery/hook callers may degrade to best-effort recording. */
+export declare function withServedDatabase<T>(root: string, run: (db: DatabaseSync) => T): T;
+/** Append delivery receipts. Never throws — a receipt must never cost a delivery. */
+export declare function recordServed(root: string, entries: readonly ServedEntry[]): void;
+/** The ledger, aggregated per record. Never throws; an unreadable ledger reads as empty. */
+export declare function servedSummary(root: string): ServedSummary;
+export {};

package/dist/core/served.js

@@ -15,6 +15,7 @@
 import { createRequire } from "node:module";
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { assertReportPath } from "./taskReportPaths.js";
 /** Load node:sqlite while swallowing ONLY its ExperimentalWarning — the same
  *  discipline as src/store/db.ts: this module rides the hook into every CLI
  *  invocation, and Hunch's stderr reaches humans, hooks, and MCP clients. A
@@ -71,6 +72,7 @@ function openServedDb(root) {
     const dir = join(root, ".hunch-cache");
     mkdirSync(dir, { recursive: true });
     const db = new sqlite.DatabaseSync(join(dir, "served.db"));
+    db.exec("PRAGMA busy_timeout = 100");
     db.exec(`CREATE TABLE IF NOT EXISTS served (
     at TEXT NOT NULL,
     session TEXT,
@@ -83,6 +85,18 @@ function openServedDb(root) {
     ensureReceiptColumns(db);
     return db;
 }
+/** Shared observation ledger. Explicit report operations surface failures; only
+ * passive delivery/hook callers may degrade to best-effort recording. */
+export function withServedDatabase(root, run) {
+    assertReportPath(root, ".hunch-cache", "served.db");
+    const db = openServedDb(root);
+    try {
+        return run(db);
+    }
+    finally {
+        db.close();
+    }
+}
 /** Append delivery receipts. Never throws — a receipt must never cost a delivery. */
 export function recordServed(root, entries) {
     if (!entries.length)