@fusengine/harness 0.1.41 → 0.1.42

package/README.md

@@ -45,6 +45,11 @@ automatically under `<project>/.harness/` (track, cache, memory).
 | `harness init [id]` | Write the pre+post hook wiring for the detected (or named) harness. |
 | `harness hook <id>` | Runtime: read a hook payload on stdin, gate (pre) or record (post), print the native response. (Hooks call this — you don't.) |
 | `harness check` | cli-mode: check staged files in a pre-commit step, exit non-zero on a violation. For harnesses without hooks. |
+| `harness doctor` | Print the version + resolved path of the harness *actually executing*, and compare it to npm's latest — the fast way to catch a stale global (see Pinning). |
+| `harness --version` | Print the running version (bare, on stdout) and exit. |
+
+Every invocation writes a `@fusengine/harness vX.Y.Z` banner to **stderr** (never
+stdout — the hook JSON contract stays clean) so you can see which version ran.
 
 cli-mode (Aider / Windsurf / OpenHands), as a pre-commit step:
 
@@ -53,6 +58,48 @@ cli-mode (Aider / Windsurf / OpenHands), as a pre-commit step:
 npx harness check
 ```
 
+### Pinning (required for hook consumers)
+
+Any consumer `hooks.json` / `settings.json` that runs the harness via `bunx`
+**MUST pin an exact version** — `@fusengine/harness@X.Y.Z` — never a range
+(`^` / `~`) and never the bare or `@latest` spec:
+
+```jsonc
+// .claude/settings.json — correct: exact pin
+"command": "bunx @fusengine/harness@0.1.41 hook claude"
+// WRONG — may silently keep running a stale global install:
+"command": "bunx @fusengine/harness hook claude"
+```
+
+**Why.** A still-open bun bug ([oven-sh/bun#5791]) makes an unpinned `bunx <pkg>`
+prefer an already-installed **global** copy over npm-latest, and publishing a new
+version updates neither that global nor the bunx cache (`bun pm cache rm` does
+**not** remove the global). A hook wired without an exact pin can therefore keep
+executing an old harness indefinitely after you publish a fix — the failure is
+silent because the smoke test (importing the local dist) never exercises the
+`bunx`-resolved binary. Pinning `@X.Y.Z` forces the exact version to resolve.
+
+Run `harness doctor` to see which version is actually executing and whether npm
+has a newer one:
+
+```sh
+harness doctor
+# @fusengine/harness doctor
+#   running:    0.1.41
+#   package:    /Users/you/.bun/install/global/node_modules/@fusengine/harness
+#   runtime:    /Users/you/.bun/bin/bun
+#   npm latest: 0.1.42
+#   ! stale — npm serves 0.1.42. Pin "@fusengine/harness@0.1.42" in hooks.json.
+```
+
+If `doctor` reports a stale global, clear it and re-pin:
+
+```sh
+bun remove -g @fusengine/harness && bun pm cache rm
+```
+
+[oven-sh/bun#5791]: https://github.com/oven-sh/bun/issues/5791
+
 ## What it enforces
 
 Ten portable guards + the APEX gate chain, all evaluated before a tool runs:

package/dist/adapters/claude/index.mjs

@@ -1,2 +1,2 @@
-import { a as guard, i as fileSizeGuard, n as contextResponse, o as readClaudeInput, r as denyResponse, s as toClaudeResponse, t as blockResponse } from "../../claude-BnFrSfMo.mjs";
+import { a as guard, i as fileSizeGuard, n as contextResponse, o as readClaudeInput, r as denyResponse, s as toClaudeResponse, t as blockResponse } from "../../claude-CeRYMOaG.mjs";
 export { blockResponse, contextResponse, denyResponse, fileSizeGuard, guard, readClaudeInput, toClaudeResponse };

package/dist/adapters/cline/index.mjs

@@ -1,4 +1,4 @@
-import { t as evaluate } from "../../evaluate-B1n1ti0N.mjs";
+import { t as evaluate } from "../../evaluate-CeivW6G0.mjs";
 import { t as formatPrompt } from "../../types-ernB1Dy3.mjs";
 //#region src/adapters/cline/index.ts
 /**

package/dist/adapters/codex/index.mjs

@@ -1,2 +1,2 @@
-import { a as guard, n as contextResponse, o as readClaudeInput, r as denyResponse } from "../../claude-BnFrSfMo.mjs";
+import { a as guard, n as contextResponse, o as readClaudeInput, r as denyResponse } from "../../claude-CeRYMOaG.mjs";
 export { contextResponse, denyResponse, guard, readClaudeInput as readCodexInput };

package/dist/adapters/cursor/index.d.mts

@@ -1,4 +1,4 @@
-//#region src/adapters/cursor/index.d.ts
+//#region src/adapters/cursor/interfaces/types.d.ts
 /** `beforeShellExecution` stdin payload (subset). */
 interface CursorShellPayload {
   command?: string;
@@ -21,6 +21,8 @@ interface CursorResponse {
   userMessage?: string;
   agentMessage?: string;
 }
+//#endregion
+//#region src/adapters/cursor/index.d.ts
 /** Guard a shell command (git/install policies). */
 declare function beforeShellExecution(payload: CursorShellPayload): CursorResponse;
 /** Observe a file edit (Cursor cannot block here). Returns the verdict for logging. */
@@ -28,4 +30,4 @@ declare function afterFileEdit(payload: CursorEditPayload): {
   violation: string | null;
 };
 //#endregion
-export { CursorEditPayload, CursorResponse, CursorShellPayload, afterFileEdit, beforeShellExecution };
+export { type CursorEditPayload, type CursorResponse, type CursorShellPayload, afterFileEdit, beforeShellExecution };

package/dist/adapters/cursor/index.mjs

@@ -1,4 +1,4 @@
-import { t as evaluate } from "../../evaluate-B1n1ti0N.mjs";
+import { t as evaluate } from "../../evaluate-CeivW6G0.mjs";
 import { t as formatPrompt } from "../../types-ernB1Dy3.mjs";
 //#region src/adapters/cursor/index.ts
 /**

package/dist/adapters/gemini/index.mjs

@@ -1,4 +1,4 @@
-import { t as evaluate } from "../../evaluate-B1n1ti0N.mjs";
+import { t as evaluate } from "../../evaluate-CeivW6G0.mjs";
 import { t as formatPrompt } from "../../types-ernB1Dy3.mjs";
 //#region src/adapters/gemini/index.ts
 /**

package/dist/cache/index.mjs

@@ -1,3 +1,3 @@
-import { a as cachePath, c as extractText, d as compactMarkdown, f as jaccardSimilar, i as cacheLookupSubstring, l as loadIndex, n as webfetchCacheWrite, o as cacheStore, p as queryHash, r as cacheLookup, s as mcpCacheKey, t as mcpCacheWrite, u as summarizeIndex } from "../mcp-store-CDUVqtJ0.mjs";
+import { a as cachePath, c as extractText, d as compactMarkdown, f as jaccardSimilar, i as cacheLookupSubstring, l as loadIndex, n as webfetchCacheWrite, o as cacheStore, p as queryHash, r as cacheLookup, s as mcpCacheKey, t as mcpCacheWrite, u as summarizeIndex } from "../mcp-store-CnsW9oFj.mjs";
 import "../cache-la_KkjCS.mjs";
 export { cacheLookup, cacheLookupSubstring, cachePath, cacheStore, compactMarkdown, extractText, jaccardSimilar, loadIndex, mcpCacheKey, mcpCacheWrite, queryHash, summarizeIndex, webfetchCacheWrite };

package/dist/{claude-BnFrSfMo.mjs → claude-CeRYMOaG.mjs}

@@ -1,4 +1,4 @@
-import { t as evaluate } from "./evaluate-B1n1ti0N.mjs";
+import { t as evaluate } from "./evaluate-CeivW6G0.mjs";
 import { t as formatPrompt } from "./types-ernB1Dy3.mjs";
 import { dirname, join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";

package/dist/cli/bin.mjs

@@ -2,12 +2,14 @@
 import { r as resolveTtlSec } from "../ttl-BG55s6HZ.mjs";
 import { r as loadDotenv } from "../dotenv-DGyLln7U.mjs";
 import { t as detectHarness } from "../harness-C8Nxxyn_.mjs";
-import { n as stagedContent, r as stagedFiles, t as checkStaged } from "../run-D-Ydrw3D.mjs";
+import { n as stagedContent, r as stagedFiles, t as checkStaged } from "../run-jgivVDv6.mjs";
 import { n as writeInitFile, t as initFor } from "../run-Do2JltgU.mjs";
-import { Ot as todayUtc, kt as claudeHome, t as handleHook } from "../handle-VhWQxvyN.mjs";
-import { delimiter, join } from "node:path";
+import { f as claudeHome } from "../store-CdWOQ9zD.mjs";
+import { Ot as todayUtc, t as handleHook } from "../handle-BTHcKWQ5.mjs";
+import { delimiter, dirname, join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
 //#region src/changelog/fetch.ts
 /**
 * Changelog scanner — ports the changelog-watcher plugin's `fetch-changelog`
@@ -137,6 +139,90 @@ function discoverRefs(home, cwd, marketplaces) {
 	return [...bySkill.values()].join(delimiter);
 }
 //#endregion
+//#region src/cli/doctor.ts
+/**
+* `harness doctor` — diagnose which `@fusengine/harness` is actually running.
+*
+* A confirmed, still-open bun bug (oven-sh/bun #5791; scoped-pkg behaviour
+* reinforced by #32019/#32150) makes `bunx <pkg>` (unpinned) prefer a stale
+* GLOBAL install over npm-latest, so a consumer can silently run an old harness
+* after a publish. This command surfaces the truth: the resolved version +
+* package path of the code executing right now, the runtime binary, and the
+* latest version published on npm. It queries the registry over HTTP (not
+* `npm view`, whose exit code is 0 even on an empty result — npm/cli#6408) and
+* never throws: an offline environment yields `latest: null`, never a crash.
+*/
+const PKG = "@fusengine/harness";
+/** Walk up from `startDir` for the `@fusengine/harness` `package.json`. */
+function findPackage(startDir) {
+	let dir = startDir;
+	for (let depth = 0; depth < 6; depth++) {
+		try {
+			const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+			if (pkg.name === PKG) return {
+				version: pkg.version ?? "unknown",
+				path: dir
+			};
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
+/** Resolve the running version + package path (no network), from a module URL. */
+function runningVersion(moduleUrl) {
+	const found = findPackage(dirname(fileURLToPath(moduleUrl)));
+	return {
+		version: found?.version ?? "unknown",
+		path: found?.path ?? "unknown"
+	};
+}
+/** One-line `pkg vX.Y.Z` banner (written to stderr on every CLI invocation). */
+function versionBanner(moduleUrl) {
+	return `${PKG} v${runningVersion(moduleUrl).version}`;
+}
+/** Latest published version via the npm registry HTTP API. `null` on any failure. */
+async function npmLatest() {
+	try {
+		const res = await fetch(`https://registry.npmjs.org/${PKG}/latest`, { signal: AbortSignal.timeout(8e3) });
+		if (!res.ok) return null;
+		return (await res.json()).version ?? null;
+	} catch {
+		return null;
+	}
+}
+/** Build the full diagnostic report for the module at `moduleUrl`. */
+async function buildDoctorReport(moduleUrl) {
+	const { version, path } = runningVersion(moduleUrl);
+	const latest = await npmLatest();
+	return {
+		running: version,
+		packagePath: path,
+		runtime: process.execPath,
+		latest,
+		stale: latest !== null && latest !== version
+	};
+}
+/** Render a {@link DoctorReport} as human-readable stdout text. */
+function formatDoctor(r) {
+	const lines = [
+		`${PKG} doctor`,
+		`  running:    ${r.running}`,
+		`  package:    ${r.packagePath}`,
+		`  runtime:    ${r.runtime}`,
+		`  npm latest: ${r.latest ?? "(unavailable — offline or unreachable)"}`
+	];
+	if (r.stale) lines.push(`  ! stale — npm serves ${r.latest}. Pin "@fusengine/harness@${r.latest}" in hooks.json (see README).`);
+	else if (r.latest !== null) lines.push(`  ok — running the latest published version.`);
+	return lines.join("\n");
+}
+/** Run `harness doctor`: print the diagnostic to stdout. Always resolves 0 (pure info). */
+async function runDoctor(moduleUrl) {
+	process.stdout.write(formatDoctor(await buildDoctorReport(moduleUrl)) + "\n");
+	return 0;
+}
+//#endregion
 //#region src/cli/bin.ts
 /**
 * harness — CLI for @fusengine/harness.
@@ -158,7 +244,12 @@ async function readStdin() {
 	}
 }
 const cmd = process.argv[2];
-if (cmd === "hook") {
+process.stderr.write(versionBanner(import.meta.url) + "\n");
+if (cmd === "--version" || cmd === "-v") {
+	process.stdout.write(runningVersion(import.meta.url).version + "\n");
+	process.exit(0);
+} else if (cmd === "doctor") process.exit(await runDoctor(import.meta.url));
+else if (cmd === "hook") {
 	const id = process.argv[3] ?? detectHarness().id;
 	loadDotenv(id);
 	const scopeArg = process.argv[4];

package/dist/cli/index.mjs

@@ -1,2 +1,2 @@
-import { n as stagedContent, r as stagedFiles, t as checkStaged } from "../run-D-Ydrw3D.mjs";
+import { n as stagedContent, r as stagedFiles, t as checkStaged } from "../run-jgivVDv6.mjs";
 export { checkStaged, stagedContent, stagedFiles };

package/dist/config/index.d.mts

@@ -1,2 +1,2 @@
-import { _ as parseEnvInt, a as ProjectLayout, c as projectLayout, d as resolveMaxLines, f as splitTarget, g as ttlLabel, h as resolveTtlSec, i as parseEnvFile, l as DEFAULT_MAX_LINES, m as TTL_ENV_KEY, n as envCandidates, o as STATE_GITIGNORE, p as DEFAULT_TTL_SEC, r as loadDotenv, s as STATE_ROOT, t as HOME_DIR, u as MAX_LINES_ENV_KEY } from "../index-COBvvc3L.mjs";
+import { _ as parseEnvInt, a as ProjectLayout, c as projectLayout, d as resolveMaxLines, f as splitTarget, g as ttlLabel, h as resolveTtlSec, i as parseEnvFile, l as DEFAULT_MAX_LINES, m as TTL_ENV_KEY, n as envCandidates, o as STATE_GITIGNORE, p as DEFAULT_TTL_SEC, r as loadDotenv, s as STATE_ROOT, t as HOME_DIR, u as MAX_LINES_ENV_KEY } from "../index-DXQfL1u8.mjs";
 export { DEFAULT_MAX_LINES, DEFAULT_TTL_SEC, HOME_DIR, MAX_LINES_ENV_KEY, ProjectLayout, STATE_GITIGNORE, STATE_ROOT, TTL_ENV_KEY, envCandidates, loadDotenv, parseEnvFile, parseEnvInt, projectLayout, resolveMaxLines, resolveTtlSec, splitTarget, ttlLabel };

package/dist/detect/index.d.mts

@@ -1,2 +1,2 @@
-import { a as detectHarness, i as HarnessVia, n as HarnessInfo, o as detectMode, r as HarnessMode, s as modeFor, t as HarnessId } from "../harness-DwJskkz_.mjs";
-export { HarnessId, HarnessInfo, HarnessMode, HarnessVia, detectHarness, detectMode, modeFor };
+import { a as HarnessInfo, i as HarnessId, n as detectMode, o as HarnessMode, r as modeFor, s as HarnessVia, t as detectHarness } from "../harness-BPPu5CrN.mjs";
+export { type HarnessId, type HarnessInfo, type HarnessMode, type HarnessVia, detectHarness, detectMode, modeFor };

package/dist/{evaluate-B1n1ti0N.mjs → evaluate-CeivW6G0.mjs}

@@ -189,15 +189,15 @@ function securityGuard(ctx) {
 /**
 * Path fragments that mark a location as internal/generated state.
 *
-* Parity with safe_paths.py: `~/.claude/fusengine-cache` is a *writable* cache
-* the harness owns (lessons, MCP cache, per-type state) — only the
-* `fusengine-cache/sessions` subtree is protected, not the whole cache.
+* Parity with safe_paths.py: `~/.fuse-harness/cache` is a *writable*
+* cache the harness owns (lessons, MCP cache, per-type state) — only the
+* `cache/sessions` subtree is protected, not the whole cache.
 */
 const PROTECTED_FRAGMENTS = [
 	".claude/plugins/marketplaces",
 	".claude/plugins/cache",
 	".claude/logs/00-apex",
-	".claude/fusengine-cache/sessions",
+	".fuse-harness/cache/sessions",
 	".claude/apex/",
 	".harness/track",
 	".harness/memory/state"

package/dist/freshness/index.mjs

@@ -1,3 +1,3 @@
 import { i as resolveSessions, n as formatDocSatisfactionStatus, r as isDocConsulted, t as formatDocDeny } from "../doc-helpers-BhzDmJ18.mjs";
-import { t as incrementTrivialEditCounter } from "../freshness-43gxYpiX.mjs";
+import { t as incrementTrivialEditCounter } from "../freshness-BV3PQkDB.mjs";
 export { formatDocDeny, formatDocSatisfactionStatus, incrementTrivialEditCounter, isDocConsulted, resolveSessions };

package/dist/{freshness-43gxYpiX.mjs → freshness-BV3PQkDB.mjs}

@@ -1,4 +1,4 @@
-import { a as writeJsonFile, i as readJsonFile, n as ensureDir } from "./json-io-CvSumjtz.mjs";
+import { a as writeJsonFile, i as readJsonFile, n as ensureDir } from "./json-io-DisYd2fb.mjs";
 import { dirname } from "node:path";
 //#region src/freshness/trivial-edit-counter.ts
 /**