fix(build): migrate loopover-miner/loopover-mcp to out-of-place dist/ emit

Completes the proper fix for the 2026-07-24 codecov/patch (0%/99%)
incident. #8564 deleted in-place build output before the coverage run;
#8568 replaced that with a vitest resolver plugin forcing in-process
resolution to .ts regardless of a coexisting .js. Both were workarounds
around the real root cause: packages/loopover-{miner,mcp} compiled
in-place (tsconfig outDir "."), so compiled .js sat in the same
directory as its .ts source -- the actual, recurring bug class (three
prior incidents: stale .js shadowing fresh .ts, a no-op incremental
build lying about freshness, then the coverage-attribution bug).

This migrates both packages to out-of-place emit (outDir "dist"),
matching how packages/loopover-engine already builds. .ts source and
compiled .js output now live in physically separate directories, so
there is never a same-directory collision for any resolver to work
around -- the #8568 plugin is removed as dead code.

Turbo caching fixed alongside the directory move (a real, deferred
optimization surfaced by grep'ing this exact history): build:tsc's
`cache: false` was explicit migration-era caution a prior PR (#7317)
already flagged as safe to remove once bin/lib became fully
compiler-owned; the dist/ split removes the original hazard entirely.
Both packages' build tasks now declare real outputs (including
.tsbuildinfo, so a cache HIT keeps tsc's own incremental state
consistent with what's restored) instead of never caching at all.

Every literal reference to the old in-place bin/lib layout is updated:
the shared CLI test harnesses (which had to give up spawning bin/*.ts
directly via --experimental-strip-types -- that only worked because
Node's resolver found the entry's internal lib/*.js imports sitting
right next to it; it does not fall back .js->.ts the way Vite/esbuild
do), ~40 test files with hardcoded subprocess/readFileSync paths, 4
fixture scripts, the pack-check scripts' allowlists, check-syntax.mjs
in both packages, the DEPLOYMENT.md audit script + its documented
paths, and package.json's bin/files fields.

Two production-source bugs found and fixed properly, not patched
around: bin/loopover-mcp.ts and lib/status.ts both compute paths
relative to their own file location (own package.json, CHANGELOG.md,
the monorepo-sibling loopover-engine package) -- these files are ALSO
imported in-process by tests that resolve against the real .ts source,
so a single hardcoded relative depth cannot be correct for both
contexts. Both now try the source-relative depth first, falling back
to the dist-relative depth, so they work correctly however they're
currently loaded. bin/loopover-mcp.ts's dynamic
`import("@loopover/miner/lib/claim-ledger.js")` -- a published-package
subpath import into miner's internals, invisible to any relative-path
grep -- is fixed via an explicit `exports` map in miner's package.json
instead of hardcoding "dist/" into mcp's own source, so the public
contract between the two packages stays stable independent of miner's
internal layout.

package-lock.json's bin fields resynced (npm mirrors workspace
packages' bin targets there); node_modules/.bin symlinks regenerated
via a real `npm install` (--package-lock-only does not relink them).

Docs: contributing-to-loopover's reference.md and SKILL.md corrected
-- they previously said miner/mcp tests "run straight off the .ts"
with no build needed, which is no longer true for the CLI-harness and
stdio-transport-spawning tests now that dist/ is a separate directory.

Validated: full unsharded suite (21,541/21,541 passing), typecheck
clean, both real compiled CLIs execute and self-report their version
correctly, turbo cache save+restore verified to actually restore
dist/bin, dist/lib, and dist/package.json on a hit, and the monorepo
package-check scripts pass against the real built workspace.

Author: JSONbored

.claude/skills/contributing-to-loopover/SKILL.md

@@ -191,6 +191,13 @@ This is where most PRs fail Codecov. The bar is **every changed line AND every c
   it is not wired into CI or the Codecov gate. Before pushing, run the whole suite
   **unsharded** — `npm run test:coverage` — the only faithful local coverage signal (CI shards + merges,
   so a single shard under-reports).
+  - **Touching `packages/loopover-{miner,mcp}`?** Run `npm run build:miner`/`build:mcp` once before
+    scoping to an individual test file. Most miner/mcp tests import `lib/*.js` in-process (resolves
+    straight to the `.ts`, no build needed) — but the shared CLI harnesses and every stdio-transport
+    test (`mcp-cli-*.test.ts`, `mcp-feasibility-gate.test.ts`, etc.) spawn the real compiled
+    `dist/bin/*.js`, and will fail with a confusing `ENOENT`/module-resolve error against a stale or
+    missing `dist/` if you skip this. Re-run the build after editing miner/mcp source, same as you'd
+    re-run any other build before testing its output.
 - **Find the uncovered branch.** In the v8 text report, read the **% Branch** column and the
   **Uncovered Line #s** for your changed file — a line at 100% lines but <100% branch has an un-taken
   `??`/ternary/`&&` side; add that case. Aim for **100% branch on your diff locally** so normal CI

.claude/skills/contributing-to-loopover/reference.md

@@ -42,10 +42,16 @@ jobs run only if their path filter matched; on push to `main`, everything runs.
 | miner → pack | tarball hygiene | `npm run test:miner-pack` | unexpected/forbidden file in the miner npm tarball |
 
 `packages/loopover-{miner,mcp}` are `.ts`-only in git: editing their `bin`/`lib` source means editing `.ts`
-and nothing else — the compiled `.js`/`.d.ts` these two `build` commands produce is gitignored, never
-committed, and never something a PR needs to touch. Tests (in-process imports and the CLI-harness
-subprocess spawns alike) run straight off the `.ts`; `build:mcp`/`build:miner` above exist only to
-validate the real publishable artifact still compiles and packs cleanly.
+and nothing else — the compiled `.js`/`.d.ts` these two `build` commands produce lands in a gitignored
+`dist/` (out-of-place, mirroring `packages/loopover-engine`'s own `src/` → `dist/` split), never committed,
+and never something a PR needs to touch. Tests that **import** miner/mcp `lib/*.js` in-process (the vast
+majority) resolve straight to the sibling `.ts` with no build needed. Tests that **spawn a real subprocess**
+— the shared CLI harnesses (`test/unit/support/{miner,mcp}-cli-harness.ts`) and every `mcp-cli-*.test.ts`/
+`mcp-feasibility-gate.test.ts`-style file connecting a `StdioClientTransport` — run the actual compiled
+`dist/bin/*.js`, so **`npm run build:mcp`/`build:miner` must run before `test:coverage`** for those to pass;
+`npm run test:ci` already sequences this correctly, so this only bites if you invoke `vitest`/`test:coverage`
+directly without it. `build:mcp`/`build:miner`'s pack-check role (validating the real publishable artifact
+still compiles and packs cleanly) is unchanged.
 
 | rees → test | review-enrichment-service's own suite | `npm run rees:test` | any failing test under `review-enrichment/` |
 | ui → openapi drift | spec check | `npm run ui:openapi:check` | committed `openapi.json` is stale (run `npm run ui:openapi`) |

.github/workflows/ci.yml

@@ -544,11 +544,11 @@ jobs:
         run: npm run test:mcp-pack
       # Same "ships .ts only, this build is for the published npm tarball + the pack-check below, not for
       # tests" story as MCP's own "Build MCP" step above. Invokes turbo.json's @loopover/miner#build:tsc
-      # (cache: false -- historically to avoid a cache restore stomping this package's hand-written .js
-      # files while the #7290 migration was still in-flight; now that #7317 closed it out, every bin/lib
-      # file is compiler-owned and that original risk no longer applies, but re-enabling caching here is a
-      # separate change this PR doesn't make) and @loopover/miner#build:verify (real caching win: skips
-      # re-`node --check`-ing all 121 bin/lib files when neither changed) DIRECTLY as their own task names,
+      # (real caching win since the 2026-07-24 dist/ migration -- previously cache: false, historically to
+      # avoid a cache restore stomping this package's hand-written .js files while the #7290 migration was
+      # still in-flight; #7317 closed that out, and the dist/ split removed the original in-place-emit
+      # hazard entirely, so caching was finally enabled) and @loopover/miner#build:verify (real caching
+      # win: skips re-`node --check`-ing all bin/lib files when neither changed) DIRECTLY as their own task names,
       # deliberately NOT via the aggregate `@loopover/miner#build` task (which exists for standalone/local
       # `npm run build` callers) -- that aggregate's own script is `npm run build:tsc && npm run
       # build:verify`, i.e. it re-invokes both of these exact scripts a second time even when turbo already

.gitignore

@@ -1,18 +1,15 @@
 node_modules
 dist/
 dist-ssr/
-# packages/loopover-{miner,mcp} compile real TypeScript in place (tsc's outDir === rootDir) and never
-# commit the emitted output -- both ship as installable CLIs, so the .js still has to exist in the
-# published npm tarball (built fresh by `npm run build:{miner,mcp}` / the publish workflows), but nothing
-# else needs a prior build: Vite/esbuild resolve the .js-suffixed import specifiers these packages write
-# straight to the sibling .ts by default (same as packages/loopover-engine/src/**, which has never had a
-# committed .js either), and the CLI-harness tests spawn the .ts directly via Node's own type-stripping.
-packages/loopover-miner/bin/*.js
-packages/loopover-miner/bin/*.d.ts
-packages/loopover-miner/lib/*.js
-packages/loopover-miner/lib/*.d.ts
-packages/loopover-mcp/bin/*.js
-packages/loopover-mcp/lib/*.js
+# packages/loopover-{miner,mcp} compile real TypeScript out-of-place into dist/ (tsc's outDir "dist",
+# matching packages/loopover-engine's src/ -> dist/ split) and never commit the emitted output -- both
+# ship as installable CLIs, so the .js still has to exist in the published npm tarball (built fresh by
+# `npm run build:{miner,mcp}` / the publish workflows), but nothing else needs a prior build: Vite/esbuild
+# resolve the .js-suffixed import specifiers these packages write straight to the sibling .ts by default
+# (same as packages/loopover-engine/src/**, which has never had a committed .js either), and the
+# CLI-harness tests spawn the .ts directly via Node's own type-stripping. The generic "dist/" pattern
+# above already covers packages/loopover-{miner,mcp}/dist/** -- no package-specific line needed (this was
+# in-place emit with its own explicit ignore lines here until the 2026-07-24 migration).
 .turbo/
 .output
 .vinxi

Dockerfile

@@ -13,7 +13,7 @@ WORKDIR /app
 # (workspaces: apps/*, packages/*), and `npm ci` only symlinks node_modules/<pkg> to a workspace whose
 # directory already exists on disk. Copying just the root package*.json first (the usual dependency-layer
 # caching trick) left every workspace package.json missing at `npm ci` time, so npm silently skipped every
-# internal symlink -- @loopover/engine (a workspace dependency of loopover-miner's checked-in
+# internal symlink -- @loopover/engine (a workspace dependency of loopover-miner's built
 # lib/*.js artifacts, #2281) then couldn't be resolved by esbuild no matter how/when its own dist/ was built.
 COPY . .
 # --ignore-scripts: no native builds are needed (SQLite is the built-in node:sqlite; @hono/node-server is

package-lock.json

@@ -5,7 +5,7 @@ import { createHash } from "node:crypto";
 import { closeSync, constants as fsConstants, existsSync, fstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { buildFeasibilityVerdict, buildPrTextLint, buildGateDispositions, buildPublicPrBodyDraft } from "@loopover/engine";
@@ -48,10 +48,25 @@ import { redactKnownLocalPaths, redactLocalPath } from "../lib/redact-local-path
 // side by side unaliased would read as the same function (#6238).
 import { recordMcpToolCall as recordLocalMcpToolCall } from "../lib/telemetry.js";
 
+// Path to a file next to this package's own root, computed relative to THIS module's own on-disk
+// location -- which differs by one directory level depending on how this file is currently running:
+// imported in-process (e.g. by the vitest unit tests that exercise the CLI dispatcher + stdio tools
+// directly against bin/loopover-mcp.ts, per the invokedPath check below) resolves relative to the
+// real source bin/, while a real CLI invocation resolves relative to the compiled dist/bin/ (one
+// level deeper, since the 2026-07-24 dist/ migration; see tsconfig.json's outDir comment). A single
+// hardcoded relative depth can only ever be correct for one of those two contexts, so this tries
+// both, preferring whichever the current on-disk layout actually has.
+function resolveOwnPackageSiblingPath(...segments: string[]): URL {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const fromBin = join(here, "..", ...segments);
+  if (existsSync(fromBin)) return pathToFileURL(fromBin);
+  return pathToFileURL(join(here, "..", "..", ...segments));
+}
+
 // Read name/version from this package's own package.json (always present in any install --
 // global, npx, or local -- npm ships it regardless of the "files" allowlist) instead of hand-synced
 // literals, so a release bump never has a second place to forget.
-const ownPackageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const ownPackageJson = JSON.parse(readFileSync(resolveOwnPackageSiblingPath("package.json"), "utf8"));
 
 const defaultApiUrl = "https://api.loopover.ai";
 const legacyDefaultApiUrls = new Set([
@@ -71,7 +86,7 @@ const decisionPackCacheSchemaVersion = 1;
 const decisionPackCacheMaxEntries = 25;
 const decisionPackCacheMaxBytes = 512 * 1024;
 const cliTextFileMaxBytes = 1024 * 1024;
-const changelogPath = new URL("../CHANGELOG.md", import.meta.url);
+const changelogPath = resolveOwnPackageSiblingPath("CHANGELOG.md");
 const cliArgs = process.argv.slice(2);
 
 // #7764: true only when this file is the process entrypoint (`node .../loopover-mcp.js`, incl. via the npm

packages/loopover-mcp/bin/loopover-mcp.ts

@@ -26,15 +26,12 @@
     "access": "public"
   },
   "bin": {
-    "loopover-mcp": "bin/loopover-mcp.js"
+    "loopover-mcp": "dist/bin/loopover-mcp.js"
   },
   "files": [
-    "bin",
-    "lib",
+    "dist",
     "scripts",
     "CHANGELOG.md",
-    "!bin/**/*.ts",
-    "!lib/**/*.ts",
     "!scripts/check-syntax.mjs",
     "!scripts/strip-bin-sourcemap.mjs"
   ],

packages/loopover-mcp/package.json

@@ -19,7 +19,7 @@ function listFiles(dir, extension) {
     .map((entry) => join(dir, entry.name));
 }
 
-const files = [...listFiles("bin", ".js"), ...listFiles("lib", ".js"), ...listFiles("scripts", ".mjs")].sort();
+const files = [...listFiles("dist/bin", ".js"), ...listFiles("dist/lib", ".js"), ...listFiles("scripts", ".mjs")].sort();
 
 const failures = [];
 for (const file of files) {
@@ -38,4 +38,4 @@ if (failures.length > 0) {
   process.exit(1);
 }
 
-console.log(`node --check passed for all ${files.length} files in bin/, lib/, and scripts/.`);
+console.log(`node --check passed for all ${files.length} files in dist/bin/, dist/lib/, and scripts/.`);

packages/loopover-mcp/scripts/check-syntax.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-// Strip the trailing inline sourceMappingURL from compiled bin/*.js after tsc.
+// Strip the trailing inline sourceMappingURL from compiled dist/bin/*.js after tsc.
 //
 // The package tsconfig uses inlineSourceMap so small lib modules stay coverage-remapable without
-// publishing a new *.map file type. For bin/loopover-mcp.js (~6.5k lines) the inline map roughly
+// publishing a new *.map file type. For dist/bin/loopover-mcp.js (~6.5k lines) the inline map roughly
 // doubles the shipped file past LoopOver's patch-less secrets-scan fetch cap (512KB), which made
 // the prior Phase 3 attempt (#7431) fail closed. Bin is subprocess-only tested (mcp-cli harness),
 // so v8 never remaps through this file anyway — stripping the map keeps the published/committed
@@ -12,7 +12,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
-const BIN = join(ROOT, "bin");
+const BIN = join(ROOT, "dist/bin");
 const MARKER = "\n//# sourceMappingURL=";
 
 let stripped = 0;
@@ -26,4 +26,4 @@ for (const entry of readdirSync(BIN, { withFileTypes: true })) {
   stripped += 1;
 }
 
-console.log(`stripped inline sourcemaps from ${stripped} bin/*.js file(s)`);
+console.log(`stripped inline sourcemaps from ${stripped} dist/bin/*.js file(s)`);