harnery 0.41.0 → 0.42.0

package/src/commands/disk.ts

@@ -0,0 +1,114 @@
+import { type Command, InvalidArgumentError } from "commander";
+import type { EmitContext } from "../commander.ts";
+import {
+  type DiskGroup,
+  type DiskOptions,
+  type DiskReport,
+  diskUsage,
+  parseDiskSize,
+} from "../lib/disk-usage.ts";
+
+function positive(value: string): number {
+  if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < 1)
+    throw new InvalidArgumentError("requires a positive integer");
+  return Number(value);
+}
+
+export function registerDiskCommand(program: Command, emit: EmitContext): void {
+  program
+    .command("disk [path]")
+    .description("Measure checkout disk usage, including nested repositories and ignored files")
+    .option(
+      "--git <states>",
+      "Filter: tracked, untracked, ignored, git-metadata, non-repository, unknown (comma-separated)",
+    )
+    .option(
+      "--type <types>",
+      "File extensions or video, audio, image, media, archive (comma-separated)",
+    )
+    .option(
+      "--exclude <paths>",
+      "Skip directory names at any depth or root-relative paths; repeatable, comma-separated",
+      (value: string, previous: string[]) => [...previous, value],
+      [],
+    )
+    .option("--group <by>", "Group by directory, repository, extension, git, or files", "directory")
+    .option("--depth <n>", "Directory grouping depth; does not limit the scan", positive, 1)
+    .option("--top <n>", "Maximum groups and largest files to display", positive, 20)
+    .option(
+      "--min-size <size>",
+      "Include individual files at least this size (e.g. 10MB, 1GiB)",
+      parseDiskSize,
+    )
+    .option("--apparent", "Rank and filter by file lengths instead of allocated blocks")
+    .option("--json", "Emit the versioned disk usage report")
+    .action(
+      (path: string | undefined, options: DiskOptions & { group: DiskGroup; json?: boolean }) => {
+        try {
+          const { json, ...filters } = options;
+          const report = diskUsage(path, filters);
+          if (json) {
+            emit.config({ format: "json" });
+            emit.data(report);
+          } else emit.text(renderDiskUsage(report));
+          if (!report.complete) emit.setExitCode(1);
+        } catch (error) {
+          emit.error({
+            code: "disk_usage_failed",
+            message: error instanceof Error ? error.message : String(error),
+          });
+          emit.setExitCode(1);
+        }
+      },
+    );
+}
+
+export function renderDiskUsage(report: DiskReport): string {
+  const bytes = (value: number): string =>
+    value >= 1e9
+      ? `${(value / 1e9).toFixed(2)} GB`
+      : value >= 1e6
+        ? `${(value / 1e6).toFixed(2)} MB`
+        : value >= 1e3
+          ? `${(value / 1e3).toFixed(2)} KB`
+          : `${value} B`;
+  const size = (row: { allocated_bytes: number | null; apparent_bytes: number }): string =>
+    bytes(
+      report.measurement === "allocated"
+        ? (row.allocated_bytes ?? row.apparent_bytes)
+        : row.apparent_bytes,
+    );
+  const lines = [
+    `Disk usage: ${report.root}`,
+    `${size(report.totals)} in ${report.totals.files.toLocaleString()} regular files (${report.measurement})`,
+    `File lengths: ${bytes(report.totals.apparent_bytes)}. Directory metadata and symlinks are excluded.`,
+    "",
+    "Git state:",
+  ];
+  for (const [state, totals] of Object.entries(report.git))
+    if (totals.files)
+      lines.push(
+        `${size(totals).padStart(12)}  ${String(totals.files).padStart(8)} files  ${state}`,
+      );
+  lines.push(
+    "",
+    `Largest ${report.filters.group} groups (${report.groups.length} of ${report.group_count}):`,
+  );
+  for (const row of report.groups)
+    lines.push(`${size(row).padStart(12)}  ${String(row.files).padStart(8)} files  ${row.path}`);
+  if (report.filters.group !== "files") {
+    lines.push("", "Largest files:");
+    for (const row of report.largest_files)
+      lines.push(`${size(row).padStart(12)}  ${row.git.padEnd(14)}  ${row.path}`);
+  }
+  if (report.skipped.symlinks || report.skipped.special_files || report.skipped.excluded)
+    lines.push(
+      "",
+      `Skipped: ${report.skipped.symlinks} symlinks, ${report.skipped.special_files} special files, ${report.skipped.excluded} excluded entries.`,
+    );
+  if (report.issues.length) {
+    lines.push("", "Incomplete scan:");
+    for (const issue of report.issues) lines.push(`${issue.path}: ${issue.message}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/doctor.ts

@@ -18,7 +18,7 @@ import path from "node:path";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
 import { BUILTIN_ADAPTER_IDS } from "../core/adapters/index.ts";
-import { resolveBinName, ripgrepAutoInstall } from "../core/config.ts";
+import { codexWindowsBridgeConfig, resolveBinName, ripgrepAutoInstall } from "../core/config.ts";
 import {
   countSummarizedSinceV3,
   listDiagnosticSummariesV3,
@@ -33,6 +33,7 @@ import {
   type CodexWslBridgeStatus,
   inspectCodexWslBridge,
 } from "../core/hooks/codex-wsl-bridge.ts";
+import { findUnfinishedHookRuns } from "../core/hooks/run-markers.ts";
 import {
   ADAPTER_BINARIES,
   ADAPTER_INSTALL_HINTS,
@@ -115,6 +116,8 @@ export async function runChecks(): Promise<Check[]> {
   const codexWslStatus = inspectCodexWslBridge();
   const recentCodexMidFlightCount = root ? countRecentCodexMidFlightOnboardings(root) : 0;
   const codexWslBridge = codexWslBridgeCheck(codexWslStatus, recentCodexMidFlightCount);
+  const codexHookRuns = codexHookRunsCheck(root);
+  const codexWindowsRoute = codexWindowsBridgeCheck(root);
   // Probe the adapter CLIs before the hook check runs, not in output order:
   // an unwired adapter only matters if its CLI is actually installed, and
   // probing once here keeps that join to one spawn per CLI.
@@ -131,6 +134,8 @@ export async function runChecks(): Promise<Check[]> {
     ...(codexAuthorization ? [codexAuthorization] : []),
     checkGitHookRegions(),
     ...(codexWslBridge ? [codexWslBridge] : []),
+    ...(codexWindowsRoute ? [codexWindowsRoute] : []),
+    ...(codexHookRuns ? [codexHookRuns] : []),
     ...workflow.map((w) => w.check),
     checkRestic(),
     checkRclone(),
@@ -189,6 +194,52 @@ export function codexWslBridgeCheck(
   };
 }
 
+/**
+ * Hook runs that started but never finished (ADR 0197). Codex kills a hook at
+ * its timeout and the tool proceeds without that hook's checks; the start
+ * marker is the only trace such a run leaves.
+ */
+export function codexHookRunsCheck(
+  coordRoot: string | null,
+  nowMs = Date.now(),
+  isAlive?: (pid: number) => boolean,
+): Check | null {
+  if (!coordRoot) return null;
+  const runs = findUnfinishedHookRuns(coordRoot, nowMs, undefined, isAlive);
+  if (runs.count === 0) return null;
+  const events = runs.events.map((e) => `${e.event} ×${e.count}`).join(", ");
+  return {
+    name: "codex:hook runs",
+    severity: "warn",
+    detail:
+      `${runs.count} hook run${runs.count === 1 ? "" : "s"} started but never finished in the last 24h ` +
+      `(${events}; latest ${runs.latest}); their tools proceeded without those hooks' checks`,
+    hint: "a hook that outlives its timeout is killed; look for a stalled WSL session or a slow hook",
+  };
+}
+
+/** Report the per-project Windows bridge opt-in, or an invalid value init ignored. */
+export function codexWindowsBridgeCheck(coordRoot: string | null): Check | null {
+  if (!coordRoot) return null;
+  const bridge = codexWindowsBridgeConfig(coordRoot);
+  if (bridge.error) {
+    return {
+      name: "codex:Windows hook route",
+      severity: "warn",
+      detail: `${bridge.error}; Codex hooks are wired without commandWindows`,
+      hint: "set hooks.codexWindowsBridge.entryPoint to a plain command name in .harnery/config.jsonc, then re-run init",
+    };
+  }
+  if (!bridge.entryPoint) return null;
+  return {
+    name: "codex:Windows hook route",
+    severity: "ok",
+    detail:
+      `opted in: Windows-native Codex hooks hand off to \`${bridge.entryPoint}\` from WSL paths ` +
+      `when it is on PATH, otherwise run the usual command; bridge health is reported by the bridge itself`,
+  };
+}
+
 const CODEX_MID_FLIGHT_HISTORY_WINDOW_MS = 48 * 60 * 60 * 1000;
 
 /** Count bounded, privacy-safe recovery diagnostics so a healthy environment

package/src/commands/files.ts

@@ -5,7 +5,21 @@ import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import { resolveCoordRoot } from "../core/agents/coord-client.ts";
 import { DEFAULT_WEB_PORT, resolveWebPort } from "../core/config.ts";
 import { coordRootId, localCoordRootIdUrl } from "../lib/coord-root-id.ts";
-import { localFilesOriginUrl, localFileViewerUrl } from "../lib/local-file-url.ts";
+import {
+  encodedRepoPath,
+  encodeLinkSafeComponent,
+  FILES_ORIGIN_HOST,
+  localFilesOriginUrl,
+  localFileViewerUrl,
+} from "../lib/local-file-url.ts";
+import { isPathAllowed } from "../lib/tunnel/path-scope.ts";
+import {
+  isTunnelStateLive,
+  listStates,
+  type ProcessAliveCheck,
+  type TunnelState,
+  tunnelTargetPort,
+} from "../lib/tunnel/state.ts";
 
 export { FILES_ORIGIN_HOST } from "../lib/local-file-url.ts";
 
@@ -162,6 +176,72 @@ export function mintLocalFileUrl(input: string, options: LocalFileUrlOptions): L
   return { url, relPath, mode };
 }
 
+export class TunnelLinkError extends Error {
+  constructor(
+    message: string,
+    readonly hint: string,
+  ) {
+    super(message);
+    this.name = "TunnelLinkError";
+  }
+}
+
+function vhostName(vhost: string): string {
+  return vhost.replace(/:\d+$/, "").toLowerCase();
+}
+
+function newestFirst(states: TunnelState[]): TunnelState[] {
+  return [...states].sort((a, b) => b.started_at.localeCompare(a.started_at));
+}
+
+/**
+ * Turn a minted local URL into the same file's URL on a live tunnel.
+ *
+ * HTML needs a tunnel in front of the isolated files origin (its vhost is
+ * FILES_ORIGIN_HOST), because only that origin renders the page and serves its
+ * relative assets; a dashboard tunnel can only show the viewer, which displays
+ * HTML as source. Other files need a dashboard tunnel that serves the viewer.
+ * In both cases the tunnel's path scope must forward the request, or its gate
+ * would refuse the link, so a tunnel that does not cover the file is skipped.
+ */
+export function tunnelFileUrl(
+  local: LocalFileUrl,
+  port: number,
+  states: TunnelState[],
+  processAlive?: ProcessAliveCheck,
+): string {
+  const live = states.filter(
+    (state) => tunnelTargetPort(state) === port && isTunnelStateLive(state, processAlive),
+  );
+  if (local.mode === "raw") {
+    const path = `/${encodedRepoPath(local.relPath)}`;
+    const tunnel = newestFirst(live).find(
+      (state) =>
+        vhostName(state.vhost) === FILES_ORIGIN_HOST && isPathAllowed(path, state.allow_paths),
+    );
+    if (tunnel) return `${tunnel.url.replace(/\/+$/, "")}${path}`;
+    const folder = local.relPath.includes("/")
+      ? `/${local.relPath.slice(0, local.relPath.lastIndexOf("/"))}`
+      : "/";
+    throw new TunnelLinkError(
+      `no live tunnel serves the files origin for /${local.relPath}`,
+      `Start one scoped to the page's folder, for example: tunnel up --name pages --target 127.0.0.1:${port} --vhost ${FILES_ORIGIN_HOST} --allow-path ${folder}`,
+    );
+  }
+  const tunnel = newestFirst(live).find(
+    (state) =>
+      vhostName(state.vhost) !== FILES_ORIGIN_HOST &&
+      ["/files", "/api/file", "/_next"].every((path) => isPathAllowed(path, state.allow_paths)),
+  );
+  if (tunnel) {
+    return `${tunnel.url.replace(/\/+$/, "")}/files?path=${encodeLinkSafeComponent(local.relPath)}`;
+  }
+  throw new TunnelLinkError(
+    `no live tunnel serves the dashboard file viewer on port ${port}`,
+    `Start one, for example: tunnel up --name files --target 127.0.0.1:${port} --allow-path /files --allow-path /api/file --allow-path /_next`,
+  );
+}
+
 export function registerFilesCommand(
   program: Command,
   emit: EmitContext,
@@ -180,6 +260,10 @@ export function registerFilesCommand(
     .option("--raw", "Use the isolated files origin, regardless of extension")
     .option("--viewer", "Use the dashboard file viewer, regardless of extension")
     .option("--no-verify", "Mint without checking the running dashboard's repository identity")
+    .option(
+      "--tunnel",
+      "Print the file's URL on a live tunnel instead of localhost (HTML uses a files-origin tunnel)",
+    )
     .action(
       async (
         filePath: string,
@@ -189,6 +273,7 @@ export function registerFilesCommand(
           raw?: boolean;
           viewer?: boolean;
           verify?: boolean;
+          tunnel?: boolean;
         },
       ) => {
         if (opts.raw && opts.viewer) {
@@ -224,8 +309,14 @@ export function registerFilesCommand(
             mode: opts.raw ? "raw" : opts.viewer ? "viewer" : "auto",
           });
           if (opts.verify !== false) await verifyDashboardRoot(coordRoot, port);
-          emit.text(`${result.url}\n`);
+          const url = opts.tunnel ? tunnelFileUrl(result, port, listStates(coordRoot)) : result.url;
+          emit.text(`${url}\n`);
         } catch (error) {
+          if (error instanceof TunnelLinkError) {
+            emit.error({ code: "no_tunnel_for_file", message: error.message, hint: error.hint });
+            emit.setExitCode(1);
+            return;
+          }
           if (error instanceof DashboardRootError) {
             emit.error({ code: error.code, message: error.message, hint: error.hint });
             emit.setExitCode(1);

package/src/commands/init.ts

@@ -27,7 +27,12 @@ import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
-import { DEFAULT_BIN_NAME, pinnedBinName, stripJsonComments } from "../core/config.ts";
+import {
+  codexWindowsBridgeConfig,
+  DEFAULT_BIN_NAME,
+  pinnedBinName,
+  stripJsonComments,
+} from "../core/config.ts";
 import { canonicalJsonV3 } from "../core/events/v3/canonical.ts";
 import { ADAPTER_CAPABILITY_PROFILES_V3 } from "../core/events/v3/capabilities.ts";
 import type { EventV3ControlState } from "../core/events/v3/control.ts";
@@ -48,13 +53,17 @@ import {
   CURSOR_STOP_FOLLOWUP_LOOP_LIMIT,
   commandWiresSubcommand,
   diffWiring,
+  expectedCommandWindows,
   groupCommands,
   type HookGroup,
   hookCommand,
+  hookTimeoutFor,
   isAgentHookCommand,
   makeEntry,
+  orderHandlerKeys,
   type SettingsFile,
   summarizeAdapterWiring,
+  type WiringOptions,
 } from "../core/hooks/adapter/wiring.ts";
 import { detectInstalledAdapters } from "../core/workflow/adapters.ts";
 import { applyIndexerExclusions } from "../lib/indexer-exclusions.ts";
@@ -147,7 +156,11 @@ function checkAdapterHooks(
   let drift = false;
   try {
     const settings = JSON.parse(readFileSync(settingsPath, "utf8")) as SettingsFile;
-    const hookDiff = diffWiring(settings, spec, { agentHookPath: agentHook, adapter });
+    const hookDiff = diffWiring(settings, spec, {
+      agentHookPath: agentHook,
+      adapter,
+      windowsBridgeEntryPoint: codexWindowsBridgeConfig(projectRoot).entryPoint,
+    });
     drift =
       hookDiff.missing.length > 0 ||
       hookDiff.stale.length > 0 ||
@@ -460,11 +473,16 @@ export function registerInitCommand(program: Command, emit: EmitContext, binName
           } else {
             settings = {};
           }
+          const bridge = codexWindowsBridgeConfig(projectRoot);
+          if (bridge.error && spec.windowsBridgeHooks) {
+            actions.push(`⚠ ${bridge.error}; writing ${adapter} hooks without commandWindows`);
+          }
           const { wired, already, removed, upgraded } = wireHooks(
             settings,
             spec,
             agentHook,
             adapter,
+            { windowsBridgeEntryPoint: bridge.entryPoint },
           );
 
           if (wired === 0 && removed === 0 && upgraded === 0) {
@@ -588,6 +606,7 @@ export function wireHooks(
   spec: AdapterSpec,
   agentHookPath: string,
   adapter: AdapterId,
+  options?: WiringOptions,
 ): { wired: number; already: number; removed: number; upgraded: number } {
   if (spec.rootVersion !== undefined && settings.version === undefined) {
     settings.version = spec.rootVersion;
@@ -606,6 +625,19 @@ export function wireHooks(
   }
   for (const { settingsKey, subcommand } of spec.events) {
     const command = hookCommand(spec, agentHookPath, subcommand, adapter);
+    const timeout = hookTimeoutFor(spec, subcommand);
+    const commandWindows = expectedCommandWindows(
+      spec,
+      agentHookPath,
+      subcommand,
+      adapter,
+      options,
+    );
+    const handlerFields = {
+      timeout,
+      commandWindows,
+      windowsBridge: spec.windowsBridgeHooks === true,
+    };
     let present = false;
     for (const key of Object.keys(settings.hooks)) {
       if (key === settingsKey) continue;
@@ -616,7 +648,7 @@ export function wireHooks(
     const groups = settings.hooks[settingsKey] ?? [];
     const nextGroups: HookGroup[] = [];
     for (const group of groups) {
-      const normalized = normalizeEventGroup(group, subcommand, command, present);
+      const normalized = normalizeEventGroup(group, subcommand, command, handlerFields, present);
       if (normalized.found && !present) present = true;
       upgraded += normalized.upgraded;
       removed += normalized.removed;
@@ -635,7 +667,7 @@ export function wireHooks(
         command,
         spec.entryShape === "cursor" && subcommand === "stop"
           ? { loop_limit: CURSOR_STOP_FOLLOWUP_LOOP_LIMIT }
-          : undefined,
+          : { timeout, commandWindows },
       ),
     );
     settings.hooks[settingsKey] = current;
@@ -658,6 +690,7 @@ function normalizeEventGroup(
   group: HookGroup,
   subcommand: string,
   canonical: string,
+  fields: { timeout?: number; commandWindows?: string; windowsBridge: boolean },
   alreadyFound: boolean,
 ): { group: HookGroup | null; found: boolean; upgraded: number; removed: number } {
   let found = false;
@@ -676,7 +709,8 @@ function normalizeEventGroup(
   }
   if ("hooks" in group && Array.isArray(group.hooks)) {
     const kept = [] as typeof group.hooks;
-    for (const hook of group.hooks) {
+    for (const original of group.hooks) {
+      let hook = original;
       if (typeof hook.command !== "string" || !commandWiresSubcommand(hook.command, subcommand)) {
         kept.push(hook);
         continue;
@@ -686,8 +720,24 @@ function normalizeEventGroup(
         continue;
       }
       found = true;
+      let changed = false;
       if (hook.command !== canonical) {
         hook.command = canonical;
+        changed = true;
+      }
+      if (fields.timeout !== undefined && hook.timeout !== fields.timeout) {
+        hook.timeout = fields.timeout;
+        changed = true;
+      }
+      // Harnery owns commandWindows on its own handlers for adapters that run
+      // it: write the opted-in command, or remove one a project opted out of.
+      if (fields.windowsBridge && hook.commandWindows !== fields.commandWindows) {
+        if (fields.commandWindows === undefined) delete hook.commandWindows;
+        else hook.commandWindows = fields.commandWindows;
+        changed = true;
+      }
+      if (changed) {
+        hook = orderHandlerKeys(hook);
         upgraded++;
       }
       kept.push(hook);

package/src/commands/rm.ts

@@ -0,0 +1,115 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import { resolveCoordRoot } from "../core/agents/coord-client.ts";
+import {
+  readCoordinationViewV3,
+  requireAuthoritySafeCoordinationViewV3,
+} from "../core/events/v3/coordination-view.ts";
+import { liveInstanceIdV3 } from "../core/events/v3/live-route-observer.ts";
+import { resolveOwner } from "../core/hooks/resolve/owner.ts";
+import { guardedRemove, type RemoveOptions } from "../lib/guarded-remove.ts";
+
+export function registerRmCommand(
+  program: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  program
+    .command("rm <paths...>")
+    .description("Preview guarded removal of untracked files; --yes applies permanent deletion")
+    .requiredOption(
+      "--root <directory>",
+      "Allowed directory; each target must be strictly inside it",
+    )
+    .option("-r, --recursive", "Permit directory removal after inspecting its complete contents")
+    .option(
+      "--allow-protected <path>",
+      "Remove this one protected path (Git metadata, credentials, Harnery state, keys) inside a target; repeat per path",
+      (value: string, previous: string[] = []) => [...previous, value],
+    )
+    .option("--yes", "Permanently remove validated targets")
+    .option("--dry-run", "Preview only, even with --yes")
+    .option("--json", "Emit the versioned removal report")
+    .action((paths: string[], options: RemoveOptions & { json?: boolean }) => {
+      try {
+        const coordRoot = context?.resolveCoordRoot?.() ?? context?.repoRoot ?? resolveCoordRoot();
+        const checkClaims = (targets: string[]): void => {
+          if (!coordRoot || !existsSync(resolve(coordRoot, ".harnery"))) return;
+          const view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(coordRoot));
+          const owner = resolveOwner({ payload: null, coordRoot });
+          const ownId = owner ? liveInstanceIdV3(owner.instance_id) : undefined;
+          const ownSession = ownId ? view.instances[ownId]?.session_id : undefined;
+          for (const peer of Object.values(view.instances)) {
+            if (
+              !peer.authority_eligible ||
+              peer.instance_id === ownId ||
+              (ownSession && peer.session_id === ownSession)
+            )
+              continue;
+            for (const claim of peer.files_touched) {
+              const claimed = resolve(coordRoot, claim);
+              for (const target of targets) {
+                if (overlaps(target, claimed))
+                  throw new Error(
+                    `Target overlaps another agent's claim: ${claim} (${peer.instance_id})`,
+                  );
+              }
+            }
+          }
+        };
+        // The workspace this command coordinates, and the checkout it runs in:
+        // their own .git and .harnery can never be allowed.
+        const liveRoots = [coordRoot, gitTopLevel(process.cwd())].filter((dir): dir is string =>
+          Boolean(dir),
+        );
+        const report = guardedRemove(paths, { ...options, liveRoots }, checkClaims);
+        if (options.json) {
+          emit.config({ format: "json" });
+          emit.data(report);
+        } else {
+          const lines = [
+            `${report.applied ? "Removed" : "Would remove"} ${report.targets.length} target(s), ${report.entries} entries, ${report.bytes} bytes:`,
+            ...report.targets,
+          ];
+          if (report.protected.length)
+            lines.push(
+              "Protected paths named with --allow-protected:",
+              ...report.protected.map((path) => `  ${path}`),
+            );
+          if (report.links.length)
+            lines.push(
+              "Links removed as links (their targets are untouched):",
+              ...report.links.map((link) => `  ${link.path} -> ${link.target}`),
+            );
+          if (!report.applied)
+            lines.push("Preview only. Add --yes to permanently delete these targets.");
+          emit.text(lines.join("\n"));
+        }
+      } catch (error) {
+        emit.error({
+          code: "removal_refused",
+          message: error instanceof Error ? error.message : String(error),
+        });
+        emit.setExitCode(1);
+      }
+    });
+}
+
+function gitTopLevel(dir: string): string | undefined {
+  const result = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
+    encoding: "utf8",
+    timeout: 10_000,
+  });
+  return result.status === 0 ? result.stdout.trim() || undefined : undefined;
+}
+
+function overlaps(a: string, b: string): boolean {
+  const inside = (parent: string, child: string) => {
+    const rel = relative(parent, child);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+  };
+  return inside(a, b) || inside(b, a);
+}