@davesheffer/hunch 1.32.8 → 1.35.0

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/extractors/git.js

@@ -1838,16 +1838,9 @@ export function isLinkedWorktree(cwd) {
     const own = gitSafe(["rev-parse", "--absolute-git-dir"], cwd);
     if (!common || !own)
         return false;
-    // realpath BOTH before comparing: `--absolute-git-dir` is symlink-resolved while
-    // gitCommonDir is not, so on macOS the main checkout would otherwise mismatch on
-    // /var vs /private/var and falsely read as "linked".
-    const norm = (p) => { try {
-        return realpathSync(p);
-    }
-    catch {
-        return resolve(p);
-    } };
-    return norm(own) !== norm(common);
+    // Git can spell the same directory differently: /var vs /private/var on
+    // macOS, or long vs 8.3/case variants on Windows. Compare physical identity.
+    return !sameFilesystemEntry(own, common);
 }
 /** Current branch name (e.g. "main", "feat/x"), or "" in detached HEAD / non-repo.
  *  Stamped onto auto-captured decisions so branch-scoped work stays filterable. */

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;

package/dist/mcp/server.js

@@ -1,3 +1,5 @@
+import { conventionSupplements } from '../core/conventionDelivery.js';
+import { fieldCitationText } from "../core/fieldProvenance.js";
 /**
  * MCP server — the structured two-way API into the Hunch (DESIGN.md §7 / App. A).
  * Exposes read tools (query/why/bug_lineage/check_constraints/get_dependents) and
@@ -843,6 +845,10 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             parts.push(`\nCOMPONENTS: ${w.components.map((c) => `${c.name} (${c.id})`).join(", ")}`);
         if (w.symbols.length)
             parts.push(`\nSYMBOLS: ${w.symbols.slice(0, WHY_CAP * 2).map((s) => `${s.name} [fan-in ${s.metrics.fan_in}, churn ${s.metrics.churn_90d}]`).join(", ")}${more(w.symbols.length, WHY_CAP * 2)}`);
+        const recentTasks = store.tasksFor(target, 5);
+        if (recentTasks.length) {
+            parts.push(`\nRECENT TASKS (agent work that touched this):\n${recentTasks.map((t) => `  • ${t.id} ${t.finished_at.slice(0, 10)} ${t.title} — ${t.lessons.length} lesson(s), ${t.applied.length} applied, ${t.saved.length} saved${t.conformance.some((c) => c.outcome === "violated") ? ", rule VIOLATED" : ""}`).join("\n")}`);
+        }
         if (parts.length === 1)
             parts.push("\n(No recorded decisions/bugs/constraints yet for this target.)");
         return ok(parts.join("\n"));
@@ -1069,7 +1075,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                     const records = as_of ? [] : snapshotDeliveredRecords(store, envelope);
                     // First delivery of a revision in this task earns one line; repeats stay quiet.
                     const recalled = renderRecalledLine(unseenLessons(root, task_id, records));
-                    const occurrence = recordTaskDelivery(root, task_id, envelope, records);
+                    const occurrence = recordTaskDelivery(root, task_id, envelope, records, undefined, target);
                     result.content.push({ type: "text", text: `${recalled ? `${recalled}\n` : ""}Task evidence: ${task_id} · occurrence ${occurrence}.\n${records.slice(0, 20).map(r => `${r.record_id} @ ${r.content_hash}`).join("\n")}${records.length > 20 ? "\nMore record identities: hunch_report(task_id)." : ""}` });
                 }
                 catch {
@@ -1102,7 +1108,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             decisionCorpus: store.recs("decisions"),
             historical: !!asOf,
             profile: profile ?? "builder",
-            supplements: [...(dnaSupplement ? [dnaSupplement] : []), ...stateGrounding],
+            supplements: [...(dnaSupplement ? [dnaSupplement] : []), ...stateGrounding, ...(asOf ? [] : conventionSupplements(store.recs("conventions")))],
         };
         // Task-phrase input ("improve retrieval ranking") resolves no file/symbol and
         // used to return an empty brief while the graph held the answer — fall back to
@@ -1822,7 +1828,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                     const r = (response.records ?? {})[ref.id] ?? {};
                     const g = (k) => { const v = r[k]; return typeof v === "string" ? v : v == null ? "" : JSON.stringify(v); };
                     if (ref.facet === "derived")
-                        return `- ${label} derived ${ref.id} · computed ${g("computed_at")} · ${r.dependencies?.length ?? 0} dependencies\n    ${g("content").slice(0, 1200)}`;
+                        return `- ${label} derived ${ref.id} · computed ${g("computed_at")} · ${r.dependencies?.length ?? 0} dependencies\n    ${g("content").slice(0, 1200)}${fieldCitationText(r)}`;
                     if (ref.facet === "commitments")
                         return `- ${label} commitment ${ref.id} · ${g("status")} · due ${g("due")} · owner ${g("owner")}: ${g("title")}${r.closed_by ? ` · closed by ${g("closed_by")}` : ""}`;
                     if (ref.facet === "receipts") {
@@ -1858,7 +1864,11 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                             : sor.observed_truncated ? ['- More observations exist; read this subject with observed_page:{} in one partition, then follow next_cursor.'] : []),
                         ...(sor.invalidated_by.length ? [`- invalidated by: ${sor.invalidated_by.join(", ")}`] : [])].join("\n") || "(nothing on record for this subject)"
                     : "";
-                return stateResult(`${response.receipt_id} · ${summary}${deniedNote}${stateText ? `\n\nState of record:\n${stateText}` : ""}\n\n${envelope.text}`, response);
+                const conventionText = response.conventions ? '\n\nExplicit conventions (advisory; no scope takes precedence):\n' + response.conventions.items.map(item => {
+                    const record = response.records?.[item.ref.id];
+                    return `- ${item.ref.scope.kind}/${item.ref.scope.id} · ${item.key} · ${record?.status}/${item.currentness}${item.conflict ? ' · CONFLICT' : ''}: ${String(record?.value ?? '').slice(0, 300)} (${item.ref.id})`;
+                }).join('\n') + (response.conventions.truncated ? '\nMore conventions exist; this view is incomplete.' : '') : '';
+                return stateResult(`${response.receipt_id} · ${summary}${deniedNote}${stateText ? `\n\nState of record:\n${stateText}` : ""}\n\n${envelope.text}${conventionText}`, response);
             }
             catch (e) {
                 return stateRefusal(e);
@@ -1866,7 +1876,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         });
         server.registerTool("nuryel_write", {
             title: "nuryel.state/1 write — provenance + idempotency in, durability out",
-            description: "Write one record into a facet (receipts, commitments, derived, entities, relationships, or the legacy decisions/constraints/bugs/findings). The record must carry provenance; the request must carry an idempotency_key — a replay returns the original, a reused key with a different payload is refused. Ids are derived from the record's facts, never chosen. A second live decision on a topic is refused with the incumbent named; pass supersedes to replace it explicitly. organization/team/user partitions never ride a repository: they require an overlay. To show an existing captured observation under another subject without copying it, write a relationship type observation_about with from=observation id, to=subject, observation_hash, lifecycle=active, reason and hashed external evidence of the explicit association. Retire the relationship to unlink; reactivation requires expected_version.",
+            description: "Write one record into a facet (receipts, commitments, derived, entities, relationships, or the legacy decisions/constraints/bugs/findings). The record must carry provenance; the request must carry an idempotency_key — a replay returns the original, a reused key with a different payload is refused. Ids are derived from the record's facts, never chosen. A second live decision on a topic is refused with the incumbent named; pass supersedes to replace it explicitly. organization/team/user partitions never ride a repository: they require an overlay. To show an existing captured observation under another subject without copying it, write a relationship type observation_about with from=observation id, to=subject, observation_hash, lifecycle=active, reason and hashed external evidence of the explicit association. Retire the relationship to unlink; reactivation requires expected_version. With capability nuryel.field-provenance/1, a derived record may carry field_provenance: [{selector:{kind:json_pointer,path:/field} or {kind:text,start:0,end:10}, value_hash:stateHash(selected scalar or text), dependency_hashes:[stateHash(existing dependency)]}]. Text offsets count Unicode code points, end exclusive. Citations are writer-supplied traceability, not verified support; negotiate support in every shared reader before writing them. With nuryel.record-visibility/1, records may carry visibility:{owner:principal-id,readers:[ids],writers:[ids]}; the owner is implicit in both lists, and writers must be readers. Owner-only audience changes require expected_version, including supersession. Restricted records require a dedicated partition; local stdio principal assertions assume trusted callers.",
             inputSchema: { ...WriteRequestSchema.omit({ schema: true }).shape, cwd: cwdHintField },
             outputSchema: WriteResultSchema.shape,
         }, async ({ cwd: _cwd, ...input }) => {

package/dist/mcp/taskReportTools.d.ts

@@ -17,7 +17,7 @@ export declare function boundedTaskReport(report: ReturnType<typeof readTaskRepo
         finished_at: string | null;
         state: "open" | "completed" | "interrupted";
     };
-    coverage: "delivered" | "no-delivery-observed" | "no-relevant-memory";
+    coverage: "no-delivery-observed" | "no-relevant-memory" | "delivered";
     content_hash: string;
     unknowns: string[];
     deliveries: {
@@ -73,7 +73,7 @@ export declare function boundedTaskReport(report: ReturnType<typeof readTaskRepo
         title: string;
         home: "public" | "private";
         operation: "updated" | "created";
-        durability: "committed" | "pushed" | "local";
+        durability: "local" | "committed" | "pushed";
     }[];
     refusals: ({
         source: "native-edit-gate";
@@ -106,7 +106,7 @@ export declare function boundedTaskReportForHost(report: ReturnType<typeof readT
         finished_at: string | null;
         state: "open" | "completed" | "interrupted";
     };
-    coverage: "delivered" | "no-delivery-observed" | "no-relevant-memory";
+    coverage: "no-delivery-observed" | "no-relevant-memory" | "delivered";
     content_hash: string;
     unknowns: string[];
     deliveries: {
@@ -162,7 +162,7 @@ export declare function boundedTaskReportForHost(report: ReturnType<typeof readT
         title: string;
         home: "public" | "private";
         operation: "updated" | "created";
-        durability: "committed" | "pushed" | "local";
+        durability: "local" | "committed" | "pushed";
     }[];
     refusals: ({
         source: "native-edit-gate";

package/dist/mcp/taskReportTools.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { fileURLToPath } from "node:url";
 import { TaskIdSchema, ReportClaimSchema, LessonReferenceSchema, finishReportTask, listReportTasks, readTaskReport, readLessonHistory, recordReportClaim, reportPresentationEnabled, startReportTask } from "../core/taskReport.js";
+import { persistTaskRecord } from "../core/taskRecord.js";
 import { reportSourceSnapshot, runReportConformance } from "../core/taskReportEvidence.js";
 import { renderTaskReport, writeTaskReportHtml } from "../core/taskReportRender.js";
 function applicationReferences(report) {
@@ -73,7 +74,18 @@ export function registerTaskReportTools(server, getRoot, getStore) {
             if (action === "start") {
                 if (!title || applications?.length || outcome)
                     throw new Error("start requires a short task title and no completion evidence");
-                const task = startReportTask(root, title, task_id);
+                let task;
+                try {
+                    task = startReportTask(root, title, task_id);
+                }
+                catch (error) {
+                    // A native prompt task already exists under this exact ID (opened by the
+                    // host hook). Its persisted title is authoritative; a paraphrased title
+                    // from the model must not fork a second report or fail the start.
+                    if (!task_id || !/different title/.test(error.message))
+                        throw error;
+                    task = readTaskReport(root, task_id, reportSourceSnapshot(root).hash).task;
+                }
                 const launcher = verificationLauncher();
                 return { content: [{ type: "text", text: `Task ${task.task_id} · ${task.state}. Pass task_id to every hunch_context and decision/correction/finding capture call. Before the final response, finish with hunch_task and include its contribution card. For checks use this exact installation (the global hunch binary may be stale): ${launcher.shell} task verify ${task.task_id} -- <command> [arguments]. The default budget is 2 minutes; add --timeout <seconds> before -- for a long suite.` }], structuredContent: { task, verification_argv: [...launcher.argv, "task", "verify", task.task_id, "--"] } };
             }
@@ -90,6 +102,23 @@ export function registerTaskReportTools(server, getRoot, getStore) {
                 catch { /* unknowns disclose it */ }
             }
             finishReportTask(root, task_id, outcome ?? "completed");
