@davesheffer/hunch 1.33.0 → 1.35.0

package/dist/core/types.d.ts

@@ -578,6 +578,96 @@ export declare const FindingSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type Finding = z.infer<typeof FindingSchema>;
+/** A finished agent task as durable graph memory: what Hunch delivered, what the
+ * agent says it applied, what it saved and checked, and which files it touched.
+ * Written automatically when a task finishes with at least one observation; the
+ * raw observation ledger (.hunch-cache/served.db) stays machine-local. Titles are
+ * the only prose; no prompt text, transcript, or private context payload is kept. */
+export declare const TaskRecordSchema: z.ZodObject<{
+    visibility: z.ZodOptional<z.ZodObject<{
+        owner: z.ZodString;
+        readers: z.ZodArray<z.ZodString>;
+        writers: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    id: z.ZodString;
+    title: z.ZodString;
+    state: z.ZodEnum<{
+        completed: "completed";
+        interrupted: "interrupted";
+    }>;
+    started_at: z.ZodString;
+    finished_at: z.ZodString;
+    coverage: z.ZodEnum<{
+        "no-delivery-observed": "no-delivery-observed";
+        "no-relevant-memory": "no-relevant-memory";
+        delivered: "delivered";
+    }>;
+    lessons: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        record_id: z.ZodString;
+        content_hash: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strip>>>;
+    applied: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        record_id: z.ZodString;
+        content_hash: z.ZodString;
+        action: z.ZodString;
+        supported_by: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    saved: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        record_id: z.ZodString;
+        content_hash: z.ZodString;
+        home: z.ZodEnum<{
+            public: "public";
+            private: "private";
+        }>;
+        operation: z.ZodEnum<{
+            updated: "updated";
+            created: "created";
+        }>;
+        durability: z.ZodEnum<{
+            local: "local";
+            committed: "committed";
+            pushed: "pushed";
+        }>;
+    }, z.core.$strip>>>;
+    checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        state: z.ZodEnum<{
+            passed: "passed";
+            failed: "failed";
+            cancelled: "cancelled";
+            "timed out": "timed out";
+        }>;
+        exit_code: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    conformance: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            decisions: "decisions";
+            constraints: "constraints";
+        }>;
+        record_id: z.ZodString;
+        content_hash: z.ZodString;
+        outcome: z.ZodEnum<{
+            satisfied: "satisfied";
+            violated: "violated";
+            "not-exercised": "not-exercised";
+            unavailable: "unavailable";
+        }>;
+    }, z.core.$strip>>>;
+    refusals: z.ZodDefault<z.ZodNumber>;
+    files: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    source_snapshot: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    report_hash: z.ZodString;
+    provenance: z.ZodObject<{
+        source: z.ZodString;
+        confidence: z.ZodNumber;
+        evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        last_verified: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type TaskRecord = z.infer<typeof TaskRecordSchema>;
 export declare const LANDSCAPE_DRIFT_CANDIDATE_SCHEMA_VERSION: "hunch.landscape-drift-candidate/1";
 /**
  * An external observer's content-addressed mismatch claim. It is intake evidence
@@ -610,7 +700,7 @@ export declare function assertLandscapeDriftCandidate(value: unknown): asserts v
 /** Convert one valid external observation into advisory Hunch memory, never graph authority. */
 export declare function landscapeDriftCandidateFinding(value: unknown): Finding;
 /** The entity collections, keyed by their on-disk directory name. */
-export declare const ENTITY_KINDS: readonly ["components", "resources", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings", "receipts", "commitments", "derived", "entities", "relationships", "conventions"];
+export declare const ENTITY_KINDS: readonly ["components", "resources", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings", "receipts", "commitments", "derived", "entities", "relationships", "conventions", "tasks"];
 export type EntityKind = (typeof ENTITY_KINDS)[number];
 export declare const SCHEMAS: {
     readonly components: z.ZodObject<{
@@ -1358,6 +1448,90 @@ export declare const SCHEMAS: {
             last_verified: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     }, z.core.$strict>;
+    readonly tasks: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+        id: z.ZodString;
+        title: z.ZodString;
+        state: z.ZodEnum<{
+            completed: "completed";
+            interrupted: "interrupted";
+        }>;
+        started_at: z.ZodString;
+        finished_at: z.ZodString;
+        coverage: z.ZodEnum<{
+            "no-delivery-observed": "no-delivery-observed";
+            "no-relevant-memory": "no-relevant-memory";
+            delivered: "delivered";
+        }>;
+        lessons: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            kind: z.ZodString;
+            record_id: z.ZodString;
+            content_hash: z.ZodString;
+            title: z.ZodString;
+        }, z.core.$strip>>>;
+        applied: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            record_id: z.ZodString;
+            content_hash: z.ZodString;
+            action: z.ZodString;
+            supported_by: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>;
+        saved: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            kind: z.ZodString;
+            record_id: z.ZodString;
+            content_hash: z.ZodString;
+            home: z.ZodEnum<{
+                public: "public";
+                private: "private";
+            }>;
+            operation: z.ZodEnum<{
+                updated: "updated";
+                created: "created";
+            }>;
+            durability: z.ZodEnum<{
+                local: "local";
+                committed: "committed";
+                pushed: "pushed";
+            }>;
+        }, z.core.$strip>>>;
+        checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            state: z.ZodEnum<{
+                passed: "passed";
+                failed: "failed";
+                cancelled: "cancelled";
+                "timed out": "timed out";
+            }>;
+            exit_code: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>>;
+        conformance: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                decisions: "decisions";
+                constraints: "constraints";
+            }>;
+            record_id: z.ZodString;
+            content_hash: z.ZodString;
+            outcome: z.ZodEnum<{
+                satisfied: "satisfied";
+                violated: "violated";
+                "not-exercised": "not-exercised";
+                unavailable: "unavailable";
+            }>;
+        }, z.core.$strip>>>;
+        refusals: z.ZodDefault<z.ZodNumber>;
+        files: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        source_snapshot: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        report_hash: z.ZodString;
+        provenance: z.ZodObject<{
+            source: z.ZodString;
+            confidence: z.ZodNumber;
+            evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            last_verified: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
 };
 export type EntityFor = {
     components: Component;
@@ -1375,6 +1549,7 @@ export type EntityFor = {
     derived: DerivedState;
     entities: ExternalEntity;
     relationships: StateRelationship;
+    tasks: TaskRecord;
 };
 /** Default provenance helper for deterministic (extracted) records. */
 export declare function extracted(confidence: number, evidence?: string[]): Provenance;

package/dist/core/types.js

@@ -468,6 +468,44 @@ export const FindingSchema = z.object({
     resolved_commit: z.string().nullable().default(null).describe("the commit that fixed it (set when triage becomes resolved)"),
     provenance: ProvenanceSchema,
 });
+/** A finished agent task as durable graph memory: what Hunch delivered, what the
+ * agent says it applied, what it saved and checked, and which files it touched.
+ * Written automatically when a task finishes with at least one observation; the
+ * raw observation ledger (.hunch-cache/served.db) stays machine-local. Titles are
+ * the only prose; no prompt text, transcript, or private context payload is kept. */
+export const TaskRecordSchema = z.object({
+    visibility: RecordVisibilitySchema.optional(),
+    id: z.string().describe("htask_*"),
+    title: z.string(),
+    state: z.enum(["completed", "interrupted"]),
+    started_at: z.string(),
+    finished_at: z.string(),
+    coverage: z.enum(["no-delivery-observed", "no-relevant-memory", "delivered"]),
+    lessons: z.array(z.object({
+        kind: z.string(), record_id: z.string(), content_hash: z.string(), title: z.string(),
+    })).default([]).describe("exact record revisions Hunch delivered to the agent"),
+    applied: z.array(z.object({
+        record_id: z.string(), content_hash: z.string(), action: z.string(),
+        supported_by: z.string().nullable().default(null),
+    })).default([]).describe("agent-reported applications; supported_by names Hunch's own rule evaluation when one held"),
+    saved: z.array(z.object({
+        kind: z.string(), record_id: z.string(), content_hash: z.string(),
+        home: z.enum(["public", "private"]), operation: z.enum(["created", "updated"]),
+        durability: z.enum(["local", "committed", "pushed"]),
+    })).default([]).describe("memory the task wrote, with its actual home and proven durability"),
+    checks: z.array(z.object({
+        label: z.string(), state: z.enum(["passed", "failed", "timed out", "cancelled"]), exit_code: z.number().int().nullable(),
+    })).default([]).describe("independently observed command results (hunch task verify)"),
+    conformance: z.array(z.object({
+        kind: z.enum(["constraints", "decisions"]), record_id: z.string(), content_hash: z.string(),
+        outcome: z.enum(["satisfied", "violated", "not-exercised", "unavailable"]),
+    })).default([]).describe("Hunch's deterministic evaluation of each delivered rule against the changed files"),
+    refusals: z.number().int().nonnegative().default(0).describe("edits the native gate denied during the task"),
+    files: z.array(z.string()).default([]).describe("files the task touched: delivery targets, rule-checked changes, denied edits"),
+    source_snapshot: z.string().nullable().default(null).describe("bounded source snapshot hash at the last check, when one ran"),
+    report_hash: z.string().describe("content hash of the full local report this record summarizes"),
+    provenance: ProvenanceSchema,
+});
 export const LANDSCAPE_DRIFT_CANDIDATE_SCHEMA_VERSION = "hunch.landscape-drift-candidate/1";
 const LANDSCAPE_DRIFT_HASH = /^sha256:[a-f0-9]{64}$/;
 const LANDSCAPE_DRIFT_RECEIPT_ID = /^[a-z][a-z0-9_:-]{2,127}$/;
@@ -599,7 +637,7 @@ export function landscapeDriftCandidateFinding(value) {
 // loads exactly as before, and an older build ignores directories it does not know.
 export const ENTITY_KINDS = [
     "components", "resources", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings",
-    "receipts", "commitments", "derived", "entities", "relationships", "conventions",
+    "receipts", "commitments", "derived", "entities", "relationships", "conventions", "tasks",
 ];
 export const SCHEMAS = {
     components: ComponentSchema,
@@ -617,6 +655,7 @@ export const SCHEMAS = {
     derived: DerivedStateSchema,
     entities: ExternalEntitySchema,
     relationships: StateRelationshipSchema,
+    tasks: TaskRecordSchema,
 };
 /** Default provenance helper for deterministic (extracted) records. */
 export function extracted(confidence, evidence = []) {

package/dist/core/updatecheck.d.ts

@@ -0,0 +1,51 @@
+/** Best-effort update notices for interactive CLI commands.
+ *
+ * The foreground process only reads a small cache and starts an unreferenced,
+ * detached worker when that cache is stale. Network I/O happens in the worker,
+ * so an unavailable registry cannot hold the user's command open. The first
+ * cold invocation populates the cache; later invocations can display it.
+ */
+import { spawn } from "node:child_process";
+export interface UpdateCheckResult {
+    current: string;
+    latest: string;
+}
+export interface UpdateCachePathOptions {
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    platform?: NodeJS.Platform;
+}
+/** Use each platform's normal per-user cache root. This deliberately never
+ * creates a `.hunch` path segment: `.hunch` is the repository marker used by
+ * findRoot(), so placing a cache there could redirect commands to the wrong
+ * project. */
+export declare function defaultCacheFile(opts?: UpdateCachePathOptions): string;
+/** Full SemVer precedence for the release and prerelease fields. */
+export declare function isNewerVersion(candidate: string, current: string): boolean;
+export interface RefreshUpdateCacheOptions {
+    cacheFile?: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+/** Worker entry point, exported so network/cache behavior is testable without
+ * spawning a process or contacting the real registry. */
+export declare function refreshUpdateCache(opts?: RefreshUpdateCacheOptions): Promise<boolean>;
+export interface ScheduleUpdateCheckOptions {
+    cacheFile?: string;
+    currentVersion?: string;
+    now?: () => number;
+    workerFile?: string;
+    spawnImpl?: typeof spawn;
+}
+/** Read any known update immediately and schedule at most one refresh per day.
+ * Claiming the interval before spawning also bounds offline requests: failed
+ * checks are not retried on every CLI command. */
+export declare function scheduleUpdateCheck(opts?: ScheduleUpdateCheckOptions): UpdateCheckResult | null;
+export interface UpdateCheckGateOptions {
+    commandName: string;
+    isTTY: boolean;
+    installed: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function shouldCheckForUpdate({ commandName, isTTY, installed, env }: UpdateCheckGateOptions): boolean;
+export declare function formatUpdateNotice(result: UpdateCheckResult): string;

package/dist/core/updatecheck.js

@@ -0,0 +1,266 @@
+/** Best-effort update notices for interactive CLI commands.
+ *
+ * The foreground process only reads a small cache and starts an unreferenced,
+ * detached worker when that cache is stale. Network I/O happens in the worker,
+ * so an unavailable registry cannot hold the user's command open. The first
+ * cold invocation populates the cache; later invocations can display it.
+ */
+import { spawn } from "node:child_process";
+import { lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+import { HUNCH_PACKAGE_NAME, HUNCH_VERSION } from "./version.js";
+const REGISTRY_URL = `https://registry.npmjs.org/${HUNCH_PACKAGE_NAME}/latest`;
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 1500;
+const WORKER_FLAG = "--hunch-refresh-update-cache";
+const MAX_CACHE_BYTES = 4096;
+function configuredCacheRoot(value, platform) {
+    if (!value)
+        return null;
+    const absolute = platform === "win32" ? win32.isAbsolute(value) : isAbsolute(value);
+    const containsMarker = value.replace(/\\/g, "/").split("/").some(part => {
+        // Win32 aliases path components with trailing spaces or periods to the
+        // unadorned name, so `.hunch.` and `.hunch ` can address `.hunch` too.
+        const normalized = platform === "win32" ? part.replace(/[ .]+$/g, "") : part;
+        return normalized.toLowerCase() === ".hunch";
+    });
+    if (!absolute || containsMarker)
+        return null;
+    return value;
+}
+/** Use each platform's normal per-user cache root. This deliberately never
+ * creates a `.hunch` path segment: `.hunch` is the repository marker used by
+ * findRoot(), so placing a cache there could redirect commands to the wrong
+ * project. */
+export function defaultCacheFile(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? homedir();
+    const platform = opts.platform ?? process.platform;
+    const cacheHome = configuredCacheRoot(env.XDG_CACHE_HOME, platform)
+        || (platform === "win32" && configuredCacheRoot(env.LOCALAPPDATA, platform))
+        || (platform === "darwin" ? join(home, "Library", "Caches") : join(home, ".cache"));
+    return join(cacheHome, "hunch", "update-check.json");
+}
+function readCache(file) {
+    try {
+        const stat = lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_CACHE_BYTES)
+            return null;
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (!Number.isFinite(parsed.lastCheckedAt) || (parsed.lastCheckedAt ?? -1) < 0)
+            return null;
+        if (parsed.latestSeen !== undefined && parseVersion(parsed.latestSeen) === null)
+            return null;
+        return { lastCheckedAt: parsed.lastCheckedAt, ...(parsed.latestSeen ? { latestSeen: parsed.latestSeen } : {}) };
+    }
+    catch {
+        return null;
+    }
+}
+/** Cache writes are atomic even though this cache is derived and disposable:
+ * concurrent CLI processes must not leave malformed JSON that causes every
+ * subsequent command to schedule another network request. */
+function writeCache(file, cache) {
+    const temp = join(dirname(file), `.${basename(file)}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(temp, `${JSON.stringify(cache)}\n`, { mode: 0o600 });
+        renameSync(temp, file);
+        return true;
+    }
+    catch {
+        try {
+            unlinkSync(temp);
+        }
+        catch { /* best-effort cleanup */ }
+        return false;
+    }
+}
+/** Strict SemVer parsing keeps untrusted registry text out of terminal output. */
+function parseVersion(version) {
+    if (version.length > 256)
+        return null;
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(version);
+    if (!match)
+        return null;
+    const prerelease = match[4]?.split(".") ?? null;
+    if (prerelease?.some(part => /^\d+$/.test(part) && part.length > 1 && part.startsWith("0")))
+        return null;
+    return {
+        core: [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])],
+        prerelease,
+    };
+}
+/** Full SemVer precedence for the release and prerelease fields. */
+export function isNewerVersion(candidate, current) {
+    const a = parseVersion(candidate);
+    const b = parseVersion(current);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < a.core.length; i++) {
+        if (a.core[i] !== b.core[i])
+            return a.core[i] > b.core[i];
+    }
+    if (a.prerelease === null || b.prerelease === null)
+        return a.prerelease === null && b.prerelease !== null;
+    for (let i = 0; i < Math.max(a.prerelease.length, b.prerelease.length); i++) {
+        const left = a.prerelease[i];
+        const right = b.prerelease[i];
+        if (left === undefined || right === undefined)
+            return right === undefined;
+        if (left === right)
+            continue;
+        const leftNumeric = /^\d+$/.test(left);
+        const rightNumeric = /^\d+$/.test(right);
+        if (leftNumeric && rightNumeric)
+            return BigInt(left) > BigInt(right);
+        if (leftNumeric !== rightNumeric)
+            return !leftNumeric;
+        return left > right;
+    }
+    return false;
+}
+async function fetchLatestVersion(fetchImpl) {
+    try {
+        const response = await fetchImpl(REGISTRY_URL, {
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            redirect: "error",
+        });
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        return typeof body.version === "string" && parseVersion(body.version) ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Worker entry point, exported so network/cache behavior is testable without
+ * spawning a process or contacting the real registry. */
+export async function refreshUpdateCache(opts = {}) {
+    const cacheFile = opts.cacheFile ?? defaultCacheFile();
+    const latest = await fetchLatestVersion(opts.fetchImpl ?? fetch);
+    if (latest === null)
+        return false;
+    return writeCache(cacheFile, { lastCheckedAt: (opts.now ?? Date.now)(), latestSeen: latest });
+}
+function cacheIsFresh(cache, now) {
+    return cache !== null && cache.lastCheckedAt <= now && now - cache.lastCheckedAt < CHECK_INTERVAL_MS;
+}
+/** Serialize the short cache claim across simultaneous CLI processes. This
+ * advisory fails closed when a prior process left the lock behind: reclaiming
+ * a pathname without an OS lock cannot distinguish that stale file from a new
+ * owner's lock on both POSIX and Windows. */
+function acquireRefreshLock(cacheFile, now) {
+    const lockFile = `${cacheFile}.lock`;
+    try {
+        mkdirSync(dirname(cacheFile), { recursive: true });
+    }
+    catch {
+        return null;
+    }
+    try {
+        writeFileSync(lockFile, `${now}\n`, { flag: "wx", mode: 0o600 });
+        return lockFile;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read any known update immediately and schedule at most one refresh per day.
+ * Claiming the interval before spawning also bounds offline requests: failed
+ * checks are not retried on every CLI command. */
+export function scheduleUpdateCheck(opts = {}) {
+    try {
+        const cacheFile = opts.cacheFile ?? defaultCacheFile();
+        const currentVersion = opts.currentVersion ?? HUNCH_VERSION;
+        const now = (opts.now ?? Date.now)();
+        const cache = readCache(cacheFile);
+        const notice = cache?.latestSeen && isNewerVersion(cache.latestSeen, currentVersion)
+            ? { current: currentVersion, latest: cache.latestSeen }
+            : null;
+        if (cacheIsFresh(cache, now))
+            return notice;
+        const lockFile = acquireRefreshLock(cacheFile, now);
+        if (!lockFile)
+            return notice;
+        let claimed = false;
+        try {
+            // Another process may have refreshed while this one was acquiring the
+            // claim. Re-read under the lock before deciding to schedule a worker.
+            const current = readCache(cacheFile);
+            if (cacheIsFresh(current, now))
+                return notice;
+            // If the cache cannot record the claim, skip the request. Otherwise a
+            // read-only/misconfigured cache directory would trigger a request forever.
+            claimed = writeCache(cacheFile, { lastCheckedAt: now, ...(current?.latestSeen ? { latestSeen: current.latestSeen } : {}) });
+        }
+        finally {
+            try {
+                unlinkSync(lockFile);
+            }
+            catch { /* derived lock cleanup is best effort */ }
+        }
+        if (!claimed)
+            return notice;
+        const workerFile = opts.workerFile ?? fileURLToPath(import.meta.url);
+        try {
+            const child = (opts.spawnImpl ?? spawn)(process.execPath, [workerFile, WORKER_FLAG, cacheFile], {
+                detached: true,
+                stdio: "ignore",
+                windowsHide: true,
+            });
+            child.once?.("error", () => { });
+            child.unref();
+        }
+        catch { /* the cached notice remains useful even when refresh cannot start */ }
+        return notice;
+    }
+    catch {
+        return null;
+    }
+}
+/** Commands used by hooks, servers, CI, or the updater itself must never start
+ * an advisory worker, even when they inherit a terminal. */
+const PLUMBING_COMMANDS = new Set([
+    "mcp",
+    "check",
+    "merge-driver",
+    "merge-driver-grounding",
+    "sync",
+    "repair-provenance",
+    "hook",
+    "ci",
+    "serve",
+    "update",
+]);
+export function shouldCheckForUpdate({ commandName, isTTY, installed, env = process.env }) {
+    if (PLUMBING_COMMANDS.has(commandName) || /^(?:task|integrations|serve)\s/.test(commandName) || !isTTY || !installed)
+        return false;
+    return !env.CI && !env.HUNCH_NO_UPDATE_CHECK && !env.NO_UPDATE_NOTIFIER;
+}
+export function formatUpdateNotice(result) {
+    return (`A newer Hunch version is available: ${result.current} -> ${result.latest}\n` +
+        "Run `hunch update` in the repository (`hunch update --global` if this CLI is global). " +
+        "Set HUNCH_NO_UPDATE_CHECK=1 to stop checking.");
+}
+function isWorkerInvocation() {
+    if (process.argv[2] !== WORKER_FLAG || !process.argv[1])
+        return false;
+    try {
+        return resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isWorkerInvocation()) {
+    // This process is detached from the user's command. All errors are local to
+    // the derived cache and intentionally produce neither output nor a nonzero
+    // exit that could be mistaken for the command's result.
+    void refreshUpdateCache({ cacheFile: process.argv[3] }).catch(() => { });
+}
+//# sourceMappingURL=updatecheck.js.map

package/dist/core/version.d.ts

@@ -1,4 +1,6 @@
 export declare const HUNCH_VERSION: string;
+/** Shared identity for Hunch's published package. */
+export declare const HUNCH_PACKAGE_NAME = "@davesheffer/hunch";
 /** Exact public npm package consumed by generated CI and shared MCP/provider
  * configs. A floating package name would let one committed configuration run
  * different Hunch semantics as npm's latest release changes. */

package/dist/core/version.js

@@ -16,10 +16,12 @@ export const HUNCH_VERSION = (() => {
         return "0.0.0";
     }
 })();
+/** Shared identity for Hunch's published package. */
+export const HUNCH_PACKAGE_NAME = "@davesheffer/hunch";
 /** Exact public npm package consumed by generated CI and shared MCP/provider
  * configs. A floating package name would let one committed configuration run
  * different Hunch semantics as npm's latest release changes. */
-export const HUNCH_PACKAGE_SPEC = `@davesheffer/hunch@${HUNCH_VERSION}`;
+export const HUNCH_PACKAGE_SPEC = `${HUNCH_PACKAGE_NAME}@${HUNCH_VERSION}`;
 /** npm alias used by npx launchers. Giving the fetched package a distinct local
  * alias prevents npm exec from treating this repository (which has the same
  * package name) as satisfying the request and then falling through to an older

package/dist/integrations/gitignore.js

@@ -61,6 +61,7 @@ const MEM_ENTRIES = [
     ".hunch/edges/",
     ".hunch/runbooks/",
     ".hunch/findings/",
+    ".hunch/tasks/",
     // nuryel.state/1 record kinds (state facets)
     ".hunch/receipts/",
     ".hunch/commitments/",

package/dist/integrations/health.js

@@ -164,14 +164,39 @@ export function inspectIntegrations(root, selected) {
             continue;
         const capabilities = Object.fromEntries(CAPABILITIES.map(c => [c, { status: "untested", detail: "No runtime evidence" }]));
         report.harnesses.push({ harness, capabilities });
+        const mcpPath = join(root, spec.mcp);
+        const hooksFileExists = Boolean(spec.hooks && existsSync(join(root, spec.hooks)));
+        let mcpEntryAbsent = false;
+        try {
+            lstatSync(mcpPath);
+        }
+        catch (e) {
+            mcpEntryAbsent = e.code === "ENOENT";
+        }
         try {
             const launcher = readLauncher(root, harness);
             recordPins(spec.mcp, [launcher.command, ...launcher.args]);
             capabilities.mcp.detail = "Configured locally; use --probe to verify a fresh server, then reconnect the host";
         }
         catch (e) {
-            report.issues.push({ file: spec.mcp, code: "mcp-config", detail: e.message });
-            capabilities.mcp.detail = "MCP configuration missing, disabled, invalid, or outside supported inspection format";
+            // A harness can be detected here via its hooks file alone —
+            // some hooks files are deliberately committed while their MCP config is
+            // a per-clone, gitignored scaffold (e.g. this repo's own
+            // .windsurf/hooks.json). On a fresh checkout that config simply doesn't
+            // exist yet, which is a "not configured on this machine" state, not a
+            // repository-level misconfiguration — it must stay `untested`
+            // (informational, matching every other not-yet-evidenced capability
+            // here), not a hard `issues` entry that fails `hunch doctor` on every
+            // clone forever. A file that EXISTS but is malformed/disabled/
+            // unreadable in some other way is still a genuine issue.
+            // lstat distinguishes a truly absent per-machine file from a dangling
+            // symlink. The latter is a broken configuration and must remain loud.
+            const notConfiguredHere = !selected && hooksFileExists && mcpEntryAbsent && e.code === "ENOENT";
+            if (!notConfiguredHere)
+                report.issues.push({ file: spec.mcp, code: "mcp-config", detail: e.message });
+            capabilities.mcp.detail = notConfiguredHere
+                ? "Not configured on this machine — a hooks file exists, but no local MCP config exists yet; run `hunch init` or set up this host"
+                : "MCP configuration disabled, invalid, or outside supported inspection format";
         }
         let events = {};
         let disabled = false;