@draht/tools 2026.7.30 → 2026.9.5-1

package/bin/draht-tools.cjs

@@ -7,8 +7,10 @@
  */
 
 const fs = require("node:fs");
+const crypto = require("node:crypto");
 const path = require("node:path");
-const { execSync, execFileSync } = require("node:child_process");
+const os = require("node:os");
+const { execSync, execFileSync, spawn, spawnSync } = require("node:child_process");
 
 const PLANNING_DIR = ".planning";
 const BANNER_WIDTH = 55;
@@ -275,7 +277,7 @@ commands["map-codebase"] = function (dir) {
 	// so `map-codebase` is a single command that produces both the prose docs and the graphify map.
 	let kg = null;
 	try {
-		kg = visWriteOutputs(repoRoot);
+		kg = graphBuildOutputs(repoRoot);
 	} catch (err) {
 		console.error(`\n⚠️  Knowledge graph build failed (run \`draht-tools map-graph\` to retry): ${err.message}`);
 	}
@@ -5095,32 +5097,421 @@ function visRenderReport(map) {
 	return L.join("\n");
 }
 
-function visWriteOutputs(root, opts = {}) {
+// ============================================================================
+// Go graph engine — delegation shim
+// Resolution order: $DRAHT_GRAPH_BIN → <this bin/> → ~/.draht/bin → $PATH.
+// Engine choice: $DRAHT_GRAPH_ENGINE = auto (default) | go | js.
+// See .planning/kg-integration/SPEC.md § "Go engine cutover".
+// ============================================================================
+
+// Commands the Go engine implements with byte-identical stdout AND exit codes.
+// Anything not listed here always runs the JS implementation below.
+const GRAPH_GO_COMMANDS = new Set([
+	"map-graph", "map-serve", "graph-context", "graph-impact", "graph-callers",
+	"graph-callees", "graph-path", "graph-query", "graph-hotspots",
+	"graph-clusters", "graph-hook",
+]);
+
+// Deliberately NOT "draht-tools": the $PATH scan below would otherwise find the
+// npm shim for THIS file and spawn it forever. See also DRAHT_GRAPH_DELEGATED.
+const GRAPH_BIN_NAME = process.platform === "win32" ? "draht-graph.exe" : "draht-graph";
+
+// Must equal visBuildMap()'s schemaVersion (see the `schemaVersion: 5` literal
+// above). A stamped binary built for another schema is rejected rather than
+// silently producing an incompatible MAP.json.
+const GRAPH_SCHEMA_VERSION = 5;
+
+// Flip to true only when every gate in SPEC.md § "Requiring the Go engine" is
+// green. Until then a missing binary is a silent JS fallback, not an error.
+const GRAPH_REQUIRE_GO = false;
+
+function graphEngineMode() {
+	const v = String(process.env.DRAHT_GRAPH_ENGINE || "auto").trim().toLowerCase();
+	return v === "go" || v === "js" ? v : "auto";
+}
+
+// One statSync per candidate — existence AND the exec bit come from the same call.
+function graphStat(p) {
+	try {
+		const st = fs.statSync(p);
+		if (!st.isFile()) return null;
+		if (process.platform !== "win32" && (st.mode & 0o111) === 0) return null;
+		return st;
+	} catch {
+		return null;
+	}
+}
+
+// Unstamped binaries are trusted (dev builds and $PATH). If a stamp exists,
+// however, it marks a managed binary and every identity/integrity field is
+// mandatory; malformed or stale metadata must never turn verification off.
+// The stamp is written by `install-graph-engine` (packages/draht-claude/cli.mjs,
+// packages/draht-codex/cli.mjs), not read from the release manifest.json.
+function graphStampOk(binPath, st) {
+	const stampPath = path.join(path.dirname(binPath), ".draht-graph.json");
+	if (!fs.existsSync(stampPath)) return true;
+	let s;
+	try {
+		s = JSON.parse(fs.readFileSync(stampPath, "utf-8"));
+	} catch {
+		return false;
+	}
+	// JSON.parse("null")/("42")/("[]") all succeed without throwing, so `s` may be
+	// anything JSON-serializable here, not just an object — guard before touching
+	// `.size`/`.schemaVersion` or a malformed stamp file crashes the CLI BEFORE the
+	// JS fallback ever runs (see Phase 4 review finding #1).
+	if (!s || typeof s !== "object" || Array.isArray(s)) return false;
+	if (s.name !== "draht-graph" || typeof s.version !== "string" || s.version.length === 0) return false;
+	if (s.schemaVersion !== GRAPH_SCHEMA_VERSION || !Number.isSafeInteger(s.size) || s.size < 0 || s.size !== st.size) return false;
+	if (typeof s.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(s.sha256)) return false;
+	const actual = crypto.createHash("sha256").update(fs.readFileSync(binPath)).digest("hex");
+	return actual === s.sha256;
+}
+
+let graphBinCache; // undefined = unresolved · null = resolved-as-missing · string = path
+let graphBinTried = []; // candidates actually stat'd — quoted verbatim in the error message
+let graphBinRejected = []; // candidates that exist + are executable but graphStampOk() rejected
+function graphResolveBin() {
+	if (graphBinCache !== undefined) return graphBinCache;
+	graphBinCache = null;
+	graphBinTried = [];
+	graphBinRejected = [];
+
+	const override = process.env.DRAHT_GRAPH_BIN;
+	if (override) { // explicit override: never silently ignored
+		graphBinTried.push(override);
+		const st = graphStat(override);
+		if (!st) {
+			console.error(`draht-tools: DRAHT_GRAPH_BIN=${override} is not an executable file`);
+		} else if (!graphStampOk(override, st)) {
+			graphBinRejected.push(override);
+			console.error(`draht-tools: DRAHT_GRAPH_BIN=${override} rejected by its .draht-graph.json provenance stamp (malformed or stale size/schema/SHA-256)`);
+		} else {
+			graphBinCache = override;
+		}
+		return graphBinCache;
+	}
+
+	const home = (() => {
+		try {
+			return os.homedir();
+		} catch {
+			return null;
+		}
+	})();
+	const dirs = [__dirname];
+	if (home) dirs.push(path.join(home, ".draht", "bin"));
+	const cands = [];
+	for (const d of dirs) cands.push(path.join(d, GRAPH_BIN_NAME));
+	for (const d of String(process.env.PATH || "").split(path.delimiter)) {
+		if (d) cands.push(path.join(d, GRAPH_BIN_NAME));
+	}
+	for (const c of cands) {
+		graphBinTried.push(c);
+		const st = graphStat(c);
+		if (!st) continue;
+		if (!graphStampOk(c, st)) {
+			// Found and executable, but its .draht-graph.json provenance stamp is stale
+			// (size/schemaVersion mismatch). NOT silent: a stale stamp otherwise reverts
+			// every user to the ~6x slower JS engine with zero diagnostic (Phase 4 review
+			// finding #3). graphMissingMessage() below surfaces this distinctly too.
+			graphBinRejected.push(c);
+			console.error(`draht-tools: ${c} rejected by its .draht-graph.json provenance stamp (malformed or stale size/schema/SHA-256) — skipping`);
+			continue;
+		}
+		graphBinCache = c;
+		return graphBinCache;
+	}
+	return graphBinCache;
+}
+
+function graphMissingMessage() {
+	const rejectedNote = graphBinRejected.length
+		? [
+			"",
+			"Note: the following WERE found but rejected by their .draht-graph.json",
+			"provenance stamp (malformed or stale size/schema/SHA-256) — this is not the same as",
+			"\"not found\"; reinstall or remove the stale .draht-graph.json next to it:",
+			...graphBinRejected.map((p) => `  ${p}`),
+		]
+		: [];
+	return [
+		`draht-tools: the Go graph engine was required (DRAHT_GRAPH_ENGINE=go) but no usable \`draht-graph\` binary was found.`,
+		...rejectedNote,
+		"",
+		"Looked for:",
+		...graphBinTried.map((p) => `  ${p}`),
+		"",
+		"Install it:",
+		"  npx draht-claude install-graph-engine     # or: npx draht-codex install-graph-engine",
+		"",
+		"Build it from source:",
+		"  cd go && make build && mkdir -p ~/.draht/bin && cp bin/draht-tools ~/.draht/bin/draht-graph",
+		"",
+		"Or point at an existing build:",
+		"  export DRAHT_GRAPH_BIN=/path/to/draht-graph",
+		"",
+		"Or use the built-in JS engine instead:",
+		"  unset DRAHT_GRAPH_ENGINE          # (equivalent to DRAHT_GRAPH_ENGINE=auto)",
+	].join("\n");
+}
+
+// Delegates and EXITS the process on success; returns normally to fall through to JS.
+// Value-taking Go-only flags (accepted by the Go engine's own CLI, meaningless to
+// the JS engine's arg parsers) vs. boolean ones. graphParseArgs/map-graph's own
+// loop treat an unconsumed flag VALUE as a positional file/dir argument, so these
+// must be stripped — not just documented as "ignored" — before the JS path ever
+// sees argv (Phase 4 review finding #4).
+const GRAPH_GO_ONLY_VALUE_FLAGS = new Set(["jobs", "parser", "cache-dir", "out", "ast-max-bytes", "ast-max-line"]);
+const GRAPH_GO_ONLY_BOOL_FLAGS = new Set(["verbose", "symbol-signatures"]);
+function graphStripGoOnlyFlags(args) {
+	const out = [];
+	for (let i = 0; i < args.length; i++) {
+		const a = String(args[i]);
+		const eq = a.indexOf("=");
+		const key = (eq === -1 ? a : a.slice(0, eq)).replace(/^--?/, "");
+		if (GRAPH_GO_ONLY_BOOL_FLAGS.has(key)) continue;
+		if (GRAPH_GO_ONLY_VALUE_FLAGS.has(key)) {
+			if (eq === -1) i++; // also skip the separate value token, e.g. `--out /tmp/x`
+			continue;
+		}
+		out.push(args[i]);
+	}
+	return out;
+}
+
+// MAP.json is a committed, hook-refreshed artifact (gsd-post-phase, the git
+// post-commit hook) — it must not silently change shape depending on whether the
+// person/CI running map-graph happens to have the Go binary installed. The Go
+// CLI's own default is `--parser treesitter` (AST; a deliberate improvement, see
+// go/README.md), which is NOT byte-identical to the JS engine's regex-based
+// output. Until a project-wide, version-controlled decision to switch the
+// committed artifact to AST lands (see .planning/kg-integration/SPEC.md § "Go
+// engine cutover"), pin delegated `map-graph` and `map-serve` runs to
+// `--parser regex` so the two engines produce identical MAP.json — unless the
+// caller explicitly asked for a different parser. (Phase 4 review finding #11.)
+function graphPinRegexParser(cmd, args) {
+	if (cmd !== "map-graph" && cmd !== "map-serve") return args;
+	if (args.some((a) => a === "--parser" || String(a).startsWith("--parser="))) return args;
+	return ["--parser", "regex", ...args];
+}
+
+function graphWantsSymbolSignatures(cmd, args) {
+	return cmd === "map-graph" && args.some((a) => a === "--symbol-signatures");
+}
+
+function graphSignatureFallbackWarning() {
+	return "draht-tools: --symbol-signatures requires the Go graph engine, but no usable `draht-graph` binary is available; continuing with the JavaScript engine without symbol signatures.";
+}
+
+function graphMaybeDelegate(cmd, args) {
+	if (!GRAPH_GO_COMMANDS.has(cmd)) return;
+	if (process.env.DRAHT_GRAPH_DELEGATED) return; // recursion guard, belt and braces
+	const mode = graphEngineMode();
+	if (mode === "js") return;
+	const bin = graphResolveBin();
+	if (!bin) {
+		if (mode === "go" || GRAPH_REQUIRE_GO) {
+			console.error(graphMissingMessage());
+			process.exit(127);
+		}
+		if (graphWantsSymbolSignatures(cmd, args)) console.error(graphSignatureFallbackWarning());
+		return; // auto: silent JS fallback
+	}
+	const res = spawnSync(bin, [cmd, ...graphPinRegexParser(cmd, args)], {
+		stdio: "inherit", // byte-identical stdout/stderr, TTY preserved
+		windowsHide: true,
+		env: { ...process.env, DRAHT_GRAPH_DELEGATED: "1" },
+	});
+	if (res.error) { // raced the stat (deleted / EACCES / ENOEXEC)
+		if (mode === "go" || GRAPH_REQUIRE_GO) {
+			console.error(`draht-tools: failed to execute ${bin}: ${res.error.message}`);
+			process.exit(127);
+		}
+		if (graphWantsSymbolSignatures(cmd, args)) console.error(graphSignatureFallbackWarning());
+		return; // auto: JS fallback
+	}
+	if (res.signal) {
+		const n = os.constants.signals[res.signal];
+		process.exit(n ? 128 + n : 1);
+	}
+	process.exit(res.status === null ? 1 : res.status);
+}
+
+// map-codebase needs the built map IN-PROCESS (it prints stats/paths from it), so it
+// cannot use the stdout-passthrough path. Run the Go engine for its side effects, then
+// read MAP.json back. Any failure falls through to the JS builder, which is idempotent.
+function graphBuildOutputs(root, opts = {}) {
+	const mode = graphEngineMode();
+	const bin = mode === "js" ? null : graphResolveBin();
+	if (!bin) {
+		if (mode === "go" || GRAPH_REQUIRE_GO) {
+			console.error(graphMissingMessage());
+			process.exit(127);
+		}
+		return visWriteOutputs(root, opts);
+	}
+	const argv = ["map-graph", "--parser", "regex"]; // see graphPinRegexParser's doc comment
+	if (opts.quiet) argv.push("--quiet");
+	const res = spawnSync(bin, argv, {
+		cwd: root,
+		stdio: ["ignore", "ignore", "inherit"], // its stdout is map-graph's banner, not map-codebase's
+		windowsHide: true,
+		env: { ...process.env, DRAHT_GRAPH_DELEGATED: "1" },
+	});
+	if (res.error || res.status !== 0) return visWriteOutputs(root, opts);
 	const outDir = path.join(root, PLANNING_DIR, "codebase");
+	const jsonPath = path.join(outDir, "MAP.json");
+	try {
+		return {
+			jsonPath,
+			htmlPath: path.join(outDir, "MAP.html"),
+			reportPath: path.join(outDir, "GRAPH_REPORT.md"),
+			map: JSON.parse(fs.readFileSync(jsonPath, "utf-8")),
+			unchanged: false,
+		};
+	} catch {
+		return visWriteOutputs(root, opts);
+	}
+}
+
+const GRAPH_PUBLISH_LOCK = ".map-publish-lock";
+const GRAPH_LOCK_STALE_MS = 2000;
+const GRAPH_LOCK_WAIT_MS = 120000;
+const GRAPH_LOCK_HEARTBEAT_MS = 250;
+
+function graphSleep(ms) {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function graphAcquirePublication(outDir) {
 	ensureDir(outDir);
-	const map = visBuildMap(root);
+	const lockDir = path.join(fs.realpathSync(outDir), GRAPH_PUBLISH_LOCK);
+	const token = crypto.randomBytes(16).toString("hex");
+	const ownerPath = path.join(lockDir, `.owner-${token}.json`);
+	const deadline = Date.now() + GRAPH_LOCK_WAIT_MS;
+	for (;;) {
+		try {
+			fs.mkdirSync(lockDir, { mode: 0o700 });
+			fs.writeFileSync(ownerPath, JSON.stringify({ token, pid: process.pid }), { mode: 0o600, flag: "wx" });
+			// An IPC channel is an OS-owned parent-liveness signal and cannot be
+			// fooled by PID reuse. The token-specific pathname prevents a delayed
+			// heartbeat from refreshing a successor after stale-lock recovery.
+			const heartbeatScript = `const fs=require("node:fs");const [owner,interval]=process.argv.slice(1);process.on("disconnect",()=>process.exit(0));setInterval(()=>{try{const now=new Date();fs.utimesSync(owner,now,now)}catch{process.exit(0)}},Number(interval));`;
+			const heartbeat = spawn(process.execPath, ["-e", heartbeatScript, ownerPath, String(GRAPH_LOCK_HEARTBEAT_MS)], {
+				stdio: ["ignore", "ignore", "ignore", "ipc"], windowsHide: true,
+			});
+			heartbeat.unref();
+			heartbeat.channel?.unref();
+			return { lockDir, ownerPath, token, heartbeat };
+		} catch (error) {
+			if (error.code !== "EEXIST") {
+				try { fs.rmSync(ownerPath, { force: true }); fs.rmdirSync(lockDir); } catch { /* best effort for our incomplete lock */ }
+				throw error;
+			}
+			let info;
+			let heartbeatPath = null;
+			try {
+				const lockInfo = fs.lstatSync(lockDir);
+				if (!lockInfo.isDirectory()) throw new Error(`graph publication lock path is not a directory: ${lockDir}`);
+				info = lockInfo;
+				const owners = fs.readdirSync(lockDir, { withFileTypes: true })
+					.filter((entry) => entry.isFile() && /^\.owner-[a-f0-9]{32}\.json$/.test(entry.name));
+				if (owners.length === 1) {
+					const candidate = path.join(lockDir, owners[0].name);
+					try {
+						const owner = JSON.parse(fs.readFileSync(candidate, "utf8"));
+						const token = owners[0].name.slice(".owner-".length, -".json".length);
+						if (owner?.token === token && Number.isSafeInteger(owner.pid) && owner.pid > 0) {
+							info = fs.statSync(candidate);
+							heartbeatPath = candidate;
+						}
+					} catch { /* malformed owner: recover according to directory age */ }
+				}
+			} catch (inspectError) {
+				if (inspectError.code === "ENOENT") continue;
+				throw inspectError;
+			}
+			if (Date.now() - info.mtimeMs > GRAPH_LOCK_STALE_MS) {
+				if (heartbeatPath) {
+					const observed = info.mtimeMs;
+					graphSleep(2 * GRAPH_LOCK_HEARTBEAT_MS);
+					try { if (fs.lstatSync(heartbeatPath).mtimeMs > observed) continue; }
+					catch (recheckError) { if (recheckError.code !== "ENOENT") throw recheckError; }
+				}
+				const stale = `${lockDir}.stale-${process.pid}-${crypto.randomBytes(6).toString("hex")}`;
+				try { fs.renameSync(lockDir, stale); fs.rmSync(stale, { recursive: true, force: true }); } catch { /* another waiter won */ }
+				continue;
+			}
+			if (Date.now() >= deadline) throw new Error(`timed out waiting for graph publication lock ${lockDir}`);
+			graphSleep(10);
+		}
+	}
+}
+
+function graphReleasePublication(lock) {
+	try { lock.heartbeat.kill(); } catch { /* already exited */ }
+	// Token-specific unlink + rmdir is ABA-safe: an obsolete owner can never
+	// remove a successor's owner file, and rmdir fails while that file exists.
+	try { fs.rmSync(lock.ownerPath, { force: true }); } catch { /* stale recovery moved it */ }
+	try { fs.rmdirSync(lock.lockDir); } catch { /* stale recovery or successor owns it */ }
+}
+
+function visSourceGeneration(root) {
+	const hash = crypto.createHash("sha256");
+	for (const file of visWalk(root).files) {
+		hash.update(path.relative(root, file).split(path.sep).join("/"));
+		hash.update("\0");
+		try { hash.update(fs.readFileSync(file)); } catch (error) { hash.update(String(error.code || error.message)); }
+		hash.update("\0");
+	}
+	for (const relative of ["GROUPS.json", "FLOWS.json", "STATE.md", "ROADMAP.md", "PROJECT.md", "DOMAIN.md", "DOMAIN-MODEL.md"]) {
+		const file = path.join(root, PLANNING_DIR, relative === "GROUPS.json" || relative === "FLOWS.json" ? "codebase" : "", relative);
+		hash.update(relative);
+		try { hash.update(fs.readFileSync(file)); } catch (error) { hash.update(String(error.code || error.message)); }
+		hash.update("\0");
+	}
+	return hash.digest("hex");
+}
+
+function visWriteOutputs(root, opts = {}) {
+	const outDir = path.join(root, PLANNING_DIR, "codebase");
 	const jsonPath = path.join(outDir, "MAP.json");
 	const htmlPath = path.join(outDir, "MAP.html");
 	const reportPath = path.join(outDir, "GRAPH_REPORT.md");
-	// Idempotent write: if the new map differs from the committed file ONLY in the volatile
-	// generatedAt/buildMs fields, leave every artifact untouched — so the post-commit hook /
-	// stale rebuild never produces spurious git churn. Graph data is deterministic (see verify gate).
-	let unchanged = false;
+	const lock = graphAcquirePublication(outDir);
 	try {
-		const prev = JSON.parse(fs.readFileSync(jsonPath, "utf-8"));
-		unchanged = JSON.stringify(Object.assign({}, prev, { generatedAt: 0, buildMs: 0 }))
-			=== JSON.stringify(Object.assign({}, map, { generatedAt: 0, buildMs: 0 }));
-	} catch { /* no/invalid prior file → write fresh */ }
-	if (!unchanged) {
-		fs.writeFileSync(jsonPath, JSON.stringify(map, null, 2) + "\n", "utf-8");
-		fs.writeFileSync(reportPath, visRenderReport(map), "utf-8"); // a fresh human report is a parity feature
-	}
-	// MAP.html is a derived view artifact (not the git-committed source of truth), so on any full
-	// (non-quiet) build we always refresh it — otherwise template/visualization changes never reach
-	// MAP.html when the underlying graph data is unchanged. The JSON/report stay gated above so the
-	// committed data never churns. The post-commit hook uses --quiet and skips the HTML entirely.
-	if (!opts.quiet) fs.writeFileSync(htmlPath, visRenderHtml(jsonPath, map), "utf-8");
-	return { jsonPath, htmlPath, reportPath, map, unchanged };
+		for (;;) {
+			const before = visSourceGeneration(root);
+			const map = visBuildMap(root);
+			const stage = fs.mkdtempSync(path.join(outDir, ".map-publish-stage-js-"));
+			try {
+				const stageJSON = path.join(stage, "MAP.json");
+				const stageHTML = path.join(stage, "MAP.html");
+				const stageReport = path.join(stage, "GRAPH_REPORT.md");
+				let unchanged = false;
+				try {
+					const prev = JSON.parse(fs.readFileSync(jsonPath, "utf-8"));
+					unchanged = JSON.stringify(Object.assign({}, prev, { generatedAt: 0, buildMs: 0 }))
+						=== JSON.stringify(Object.assign({}, map, { generatedAt: 0, buildMs: 0 }));
+				} catch { /* no/invalid prior file */ }
+				if (!unchanged) {
+					fs.writeFileSync(stageJSON, JSON.stringify(map, null, 2) + "\n", "utf-8");
+					fs.writeFileSync(stageReport, visRenderReport(map), "utf-8");
+				}
+				if (!opts.quiet) fs.writeFileSync(stageHTML, visRenderHtml(jsonPath, map), "utf-8");
+				if (before !== visSourceGeneration(root)) continue;
+				if (!unchanged) fs.renameSync(stageReport, reportPath);
+				if (!opts.quiet) fs.renameSync(stageHTML, htmlPath);
+				if (!unchanged) fs.renameSync(stageJSON, jsonPath);
+				return { jsonPath, htmlPath, reportPath, map, unchanged };
+			} finally {
+				fs.rmSync(stage, { recursive: true, force: true });
+			}
+		}
+	} finally {
+		graphReleasePublication(lock);
+	}
 }
 
 // --- map-graph ---
@@ -5157,6 +5548,25 @@ const VIS_WATCH_EXTS = new Set(
 );
 // Workspace/package manifests: don't carry a "code" extension but change the dependency graph.
 const VIS_WATCH_MANIFESTS = new Set(["package.json", "pnpm-workspace.yaml", "turbo.json", "nx.json", "lerna.json"]);
+// Planning inputs consumed verbatim by visSourceGeneration(). Keep this exact allowlist in sync with
+// that function: all other .planning paths are generated publications, caches, locks, or staging.
+const VIS_WATCH_PLANNING_INPUTS = new Set([
+	".planning/STATE.md", ".planning/ROADMAP.md", ".planning/PROJECT.md",
+	".planning/DOMAIN.md", ".planning/DOMAIN-MODEL.md",
+	".planning/codebase/GROUPS.json", ".planning/codebase/FLOWS.json",
+]);
+
+function visShouldWatchPath(file) {
+	if (VIS_WATCH_PLANNING_INPUTS.has(file)) return true;
+	if (file === ".planning" || file.startsWith(".planning/") || file.includes("/.planning/")) return false;
+	const firstSeg = file.split("/")[0];
+	if (VIS_DEFAULT_IGNORES.has(firstSeg)) return false;
+	if (file.includes("/node_modules/") || file.includes("/.git/")) return false;
+	const base = file.split("/").pop() || "";
+	const dot = base.lastIndexOf(".");
+	const ext = dot >= 0 ? base.slice(dot).toLowerCase() : "";
+	return VIS_WATCH_MANIFESTS.has(base) || VIS_WATCH_EXTS.has(ext);
+}
 
 commands["map-serve"] = function (...args) {
 	const http = require("node:http");
@@ -5183,6 +5593,17 @@ commands["map-serve"] = function (...args) {
 	console.log(`Indexed ${lastBuild.map.stats.files} modules in ${lastBuild.map.buildMs}ms`);
 
 	const clients = new Set();
+	const dropClient = (client) => {
+		clients.delete(client);
+		try { client.end(); } catch { /* already closed */ }
+	};
+	const sendClient = (client, message) => {
+		try {
+			if (!client.write(message)) dropClient(client);
+		} catch {
+			dropClient(client);
+		}
+	};
 	let regenTimer = null;
 	const regen = () => {
 		clearTimeout(regenTimer);
@@ -5192,7 +5613,7 @@ commands["map-serve"] = function (...args) {
 				const ts = new Date().toLocaleTimeString();
 				console.log(`[${ts}] regenerated MAP.json (${lastBuild.map.stats.files} modules, ${lastBuild.map.buildMs}ms)`);
 				for (const c of clients) {
-					try { c.write("data: changed\n\n"); } catch { /* empty */ }
+					sendClient(c, "data: changed\n\n");
 				}
 			} catch (err) {
 				console.error("regen failed:", err.message);
@@ -5206,20 +5627,11 @@ commands["map-serve"] = function (...args) {
 		try {
 			const w = fs.watch(target, { recursive: recursive }, (_evt, fname) => {
 				if (!fname) return;
-				// Defect 16: normalize to posix separators BEFORE any segment/substring check — the
-				// previous checks below (`/node_modules/`, `/.git/`, …) silently never matched on win32,
-				// where fs.watch reports paths with backslashes.
-				const f = fname.toString().split(path.sep).join("/");
-				const firstSeg = f.split("/")[0];
-				if (VIS_DEFAULT_IGNORES.has(firstSeg)) return;
-				if (f.includes("/node_modules/") || f.includes("/.git/")) return;
-				if (f === ".planning" || f.startsWith(".planning/") || f.includes("/.planning/")) return;
-				// Defect 16: only code-language files (+ workspace manifests) trigger a rebuild — a
-				// touched README or a stray editor swapfile used to rebuild the whole graph.
-				const base = f.split("/").pop() || "";
-				const dot = base.lastIndexOf(".");
-				const ext = dot >= 0 ? base.slice(dot).toLowerCase() : "";
-				if (!VIS_WATCH_MANIFESTS.has(base) && !VIS_WATCH_EXTS.has(ext)) return;
+				// Normalize both separators and watcher-relative names to one repo-relative path.
+				// Linux fallback watchers report STATE.md while watching .planning; recursive root
+				// watchers report .planning/STATE.md. Admission must see the same path in both cases.
+				const f = path.relative(cwd, path.resolve(target, fname.toString())).split(path.sep).join("/");
+				if (!visShouldWatchPath(f)) return;
 				regen();
 			});
 			watchers.push(w);
@@ -5232,9 +5644,12 @@ commands["map-serve"] = function (...args) {
 		tryWatch(cwd, false);
 		for (const e of fs.readdirSync(cwd, { withFileTypes: true })) {
 			if (!e.isDirectory()) continue;
-			if (VIS_DEFAULT_IGNORES.has(e.name)) continue;
+			if (VIS_DEFAULT_IGNORES.has(e.name) && e.name !== PLANNING_DIR) continue;
 			tryWatch(path.join(cwd, e.name), false);
 		}
+		// GROUPS/FLOWS live one level below .planning. Linux's non-recursive fallback needs
+		// an explicit watcher there; exact path admission still rejects every generated peer.
+		tryWatch(path.join(cwd, PLANNING_DIR, "codebase"), false);
 		if (watchers.length === 0) console.error("map-serve: file watching unavailable — live reload disabled (use the reload button).");
 	}
 
@@ -5258,7 +5673,7 @@ commands["map-serve"] = function (...args) {
 					"cache-control": "no-cache",
 					connection: "keep-alive",
 				});
-				res.write("retry: 2000\n\n");
+				if (!res.write("retry: 2000\n\n")) { dropClient(res); return; }
 				clients.add(res);
 				req.on("close", () => clients.delete(res));
 			} else if (url === "/health") {
@@ -5279,7 +5694,7 @@ commands["map-serve"] = function (...args) {
 	// EventSource ignores lines starting with ":", so this never fires a message event.
 	const pingTimer = setInterval(() => {
 		for (const c of clients) {
-			try { c.write(": ping\n\n"); } catch { /* empty */ }
+			sendClient(c, ": ping\n\n");
 		}
 	}, 25000);
 
@@ -5635,6 +6050,16 @@ Knowledge Graph (query MAP.json instead of grepping — run map-graph first):
   graph-clusters [--surprising] Structural neighborhoods (+ surprising/bridge connections)
   graph-hook install|uninstall|status   Git post-commit hook that refreshes MAP.json
   (all accept --json for machine output)
+
+  Knowledge graph commands run through a prebuilt \`draht-graph\` binary when one
+  resolves (~6x faster on a cold build), and fall back to this file's built-in JS
+  engine otherwise. DRAHT_GRAPH_ENGINE=go|js|auto (default auto) forces the choice;
+  DRAHT_GRAPH_BIN=/path/to/draht-graph overrides binary resolution. Go-only flags
+  (--jobs, --parser, --cache-dir, --out, --ast-max-bytes, --verbose) are recognized
+  and forwarded when the Go binary handles the command, and are stripped (not
+  passed through, not an error) when the JS engine handles it instead — so a
+  script using them works either way. Install the binary with
+  \`npx draht-claude install-graph-engine\` (or draht-codex).
   create-project [name]         Create PROJECT.md
   create-requirements           Create REQUIREMENTS.md
   create-domain-model           Generate DOMAIN-MODEL.md from PROJECT.md
@@ -5687,7 +6112,13 @@ const [cmd, ...args] = process.argv.slice(2);
 	if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
 		commands.help();
 	} else if (commands[cmd]) {
-		await commands[cmd](...args);
+		graphMaybeDelegate(cmd, args); // exits the process when the Go engine handles it
+		// Go-only flags (--jobs, --parser, --cache-dir, --out, --ast-max-bytes, --verbose)
+		// mean nothing to the JS engine and, left in, corrupt its own arg parsing (an
+		// unconsumed value token gets read as a positional file/dir — finding #4). Strip
+		// them here so the two engines accept the same command line.
+		const jsArgs = GRAPH_GO_COMMANDS.has(cmd) ? graphStripGoOnlyFlags(args) : args;
+		await commands[cmd](...jsArgs);
 	} else {
 		console.error(`Unknown command: ${cmd}\nRun: draht-tools help`);
 		process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@draht/tools",
-	"version": "2026.7.30",
+	"version": "2026.9.5-1",
 	"description": "Draht Tools — Get Shit Done CLI (canonical source shared by draht-claude and @draht/coding-agent).",
 	"type": "commonjs",
 	"bin": {
@@ -13,7 +13,7 @@
 		"CHANGELOG.md"
 	],
 	"scripts": {
-		"test": "node bin/draht-tools.cjs --help > /dev/null"
+		"test": "node --test test/delegation.test.mjs test/graph-delegation.test.cjs && node bin/draht-tools.cjs --help > /dev/null"
 	},
 	"keywords": [
 		"draht",