+            // The finished task becomes graph memory through the normal capture path;
+            // a failed write is disclosed on the card, never a reason to lose it.
+            let graph = null;
+            let graphNote = "";
+            try {
+                const saved = persistTaskRecord(root, getStore(), task_id);
+                if (saved) {
+                    graph = { id: saved.record.id, home: saved.home, flushed: saved.flushed, changed: saved.changed };
+                    graphNote = `\nGraph     ${saved.changed ? "saved" : "already saved"} as ${saved.record.id} (${saved.home}${saved.flushed ? `, ${saved.flushed}` : ""})`;
+                }
+                else {
+                    graphNote = "\nGraph     nothing to keep (no observation, or task records disabled)";
+                }
+            }
+            catch (error) {
+                graphNote = `\nGraph     not saved: ${error.message}`;
+            }
             const report = readTaskReport(root, task_id, reportSourceSnapshot(root).hash);
             const show = reportPresentationEnabled(root);
             let file = null;
@@ -97,8 +126,8 @@ export function registerTaskReportTools(server, getRoot, getStore) {
                 file = writeTaskReportHtml(root, task_id);
             }
             catch { /* retained report remains inspectable through MCP */ }
-            const card = file ? renderTaskReport(report).replace(/^Evidence .*$/m, `Evidence  [Open local report](<${file}>)`) : renderTaskReport(report);
-            return { content: [{ type: "text", text: show ? card : "Task report retained. Automatic presentation is disabled; omit the contribution card from the final response." }], structuredContent: { ...boundedTaskReportForHost(report), presentation_enabled: show, contribution_card: show ? card : null, report_path: file } };
+            const card = (file ? renderTaskReport(report).replace(/^Evidence .*$/m, `Evidence  [Open local report](<${file}>)`) : renderTaskReport(report)) + graphNote;
+            return { content: [{ type: "text", text: show ? card : "Task report retained. Automatic presentation is disabled; omit the contribution card from the final response." }], structuredContent: { ...boundedTaskReportForHost(report), presentation_enabled: show, contribution_card: show ? card : null, report_path: file, graph_record: graph } };
         }
         catch (error) {
             const message = `Task report unavailable: ${error.message}`;

package/dist/serve/app.d.ts

@@ -27,6 +27,8 @@ export declare class HttpProblem extends Error {
     constructor(status: number, code: string, message: string, extra?: Record<string, unknown>);
 }
 export interface ServeOptions {
+    /** Required for key-bound credentials when supplying an in-memory configuration. */
+    authStateDir?: string;
     version?: string;
     /** Injectable for tests: how a partition's store is opened. */
     openStore?: (root: string) => HunchStore;