From b1a072c5d9e9bff5ad399d4c51a7ce9b2f665cb5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=98yvind=20Raddum=20Berg?= <elacin@gmail.com>
Date: Sun, 30 Aug 2026 22:36:51 +0200
Subject: [PATCH 01/13] scala.js: a test link emits the module kind the build
 declared (#664)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The main link path read `--module-kind`, then the project's `jsKind`. The test
path declared `ScalaJsLinkConfig.Debug` and took its `CommonJSModule` along with
the debug semantics it actually wanted, so a build saying `jsKind: esmodule` had
its tests linked as CommonJS, with no flag able to change it and nothing saying
so.

Debug semantics for a test link stay: nobody wants their tests run through the
optimizer, and the output directory is named after the mode, so this changes
where nothing lands. The module kind is not a semantics choice — it is what the
build declared.

Both paths now derive it through one function, and `runScalaJsTestSuite` is
handed the kind that was linked rather than deriving a second opinion from a
constant. The adapter picks its `Input` from that value, and a NoModule program
loaded as a module — or the reverse — fails before any test runs, so the one
thing it must never be is a guess.

Asserted on the emitted JavaScript, because the suite passed either way: the
constant was consistent, consistently wrong, and a test that checked which
config was passed around would have gone on passing throughout.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../bleep/bsp/MultiWorkspaceBspServer.scala   |  65 ++++++----
 .../scala/bleep/ScalaJsTestModuleKindIT.scala | 114 ++++++++++++++++++
 2 files changed, 157 insertions(+), 22 deletions(-)
 create mode 100644 bleep-tests/src/scala/bleep/ScalaJsTestModuleKindIT.scala

diff --git a/bleep-bsp/src/scala/bleep/bsp/MultiWorkspaceBspServer.scala b/bleep-bsp/src/scala/bleep/bsp/MultiWorkspaceBspServer.scala
index b8843b965..f2fcb441b 100644
--- a/bleep-bsp/src/scala/bleep/bsp/MultiWorkspaceBspServer.scala
+++ b/bleep-bsp/src/scala/bleep/bsp/MultiWorkspaceBspServer.scala
@@ -1850,23 +1850,7 @@ class MultiWorkspaceBspServer(
                 emitSourceMaps = linkOpts.sourceMaps.getOrElse(baseConfig.emitSourceMaps),
                 minify = linkOpts.minify.getOrElse(baseConfig.minify),
                 optimizer = linkOpts.optimize.getOrElse(baseConfig.optimizer),
-                // `--module-kind` first, then the project's own `jsKind`, and only then the constant.
-                //
-                // The project was never consulted: a build declaring `jsKind: esmodule` got a CommonJS link and no flag was needed to cause it, because the
-                // fallback was a hardcoded `CommonJSModule`. That also quietly disarmed the Closure rule below, which skips Closure for ESModule output because
-                // Scala.js rejects the pairing — a yaml-declared ESModule project reached it looking like CommonJS.
-                moduleKind = linkOpts.moduleKind
-                  .map {
-                    case "nomodule" => ScalaJsLinkConfig.ModuleKind.NoModule
-                    case "esmodule" => ScalaJsLinkConfig.ModuleKind.ESModule
-                    case _          => ScalaJsLinkConfig.ModuleKind.CommonJSModule
-                  }
-                  .orElse(project.platform.flatMap(_.jsKind).map {
-                    case model.ModuleKindJS.NoModule       => ScalaJsLinkConfig.ModuleKind.NoModule
-                    case model.ModuleKindJS.CommonJSModule => ScalaJsLinkConfig.ModuleKind.CommonJSModule
-                    case model.ModuleKindJS.ESModule       => ScalaJsLinkConfig.ModuleKind.ESModule
-                  })
-                  .getOrElse(baseConfig.moduleKind)
+                moduleKind = scalaJsModuleKind(project, linkOpts.moduleKind, baseConfig.moduleKind)
               )
               Some(crossName -> TaskDag.LinkPlatform.ScalaJs(sjsVersion, scalaVersion, config))
 
@@ -2390,7 +2374,11 @@ class MultiWorkspaceBspServer(
               .getOrElse(throw new IllegalStateException(s"Scala.js version not found for ${crossName.value}"))
             val scalaVersion =
               project.scala.flatMap(_.version).map(_.scalaVersion).getOrElse(throw new IllegalStateException(s"Scala version not found for ${crossName.value}"))
-            val config = bleep.analysis.ScalaJsLinkConfig.Debug
+            // Debug semantics for a test link are deliberate — nobody wants their tests run through the optimizer — but the module kind is not a semantics
+            // choice, it is what the build declared. `Debug` carries `CommonJSModule`, and taking that wholesale meant a project declaring `jsKind: esmodule`
+            // had its tests linked as CommonJS with nothing to say so.
+            val base = bleep.analysis.ScalaJsLinkConfig.Debug
+            val config = base.copy(moduleKind = scalaJsModuleKind(project, None, base.moduleKind))
             Some(crossName -> TaskDag.LinkPlatform.ScalaJs(sjsVersion, scalaVersion, config))
 
           case (Some(model.PlatformId.Native), true) =>
@@ -2594,7 +2582,14 @@ class MultiWorkspaceBspServer(
                   case (Some(model.PlatformId.Js), true) =>
                     runKotlinJsTestSuite(started, testTask, linkedArtifactOf(testTask.project, linkResult), testEnv, eventQueue, taskKillSignal)
                   case (Some(model.PlatformId.Js), false) =>
-                    runScalaJsTestSuite(started, testTask, classpath, testEnv, linkResult, eventQueue, taskKillSignal)
+                    // Read back off the platform this run's DAG was built with, so the runner is told how the program was emitted rather than deciding for
+                    // itself. A missing entry means a Scala.js test project reached the handler without a link node, which is a broken DAG, not a default.
+                    val moduleKind = platforms.get(testTask.project) match {
+                      case Some(TaskDag.LinkPlatform.ScalaJs(_, _, config)) => config.moduleKind
+                      case other                                            =>
+                        throw new IllegalStateException(s"No Scala.js link platform for test project ${testTask.project.value}, got $other")
+                    }
+                    runScalaJsTestSuite(started, testTask, classpath, testEnv, linkResult, moduleKind, eventQueue, taskKillSignal)
                   case (Some(model.PlatformId.Native), true) =>
                     runKotlinNativeTestSuite(started, testTask, linkedArtifactOf(testTask.project, linkResult), testEnv, eventQueue, taskKillSignal)
                   case (Some(model.PlatformId.Native), false) =>
@@ -3560,6 +3555,31 @@ class MultiWorkspaceBspServer(
   private def nodeBinaryFor(started: Started, project: model.Project): String =
     started.pre.fetchNode(project.platform.flatMap(_.jsNodeVersion).getOrElse(bleep.constants.Node)).toAbsolutePath.toString
 
+  /** The module kind a Scala.js link emits for `project`: an explicit `--module-kind` first, then the project's own `jsKind`, and only then the base
+    * configuration's own default.
+    *
+    * One function for the main link and the test link because there were two, and they disagreed. The test path declared `ScalaJsLinkConfig.Debug` and took its
+    * `CommonJSModule` along with the debug semantics it actually wanted, so a build declaring `jsKind: esmodule` had its tests linked as CommonJS and no flag
+    * could change it. The test path passes `None` for the flag — `bleep test` accepts no link options — and so always gets what the build declared.
+    */
+  private def scalaJsModuleKind(
+      project: model.Project,
+      fromFlag: Option[String],
+      fallback: ScalaJsLinkConfig.ModuleKind
+  ): ScalaJsLinkConfig.ModuleKind =
+    fromFlag
+      .map {
+        case "nomodule" => ScalaJsLinkConfig.ModuleKind.NoModule
+        case "esmodule" => ScalaJsLinkConfig.ModuleKind.ESModule
+        case _          => ScalaJsLinkConfig.ModuleKind.CommonJSModule
+      }
+      .orElse(project.platform.flatMap(_.jsKind).map {
+        case model.ModuleKindJS.NoModule       => ScalaJsLinkConfig.ModuleKind.NoModule
+        case model.ModuleKindJS.CommonJSModule => ScalaJsLinkConfig.ModuleKind.CommonJSModule
+        case model.ModuleKindJS.ESModule       => ScalaJsLinkConfig.ModuleKind.ESModule
+      })
+      .getOrElse(fallback)
+
   /** Run a Scala.js test suite: link → run via Node.js, emit events to DAG queue. */
   private def runScalaJsTestSuite(
       started: Started,
@@ -3567,6 +3587,7 @@ class MultiWorkspaceBspServer(
       classpath: List[Path],
       testEnv: Map[String, String],
       linkResult: Option[TaskDag.LinkResult],
+      moduleKind: ScalaJsLinkConfig.ModuleKind,
       eventQueue: Queue[IO, Option[TaskDag.DagEvent]],
       killSignal: Deferred[IO, KillReason]
   ): IO[TaskDag.TaskResult] = {
@@ -3574,8 +3595,8 @@ class MultiWorkspaceBspServer(
     val sjsVersion = project.platform.flatMap(_.jsVersion).getOrElse {
       throw new IllegalStateException(s"Scala.js version not found for ${testTask.project.value}")
     }
-    // No Scala version needed here any more: it was only ever used to describe the link this function used to run itself.
-    val linkConfig = bleep.analysis.ScalaJsLinkConfig.Debug
+    // Taken from the link the DAG ran rather than declared again here. The adapter picks its `Input` from this — a NoModule program loaded as a module, or the
+    // reverse, fails before any test runs — so the one thing it must never be is a second opinion about how the program was emitted.
 
     for {
       startTs <- IO.realTime.map(_.toMillis)
@@ -3598,7 +3619,7 @@ class MultiWorkspaceBspServer(
               ScalaJsTestRunner
                 .runTests(
                   mainModule,
-                  linkConfig.moduleKind,
+                  moduleKind,
                   suites,
                   eventHandler,
                   ScalaJsTestRunner.NodeEnvironment.Node,
diff --git a/bleep-tests/src/scala/bleep/ScalaJsTestModuleKindIT.scala b/bleep-tests/src/scala/bleep/ScalaJsTestModuleKindIT.scala
new file mode 100644
index 000000000..638324a68
--- /dev/null
+++ b/bleep-tests/src/scala/bleep/ScalaJsTestModuleKindIT.scala
@@ -0,0 +1,114 @@
+package bleep
+
+import java.nio.file.{Files, Path}
+import scala.jdk.CollectionConverters.*
+
+/** A Scala.js test link has to emit the module kind the build declared.
+  *
+  * The link `bleep test` runs and the link `bleep link` runs used to disagree about that. The main path read `--module-kind`, then the project's `jsKind`; the
+  * test path declared `ScalaJsLinkConfig.Debug` and took its `CommonJSModule` along with the debug semantics it actually wanted. So a build saying `jsKind:
+  * esmodule` had its tests linked as CommonJS, with no flag able to change it and nothing reporting the substitution.
+  *
+  * Asserted against the emitted JavaScript rather than the configuration, for the same reason [[ScalaJsReleaseLinkIT]] is: a test that checks which constant
+  * was passed around would have gone on passing throughout, because the constant was consistent — consistently wrong.
+  */
+class ScalaJsTestModuleKindIT extends IntegrationTestHarness {
+
+  private val mytest = model.CrossProjectName(model.ProjectName("mytest"), None)
+
+  private def yamlFor(jsKind: String): String =
+    s"""projects:
+       |  mytest:
+       |    dependencies:
+       |      - org.scalameta::munit:${model.Versions.Munit}
+       |    isTestProject: true
+       |    platform:
+       |      name: js
+       |      jsVersion: ${model.Versions.ScalaJs1}
+       |      jsNodeVersion: ${model.Versions.Node}
+       |      jsKind: $jsKind
+       |    scala:
+       |      version: ${model.Versions.Scala3}
+       |""".stripMargin
+
+  /** A passing suite, plus a top-level export.
+    *
+    * The export is what makes the module kind visible at all. Scala.js emits a program with no exported members almost identically under CommonJS and under
+    * ESModule — the difference is in how exports leave the module, so a fixture with none has nothing to tell them apart by, and the issue reporting this said
+    * as much.
+    */
+  private val Source =
+    """package example
+      |
+      |import scala.scalajs.js.annotation.JSExportTopLevel
+      |
+      |object Exports {
+      |  @JSExportTopLevel("greet")
+      |  def greet(name: String): String = s"Hello, $name!"
+      |}
+      |
+      |class ModuleKindSuite extends munit.FunSuite {
+      |  test("greets") { assertEquals(Exports.greet("world"), "Hello, world!") }
+      |}
+      |""".stripMargin
+
+  /** The linked test program, wherever under `.bleep` the test run put it. Walked rather than reconstructed from the path convention, so a change to the layout
+    * surfaces as a different file instead of as this test quietly finding nothing.
+    */
+  private def linkedTestJs(ws: Workspace): Path = {
+    val root = ws.root.resolve(".bleep")
+    val candidates =
+      Files
+        .walk(root)
+        .iterator()
+        .asScala
+        .filter(p => p.getFileName.toString == "main.js")
+        .toList
+    candidates match {
+      case one :: Nil => one
+      case Nil        => fail(s"no linked main.js under ${ws.root}")
+      case many       => fail(s"expected one linked main.js, found ${many.size}: ${many.mkString(", ")}")
+    }
+  }
+
+  private def runTests(ws: Workspace): Unit = {
+    val (_, commands, _) = ws.start()
+    commands.test(List(mytest), watch = false, only = None, exclude = None, includeTags = None, excludeTags = None)
+  }
+
+  integrationTest("a test link emits the ES module the build declared") { ws =>
+    ws.yaml(yamlFor("esmodule"))
+    ws.file("mytest/src/scala/example/ModuleKindSuite.scala", Source)
+
+    runTests(ws)
+
+    val js = Files.readString(linkedTestJs(ws))
+    // An ES module says goodbye to its exports with an `export` statement; CommonJS assigns them onto `exports`. Both markers are checked, because asserting
+    // only the absence of the wrong one would also pass for a linked file that exported nothing at all.
+    assert(
+      js.contains("export {") || js.linesIterator.exists(_.trim.startsWith("export ")),
+      s"the test link did not emit an ES module, so `jsKind: esmodule` never reached it. Tail:\n${js.takeRight(400)}"
+    )
+    assert(
+      !js.contains("exports.greet"),
+      s"the test link emitted CommonJS exports despite `jsKind: esmodule`. Tail:\n${js.takeRight(400)}"
+    )
+    succeed
+  }
+
+  integrationTest("a test link emits CommonJS when the build declares it") { ws =>
+    ws.yaml(yamlFor("commonjs"))
+    ws.file("mytest/src/scala/example/ModuleKindSuite.scala", Source)
+
+    runTests(ws)
+
+    val js = Files.readString(linkedTestJs(ws))
+    // The other direction, and the reason this pair exists: `commonjs` was what the test link produced no matter what, so a test asserting only the ESModule
+    // case would leave "does it still honour the declaration when the declaration is the old constant" unchecked.
+    assert(
+      js.contains("exports.greet"),
+      s"the test link did not emit a CommonJS module despite `jsKind: commonjs`. Tail:\n${js.takeRight(400)}"
+    )
+    succeed
+  }
+}

From 32e558410ed66abc30a26a369645ea323e029bd3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=98yvind=20Raddum=20Berg?= <elacin@gmail.com>
Date: Sun, 30 Aug 2026 22:37:03 +0200
Subject: [PATCH 02/13] run: a program's own exit code is its answer, not a
 bleep failure (#670)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`bleep <script>` ran everything through `cli.apply`, which throws on any
non-zero exit with the whole command line in the message. For git or gpg that is
right — something went wrong and the reader needs the command to diagnose it.
For a script that exits 1 to report a problem it has already described, it means
the report is followed by the java path, two `--add-opens` flags and a
hundred-jar classpath on one line, and the reader stops looking for the two
readable lines above it. The code the script chose was replaced by bleep's flat
1 as well.

`cli.exitCode` hands the code back instead of throwing; `cli.apply` is that plus
the throw, so every existing caller keeps the diagnosis it had. `bleep run` and
`bleep <script>` — JVM, node and native alike — use the former and return
`BleepException.SubprocessExit`, which renders as one line and carries the code
through to bleep's own exit status.

Covered through `JvmRunner.Forked`, which the ITs otherwise never touch: the
harness swaps in `InProcess`, and a `System.exit` there would take the test JVM
down with it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 bleep-cli/src/scala/bleep/Main.scala          | 32 +++++++--
 bleep-core/src/scala/bleep/ExitCode.scala     |  8 +--
 bleep-core/src/scala/bleep/JvmRunner.scala    |  6 +-
 bleep-core/src/scala/bleep/bootstrap.scala    |  5 +-
 bleep-core/src/scala/bleep/cli.scala          | 69 ++++++++++++------
 bleep-core/src/scala/bleep/commands/Run.scala | 12 ++--
 .../src/scala/bleep/BleepException.scala      | 12 ++++
 .../src/scala/bleep/ScriptExitCodeIT.scala    | 70 +++++++++++++++++++
 8 files changed, 171 insertions(+), 43 deletions(-)
 create mode 100644 bleep-tests/src/scala/bleep/ScriptExitCodeIT.scala

diff --git a/bleep-cli/src/scala/bleep/Main.scala b/bleep-cli/src/scala/bleep/Main.scala
index 9ec259d3a..566143be4 100644
--- a/bleep-cli/src/scala/bleep/Main.scala
+++ b/bleep-cli/src/scala/bleep/Main.scala
@@ -1606,12 +1606,25 @@ object Main {
         }
       case Right(cmd) =>
         Try(runCommand(cmd)) match {
-          case Failure(th)        => fatal("command failed unexpectedly! This really shouldn't happen. Please report.", logger, th)
-          case Success(Left(th))  => fatal("command failed", logger, th)
+          case Failure(th)        => failed("command failed unexpectedly! This really shouldn't happen. Please report.", logger, th)
+          case Success(Left(th))  => failed("command failed", logger, th)
           case Success(Right(())) => ExitCode.Success
         }
     }
 
+  /** [[fatal]], except that a program bleep launched on the user's behalf is not a bleep failure.
+    *
+    * A script that exits 1 to signal something it has already reported gets one line and its own exit code, so `bleep <script>` answers what the script
+    * answered. Everything else keeps the old treatment. See [[BleepException.SubprocessExit]].
+    */
+  private def failed(context: String, logger: Logger, th: Throwable): ExitCode =
+    th match {
+      case sub: BleepException.SubprocessExit =>
+        logger.error(sub.message)
+        ExitCode.FromSubprocess(sub.code)
+      case other => fatal(context, logger, other)
+    }
+
   /** Scripts receive their trailing arguments verbatim, including tokens that start with `--`.
     *
     * decline's `Opts.arguments` rejects anything that looks like an option (`--clients` becomes "Unexpected option: --clients"), so before parsing we insert
@@ -1672,21 +1685,28 @@ object Main {
           Try(cmd.run(startedWithLogger)) match {
             case Failure(th: BleepException) if machineOutput =>
               CommandResult.print(CommandResult.failure(th))
-              ExitCode.Failure
+              exitCodeOf(th)
             case Failure(th) if machineOutput =>
               CommandResult.print(CommandResult.Failure(th.getMessage))
               ExitCode.Failure
-            case Failure(th)                        => fatal("command failed unexpectedly! This really shouldn't happen. Please report.", logger, th)
+            case Failure(th)                        => failed("command failed unexpectedly! This really shouldn't happen. Please report.", logger, th)
             case Success(Left(th)) if machineOutput =>
               CommandResult.print(CommandResult.failure(th))
-              ExitCode.Failure
-            case Success(Left(th))  => fatal("command failed", logger, th)
+              exitCodeOf(th)
+            case Success(Left(th))  => failed("command failed", logger, th)
             case Success(Right(())) => ExitCode.Success
           }
         }
     }
   }
 
+  /** The code bleep exits with for an already-reported failure: a launched program's own code when it chose one, plain failure otherwise. */
+  private def exitCodeOf(th: BleepException): ExitCode =
+    th match {
+      case sub: BleepException.SubprocessExit => ExitCode.FromSubprocess(sub.code)
+      case _                                  => ExitCode.Failure
+    }
+
   /** Check if restArgs request machine-readable output (json or raw), logs should go to stderr. */
   private def hasMachineOutput(restArgs: List[String]): Boolean =
     restArgs.exists {
diff --git a/bleep-core/src/scala/bleep/ExitCode.scala b/bleep-core/src/scala/bleep/ExitCode.scala
index 93660c193..22fdeef39 100644
--- a/bleep-core/src/scala/bleep/ExitCode.scala
+++ b/bleep-core/src/scala/bleep/ExitCode.scala
@@ -2,13 +2,13 @@ package bleep
 
 sealed abstract class ExitCode(val value: Int) {
   final def andThen(f: => ExitCode): ExitCode =
-    this match {
-      case ExitCode.Success => f
-      case ExitCode.Failure => this
-    }
+    if (value == 0) f else this
 }
 
 object ExitCode {
   case object Success extends ExitCode(0)
   case object Failure extends ExitCode(1)
+
+  /** A program bleep launched ran to completion and chose this code, so bleep exits with it too. See [[BleepException.SubprocessExit]]. */
+  case class FromSubprocess(code: Int) extends ExitCode(code)
 }
diff --git a/bleep-core/src/scala/bleep/JvmRunner.scala b/bleep-core/src/scala/bleep/JvmRunner.scala
index 0ee28eb77..4092e7507 100644
--- a/bleep-core/src/scala/bleep/JvmRunner.scala
+++ b/bleep-core/src/scala/bleep/JvmRunner.scala
@@ -180,7 +180,9 @@ object JvmRunner {
     val outMode = if (raw) cli.Out.Raw else cli.Out.ViaLogger(logger)
     val inMode = if (raw) cli.In.Attach else cli.In.No
     val command = jvmRunCommand.cmd(resolvedJvm, jvmOptions, classpath, mainClass, args)
-    cli("run", cwd, command, logger = logger, out = outMode, in = inMode, env = env).discard()
-    Right(())
+    // `cli.exitCode`, not `cli.apply`: this is the user's own program, and its exit code is its answer rather than a bleep failure to explain with a launch
+    // command. See BleepException.SubprocessExit.
+    val (code, _) = cli.exitCode("run", cwd, command, logger = logger, out = outMode, in = inMode, env = env)
+    if (code == 0) Right(()) else Left(new BleepException.SubprocessExit(code, mainClass))
   }
 }
diff --git a/bleep-core/src/scala/bleep/bootstrap.scala b/bleep-core/src/scala/bleep/bootstrap.scala
index e78372966..238128391 100644
--- a/bleep-core/src/scala/bleep/bootstrap.scala
+++ b/bleep-core/src/scala/bleep/bootstrap.scala
@@ -35,10 +35,7 @@ object bootstrap {
         }
       }
 
-    exitCode match {
-      case ExitCode.Success => ()
-      case ExitCode.Failure => System.exit(exitCode.value)
-    }
+    if (exitCode.value != 0) System.exit(exitCode.value)
   }
 
   def from(
diff --git a/bleep-core/src/scala/bleep/cli.scala b/bleep-core/src/scala/bleep/cli.scala
index 5733d26ae..4e5f2e7f2 100644
--- a/bleep-core/src/scala/bleep/cli.scala
+++ b/bleep-core/src/scala/bleep/cli.scala
@@ -44,6 +44,19 @@ object cli {
     }
   }
 
+  /** make sure we break out of x86_64 jail when running programs when possible */
+  private def patchCmd(cmd: List[String]): List[String] =
+    OsArch.current match {
+      case OsArch.MacosArm64(freedFromJail) if freedFromJail => List("arch", "-arch", "arm64") ++ cmd
+      case _                                                 => cmd
+    }
+
+  /** Run `cmd` and throw when it exits non-zero, with the whole command line in the message.
+    *
+    * This is right for the commands bleep runs for its own purposes — git, gpg, sbt, an installer — where a non-zero exit is something that went wrong and the
+    * reader needs the command to diagnose it. It is wrong for a program bleep launched on the user's behalf, whose exit code is its own answer: use
+    * [[exitCode]] there, and see the note on [[BleepException.SubprocessExit]].
+    */
   def apply(
       action: String,
       cwd: Path,
@@ -53,11 +66,35 @@ object cli {
       in: In = In.No,
       env: List[(String, String)] = Nil
   ): WrittenLines = {
-    // make sure we break out of x86_64 jail when running programs when possible
-    val patchedCmd = OsArch.current match {
-      case OsArch.MacosArm64(freedFromJail) if freedFromJail => List("arch", "-arch", "arm64") ++ cmd
-      case _                                                 => cmd
+    val (code, lines) = exitCode(action, cwd, cmd, logger, out, in, env)
+    if (code == 0) lines
+    else {
+      val cmdStr = patchCmd(cmd).mkString(" ")
+      // Include captured stderr so callers can pattern-match on the underlying error (e.g. SnapshotTest
+      // retries on git's `index.lock` collisions). Without this, the exception message has no signal
+      // beyond the exit code.
+      val stderr = lines.stderr
+      val stderrSuffix = if (stderr.nonEmpty) s"\n${stderr.mkString("\n")}" else ""
+      throw new BleepException.Text(s"Failed external command '$action' with exit code $code in $cwd: $cmdStr$stderrSuffix")
     }
+  }
+
+  /** Run `cmd` and hand back its exit code rather than throwing.
+    *
+    * Every caller who launches a program the *user* asked for wants this one. A script that exits 1 to report a problem it has already described has not failed
+    * to run, and answering it with bleep's own launch command — the java path, the `--add-opens` flags, a classpath of a hundred jars on one line — buries the
+    * report the script just printed.
+    */
+  def exitCode(
+      action: String,
+      cwd: Path,
+      cmd: List[String],
+      logger: Logger,
+      out: Out,
+      in: In,
+      env: List[(String, String)]
+  ): (Int, WrittenLines) = {
+    val patchedCmd = patchCmd(cmd)
 
     val process = Process {
       val builder = new java.lang.ProcessBuilder(patchedCmd*)
@@ -98,28 +135,18 @@ object cli {
           )
       }
 
-    val exitCode = process.run(processIO).exitValue()
+    val code = process.run(processIO).exitValue()
 
     val ctxLogger = logger
       .withContext("action", action)
       .withContext("cwd", cwd)
       .withContext("cmd", patchedCmd)
       .withContext("env", env)
-      .withContext("exitCode", exitCode)
-
-    exitCode match {
-      case 0 =>
-        ctxLogger.debug("Command ran successfully")
-        WrittenLines(output.result())
-      case n =>
-        ctxLogger.debug("Failed command details")
-        val cmdStr = patchedCmd.mkString(" ")
-        // Include captured stderr so callers can pattern-match on the underlying error (e.g. SnapshotTest
-        // retries on git's `index.lock` collisions). Without this, the exception message has no signal
-        // beyond the exit code.
-        val stderr = output.result().collect { case WrittenLine.StdErr(line) => line }
-        val stderrSuffix = if (stderr.nonEmpty) s"\n${stderr.mkString("\n")}" else ""
-        throw new BleepException.Text(s"Failed external command '$action' with exit code $n in $cwd: $cmdStr$stderrSuffix")
-    }
+      .withContext("exitCode", code)
+
+    if (code == 0) ctxLogger.debug("Command ran successfully")
+    else ctxLogger.debug("Failed command details")
+
+    (code, WrittenLines(output.result()))
   }
 }
diff --git a/bleep-core/src/scala/bleep/commands/Run.scala b/bleep-core/src/scala/bleep/commands/Run.scala
index b00d66d12..38bb01142 100644
--- a/bleep-core/src/scala/bleep/commands/Run.scala
+++ b/bleep-core/src/scala/bleep/commands/Run.scala
@@ -135,7 +135,7 @@ case class Run(
       val outMode = if (raw) cli.Out.Raw else cli.Out.ViaLogger(started.logger)
       val inMode = if (raw) cli.In.Attach else cli.In.No
       val command = List("node", jsOutput.toAbsolutePath.toString) ++ args
-      cli(
+      val (code, _) = cli.exitCode(
         "run",
         started.pre.buildPaths.cwd,
         command,
@@ -143,8 +143,8 @@ case class Run(
         out = outMode,
         in = inMode,
         env = runEnv(started)
-      ).discard()
-      Right(())
+      )
+      if (code == 0) Right(()) else Left(new BleepException.SubprocessExit(code, project.value))
     }
   }
 
@@ -167,7 +167,7 @@ case class Run(
         val outMode = if (raw) cli.Out.Raw else cli.Out.ViaLogger(started.logger)
         val inMode = if (raw) cli.In.Attach else cli.In.No
         val command = List(binaryPath.toAbsolutePath.toString) ++ args
-        cli(
+        val (code, _) = cli.exitCode(
           "run",
           started.pre.buildPaths.cwd,
           command,
@@ -175,8 +175,8 @@ case class Run(
           out = outMode,
           in = inMode,
           env = runEnv(started)
-        ).discard()
-        Right(())
+        )
+        if (code == 0) Right(()) else Left(new BleepException.SubprocessExit(code, project.value))
     }
   }
 }
diff --git a/bleep-model/src/scala/bleep/BleepException.scala b/bleep-model/src/scala/bleep/BleepException.scala
index 601f90a97..0eb800407 100644
--- a/bleep-model/src/scala/bleep/BleepException.scala
+++ b/bleep-model/src/scala/bleep/BleepException.scala
@@ -18,6 +18,18 @@ abstract class BleepException(
     with Serializable
 
 object BleepException {
+
+  /** A program bleep launched on the user's behalf ran to completion and chose a non-zero exit code.
+    *
+    * Not a bleep failure, and rendered as such: one line naming what exited and with what code, and bleep exits with the same code so a caller of `bleep
+    * <script>` sees the script's own answer. The launch command is deliberately absent — a script that exits 1 to report a problem has already printed the
+    * report, and burying it under a java path, two `--add-opens` flags and a hundred-jar classpath is how a reader stops looking for it.
+    *
+    * A command that could not be launched, or that bleep runs for its own purposes, is a different thing and still gets the whole command line: see
+    * [[bleep.cli.apply]].
+    */
+  class SubprocessExit(val code: Int, what: String) extends BleepException(s"$what exited with code $code")
+
   class BuildNotFound(cwd: Path) extends BleepException(s"Couldn't find ${BuildLoader.BuildFileName} in directories in or above $cwd")
 
   class TargetFolderNotDetermined(projectName: model.CrossProjectName)
diff --git a/bleep-tests/src/scala/bleep/ScriptExitCodeIT.scala b/bleep-tests/src/scala/bleep/ScriptExitCodeIT.scala
new file mode 100644
index 000000000..432ccdfbe
--- /dev/null
+++ b/bleep-tests/src/scala/bleep/ScriptExitCodeIT.scala
@@ -0,0 +1,70 @@
+package bleep
+
+/** A program bleep launched exiting non-zero is that program's answer, not a bleep failure to explain.
+  *
+  * What it used to get instead was `Failed external command 'run' with exit code 1 in <dir>: <the whole java launch command>` — the java path, the
+  * `--add-opens` flags and a classpath of every jar on one line. A script that exits 1 to report a problem it has already described in two readable lines then
+  * has that report pushed off the screen by bleep's own launch line, and the exit code it chose is replaced by bleep's flat 1.
+  *
+  * Run through [[JvmRunner.Forked]] on purpose. The harness swaps in [[JvmRunner.InProcess]] for every other test, which cannot host a `System.exit` at all —
+  * it would take the test JVM down with it — so the codepath this covers is only reachable by asking for a real fork.
+  */
+class ScriptExitCodeIT extends IntegrationTestHarness {
+
+  private val a = model.CrossProjectName(model.ProjectName("a"), None)
+
+  private val Yaml =
+    """projects:
+      |  a:
+      |    platform:
+      |      name: jvm
+      |      mainClass: test.Main
+      |    scala:
+      |      version: 3.4.2
+      |""".stripMargin
+
+  private def exitingMain(code: Int): String =
+    s"""package test
+       |object Main {
+       |  def main(args: Array[String]): Unit = {
+       |    println("the report the program wrote")
+       |    System.exit($code)
+       |  }
+       |}""".stripMargin
+
+  private def runForked(ws: Workspace): Either[BleepException, Unit] = {
+    val (started, _, _) = ws.start()
+    commands
+      .Run(a, None, args = Nil, raw = false, watch = false, commands.CommonBuildOpts(commands.DisplayMode.NoTui, flamegraph = false, cancel = false))
+      .run(started.withJvmRunner(JvmRunner.Forked))
+  }
+
+  integrationTest("a non-zero exit is reported in one line, and the code survives") { ws =>
+    ws.yaml(Yaml)
+    ws.file("a/src/scala/Main.scala", exitingMain(3))
+
+    runForked(ws) match {
+      case Right(())                                => fail("a program that exited 3 was reported as success")
+      case Left(sub: BleepException.SubprocessExit) =>
+        assert(sub.code == 3, s"the program chose 3, bleep reported ${sub.code}")
+        // The whole point: what the reader is shown next to their program's own output. Two markers, because either one alone would have been satisfied by
+        // some intermediate wording — a message with no classpath but still built from the launch command, or one that dropped the command and the code too.
+        assert(!sub.message.contains(".jar"), s"the launch classpath is back in the message:\n${sub.message}")
+        assert(!sub.message.contains("--add-opens"), s"the launch flags are back in the message:\n${sub.message}")
+        assert(sub.message.contains("3"), s"the message does not say which code the program chose:\n${sub.message}")
+        succeed
+      case Left(other) =>
+        fail(s"expected a SubprocessExit, got ${other.getClass.getName}: ${other.message}")
+    }
+  }
+
+  integrationTest("a zero exit is still a success") { ws =>
+    ws.yaml(Yaml)
+    ws.file("a/src/scala/Main.scala", exitingMain(0))
+
+    runForked(ws) match {
+      case Right(())   => succeed
+      case Left(other) => fail(s"a program that exited 0 was reported as failure: ${other.message}")
+    }
+  }
+}

From dcac1a11ffe350bf7aa2f2da1b7937cfe4808521 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=98yvind=20Raddum=20Berg?= <elacin@gmail.com>
Date: Sun, 30 Aug 2026 22:37:14 +0200
Subject: [PATCH 03/13] scripts: Commands gains link, and compile reports
 whether it did anything (#663, #671)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two gaps in the surface a build script reaches, both reported against a real
build.

`Commands` declared no `link`, so a script packaging linked JavaScript into a
jar had to shell out to the `bleep` command line and pay the start-up cost a
second time. It takes the same `LinkOptions` the command line does.

`compile` returned `Unit`, so a caller could not tell a compile that rebuilt
everything from one that found nothing to do. bleep already knows: the server
reports a `CompileReason` per project and `UpToDate` is the one that means the
compiler ran and found nothing. That reason reached the client and was dropped
on the floor with a comment saying it was purely informational. It is now
accumulated, and `compile` hands back the `BuildSummary` the run produced —
verdict unchanged, so a caller who only wants "did it work" can go on ignoring
it.

`BuildSummary.noOp` is BSP's `CompileReport.noOp` computed from that. A run in
which nothing compiled at all is deliberately not a no-op: there was no compile
to be a no-op about, and answering true would let a deploy skip on the strength
of a run that never looked.

Mirrored on the Java scripting API, which is the other half of the same surface
— with a `CompileReport` narrower than the summary it comes from, since
`BuildSummary` changes shape whenever the build display does and a published
interface should not.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../analysis/BuildStateReducerTest.scala      | 40 +++++++++
 bleep-core/src/scala/bleep/Commands.scala     | 32 +++++--
 .../scala/bleep/commands/ReactiveBsp.scala    | 30 +++++--
 .../src/scala/bleep/javaapi/JCommands.scala   | 44 ++++++++--
 .../scala/bleep/testing/BuildDisplay.scala    | 14 +++
 .../src/scala/bleep/testing/BuildState.scala  | 16 +++-
 .../src/scala/bleep/ScriptCommandsIT.scala    | 86 +++++++++++++++++++
 .../src/main/java/bleepscript/Commands.java   | 19 +++-
 .../main/java/bleepscript/CompileReport.java  | 28 ++++++
 .../main/java/bleepscript/LinkOptions.java    | 71 +++++++++++++++
 docs/concepts/bleep-scripts.mdx               | 11 +++
 11 files changed, 367 insertions(+), 24 deletions(-)
 create mode 100644 bleep-tests/src/scala/bleep/ScriptCommandsIT.scala
 create mode 100644 bleepscript/src/main/java/bleepscript/CompileReport.java
 create mode 100644 bleepscript/src/main/java/bleepscript/LinkOptions.java

diff --git a/bleep-bsp-tests/src/scala/bleep/analysis/BuildStateReducerTest.scala b/bleep-bsp-tests/src/scala/bleep/analysis/BuildStateReducerTest.scala
index e38e2485f..43addf778 100644
--- a/bleep-bsp-tests/src/scala/bleep/analysis/BuildStateReducerTest.scala
+++ b/bleep-bsp-tests/src/scala/bleep/analysis/BuildStateReducerTest.scala
@@ -214,4 +214,44 @@ class BuildStateReducerTest extends AnyFunSuite with Matchers {
     state.runningSuites shouldBe empty
     state.runningTests shouldBe empty
   }
+
+  // ==========================================================================
+  // noOp — "did anything actually recompile"
+  // ==========================================================================
+
+  private def compiled(project: String, reason: bleep.bsp.protocol.CompileReason): Seq[BuildEvent] =
+    Seq(
+      BuildEvent.CompileStarted(cpn(project), ts),
+      BuildEvent.CompilationReason(cpn(project), reason, totalFiles = 1, invalidatedFiles = Nil, changedDependencies = Nil, ts + 1),
+      BuildEvent.CompileFinished(
+        cpn(project),
+        bleep.bsp.protocol.CompileStatus.Success,
+        durationMs = 5,
+        timestamp = ts + 2,
+        diagnostics = Nil,
+        skippedBecause = None
+      )
+    )
+
+  private def summaryOf(events: Seq[BuildEvent]): BuildSummary =
+    events.foldLeft(BuildState.empty)(BuildStateReducer.reduce).toSummary(durationMs = 0, wasCancelled = false)
+
+  test("noOp: every compile up to date") {
+    val summary = summaryOf(compiled("a", bleep.bsp.protocol.CompileReason.UpToDate) ++ compiled("b", bleep.bsp.protocol.CompileReason.UpToDate))
+    summary.upToDateProjects shouldBe List(cpn("a"), cpn("b"))
+    summary.noOp shouldBe true
+  }
+
+  test("noOp: one project recompiled is enough to make the run not a no-op") {
+    // The asymmetry is the point. A caller uses this to decide whether it may skip a deploy, so a single project that really compiled has to outweigh any
+    // number that did not.
+    val summary = summaryOf(compiled("a", bleep.bsp.protocol.CompileReason.UpToDate) ++ compiled("b", bleep.bsp.protocol.CompileReason.Incremental))
+    summary.upToDateProjects shouldBe List(cpn("a"))
+    summary.noOp shouldBe false
+  }
+
+  test("noOp: a run in which nothing compiled is not a no-op") {
+    // There was no compile to be a no-op about. Answering true here would tell a deploy script it may skip on the strength of a run that never looked.
+    summaryOf(Nil).noOp shouldBe false
+  }
 }
diff --git a/bleep-core/src/scala/bleep/Commands.scala b/bleep-core/src/scala/bleep/Commands.scala
index 5c3830744..3be163723 100644
--- a/bleep-core/src/scala/bleep/Commands.scala
+++ b/bleep-core/src/scala/bleep/Commands.scala
@@ -1,6 +1,7 @@
 package bleep
 
-import bleep.commands.{Publish, PublishLocal, PublishSonatype}
+import bleep.commands.{LinkOptions, Publish, PublishLocal, PublishSonatype}
+import bleep.testing.BuildSummary
 import cats.data.NonEmptyList
 
 class Commands(started: Started) {
@@ -17,11 +18,30 @@ class Commands(started: Started) {
   def clean(projects: List[model.CrossProjectName]): Unit =
     force(commands.Clean(projects.toArray))
 
-  def compile(projects: List[model.CrossProjectName], watch: Boolean = false): Unit =
-    force(
-      commands.ReactiveBsp
-        .compile(watch, projects.toArray, commands.DisplayMode.NoTui, flamegraph = false, cancel = false, diffBase = None, diffOutput = OutputMode.Text)
-    )
+  /** Compile `projects`, returning what the run reported.
+    *
+    * A failed compile still throws, so a caller who only wants "did it work" can go on ignoring the result. The summary is there for the caller who needs to
+    * know more than that — [[bleep.testing.BuildSummary.noOp]] answers "did anything actually recompile", which is the signal a deploy step needs to skip
+    * itself when the previous run already produced the same artifacts.
+    *
+    * Under `watch = true` there is no single run to summarise, so this returns [[bleep.testing.BuildSummary.empty]] when the watch ends.
+    */
+  def compile(projects: List[model.CrossProjectName], watch: Boolean = false): BuildSummary = {
+    val cmd = commands.ReactiveBsp
+      .compile(watch, projects.toArray, commands.DisplayMode.NoTui, flamegraph = false, cancel = false, diffBase = None, diffOutput = OutputMode.Text)
+    if (watch) {
+      force(cmd)
+      BuildSummary.empty
+    } else cmd.runReportingSummary(started).orThrow
+  }
+
+  /** Link `projects` — Scala.js, Scala Native, Kotlin/JS or Kotlin/Native — the way `bleep link` does.
+    *
+    * [[bleep.commands.LinkOptions.Debug]] and [[bleep.commands.LinkOptions.Release]] are the two a caller usually wants; the rest of the fields map one to one
+    * onto the command line's flags.
+    */
+  def link(projects: List[model.CrossProjectName], options: LinkOptions, watch: Boolean = false): Unit =
+    force(commands.ReactiveBsp.link(watch, projects.toArray, commands.DisplayMode.NoTui, options, flamegraph = false, cancel = false))
 
   def run(
       project: model.CrossProjectName,
diff --git a/bleep-core/src/scala/bleep/commands/ReactiveBsp.scala b/bleep-core/src/scala/bleep/commands/ReactiveBsp.scala
index a25cf26e3..be45ad333 100644
--- a/bleep-core/src/scala/bleep/commands/ReactiveBsp.scala
+++ b/bleep-core/src/scala/bleep/commands/ReactiveBsp.scala
@@ -67,10 +67,23 @@ case class ReactiveBsp(
 
   override def run(started: Started): Either[BleepException, Unit] =
     prepareDiffRun(started).flatMap { diffRun =>
-      if (watch) WatchMode.run(started, s => TransitiveProjects(s.build, projects))(s => runOnce(s, diffRun))
-      else runOnce(started, diffRun)
+      if (watch) WatchMode.run(started, s => TransitiveProjects(s.build, projects))(s => runOnce(s, diffRun).map(_ => ()))
+      else runOnce(started, diffRun).map(_ => ())
     }
 
+  /** [[run]], handing back the summary the run produced instead of discarding it.
+    *
+    * The verdict is unchanged: a failed build is still a `Left`, so a caller that only wants "did it work" can keep ignoring the value. What the summary adds
+    * is everything the run already knew and had nowhere to put — which projects were up to date, how long each phase took, what compiled. `bleep.Commands` uses
+    * it for [[bleep.testing.BuildSummary.noOp]].
+    *
+    * Not offered under `--watch`: a watch has one summary per cycle and no last one, so there is nothing honest to return.
+    */
+  private[bleep] def runReportingSummary(started: Started): Either[BleepException, BuildSummary] = {
+    require(!watch, "runReportingSummary has no single summary to return under --watch")
+    prepareDiffRun(started).flatMap(diffRun => runOnce(started, diffRun))
+  }
+
   /** Resolve and validate `--diff` BEFORE anything runs: an explicit id must exist in this workspace's store and mode-match the command; bare `--diff` must
     * find a same-mode entry. Resolving up front fails fast (never waste a compile on a doomed diff) and pins the base transcript, so a concurrent client
     * writing entries mid-run cannot shift what "previous" meant.
@@ -133,7 +146,7 @@ case class ReactiveBsp(
       }
     }
 
-  private[bleep] def runOnce(started: Started, diffRun: Option[ReactiveBsp.DiffRun]): Either[BleepException, Unit] = {
+  private[bleep] def runOnce(started: Started, diffRun: Option[ReactiveBsp.DiffRun]): Either[BleepException, BuildSummary] = {
     // The base THIS cycle diffs against, captured before the run: fixed bases were resolved up front, a rolling base is whatever the previous cycle recorded.
     // None while a rolling watch has no history yet — that cycle renders plain output.
     val diffCycleBase: Option[Transcript] = diffRun.flatMap {
@@ -172,7 +185,8 @@ case class ReactiveBsp(
           s"No projects to $modeLabel after --only-tag ${includeTags.mkString(",")}. Candidates were: ${candidateProjects.toList.map(_.value).sorted.mkString(", ")}"
         )
       else started.logger.info(s"No projects to $modeLabel")
-      return Right(())
+      // Nothing ran, so nothing is up to date either — `noOp` reads false, which is what a caller asking "may I skip the next step" needs to hear.
+      return Right(BuildSummary.empty)
     }
 
     val filterCtx: Option[bleep.testing.FilterContext] =
@@ -220,7 +234,7 @@ case class ReactiveBsp(
       filterContext: Option[bleep.testing.FilterContext],
       diffRun: Option[ReactiveBsp.DiffRun],
       diffCycleBase: Option[Transcript]
-  ): Either[BleepException, Unit] = {
+  ): Either[BleepException, BuildSummary] = {
     val bspLogger = started.logger
     val diagLog: String => Unit = _ => ()
 
@@ -294,7 +308,7 @@ case class ReactiveBsp(
       filterContext: Option[bleep.testing.FilterContext],
       diffRun: Option[ReactiveBsp.DiffRun],
       diffCycleBase: Option[Transcript]
-  ): Either[BleepException, Unit] = {
+  ): Either[BleepException, BuildSummary] = {
 
     // Determine effective mode and logger upfront (no IO needed)
     val effectiveMode = DisplayMode.resolve(displayMode)
@@ -813,8 +827,8 @@ case class ReactiveBsp(
     }
 
   /** Convert build summary to result. Shared by runWithBleepBsp and runInProcess. */
-  private def resultFromSummary(summary: BuildSummary): Either[BleepException, Unit] =
-    summary.toEither
+  private def resultFromSummary(summary: BuildSummary): Either[BleepException, BuildSummary] =
+    summary.toEither.map(_ => summary)
 
   /** Build target identifier for a project */
   private def buildTarget(buildPaths: BuildPaths, name: model.CrossProjectName): bsp4j.BuildTargetIdentifier = {
diff --git a/bleep-core/src/scala/bleep/javaapi/JCommands.scala b/bleep-core/src/scala/bleep/javaapi/JCommands.scala
index fbf8d7362..56a74964f 100644
--- a/bleep-core/src/scala/bleep/javaapi/JCommands.scala
+++ b/bleep-core/src/scala/bleep/javaapi/JCommands.scala
@@ -1,6 +1,6 @@
 package bleep.javaapi
 
-import bleep.commands.{Publish, PublishLocal, PublishSonatype}
+import bleep.commands.{LinkOptions, Publish, PublishLocal, PublishSonatype}
 import bleep.packaging.ManifestCreator
 import bleep.{model, Commands, Started}
 import cats.data.NonEmptyList
@@ -11,11 +11,45 @@ import scala.jdk.CollectionConverters.*
 final class JCommands(started: Started) extends bleepscript.Commands {
   private val underlying = new Commands(started)
 
-  override def compile(projects: java.util.List[bleepscript.CrossProjectName]): Unit =
-    underlying.compile(projects.asScala.iterator.map(JModel.toCross).toList, watch = false)
+  override def compile(projects: java.util.List[bleepscript.CrossProjectName]): bleepscript.CompileReport =
+    compile(projects, watch = false)
+
+  override def compile(projects: java.util.List[bleepscript.CrossProjectName], watch: Boolean): bleepscript.CompileReport = {
+    val summary = underlying.compile(projects.asScala.iterator.map(JModel.toCross).toList, watch = watch)
+    // Deliberately narrower than the summary it comes from. `BuildSummary` is bleep's internal accounting and changes shape whenever the build display does; a
+    // published Java interface should not.
+    new bleepscript.CompileReport(
+      summary.noOp,
+      summary.upToDateProjects.map(JModel.crossProjectName).asJava,
+      summary.compilesCompleted
+    )
+  }
+
+  override def link(projects: java.util.List[bleepscript.CrossProjectName], options: bleepscript.LinkOptions): Unit =
+    link(projects, options, watch = false)
 
-  override def compile(projects: java.util.List[bleepscript.CrossProjectName], watch: Boolean): Unit =
-    underlying.compile(projects.asScala.iterator.map(JModel.toCross).toList, watch = watch)
+  override def link(projects: java.util.List[bleepscript.CrossProjectName], options: bleepscript.LinkOptions, watch: Boolean): Unit =
+    underlying.link(
+      projects.asScala.iterator.map(JModel.toCross).toList,
+      LinkOptions(
+        releaseMode = options.releaseMode,
+        sourceMaps = toScalaOpt(options.sourceMaps).map(_.booleanValue),
+        minify = toScalaOpt(options.minify).map(_.booleanValue),
+        moduleKind = toScalaOpt(options.moduleKind).map {
+          case bleepscript.LinkOptions.ModuleKind.NO_MODULE => LinkOptions.ModuleKind.NoModule
+          case bleepscript.LinkOptions.ModuleKind.COMMON_JS => LinkOptions.ModuleKind.CommonJS
+          case bleepscript.LinkOptions.ModuleKind.ES_MODULE => LinkOptions.ModuleKind.ESModule
+        },
+        lto = toScalaOpt(options.lto).map {
+          case bleepscript.LinkOptions.LTO.NONE => LinkOptions.LTO.None
+          case bleepscript.LinkOptions.LTO.THIN => LinkOptions.LTO.Thin
+          case bleepscript.LinkOptions.LTO.FULL => LinkOptions.LTO.Full
+        },
+        optimize = toScalaOpt(options.optimize).map(_.booleanValue),
+        debugInfo = toScalaOpt(options.debugInfo).map(_.booleanValue)
+      ),
+      watch = watch
+    )
 
   override def test(projects: java.util.List[bleepscript.CrossProjectName]): Unit =
     underlying.test(
diff --git a/bleep-core/src/scala/bleep/testing/BuildDisplay.scala b/bleep-core/src/scala/bleep/testing/BuildDisplay.scala
index eb041002e..e7e75257d 100644
--- a/bleep-core/src/scala/bleep/testing/BuildDisplay.scala
+++ b/bleep-core/src/scala/bleep/testing/BuildDisplay.scala
@@ -72,6 +72,8 @@ case class BuildSummary(
     compilesFailed: Int,
     compilesSkipped: Int,
     compilesCancelled: Int,
+    /** Projects whose compile found nothing to do. See [[noOp]]. */
+    upToDateProjects: List[CrossProjectName],
     suitesTotal: Int,
     suitesCompleted: Int,
     suitesFailed: Int,
@@ -105,6 +107,17 @@ case class BuildSummary(
     historyId: Option[Long]
 ) {
 
+  /** True when every project that compiled was already up to date, so the run produced no new class files.
+    *
+    * This is BSP's `CompileReport.noOp` computed from what bleep already knows: the server reports a [[bleep.bsp.protocol.CompileReason]] per project, and
+    * `UpToDate` is the one that means the compiler ran and found nothing to do. A caller uses it to skip work that only matters when something recompiled — a
+    * deploy step, a docker build, a downstream publish.
+    *
+    * A run in which nothing compiled at all is NOT a no-op: there was no compile to be a no-op about, and answering `true` there would tell a deploy script it
+    * may skip on the strength of a run that never looked.
+    */
+  def noOp: Boolean = compilesCompleted > 0 && upToDateProjects.size == compilesCompleted
+
   /** Convert this summary to Either — Left for cancelled/failed builds, Right for success. Use this to gate post-build steps (publishing, etc.) */
   def toEither: Either[bleep.BleepException, Unit] =
     if (serverCrashed)
@@ -580,6 +593,7 @@ object BuildSummary {
     compilesFailed = 0,
     compilesSkipped = 0,
     compilesCancelled = 0,
+    upToDateProjects = Nil,
     suitesTotal = 0,
     suitesCompleted = 0,
     suitesFailed = 0,
diff --git a/bleep-core/src/scala/bleep/testing/BuildState.scala b/bleep-core/src/scala/bleep/testing/BuildState.scala
index 9b68988a8..d43363e8d 100644
--- a/bleep-core/src/scala/bleep/testing/BuildState.scala
+++ b/bleep-core/src/scala/bleep/testing/BuildState.scala
@@ -18,6 +18,10 @@ case class BuildState(
     compilesFailed: Int,
     compilesSkipped: Int,
     compilesCancelled: Int,
+    /** Projects whose compile reported [[bleep.bsp.protocol.CompileReason.UpToDate]] — the compiler ran and found nothing to do. Kept as a list rather than a
+      * count so a caller can name them.
+      */
+    upToDateProjects: List[CrossProjectName],
     testsTotal: Int,
     testsPassed: Int,
     testsFailed: Int,
@@ -82,6 +86,7 @@ case class BuildState(
       compilesFailed = compilesFailed,
       compilesSkipped = compilesSkipped,
       compilesCancelled = compilesCancelled,
+      upToDateProjects = upToDateProjects.reverse,
       suitesTotal = suitesTotal,
       suitesCompleted = suitesCompleted,
       suitesFailed = suitesFailed,
@@ -123,6 +128,7 @@ object BuildState {
     compilesFailed = 0,
     compilesSkipped = 0,
     compilesCancelled = 0,
+    upToDateProjects = Nil,
     testsTotal = 0,
     testsPassed = 0,
     testsFailed = 0,
@@ -186,9 +192,13 @@ object BuildStateReducer {
         compileStartTimes = state.compileStartTimes + (project -> timestamp)
       )
 
-    case BuildEvent.CompilationReason(_, _, _, _, _, _) =>
-      // CompilationReason is purely informational for display - no state change needed
-      state
+    case BuildEvent.CompilationReason(project, reason, _, _, _, _) =>
+      // Informational for display, except for one bit worth keeping: whether the compiler found anything to do. That is the only place a caller can learn a
+      // compile was a no-op, and `bleep.Commands.compile` hands it back so a script can skip work that only matters when something recompiled.
+      reason match {
+        case bleep.bsp.protocol.CompileReason.UpToDate => state.copy(upToDateProjects = project :: state.upToDateProjects)
+        case _                                         => state
+      }
 
     case BuildEvent.CompileFinished(project, status, durationMs, _, diagnostics, skippedBecause) =>
       import bleep.bsp.protocol.CompileStatus
diff --git a/bleep-tests/src/scala/bleep/ScriptCommandsIT.scala b/bleep-tests/src/scala/bleep/ScriptCommandsIT.scala
new file mode 100644
index 000000000..3c65240ef
--- /dev/null
+++ b/bleep-tests/src/scala/bleep/ScriptCommandsIT.scala
@@ -0,0 +1,86 @@
+package bleep
+
+import bleep.commands.LinkOptions
+
+import java.nio.file.Files
+import scala.jdk.CollectionConverters.*
+
+/** The surface a build script reaches through [[bleep.Commands]].
+  *
+  * Two gaps, both reported against a real build: there was no `link` at all, so a script that packages linked JavaScript into a jar had to shell out to the
+  * `bleep` command line and pay the start-up cost a second time; and `compile` returned `Unit`, so a script could not tell a compile that rebuilt everything
+  * from one that found nothing to do — a distinction bleep already knows and had nowhere to put.
+  */
+class ScriptCommandsIT extends IntegrationTestHarness {
+
+  private val a = model.CrossProjectName(model.ProjectName("a"), None)
+  private val myapp = model.CrossProjectName(model.ProjectName("myapp"), None)
+
+  integrationTest("compile reports whether anything actually recompiled") { ws =>
+    ws.yaml(
+      """projects:
+        |  a:
+        |    platform:
+        |      name: jvm
+        |    scala:
+        |      version: 3.4.2
+        |""".stripMargin
+    )
+    ws.file("a/src/scala/A.scala", "package test\nobject A { def one = 1 }\n")
+    val (_, commands, _) = ws.start()
+
+    val first = commands.compile(List(a))
+    assert(!first.noOp, s"the first compile of a fresh project cannot be a no-op: upToDate=${first.upToDateProjects}")
+    assert(first.compilesCompleted > 0, "the first compile reported no completed compiles at all")
+
+    val second = commands.compile(List(a))
+    assert(second.noOp, s"a repeat compile with nothing changed should be a no-op: upToDate=${second.upToDateProjects}")
+    assert(second.upToDateProjects.contains(a), s"the up-to-date project was not named: ${second.upToDateProjects}")
+
+    // And back again, so the flag is shown to track the source rather than just the call count.
+    ws.file("a/src/scala/A.scala", "package test\nobject A { def one = 1; def two = 2 }\n")
+    val third = commands.compile(List(a))
+    assert(!third.noOp, s"a compile after an edit should not be a no-op: upToDate=${third.upToDateProjects}")
+    succeed
+  }
+
+  integrationTest("link is reachable from a script") { ws =>
+    ws.yaml(
+      s"""projects:
+         |  myapp:
+         |    platform:
+         |      name: js
+         |      jsVersion: ${model.Versions.ScalaJs1}
+         |      jsNodeVersion: ${model.Versions.Node}
+         |      jsKind: none
+         |      mainClass: example.Greeter
+         |    scala:
+         |      version: ${model.Versions.Scala3}
+         |""".stripMargin
+    )
+    ws.file(
+      "myapp/src/scala/example/Greeter.scala",
+      """package example
+        |
+        |object Greeter {
+        |  def main(args: Array[String]): Unit = println("hello")
+        |}
+        |""".stripMargin
+    )
+    val (_, commands, _) = ws.start()
+
+    commands.link(List(myapp), LinkOptions.Debug)
+
+    // Asserted on the linked file, not on the call returning: `link` throws on failure, so "it did not throw" is also what a `link` that linked nothing would
+    // look like.
+    val linked = Files
+      .walk(ws.root.resolve(".bleep"))
+      .iterator()
+      .asScala
+      .filter(p => p.getFileName.toString == "main.js")
+      .toList
+    assert(linked.nonEmpty, s"commands.link produced no main.js under ${ws.root}")
+    assert(Files.size(linked.head) > 0, s"commands.link produced an empty ${linked.head}")
+    succeed
+  }
+}
diff --git a/bleepscript/src/main/java/bleepscript/Commands.java b/bleepscript/src/main/java/bleepscript/Commands.java
index 003e28518..9a1a9cd45 100644
--- a/bleepscript/src/main/java/bleepscript/Commands.java
+++ b/bleepscript/src/main/java/bleepscript/Commands.java
@@ -4,9 +4,24 @@
 import java.util.Optional;
 
 public interface Commands {
-  void compile(List<CrossProjectName> projects);
+  /**
+   * Compile {@code projects}. Throws when the compile fails; see {@link CompileReport} for what a
+   * successful one reports back.
+   */
+  CompileReport compile(List<CrossProjectName> projects);
+
+  CompileReport compile(List<CrossProjectName> projects, boolean watch);
+
+  /**
+   * Link {@code projects} — Scala.js, Scala Native, Kotlin/JS or Kotlin/Native — the way {@code
+   * bleep link} does.
+   *
+   * <p>Without this a script that packages linked JavaScript into a jar had to shell out to the
+   * {@code bleep} command line, paying the start-up cost a second time.
+   */
+  void link(List<CrossProjectName> projects, LinkOptions options);
 
-  void compile(List<CrossProjectName> projects, boolean watch);
+  void link(List<CrossProjectName> projects, LinkOptions options, boolean watch);
 
   void test(List<CrossProjectName> projects);
 
diff --git a/bleepscript/src/main/java/bleepscript/CompileReport.java b/bleepscript/src/main/java/bleepscript/CompileReport.java
new file mode 100644
index 000000000..494c55fcf
--- /dev/null
+++ b/bleepscript/src/main/java/bleepscript/CompileReport.java
@@ -0,0 +1,28 @@
+package bleepscript;
+
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * What a compile did, returned by {@link Commands#compile}.
+ *
+ * <p>The one thing a caller cannot get anywhere else is {@link #noOp()}: whether the compile
+ * produced anything. bleep knows per project whether the compiler ran and found nothing to do, and
+ * before this it had nowhere to report it, so a script that wanted to skip a deploy when nothing
+ * had changed had no signal to test.
+ *
+ * @param noOp every project that compiled was already up to date, so no class file was rewritten. A
+ *     run in which nothing compiled at all is not a no-op — there was no compile to be a no-op
+ *     about, and saying otherwise would let a deploy skip on the strength of a run that never
+ *     looked.
+ * @param upToDateProjects the projects that reported nothing to do, named rather than counted
+ * @param compilesCompleted how many project compiles finished, up to date or not
+ */
+public record CompileReport(
+    boolean noOp, List<CrossProjectName> upToDateProjects, int compilesCompleted) {
+
+  public CompileReport {
+    Objects.requireNonNull(upToDateProjects, "upToDateProjects");
+    upToDateProjects = List.copyOf(upToDateProjects);
+  }
+}
diff --git a/bleepscript/src/main/java/bleepscript/LinkOptions.java b/bleepscript/src/main/java/bleepscript/LinkOptions.java
new file mode 100644
index 000000000..e6cacea59
--- /dev/null
+++ b/bleepscript/src/main/java/bleepscript/LinkOptions.java
@@ -0,0 +1,71 @@
+package bleepscript;
+
+import java.util.Objects;
+import java.util.Optional;
+
+/**
+ * What {@link Commands#link} passes to the linker — the same settings {@code bleep link} accepts as
+ * flags.
+ *
+ * <p>Every field a platform does not have a use for is ignored by it: {@code moduleKind} and {@code
+ * minify} are JavaScript's, {@code lto} and {@code debugInfo} are the native platforms'. An empty
+ * {@link Optional} means "whatever the build and the mode decide", which is not the same as an
+ * explicit {@code false}: a project declaring {@code jsKind: esmodule} keeps its declaration when
+ * {@code moduleKind} is empty and loses it when it is set.
+ *
+ * <p>{@link #DEBUG} and {@link #RELEASE} are the two most callers want.
+ */
+public record LinkOptions(
+    boolean releaseMode,
+    Optional<Boolean> sourceMaps,
+    Optional<Boolean> minify,
+    Optional<ModuleKind> moduleKind,
+    Optional<LTO> lto,
+    Optional<Boolean> optimize,
+    Optional<Boolean> debugInfo) {
+
+  public LinkOptions {
+    Objects.requireNonNull(sourceMaps, "sourceMaps");
+    Objects.requireNonNull(minify, "minify");
+    Objects.requireNonNull(moduleKind, "moduleKind");
+    Objects.requireNonNull(lto, "lto");
+    Objects.requireNonNull(optimize, "optimize");
+    Objects.requireNonNull(debugInfo, "debugInfo");
+  }
+
+  /** Module kind for JavaScript output (Scala.js). */
+  public enum ModuleKind {
+    NO_MODULE,
+    COMMON_JS,
+    ES_MODULE
+  }
+
+  /** Link-time optimization level (Scala Native). */
+  public enum LTO {
+    NONE,
+    THIN,
+    FULL
+  }
+
+  /** Debug semantics, nothing overridden. What {@code bleep link} does with no flags. */
+  public static final LinkOptions DEBUG =
+      new LinkOptions(
+          false,
+          Optional.empty(),
+          Optional.empty(),
+          Optional.empty(),
+          Optional.empty(),
+          Optional.empty(),
+          Optional.empty());
+
+  /** Release semantics, nothing overridden. What {@code bleep link --release} does. */
+  public static final LinkOptions RELEASE =
+      new LinkOptions(
+          true,
+          Optional.empty(),
+          Optional.empty(),
+          Optional.empty(),
+          Optional.empty(),
+          Optional.empty(),
+          Optional.empty());
+}
diff --git a/docs/concepts/bleep-scripts.mdx b/docs/concepts/bleep-scripts.mdx
index de6c95fe4..6306f599f 100644
--- a/docs/concepts/bleep-scripts.mdx
+++ b/docs/concepts/bleep-scripts.mdx
@@ -55,6 +55,7 @@ Your script gets three things:
   ```java
   commands.compile(List.of(projectName));
   commands.test(List.of(projectName));
+  commands.link(List.of(jsProject), LinkOptions.DEBUG);
   commands.publishLocal(
       PublishOptions.builder()
           .groupId("com.example")
@@ -64,6 +65,16 @@ Your script gets three things:
           .build());
   ```
 
+  `compile` hands back a `CompileReport`. Its `noOp()` is true when every project it compiled was
+  already up to date, which is what a script tests before doing work that only matters when
+  something was rebuilt:
+
+  ```java
+  if (!commands.compile(List.of(projectName)).noOp()) {
+    deploy(projectName);
+  }
+  ```
+
 - **`args`**: whatever the user passed on the command line after the script name.
 
 ### Working with the build model

From 531394c6f521978932ae0fc9a6b9984a8d39f824 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=98yvind=20Raddum=20Berg?= <elacin@gmail.com>
Date: Tue, 1 Sep 2026 18:05:00 +0200
Subject: [PATCH 04/13] scripts: link reports where it put things (#677)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`commands.link` said whether it worked and nothing else, so a script that wants
the linked JavaScript — to copy it into a jar, to serve it — had to rebuild

    link-output/<debug|release>/js/main.js

by hand. That is a layout bleep owns and has already renamed once, when
`--release` grew minification and the directory had to follow the mode rather
than the optimizer.

The authoritative answer already existed and already crossed the wire.
`BuildEvent.LinkSucceeded` carries `generatedFiles`, with a comment on the field
saying it is taken from the linker "rather than found by looking in the output
directory afterwards, which is guesswork that goes stale the moment a platform
changes its layout". bleep declined to guess for its own use and then left
scripts with nothing else to do. `BuildState` dropped the field on the floor,
the same way it was dropping `CompileReason` before #671.

It is accumulated now as `BuildSummary.linkedOutputs`, and `link` returns the
summary the way `compile` does. `LinkedOutput.mainArtifact` names the ordering
convention — main artifact first, then source map and chunks — instead of
leaving callers to know that `files.head` is special.

This is what #677 actually needed. The rest of that report is already true:
`bleep test` and `bleep run` both link first, `LinkResult` is a first-class task
result the DAG tracks, and packaging is a script, which since #663 can drive the
link itself. What was missing was never the trigger — it was the address.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../analysis/BuildStateReducerTest.scala      | 36 +++++++++++++++++
 bleep-core/src/scala/bleep/Commands.scala     | 15 ++++++-
 .../src/scala/bleep/javaapi/JCommands.scala   | 12 ++++--
 .../scala/bleep/testing/BuildDisplay.scala    | 25 ++++++++++++
 .../src/scala/bleep/testing/BuildState.scala  | 10 ++++-
 .../src/scala/bleep/ScriptCommandsIT.scala    | 19 +++++++--
 .../src/main/java/bleepscript/Commands.java   |  7 +++-
 .../src/main/java/bleepscript/LinkReport.java | 33 +++++++++++++++
 .../main/java/bleepscript/LinkedOutput.java   | 40 +++++++++++++++++++
 docs/concepts/bleep-scripts.mdx               | 11 +++++
 10 files changed, 196 insertions(+), 12 deletions(-)
 create mode 100644 bleepscript/src/main/java/bleepscript/LinkReport.java
 create mode 100644 bleepscript/src/main/java/bleepscript/LinkedOutput.java

diff --git a/bleep-bsp-tests/src/scala/bleep/analysis/BuildStateReducerTest.scala b/bleep-bsp-tests/src/scala/bleep/analysis/BuildStateReducerTest.scala
index 43addf778..b31c8200c 100644
--- a/bleep-bsp-tests/src/scala/bleep/analysis/BuildStateReducerTest.scala
+++ b/bleep-bsp-tests/src/scala/bleep/analysis/BuildStateReducerTest.scala
@@ -254,4 +254,40 @@ class BuildStateReducerTest extends AnyFunSuite with Matchers {
     // There was no compile to be a no-op about. Answering true here would tell a deploy script it may skip on the strength of a run that never looked.
     summaryOf(Nil).noOp shouldBe false
   }
+  // ==========================================================================
+  // linkedOutputs — where the link put things
+  // ==========================================================================
+
+  test("linkedOutputs: the linker's own file list is kept, main artifact first") {
+    // Kept rather than recomputed, because the directory layout under `link-output/` is bleep's and has been renamed before. A caller reconstructing it is
+    // guessing; this is the linker's own answer.
+    val summary = summaryOf(
+      Seq(
+        BuildEvent.LinkStarted(cpn("frontend"), bleep.bsp.protocol.LinkPlatformName.ScalaJs, ts),
+        BuildEvent.LinkSucceeded(
+          cpn("frontend"),
+          bleep.bsp.protocol.LinkPlatformName.ScalaJs,
+          durationMs = 12,
+          generatedFiles = List("/out/js/main.js", "/out/js/main.js.map"),
+          ts + 1
+        )
+      )
+    )
+
+    summary.linkedOutputs.map(_.project) shouldBe List(cpn("frontend"))
+    summary.linkedOutputs.head.mainArtifact shouldBe java.nio.file.Path.of("/out/js/main.js")
+    summary.linkedOutputs.head.files should have size 2
+  }
+
+  test("linkedOutputs: a failed link contributes nothing to report") {
+    val summary = summaryOf(
+      Seq(
+        BuildEvent.LinkStarted(cpn("frontend"), bleep.bsp.protocol.LinkPlatformName.ScalaJs, ts),
+        BuildEvent.LinkFailed(cpn("frontend"), bleep.bsp.protocol.LinkPlatformName.ScalaJs, durationMs = 3, error = "boom", ts + 1)
+      )
+    )
+
+    summary.linkedOutputs shouldBe empty
+    summary.linkFailures should have size 1
+  }
 }
diff --git a/bleep-core/src/scala/bleep/Commands.scala b/bleep-core/src/scala/bleep/Commands.scala
index 3be163723..c98a06535 100644
--- a/bleep-core/src/scala/bleep/Commands.scala
+++ b/bleep-core/src/scala/bleep/Commands.scala
@@ -39,9 +39,20 @@ class Commands(started: Started) {
     *
     * [[bleep.commands.LinkOptions.Debug]] and [[bleep.commands.LinkOptions.Release]] are the two a caller usually wants; the rest of the fields map one to one
     * onto the command line's flags.
+    *
+    * [[bleep.testing.BuildSummary.linkedOutputs]] is where the link put things, taken from the linker rather than from the directory layout. A caller that
+    * needs the linked JavaScript — to copy it into a jar, to serve it — reads it from there instead of rebuilding `link-output/<mode>/js/main.js` by hand,
+    * which is a path bleep owns and has already changed once.
+    *
+    * Under `watch = true` there is no single run to summarise, so this returns [[bleep.testing.BuildSummary.empty]] when the watch ends.
     */
-  def link(projects: List[model.CrossProjectName], options: LinkOptions, watch: Boolean = false): Unit =
-    force(commands.ReactiveBsp.link(watch, projects.toArray, commands.DisplayMode.NoTui, options, flamegraph = false, cancel = false))
+  def link(projects: List[model.CrossProjectName], options: LinkOptions, watch: Boolean = false): BuildSummary = {
+    val cmd = commands.ReactiveBsp.link(watch, projects.toArray, commands.DisplayMode.NoTui, options, flamegraph = false, cancel = false)
+    if (watch) {
+      force(cmd)
+      BuildSummary.empty
+    } else cmd.runReportingSummary(started).orThrow
+  }
 
   def run(
       project: model.CrossProjectName,
diff --git a/bleep-core/src/scala/bleep/javaapi/JCommands.scala b/bleep-core/src/scala/bleep/javaapi/JCommands.scala
index 56a74964f..4ec962251 100644
--- a/bleep-core/src/scala/bleep/javaapi/JCommands.scala
+++ b/bleep-core/src/scala/bleep/javaapi/JCommands.scala
@@ -25,11 +25,11 @@ final class JCommands(started: Started) extends bleepscript.Commands {
     )
   }
 
-  override def link(projects: java.util.List[bleepscript.CrossProjectName], options: bleepscript.LinkOptions): Unit =
+  override def link(projects: java.util.List[bleepscript.CrossProjectName], options: bleepscript.LinkOptions): bleepscript.LinkReport =
     link(projects, options, watch = false)
 
-  override def link(projects: java.util.List[bleepscript.CrossProjectName], options: bleepscript.LinkOptions, watch: Boolean): Unit =
-    underlying.link(
+  override def link(projects: java.util.List[bleepscript.CrossProjectName], options: bleepscript.LinkOptions, watch: Boolean): bleepscript.LinkReport = {
+    val summary = underlying.link(
       projects.asScala.iterator.map(JModel.toCross).toList,
       LinkOptions(
         releaseMode = options.releaseMode,
@@ -50,6 +50,12 @@ final class JCommands(started: Started) extends bleepscript.Commands {
       ),
       watch = watch
     )
+    new bleepscript.LinkReport(
+      summary.linkedOutputs.map { out =>
+        new bleepscript.LinkedOutput(JModel.crossProjectName(out.project), out.platform.wireValue, out.files.asJava)
+      }.asJava
+    )
+  }
 
   override def test(projects: java.util.List[bleepscript.CrossProjectName]): Unit =
     underlying.test(
diff --git a/bleep-core/src/scala/bleep/testing/BuildDisplay.scala b/bleep-core/src/scala/bleep/testing/BuildDisplay.scala
index e7e75257d..996baba2f 100644
--- a/bleep-core/src/scala/bleep/testing/BuildDisplay.scala
+++ b/bleep-core/src/scala/bleep/testing/BuildDisplay.scala
@@ -74,6 +74,8 @@ case class BuildSummary(
     compilesCancelled: Int,
     /** Projects whose compile found nothing to do. See [[noOp]]. */
     upToDateProjects: List[CrossProjectName],
+    /** What each successful link wrote, in the order the links finished. See [[LinkedOutput]]. */
+    linkedOutputs: List[LinkedOutput],
     suitesTotal: Int,
     suitesCompleted: Int,
     suitesFailed: Int,
@@ -594,6 +596,7 @@ object BuildSummary {
     compilesSkipped = 0,
     compilesCancelled = 0,
     upToDateProjects = Nil,
+    linkedOutputs = Nil,
     suitesTotal = 0,
     suitesCompleted = 0,
     suitesFailed = 0,
@@ -639,6 +642,28 @@ case class LinkFailure(
     error: String
 )
 
+/** What one project's link wrote.
+  *
+  * `files` comes from the linker itself, not from listing the output directory afterwards. That distinction is the point of carrying this at all: the layout
+  * under `link-output/` is bleep's to change — it has been renamed once already, when `--release` grew minification and the directory had to follow the mode
+  * rather than the optimizer — so a caller rebuilding that path by hand is writing something bleep is free to break under it.
+  *
+  * Ordered as the linker reported, main artifact first. Prefer [[mainArtifact]] over `files.head`, so the convention has a name.
+  */
+case class LinkedOutput(
+    project: CrossProjectName,
+    platform: LinkPlatformName,
+    files: List[java.nio.file.Path]
+) {
+
+  /** The linked program: the JavaScript module a JS link produced, or the executable a native link produced. */
+  def mainArtifact: java.nio.file.Path =
+    files.headOption.getOrElse(
+      // A link that reported success and listed nothing is broken, not a case to hand back as an empty Option for the caller to explain to itself.
+      throw new bleep.BleepException.Text(s"${project.value}: the ${platform.wireValue} link reported success but listed no files")
+    )
+}
+
 case class TestFailure(
     project: CrossProjectName,
     suite: SuiteName,
diff --git a/bleep-core/src/scala/bleep/testing/BuildState.scala b/bleep-core/src/scala/bleep/testing/BuildState.scala
index d43363e8d..1d660c655 100644
--- a/bleep-core/src/scala/bleep/testing/BuildState.scala
+++ b/bleep-core/src/scala/bleep/testing/BuildState.scala
@@ -22,6 +22,8 @@ case class BuildState(
       * count so a caller can name them.
       */
     upToDateProjects: List[CrossProjectName],
+    /** What each successful link wrote, newest first during accumulation. See [[LinkedOutput]]. */
+    linkedOutputs: List[LinkedOutput],
     testsTotal: Int,
     testsPassed: Int,
     testsFailed: Int,
@@ -87,6 +89,7 @@ case class BuildState(
       compilesSkipped = compilesSkipped,
       compilesCancelled = compilesCancelled,
       upToDateProjects = upToDateProjects.reverse,
+      linkedOutputs = linkedOutputs.reverse,
       suitesTotal = suitesTotal,
       suitesCompleted = suitesCompleted,
       suitesFailed = suitesFailed,
@@ -129,6 +132,7 @@ object BuildState {
     compilesSkipped = 0,
     compilesCancelled = 0,
     upToDateProjects = Nil,
+    linkedOutputs = Nil,
     testsTotal = 0,
     testsPassed = 0,
     testsFailed = 0,
@@ -482,10 +486,14 @@ object BuildStateReducer {
     case BuildEvent.LinkStarted(project, _, _) =>
       state.copy(currentlyLinking = state.currentlyLinking + project)
 
-    case BuildEvent.LinkSucceeded(project, _, durationMs, _, _) =>
+    case BuildEvent.LinkSucceeded(project, platform, durationMs, generatedFiles, _) =>
+      // The linker's own list of what it wrote, kept rather than dropped. It is the only authority on where the output landed: the directory layout under
+      // `link-output/` belongs to bleep and has changed before, so a caller reconstructing that path is guessing. Handed to scripts via
+      // `bleep.Commands.link`.
       state.copy(
         currentlyLinking = state.currentlyLinking - project,
         linksCompleted = state.linksCompleted + 1,
+        linkedOutputs = LinkedOutput(project, platform, generatedFiles.map(java.nio.file.Path.of(_))) :: state.linkedOutputs,
         totalTaskTimeMs = state.totalTaskTimeMs + durationMs
       )
 
diff --git a/bleep-tests/src/scala/bleep/ScriptCommandsIT.scala b/bleep-tests/src/scala/bleep/ScriptCommandsIT.scala
index 3c65240ef..5c58f153d 100644
--- a/bleep-tests/src/scala/bleep/ScriptCommandsIT.scala
+++ b/bleep-tests/src/scala/bleep/ScriptCommandsIT.scala
@@ -69,18 +69,29 @@ class ScriptCommandsIT extends IntegrationTestHarness {
     )
     val (_, commands, _) = ws.start()
 
-    commands.link(List(myapp), LinkOptions.Debug)
+    val summary = commands.link(List(myapp), LinkOptions.Debug)
 
     // Asserted on the linked file, not on the call returning: `link` throws on failure, so "it did not throw" is also what a `link` that linked nothing would
     // look like.
-    val linked = Files
+    val onDisk = Files
       .walk(ws.root.resolve(".bleep"))
       .iterator()
       .asScala
       .filter(p => p.getFileName.toString == "main.js")
       .toList
-    assert(linked.nonEmpty, s"commands.link produced no main.js under ${ws.root}")
-    assert(Files.size(linked.head) > 0, s"commands.link produced an empty ${linked.head}")
+    assert(onDisk.nonEmpty, s"commands.link produced no main.js under ${ws.root}")
+    assert(Files.size(onDisk.head) > 0, s"commands.link produced an empty ${onDisk.head}")
+
+    // And the caller is told where it went. The whole reason for reporting this is that the alternative is rebuilding `link-output/<mode>/js/main.js` from a
+    // layout bleep owns and has already renamed once, so the assertion is that the reported path is the file that is really there — not merely that some path
+    // came back.
+    val reported = summary.linkedOutputs
+    assert(reported.map(_.project) == List(myapp), s"expected one linked output for myapp, got ${reported.map(_.project.value)}")
+    assert(
+      reported.head.mainArtifact.toAbsolutePath == onDisk.head.toAbsolutePath,
+      s"the reported main artifact ${reported.head.mainArtifact} is not the file the link wrote, ${onDisk.head}"
+    )
+    assert(Files.exists(reported.head.mainArtifact), s"the reported main artifact does not exist: ${reported.head.mainArtifact}")
     succeed
   }
 }
diff --git a/bleepscript/src/main/java/bleepscript/Commands.java b/bleepscript/src/main/java/bleepscript/Commands.java
index 9a1a9cd45..0c7bffd42 100644
--- a/bleepscript/src/main/java/bleepscript/Commands.java
+++ b/bleepscript/src/main/java/bleepscript/Commands.java
@@ -18,10 +18,13 @@ public interface Commands {
    *
    * <p>Without this a script that packages linked JavaScript into a jar had to shell out to the
    * {@code bleep} command line, paying the start-up cost a second time.
+   *
+   * <p>The returned {@link LinkReport} says where the link put things, taken from the linker rather
+   * than from the directory layout — see {@link LinkedOutput}.
    */
-  void link(List<CrossProjectName> projects, LinkOptions options);
+  LinkReport link(List<CrossProjectName> projects, LinkOptions options);
 
-  void link(List<CrossProjectName> projects, LinkOptions options, boolean watch);
+  LinkReport link(List<CrossProjectName> projects, LinkOptions options, boolean watch);
 
   void test(List<CrossProjectName> projects);
 
diff --git a/bleepscript/src/main/java/bleepscript/LinkReport.java b/bleepscript/src/main/java/bleepscript/LinkReport.java
new file mode 100644
index 000000000..3754a9bbd
--- /dev/null
+++ b/bleepscript/src/main/java/bleepscript/LinkReport.java
@@ -0,0 +1,33 @@
+package bleepscript;
+
+import java.util.List;
+import java.util.Objects;
+
+/** What a link did, returned by {@link Commands#link}. */
+public record LinkReport(List<LinkedOutput> outputs) {
+
+  public LinkReport {
+    Objects.requireNonNull(outputs, "outputs");
+    outputs = List.copyOf(outputs);
+  }
+
+  /**
+   * The output for one project.
+   *
+   * <p>Throws rather than returning an empty {@link java.util.Optional}: a caller asking for a
+   * project it just linked and getting nothing back has a broken build, and handing it an empty
+   * value only moves the moment it finds out.
+   */
+  public LinkedOutput forProject(CrossProjectName project) {
+    return outputs.stream()
+        .filter(o -> o.project().equals(project))
+        .findFirst()
+        .orElseThrow(
+            () ->
+                new IllegalArgumentException(
+                    "no link output for "
+                        + project.name()
+                        + "; this link produced: "
+                        + outputs.stream().map(o -> o.project().name()).toList()));
+  }
+}
diff --git a/bleepscript/src/main/java/bleepscript/LinkedOutput.java b/bleepscript/src/main/java/bleepscript/LinkedOutput.java
new file mode 100644
index 000000000..fadcbdbed
--- /dev/null
+++ b/bleepscript/src/main/java/bleepscript/LinkedOutput.java
@@ -0,0 +1,40 @@
+package bleepscript;
+
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * What one project's link wrote, as the linker reported it.
+ *
+ * <p>These paths come from the linker, not from listing the output directory afterwards. That is
+ * the reason they are handed back at all: the layout under {@code link-output/} belongs to bleep
+ * and has been renamed once already, so a script that rebuilds {@code
+ * link-output/<mode>/js/main.js} by hand is depending on something bleep is free to change.
+ *
+ * @param project which project this link was for
+ * @param platform the platform linked for, e.g. {@code Scala.js} or {@code Scala Native}
+ * @param files every file the link wrote, in the order the linker reported — main artifact first,
+ *     then source map and chunks
+ */
+public record LinkedOutput(CrossProjectName project, String platform, List<Path> files) {
+
+  public LinkedOutput {
+    Objects.requireNonNull(project, "project");
+    Objects.requireNonNull(platform, "platform");
+    Objects.requireNonNull(files, "files");
+    files = List.copyOf(files);
+  }
+
+  /**
+   * The linked program: the JavaScript module a JS link produced, or the executable a native link
+   * produced. This is the path a script copies into a jar or serves.
+   */
+  public Path mainArtifact() {
+    if (files.isEmpty()) {
+      throw new IllegalStateException(
+          project.name() + ": the " + platform + " link reported success but listed no files");
+    }
+    return files.get(0);
+  }
+}
diff --git a/docs/concepts/bleep-scripts.mdx b/docs/concepts/bleep-scripts.mdx
index 6306f599f..6331cc093 100644
--- a/docs/concepts/bleep-scripts.mdx
+++ b/docs/concepts/bleep-scripts.mdx
@@ -75,6 +75,17 @@ Your script gets three things:
   }
   ```
 
+  `link` hands back a `LinkReport` saying where the link put things. Read the path from there rather
+  than rebuilding `link-output/<mode>/js/main.js` yourself — that layout belongs to bleep and has
+  changed before:
+
+  ```java
+  Path js = commands.link(List.of(frontend), LinkOptions.DEBUG)
+      .forProject(frontend)
+      .mainArtifact();
+  Files.copy(js, serverResources.resolve("assets/main.js"), REPLACE_EXISTING);
+  ```
+
 - **`args`**: whatever the user passed on the command line after the script name.
 
 ### Working with the build model

From d3c25ebd2ff79a92746bf32618eba2b7cb792a6b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=98yvind=20Raddum=20Berg?= <elacin@gmail.com>
Date: Tue, 1 Sep 2026 18:05:01 +0200
Subject: [PATCH 05/13] scripts: test reports what ran (#671 follow-on)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Same three lines as `compile` and `link`: the run already builds a
`BuildSummary` and `Commands.test` threw it away.

The counts are the useful part, and not for the reason one might expect. A
failing test throws, so "it returned" already meant "nothing failed" — what a
caller could not learn is whether anything *ran*, which is the failure mode that
reads as green in CI. That is the same hole `testProjectsWithoutSuites` exists
to close inside bleep, now visible to a script.

Deliberately not solved here: the failure detail. `failures` and
`cancelledSuites` describe a run that threw before the caller could read them,
so a script that wants to inspect failures rather than propagate them needs a
non-throwing entry point. The Java `TestReport` carries counts only, and says
so, rather than exposing lists that are always empty by the time you hold them.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 bleep-core/src/scala/bleep/Commands.scala     | 16 ++++++--
 .../src/scala/bleep/javaapi/JCommands.scala   | 40 +++++++++++--------
 .../src/scala/bleep/ScriptCommandsIT.scala    | 34 ++++++++++++++++
 .../src/main/java/bleepscript/Commands.java   |  5 ++-
 .../src/main/java/bleepscript/TestReport.java | 11 +++++
 5 files changed, 85 insertions(+), 21 deletions(-)
 create mode 100644 bleepscript/src/main/java/bleepscript/TestReport.java

diff --git a/bleep-core/src/scala/bleep/Commands.scala b/bleep-core/src/scala/bleep/Commands.scala
index c98a06535..34c49f1d5 100644
--- a/bleep-core/src/scala/bleep/Commands.scala
+++ b/bleep-core/src/scala/bleep/Commands.scala
@@ -63,6 +63,12 @@ class Commands(started: Started) {
   ): Unit =
     force(commands.Run(project, maybeOverriddenMain, args, raw, watch, noTuiBuildOpts))
 
+  /** Run the tests in `projects`, returning what the run reported.
+    *
+    * A failing test still throws, so the summary describes a run in which everything passed: counts, suites, durations. The detail a caller most wants on a
+    * *failing* run — `failures`, `cancelledSuites` — is therefore out of reach here, because the throw gets there first. Ask for a non-throwing entry point if
+    * you need to inspect failures rather than propagate them.
+    */
   def test(
       projects: List[model.CrossProjectName],
       watch: Boolean = false,
@@ -70,8 +76,8 @@ class Commands(started: Started) {
       exclude: Option[NonEmptyList[String]],
       includeTags: Option[NonEmptyList[String]],
       excludeTags: Option[NonEmptyList[String]]
-  ): Unit =
-    force(
+  ): BuildSummary = {
+    val cmd =
       commands.ReactiveBsp.test(
         watch = watch,
         projects = projects.toArray,
@@ -89,7 +95,11 @@ class Commands(started: Started) {
         diffOutput = OutputMode.Text,
         clientEnv = bleep.bsp.protocol.BleepBspProtocol.ClientEnv.current(noColor = bleep.PreBootstrapOpts.noColorRequested)
       )
-    )
+    if (watch) {
+      force(cmd)
+      BuildSummary.empty
+    } else cmd.runReportingSummary(started).orThrow
+  }
 
   def script(name: model.ScriptName, args: List[String], watch: Boolean = false): Unit =
     force(commands.Script(name, args, watch))
diff --git a/bleep-core/src/scala/bleep/javaapi/JCommands.scala b/bleep-core/src/scala/bleep/javaapi/JCommands.scala
index 4ec962251..70429270f 100644
--- a/bleep-core/src/scala/bleep/javaapi/JCommands.scala
+++ b/bleep-core/src/scala/bleep/javaapi/JCommands.scala
@@ -57,14 +57,16 @@ final class JCommands(started: Started) extends bleepscript.Commands {
     )
   }
 
-  override def test(projects: java.util.List[bleepscript.CrossProjectName]): Unit =
-    underlying.test(
-      projects.asScala.iterator.map(JModel.toCross).toList,
-      watch = false,
-      only = None,
-      exclude = None,
-      includeTags = None,
-      excludeTags = None
+  override def test(projects: java.util.List[bleepscript.CrossProjectName]): bleepscript.TestReport =
+    toTestReport(
+      underlying.test(
+        projects.asScala.iterator.map(JModel.toCross).toList,
+        watch = false,
+        only = None,
+        exclude = None,
+        includeTags = None,
+        excludeTags = None
+      )
     )
 
   override def test(
@@ -72,16 +74,22 @@ final class JCommands(started: Started) extends bleepscript.Commands {
       watch: Boolean,
       only: Optional[java.util.List[String]],
       exclude: Optional[java.util.List[String]]
-  ): Unit =
-    underlying.test(
-      projects.asScala.iterator.map(JModel.toCross).toList,
-      watch = watch,
-      only = toNel(only),
-      exclude = toNel(exclude),
-      includeTags = None,
-      excludeTags = None
+  ): bleepscript.TestReport =
+    toTestReport(
+      underlying.test(
+        projects.asScala.iterator.map(JModel.toCross).toList,
+        watch = watch,
+        only = toNel(only),
+        exclude = toNel(exclude),
+        includeTags = None,
+        excludeTags = None
+      )
     )
 
+  /** Narrower than the summary it comes from, for the same reason [[bleepscript.CompileReport]] is. */
+  private def toTestReport(summary: bleep.testing.BuildSummary): bleepscript.TestReport =
+    new bleepscript.TestReport(summary.testsTotal, summary.testsPassed, summary.testsSkipped, summary.testsIgnored, summary.suitesTotal)
+
   override def run(project: bleepscript.CrossProjectName): Unit =
     underlying.run(JModel.toCross(project), None, Nil, raw = false, watch = false)
 
diff --git a/bleep-tests/src/scala/bleep/ScriptCommandsIT.scala b/bleep-tests/src/scala/bleep/ScriptCommandsIT.scala
index 5c58f153d..84c514108 100644
--- a/bleep-tests/src/scala/bleep/ScriptCommandsIT.scala
+++ b/bleep-tests/src/scala/bleep/ScriptCommandsIT.scala
@@ -44,6 +44,40 @@ class ScriptCommandsIT extends IntegrationTestHarness {
     succeed
   }
 
+  integrationTest("test reports what ran, so an empty run is visible") { ws =>
+    ws.yaml(
+      s"""projects:
+         |  a:
+         |    dependencies:
+         |      - org.scalameta::munit:${model.Versions.Munit}
+         |    isTestProject: true
+         |    platform:
+         |      name: jvm
+         |    scala:
+         |      version: ${model.Versions.Scala3}
+         |""".stripMargin
+    )
+    ws.file(
+      "a/src/scala/example/ASuite.scala",
+      """package example
+        |
+        |class ASuite extends munit.FunSuite {
+        |  test("one") { assertEquals(1, 1) }
+        |  test("two") { assertEquals(2, 2) }
+        |}
+        |""".stripMargin
+    )
+    val (_, commands, _) = ws.start()
+
+    val summary = commands.test(List(a), watch = false, only = None, exclude = None, includeTags = None, excludeTags = None)
+
+    // The counts are the point. `commands.test` throws when a test fails, so "it returned" already meant "nothing failed" — what it could not tell a caller is
+    // whether anything ran at all, which is the failure mode that reads as success in CI.
+    assert(summary.testsPassed == 2, s"expected 2 passing tests, summary says ${summary.testsPassed}")
+    assert(summary.suitesTotal == 1, s"expected 1 suite, summary says ${summary.suitesTotal}")
+    succeed
+  }
+
   integrationTest("link is reachable from a script") { ws =>
     ws.yaml(
       s"""projects:
diff --git a/bleepscript/src/main/java/bleepscript/Commands.java b/bleepscript/src/main/java/bleepscript/Commands.java
index 0c7bffd42..b6572e651 100644
--- a/bleepscript/src/main/java/bleepscript/Commands.java
+++ b/bleepscript/src/main/java/bleepscript/Commands.java
@@ -26,9 +26,10 @@ public interface Commands {
 
   LinkReport link(List<CrossProjectName> projects, LinkOptions options, boolean watch);
 
-  void test(List<CrossProjectName> projects);
+  /** Run the tests in {@code projects}. Throws when a test fails; see {@link TestReport}. */
+  TestReport test(List<CrossProjectName> projects);
 
-  void test(
+  TestReport test(
       List<CrossProjectName> projects,
       boolean watch,
       Optional<List<String>> only,
diff --git a/bleepscript/src/main/java/bleepscript/TestReport.java b/bleepscript/src/main/java/bleepscript/TestReport.java
new file mode 100644
index 000000000..38207bfe4
--- /dev/null
+++ b/bleepscript/src/main/java/bleepscript/TestReport.java
@@ -0,0 +1,11 @@
+package bleepscript;
+
+/**
+ * What a test run did, returned by {@link Commands#test}.
+ *
+ * <p>A failing test throws, so this describes a run in which everything passed. There is
+ * deliberately no failure list on it: by the time a caller could read one, the throw has already
+ * happened. Counts are what remain useful — chiefly for asserting that a run was not silently
+ * empty.
+ */
+public record TestReport(int total, int passed, int skipped, int ignored, int suites) {}

From 62a793ae58d5e74a040ea579cf2baabbb04aa043 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=98yvind=20Raddum=20Berg?= <elacin@gmail.com>
Date: Tue, 1 Sep 2026 20:37:01 +0200
Subject: [PATCH 06/13] publish: the version is one input with two cases, and
 dynver lives inside bleep
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`Publish.Options` carried `versionOverride: Option[String]` beside
`versionFallback: Option[() => String]` — a two-field encoding of a one-of-two
choice, with "exactly one must be set" enforced at runtime, and on the Java side
thrown from a constructor. The thunk existed so the command line could skip
shelling out to git when `--version` was given; that laziness belongs to
resolving a version, not to the shape of the input, and the Java bridge was
collapsing it on the spot anyway.

It is now `PublishVersion`: `Specified(value)` or `Dynver`. Three commands that
spelled the same idea three ways — `PublishLocal` a required `String`,
`PublishSonatype` a bare `versionOverride`, `Publish` both fields — take one
type now, and `bleep publish-local --version` becomes optional like every other
publish path.

Resolution moved with it. The command line used to build a `DynVerPlugin` and
pass it in as a lambda, while `PublishSonatype` built its own inside bleep-core;
one function builds it now, so `dynverSonatypeSnapshots = true` — and the
paragraph explaining why it must be true — is stated once instead of twice.
`PublishSonatype` still holds a dynver object, because `CiReleasePlugin` reads
git state itself and wants more than a version string, but it gets it from that
same function.

That also settles a disagreement nobody had noticed. `--assert-release` asked
"is this a snapshot" in two places and answered it two ways: `Publish` inspected
the string for `+` and `-SNAPSHOT`, `PublishSonatype` asked dynver. One answer
now, and it is dynver's.

Behaviour preserved, including the wart: `--assert-release` does not check a
version the caller spelled out. That used to read `versionOverride.isEmpty`,
which said what it did and not why; it is a case in a match now, with the reason
written down. Worth revisiting on its own, not while moving it.

Docs: the scripts page gains `.versionFromGit()` and what `--assert-release`
applies to, the CI/CD guide says the flag has nothing to check when a version is
passed, the Maven Central tutorial says the same at the flag, and the CLI
reference is regenerated for the now-optional `publish-local --version`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 bleep-cli/src/scala/bleep/Main.scala          | 25 ++++---
 .../src/scala/bleep/commands/Publish.scala    | 21 +-----
 .../scala/bleep/commands/PublishLocal.scala   |  8 +-
 .../bleep/commands/PublishSonatype.scala      | 21 ++----
 .../scala/bleep/commands/PublishVersion.scala | 56 ++++++++++++++
 .../src/scala/bleep/javaapi/JCommands.scala   | 41 ++++------
 .../bleep/PublishToHttpMavenRepoIT.scala      |  8 +-
 .../src/scala/bleep/PublishVersionTest.scala  | 75 +++++++++++++++++++
 .../main/java/bleepscript/PublishOptions.java | 42 +++++------
 .../main/java/bleepscript/PublishVersion.java | 43 +++++++++++
 docs/concepts/bleep-scripts.mdx               |  5 ++
 docs/guides/ci-cd-setup.mdx                   |  4 +-
 docs/reference/cli/publish-local.mdx          |  2 +-
 docs/tutorials/publish-to-maven.mdx           |  3 +-
 14 files changed, 246 insertions(+), 108 deletions(-)
 create mode 100644 bleep-core/src/scala/bleep/commands/PublishVersion.scala
 create mode 100644 bleep-tests/src/scala/bleep/PublishVersionTest.scala
 create mode 100644 bleepscript/src/main/java/bleepscript/PublishVersion.java

diff --git a/bleep-cli/src/scala/bleep/Main.scala b/bleep-cli/src/scala/bleep/Main.scala
index 566143be4..bb18d6dd0 100644
--- a/bleep-cli/src/scala/bleep/Main.scala
+++ b/bleep-cli/src/scala/bleep/Main.scala
@@ -941,7 +941,7 @@ object Main {
           Opts.subcommand("publish-local", "publishes your project locally (deprecated: use 'publish local-ivy')") {
             (
               Opts.option[String]("groupId", "organization you will publish under"),
-              Opts.option[String]("version", "version you will publish"),
+              Opts.option[String]("version", "version you will publish (default: from git tags)").orNone,
               Opts.option[Path]("to", s"publish to a maven repository at given path").orNone,
               projectNames,
               watch,
@@ -953,7 +953,7 @@ object Main {
               }
               val options = commands.PublishLocal.Options(
                 groupId = groupId,
-                version = version,
+                version = publishVersion(version),
                 publishTarget = publishTarget,
                 projects,
                 ManifestCreator.default
@@ -962,14 +962,6 @@ object Main {
             }
           },
           Opts.subcommand("publish", "publish artifacts to a named resolver, local-ivy, or sonatype") {
-            // `dynverSonatypeSnapshots = true` to match the two other places that derive a version from git:
-            // `GenerateResources` (which bakes `BleepVersion.current` into the client) and `PublishSonatype`.
-            // Without it a snapshot publishes as `1.0.0-M10+46-abc1234` while the client it was built alongside
-            // asks coursier for `1.0.0-M10+46-abc1234-SNAPSHOT` — so `bleep publish local-ivy` produced jars no
-            // client would ever resolve, silently leaving the previously released server in play.
-            val dynVerFallback: () => String =
-              () => new bleep.plugin.dynver.DynVerPlugin(baseDirectory = started.buildPaths.buildDir.toFile, dynverSonatypeSnapshots = true).version
-
             def publishOpts(target: commands.Publish.Target): Opts[BleepBuildCommand] =
               publishOptsWith(Opts.unit.map(_ => target))
 
@@ -984,7 +976,7 @@ object Main {
               ).mapN { case (version, assertRel, dryRun, projects, buildOpts, target) =>
                 commands.Publish(
                   false,
-                  commands.Publish.Options(version, Some(dynVerFallback), assertRel, dryRun, target, projects, ManifestCreator.default),
+                  commands.Publish.Options(publishVersion(version), assertRel, dryRun, target, projects, ManifestCreator.default),
                   buildOpts
                 )
               }
@@ -1006,7 +998,7 @@ object Main {
                   commonBuildOpts
                 ).mapN { case (version, assertRel, projects, buildOpts) =>
                   commands.PublishSonatype(
-                    commands.PublishSonatype.Options(version, assertRel, projects, ManifestCreator.default),
+                    commands.PublishSonatype.Options(publishVersion(version), assertRel, projects, ManifestCreator.default),
                     buildOpts
                   )
                 }
@@ -1707,6 +1699,15 @@ object Main {
       case _                                  => ExitCode.Failure
     }
 
+  /** `--version` if the user gave one, dynver otherwise. Every publish subcommand answers this the same way, which is the point of the ADT: the choice is one
+    * value, not a pair of fields with an "exactly one of these" rule enforced somewhere else.
+    */
+  private def publishVersion(version: Option[String]): commands.PublishVersion =
+    version match {
+      case Some(value) => commands.PublishVersion.Specified(value)
+      case None        => commands.PublishVersion.Dynver
+    }
+
   /** Check if restArgs request machine-readable output (json or raw), logs should go to stderr. */
   private def hasMachineOutput(restArgs: List[String]): Boolean =
     restArgs.exists {
diff --git a/bleep-core/src/scala/bleep/commands/Publish.scala b/bleep-core/src/scala/bleep/commands/Publish.scala
index 58b01d8c1..db4504e12 100644
--- a/bleep-core/src/scala/bleep/commands/Publish.scala
+++ b/bleep-core/src/scala/bleep/commands/Publish.scala
@@ -26,8 +26,7 @@ object Publish {
   val ReservedNames: Set[String] = Set("local-ivy", "sonatype", "setup")
 
   case class Options(
-      versionOverride: Option[String],
-      versionFallback: Option[() => String],
+      version: PublishVersion,
       assertRelease: Boolean,
       dryRun: Boolean,
       target: Target,
@@ -216,8 +215,7 @@ case class Publish(watch: Boolean, options: Publish.Options, buildOpts: CommonBu
           diffOutput = OutputMode.Text
         )
         .run(started)
-      version <- resolveVersion()
-      _ <- checkAssertRelease(version)
+      version <- PublishVersion.resolve(options.version, started.buildPaths.buildDir, options.assertRelease)
       _ <-
         if (options.dryRun) dryRun(started, projects, version)
         else
@@ -229,21 +227,6 @@ case class Publish(watch: Boolean, options: Publish.Options, buildOpts: CommonBu
           }
     } yield ()
 
-  private def resolveVersion(): Either[BleepException, String] =
-    options.versionOverride
-      .orElse(options.versionFallback.map(_.apply()))
-      .toRight(new BleepException.Text("No --version specified and no git tags found for automatic versioning."): BleepException)
-
-  private def checkAssertRelease(version: String): Either[BleepException, Unit] =
-    if (options.assertRelease && options.versionOverride.isEmpty && (version.contains("+") || version.endsWith("-SNAPSHOT")))
-      Left(
-        new BleepException.Text(
-          s"--assert-release: version '$version' is not a release. " +
-            "Ensure you are on a clean git tag (no commits after tag, no dirty files)."
-        )
-      )
-    else Right(())
-
   /** Package all projects in one call, returning per-project artifacts. Reads groupId from each project's publish config. */
   private def packageAll(
       started: Started,
diff --git a/bleep-core/src/scala/bleep/commands/PublishLocal.scala b/bleep-core/src/scala/bleep/commands/PublishLocal.scala
index b5883f221..82bcf9ebc 100644
--- a/bleep-core/src/scala/bleep/commands/PublishLocal.scala
+++ b/bleep-core/src/scala/bleep/commands/PublishLocal.scala
@@ -25,7 +25,7 @@ object PublishLocal {
 
   case class Options(
       groupId: String,
-      version: String,
+      version: PublishVersion,
       publishTarget: PublishLocal.PublishTarget,
       projects: Array[model.CrossProjectName],
       manifestCreator: ManifestCreator
@@ -50,10 +50,12 @@ case class PublishLocal(watch: Boolean, options: PublishLocal.Options, buildOpts
       )
       .run(started)
       .map { case () =>
+        // No `--assert-release` here: publishing a snapshot into the local cache is the normal case, and the flag is about what leaves the machine.
+        val version = PublishVersion.resolve(options.version, started.buildPaths.buildDir, assertRelease = false).orThrow
         val packagedLibraries: SortedMap[model.CrossProjectName, PackagedLibrary] =
           packageLibraries(
             started,
-            coordinatesFor = CoordinatesFor.Default(groupId = options.groupId, version = options.version),
+            coordinatesFor = CoordinatesFor.Default(groupId = options.groupId, version = version),
             shouldInclude = options.projects.toSet,
             publishLayout = options.publishTarget.publishLayout,
             manifestCreator = options.manifestCreator
@@ -67,7 +69,7 @@ case class PublishLocal(watch: Boolean, options: PublishLocal.Options, buildOpts
               deleteUnknowns = FileSync.DeleteUnknowns.No,
               soft = false
             )
-            .log(started.logger.withContext("projectName", projectName.value).withContext("version", options.version), "Published locally")
+            .log(started.logger.withContext("projectName", projectName.value).withContext("version", version), "Published locally")
         }
         ()
       }
diff --git a/bleep-core/src/scala/bleep/commands/PublishSonatype.scala b/bleep-core/src/scala/bleep/commands/PublishSonatype.scala
index 888ca44dd..a156e336a 100644
--- a/bleep-core/src/scala/bleep/commands/PublishSonatype.scala
+++ b/bleep-core/src/scala/bleep/commands/PublishSonatype.scala
@@ -4,7 +4,6 @@ package commands
 import bleep.nosbt.InteractionService
 import bleep.packaging.*
 import bleep.plugin.cirelease.CiReleasePlugin
-import bleep.plugin.dynver.DynVerPlugin
 import bleep.plugin.pgp.PgpPlugin
 import bleep.plugin.sonatype.Sonatype
 
@@ -12,7 +11,7 @@ import scala.collection.immutable.SortedMap
 
 object PublishSonatype {
   case class Options(
-      versionOverride: Option[String],
+      version: PublishVersion,
       assertRelease: Boolean,
       projectNames: Array[model.CrossProjectName],
       manifestCreator: ManifestCreator
@@ -39,20 +38,12 @@ case class PublishSonatype(options: PublishSonatype.Options, buildOpts: CommonBu
       )
       .run(started)
       .map { case () =>
-        val dynVer = new DynVerPlugin(
-          baseDirectory = started.buildPaths.buildDir.toFile,
-          dynverSonatypeSnapshots = true
-        )
-
-        if (options.assertRelease && options.versionOverride.isEmpty && dynVer.isSnapshot) {
-          throw new BleepException.Text(
-            "--assert-release: version would be a snapshot. " +
-              "Ensure you are on a clean git tag (no commits after tag, no dirty files). " +
-              s"Current version: ${dynVer.version}"
-          )
-        }
+        // One rule, in one place, for every publish command. See PublishVersion.resolve.
+        val version = PublishVersion.resolve(options.version, started.buildPaths.buildDir, options.assertRelease).orThrow
 
-        val version = options.versionOverride.getOrElse(dynVer.version)
+        // The release plugin wants the dynver object, not a version string — it reads the git state again to decide whether to release or to publish a
+        // snapshot. Built through the same function so `dynverSonatypeSnapshots = true` is stated once rather than in every place that needs a dynver.
+        val dynVer = PublishVersion.dynverFor(started.buildPaths.buildDir)
         started.logger.info(s"Publishing version: $version")
 
         val pgp = new PgpPlugin(
diff --git a/bleep-core/src/scala/bleep/commands/PublishVersion.scala b/bleep-core/src/scala/bleep/commands/PublishVersion.scala
new file mode 100644
index 000000000..acf2230fe
--- /dev/null
+++ b/bleep-core/src/scala/bleep/commands/PublishVersion.scala
@@ -0,0 +1,56 @@
+package bleep
+package commands
+
+import bleep.plugin.dynver.DynVerPlugin
+
+import java.nio.file.Path
+
+/** Where a publish gets its version: the caller says it, or bleep derives it from git.
+  *
+  * One field replacing two. `Publish.Options` used to carry `versionOverride: Option[String]` alongside `versionFallback: Option[() => String]`, which is a
+  * two-field encoding of a one-of-two choice, with the "exactly one must be set" rule enforced at runtime and, on the Java side, thrown from a constructor. The
+  * thunk existed so the command line could avoid shelling out to git when `--version` was given; that laziness belongs to the resolution below, not to the
+  * shape of the input, and the Java bridge was collapsing it on the spot anyway.
+  */
+sealed trait PublishVersion
+
+object PublishVersion {
+
+  /** Publish exactly this. */
+  case class Specified(value: String) extends PublishVersion
+
+  /** Derive from git tags: `<tag>` on a clean tag, `<tag>+<distance>-<sha>[-SNAPSHOT]` otherwise. */
+  case object Dynver extends PublishVersion
+
+  /** The version to publish under, failing when `assertRelease` and git says this would be a snapshot.
+    *
+    * `assertRelease` deliberately does nothing for [[Specified]]. The caller spelled the version out, and bleep has no better source to contradict them with —
+    * the flag is about what git state would produce. This preserves what the two commands did before, where the same rule was spelled `versionOverride.isEmpty`
+    * in one and `versionOverride.isEmpty` again in the other, and answered "is this a snapshot" two different ways: `Publish` inspected the string for `+` and
+    * `-SNAPSHOT` while `PublishSonatype` asked dynver. Now there is one answer, and it is dynver's.
+    */
+  def resolve(version: PublishVersion, buildDir: Path, assertRelease: Boolean): Either[BleepException, String] =
+    version match {
+      case Specified(value) => Right(value)
+      case Dynver           =>
+        val dynVer = dynverFor(buildDir)
+        if (assertRelease && dynVer.isSnapshot)
+          Left(
+            new BleepException.Text(
+              "--assert-release: version would be a snapshot. " +
+                "Ensure you are on a clean git tag (no commits after tag, no dirty files). " +
+                s"Current version: ${dynVer.version}"
+            )
+          )
+        else Right(dynVer.version)
+    }
+
+  /** `dynverSonatypeSnapshots = true` to match the two other places that derive a version from git: `GenerateResources` (which bakes `BleepVersion.current`
+    * into the client) and the Sonatype release path.
+    *
+    * Without it a snapshot publishes as `1.0.0-M10+46-abc1234` while the client built alongside it asks coursier for `1.0.0-M10+46-abc1234-SNAPSHOT` — so
+    * `bleep publish local-ivy` produced jars no client would ever resolve, silently leaving the previously released server in play.
+    */
+  private[bleep] def dynverFor(buildDir: Path): DynVerPlugin =
+    new DynVerPlugin(baseDirectory = buildDir.toFile, dynverSonatypeSnapshots = true)
+}
diff --git a/bleep-core/src/scala/bleep/javaapi/JCommands.scala b/bleep-core/src/scala/bleep/javaapi/JCommands.scala
index 70429270f..d79b99d00 100644
--- a/bleep-core/src/scala/bleep/javaapi/JCommands.scala
+++ b/bleep-core/src/scala/bleep/javaapi/JCommands.scala
@@ -1,6 +1,6 @@
 package bleep.javaapi
 
-import bleep.commands.{LinkOptions, Publish, PublishLocal, PublishSonatype}
+import bleep.commands.{LinkOptions, Publish, PublishLocal, PublishSonatype, PublishVersion}
 import bleep.packaging.ManifestCreator
 import bleep.{model, Commands, Started}
 import cats.data.NonEmptyList
@@ -139,10 +139,9 @@ final class JCommands(started: Started) extends bleepscript.Commands {
       case Some(other)                => throw new RuntimeException(s"Unknown ManifestCreator impl: ${other.getClass}")
       case None                       => ManifestCreator.default
     }
-    val version = resolveVersion(options)
     val opts = PublishLocal.Options(
       groupId = options.groupId,
-      version = version,
+      version = publishVersion(options.version),
       publishTarget = target,
       projects = options.projects.asScala.iterator.map(JModel.toCross).toArray,
       manifestCreator = manifestCreator
@@ -159,16 +158,12 @@ final class JCommands(started: Started) extends bleepscript.Commands {
       case Some(other)                => throw new RuntimeException(s"Unknown ManifestCreator impl: ${other.getClass}")
       case None                       => ManifestCreator.default
     }
-    val versionOverride = toScalaOpt(options.versionOverride)
-    val versionFallback = toScalaOpt(options.versionFallback).map(supplier => () => supplier.get())
-
     options.target match {
       case _: bleepscript.PublishTarget.LocalIvy =>
         val target = PublishLocal.LocalIvy
-        val version = resolveVersion(options)
         val opts = PublishLocal.Options(
           groupId = options.groupId,
-          version = version,
+          version = publishVersion(options.version),
           publishTarget = target,
           projects = options.projects.asScala.iterator.map(JModel.toCross).toArray,
           manifestCreator = manifestCreator
@@ -177,10 +172,9 @@ final class JCommands(started: Started) extends bleepscript.Commands {
 
       case mf: bleepscript.PublishTarget.MavenFolder =>
         val target = PublishLocal.CustomMaven(model.Repository.MavenFolder(None, mf.path))
-        val version = resolveVersion(options)
         val opts = PublishLocal.Options(
           groupId = options.groupId,
-          version = version,
+          version = publishVersion(options.version),
           publishTarget = target,
           projects = options.projects.asScala.iterator.map(JModel.toCross).toArray,
           manifestCreator = manifestCreator
@@ -189,8 +183,7 @@ final class JCommands(started: Started) extends bleepscript.Commands {
 
       case r: bleepscript.PublishTarget.Resolver =>
         val opts = Publish.Options(
-          versionOverride = versionOverride,
-          versionFallback = versionFallback,
+          version = publishVersion(options.version),
           assertRelease = options.assertRelease,
           dryRun = options.dryRun,
           target = Publish.Target.Resolver(model.ResolverName(r.name)),
@@ -204,7 +197,7 @@ final class JCommands(started: Started) extends bleepscript.Commands {
         // publishConfig in bleep.yaml. The SonatypeCentral target's fields are exposed on the
         // Java side for documentation and future use, but the Scala command treats bleep.yaml as
         // the source of truth so a script can't accidentally override what the build declares.
-        runPublishSonatype(options, manifestCreator, versionOverride)
+        runPublishSonatype(options, manifestCreator)
     }
   }
 
@@ -214,33 +207,27 @@ final class JCommands(started: Started) extends bleepscript.Commands {
       case Some(other)                => throw new RuntimeException(s"Unknown ManifestCreator impl: ${other.getClass}")
       case None                       => ManifestCreator.default
     }
-    val versionOverride = toScalaOpt(options.versionOverride)
-    runPublishSonatype(options, manifestCreator, versionOverride)
+    runPublishSonatype(options, manifestCreator)
   }
 
   private def runPublishSonatype(
       options: bleepscript.PublishOptions,
-      manifestCreator: ManifestCreator,
-      versionOverride: Option[String]
+      manifestCreator: ManifestCreator
   ): Unit =
     underlying.publishSonatype(
       PublishSonatype.Options(
-        versionOverride = versionOverride,
+        version = publishVersion(options.version),
         assertRelease = options.assertRelease,
         projectNames = options.projects.asScala.iterator.map(JModel.toCross).toArray,
         manifestCreator = manifestCreator
       )
     )
 
-  /** Resolve the version eagerly for the local-publish path, which expects a non-optional version. */
-  private def resolveVersion(options: bleepscript.PublishOptions): String =
-    toScalaOpt(options.versionOverride)
-      .orElse(toScalaOpt(options.versionFallback).map(_.get()))
-      .getOrElse(
-        throw new IllegalArgumentException(
-          "PublishOptions requires either an explicit version or a versionFallback"
-        )
-      )
+  private def publishVersion(v: bleepscript.PublishVersion): PublishVersion =
+    v match {
+      case s: bleepscript.PublishVersion.Specified => PublishVersion.Specified(s.value)
+      case _: bleepscript.PublishVersion.Dynver    => PublishVersion.Dynver
+    }
 
   private def toScalaOpt[T](o: Optional[T]): Option[T] =
     if (o.isPresent) Some(o.get) else None
diff --git a/bleep-tests/src/scala/bleep/PublishToHttpMavenRepoIT.scala b/bleep-tests/src/scala/bleep/PublishToHttpMavenRepoIT.scala
index 2d69f2c37..92206fe65 100644
--- a/bleep-tests/src/scala/bleep/PublishToHttpMavenRepoIT.scala
+++ b/bleep-tests/src/scala/bleep/PublishToHttpMavenRepoIT.scala
@@ -1,6 +1,6 @@
 package bleep
 
-import bleep.commands.Publish
+import bleep.commands.{Publish, PublishVersion}
 import bleep.packaging.ManifestCreator
 
 class PublishToHttpMavenRepoIT extends IntegrationTestHarness {
@@ -66,8 +66,7 @@ class PublishToHttpMavenRepoIT extends IntegrationTestHarness {
 
       commands.publish(
         Publish.Options(
-          versionOverride = Some("1.0.0"),
-          versionFallback = None,
+          version = PublishVersion.Specified("1.0.0"),
           assertRelease = false,
           dryRun = false,
           target = Publish.Target.Resolver(model.ResolverName("company-releases")),
@@ -133,8 +132,7 @@ class PublishToHttpMavenRepoIT extends IntegrationTestHarness {
       val ex = intercept[Throwable] {
         commands.publish(
           Publish.Options(
-            versionOverride = Some("1.0.0"),
-            versionFallback = None,
+            version = PublishVersion.Specified("1.0.0"),
             assertRelease = false,
             dryRun = false,
             target = Publish.Target.Resolver(model.ResolverName("company-releases")),
diff --git a/bleep-tests/src/scala/bleep/PublishVersionTest.scala b/bleep-tests/src/scala/bleep/PublishVersionTest.scala
new file mode 100644
index 000000000..deac38270
--- /dev/null
+++ b/bleep-tests/src/scala/bleep/PublishVersionTest.scala
@@ -0,0 +1,75 @@
+package bleep
+
+import bleep.commands.PublishVersion
+import bleep.internal.bleepLoggers
+import org.scalatest.funsuite.AnyFunSuite
+
+import java.nio.file.{Files, Path}
+
+/** Where a publish gets its version.
+  *
+  * The two cases are asserted separately because they differ in more than their source: `--assert-release` applies to the version bleep derives and not to one
+  * the caller spelled out, which used to be spelled `versionOverride.isEmpty` in two commands that then disagreed about how to decide whether a version was a
+  * snapshot — one inspected the string, the other asked dynver.
+  */
+class PublishVersionTest extends AnyFunSuite {
+
+  private val logger = bleepLoggers.silent
+
+  private def git(cwd: Path, args: String*): Unit =
+    cli(action = "git", cwd = cwd, cmd = "git" :: args.toList, logger = logger, out = cli.Out.ViaLogger(logger)).discard()
+
+  /** A git repo with one commit, tagged `v1.2.3`, and dynver's own environment neutralised so a tag really is what decides. */
+  private def gitRepo(f: Path => Unit): Unit = {
+    val dir = Files.createTempDirectory("bleep-publish-version-")
+    try {
+      git(dir, "init", "--initial-branch", "main")
+      git(dir, "config", "user.email", "test@example.com")
+      git(dir, "config", "user.name", "test")
+      Files.writeString(dir.resolve("a.txt"), "one")
+      git(dir, "add", ".")
+      git(dir, "commit", "-m", "one")
+      git(dir, "tag", "v1.2.3")
+      f(dir)
+    } finally bleep.internal.FileUtils.deleteDirectory(dir)
+  }
+
+  test("a specified version is published as given") {
+    gitRepo { dir =>
+      assert(PublishVersion.resolve(PublishVersion.Specified("9.9.9"), dir, assertRelease = false) == Right("9.9.9"))
+    }
+  }
+
+  test("--assert-release does not second-guess a version the caller spelled out") {
+    // Deliberate, and preserved from before this was an ADT: the flag is about what git state would produce, and bleep has no better source to contradict an
+    // explicit version with. A caller who types a snapshot version has said what they want.
+    gitRepo { dir =>
+      assert(PublishVersion.resolve(PublishVersion.Specified("1.0.0+3-abcdef-SNAPSHOT"), dir, assertRelease = true) == Right("1.0.0+3-abcdef-SNAPSHOT"))
+    }
+  }
+
+  test("dynver reads the tag, and lives inside bleep") {
+    // The point of the ADT: no supplier is passed in, and no caller has to know how to ask git. `Dynver` names the intent and bleep does the work.
+    gitRepo { dir =>
+      assert(PublishVersion.resolve(PublishVersion.Dynver, dir, assertRelease = false) == Right("1.2.3"))
+    }
+  }
+
+  test("--assert-release fails on a dirty tree") {
+    gitRepo { dir =>
+      Files.writeString(dir.resolve("a.txt"), "two")
+      PublishVersion.resolve(PublishVersion.Dynver, dir, assertRelease = true) match {
+        case Right(version) => fail(s"a dirty tree should not pass --assert-release, got version $version")
+        case Left(err)      =>
+          assert(err.message.contains("--assert-release"), s"unexpected message: ${err.message}")
+          assert(err.message.contains("snapshot"), s"the message should say what is wrong: ${err.message}")
+      }
+    }
+  }
+
+  test("a clean tag passes --assert-release") {
+    gitRepo { dir =>
+      assert(PublishVersion.resolve(PublishVersion.Dynver, dir, assertRelease = true) == Right("1.2.3"))
+    }
+  }
+}
diff --git a/bleepscript/src/main/java/bleepscript/PublishOptions.java b/bleepscript/src/main/java/bleepscript/PublishOptions.java
index a5d218cc6..bc236763d 100644
--- a/bleepscript/src/main/java/bleepscript/PublishOptions.java
+++ b/bleepscript/src/main/java/bleepscript/PublishOptions.java
@@ -4,12 +4,10 @@
 import java.util.List;
 import java.util.Objects;
 import java.util.Optional;
-import java.util.function.Supplier;
 
 public record PublishOptions(
     String groupId,
-    Optional<String> versionOverride,
-    Optional<Supplier<String>> versionFallback,
+    PublishVersion version,
     boolean assertRelease,
     boolean dryRun,
     PublishTarget target,
@@ -18,18 +16,13 @@ public record PublishOptions(
 
   public PublishOptions {
     Objects.requireNonNull(groupId, "groupId");
-    Objects.requireNonNull(versionOverride, "versionOverride");
-    Objects.requireNonNull(versionFallback, "versionFallback");
+    Objects.requireNonNull(version, "version");
     Objects.requireNonNull(target, "target");
     Objects.requireNonNull(projects, "projects");
     Objects.requireNonNull(manifestCreator, "manifestCreator");
     if (projects.isEmpty()) {
       throw new IllegalArgumentException("projects must not be empty");
     }
-    if (versionOverride.isEmpty() && versionFallback.isEmpty()) {
-      throw new IllegalArgumentException(
-          "at least one of versionOverride or versionFallback is required");
-    }
     projects = List.copyOf(projects);
   }
 
@@ -39,8 +32,7 @@ public static Builder builder() {
 
   public static final class Builder {
     private String groupId;
-    private String versionOverride;
-    private Supplier<String> versionFallback;
+    private PublishVersion version = PublishVersion.fromGit();
     private boolean assertRelease = false;
     private boolean dryRun = false;
     private PublishTarget target;
@@ -54,25 +46,30 @@ public Builder groupId(String groupId) {
       return this;
     }
 
-    /** Set the version explicitly. Takes precedence over {@link #versionFallback}. */
+    /** Publish exactly this version. */
     public Builder version(String version) {
-      this.versionOverride = Objects.requireNonNull(version, "version");
+      this.version = PublishVersion.of(version);
+      return this;
+    }
+
+    public Builder version(PublishVersion version) {
+      this.version = Objects.requireNonNull(version, "version");
       return this;
     }
 
     /**
-     * Set a fallback version supplier, called only when no explicit version is set. Typical use:
-     * derive the version from a git tag.
+     * Derive the version from git tags, which is also what happens when no version is set at all.
+     * Git is read when the publish runs.
      */
-    public Builder versionFallback(Supplier<String> versionFallback) {
-      this.versionFallback = Objects.requireNonNull(versionFallback, "versionFallback");
+    public Builder versionFromGit() {
+      this.version = PublishVersion.fromGit();
       return this;
     }
 
     /**
-     * When true, refuse to publish if the resolved version is not a release version (contains
-     * {@code +} or ends with {@code -SNAPSHOT}). Only applies to versions resolved via {@link
-     * #versionFallback}; explicit {@link #version} values are not checked.
+     * When true, refuse to publish if git state would produce a snapshot version. Applies only to
+     * {@link PublishVersion.Dynver}: a version you spelled out yourself is published as given,
+     * since bleep has no better source to contradict it with.
      */
     public Builder assertRelease(boolean assertRelease) {
       this.assertRelease = assertRelease;
@@ -149,12 +146,9 @@ public PublishOptions build() {
         throw new IllegalStateException(
             "target is required (toLocalIvy, toMavenFolder, or toResolver)");
       if (projects.isEmpty()) throw new IllegalStateException("at least one project is required");
-      if (versionOverride == null && versionFallback == null)
-        throw new IllegalStateException("at least one of version or versionFallback is required");
       return new PublishOptions(
           groupId,
-          Optional.ofNullable(versionOverride),
-          Optional.ofNullable(versionFallback),
+          version,
           assertRelease,
           dryRun,
           target,
diff --git a/bleepscript/src/main/java/bleepscript/PublishVersion.java b/bleepscript/src/main/java/bleepscript/PublishVersion.java
new file mode 100644
index 000000000..a3c031688
--- /dev/null
+++ b/bleepscript/src/main/java/bleepscript/PublishVersion.java
@@ -0,0 +1,43 @@
+package bleepscript;
+
+import java.util.Objects;
+
+/**
+ * Where a publish gets its version: you say it, or bleep derives it from git.
+ *
+ * <p>One value replacing two fields. {@link PublishOptions} used to carry {@code versionOverride}
+ * beside {@code versionFallback}, a {@code Supplier<String>} called only when the first was absent
+ * — so "exactly one of these must be set" was a rule checked at construction and thrown as an
+ * {@link IllegalArgumentException}, rather than something the type made impossible to get wrong.
+ * The laziness that motivated the supplier belongs to bleep, which now decides whether to consult
+ * git.
+ */
+public sealed interface PublishVersion permits PublishVersion.Specified, PublishVersion.Dynver {
+
+  /** Publish exactly this version. */
+  record Specified(String value) implements PublishVersion {
+    public Specified {
+      Objects.requireNonNull(value, "value");
+      if (value.isEmpty()) throw new IllegalArgumentException("version must not be empty");
+    }
+  }
+
+  /**
+   * Derive the version from git tags: {@code <tag>} on a clean tag, {@code
+   * <tag>+<distance>-<sha>[-SNAPSHOT]} otherwise. Git is consulted when the publish runs, not when
+   * these options are built.
+   */
+  final class Dynver implements PublishVersion {
+    public static final Dynver INSTANCE = new Dynver();
+
+    private Dynver() {}
+  }
+
+  static PublishVersion of(String version) {
+    return new Specified(version);
+  }
+
+  static PublishVersion fromGit() {
+    return Dynver.INSTANCE;
+  }
+}
diff --git a/docs/concepts/bleep-scripts.mdx b/docs/concepts/bleep-scripts.mdx
index 6331cc093..81d07554a 100644
--- a/docs/concepts/bleep-scripts.mdx
+++ b/docs/concepts/bleep-scripts.mdx
@@ -65,6 +65,11 @@ Your script gets three things:
           .build());
   ```
 
+  A publish takes its version from one of two places, and says which: `.version("1.0.0")` publishes
+  exactly that, and `.versionFromGit()` — the default when you set nothing — lets bleep derive it
+  from git tags when the publish runs. `--assert-release` applies only to the derived one; a version
+  you spelled out is published as given.
+
   `compile` hands back a `CompileReport`. Its `noOp()` is true when every project it compiled was
   already up to date, which is what a script tests before doing work that only matters when
   something was rebuilt:
diff --git a/docs/guides/ci-cd-setup.mdx b/docs/guides/ci-cd-setup.mdx
index 30ebecc5f..4acfeb164 100644
--- a/docs/guides/ci-cd-setup.mdx
+++ b/docs/guides/ci-cd-setup.mdx
@@ -279,7 +279,9 @@ jobs:
 
 `--assert-release` fails the job if dynver would emit a snapshot
 version (uncommitted changes, commits past the tag. No tags at
-all). See [Publish to Maven Central](/docs/tutorials/publish-to-maven)
+all). It has nothing to check when you pass `--version` yourself —
+an explicit version is published as given. See
+[Publish to Maven Central](/docs/tutorials/publish-to-maven)
 for the full release-pipeline story.
 
 ## CI flags
diff --git a/docs/reference/cli/publish-local.mdx b/docs/reference/cli/publish-local.mdx
index 542658873..29dc2a673 100644
--- a/docs/reference/cli/publish-local.mdx
+++ b/docs/reference/cli/publish-local.mdx
@@ -27,7 +27,7 @@ bleep publish-local <project name...> [flags]
 | Flag | Description |
 |------|-------------|
 | `--groupId <string>` | organization you will publish under |
-| `--version <string>` | version you will publish |
+| `--version <string>` | version you will publish (default: from git tags) |
 | `--to <path>` | publish to a maven repository at given path |
 | `--watch, -w` | start in watch mode |
 | `--no-tui` | disable TUI, keep the full streaming trace (for CI/agents that read logs) |
diff --git a/docs/tutorials/publish-to-maven.mdx b/docs/tutorials/publish-to-maven.mdx
index 6b62d8fc6..f0a58c672 100644
--- a/docs/tutorials/publish-to-maven.mdx
+++ b/docs/tutorials/publish-to-maven.mdx
@@ -114,7 +114,8 @@ What happens:
 
 Useful flags:
 
-- `--version 1.2.3`, override the dynver-inferred version.
+- `--version 1.2.3`, publish exactly this instead of asking git. Not
+  second-guessed by `--assert-release`: you said what you wanted.
 - `--assert-release`, fail rather than publish a snapshot. Use this
   in CI release jobs.
 - `mylib`, publish only the named project (and its publishable

From 99cc158385552b8bd05344348661a3ecebb1d4fb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=98yvind=20Raddum=20Berg?= <elacin@gmail.com>
Date: Tue, 1 Sep 2026 21:59:19 +0200
Subject: [PATCH 07/13] kotlin/js: the build's declared module kind is read,
 and link and test share one output directory
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two loose ends noted while fixing #664 and #673, both of which turned out to be
hiding a third thing.

**Kotlin/JS ignored `kotlin.js.moduleKind`.** The main link read the
`--module-kind` flag and otherwise used a hardcoded CommonJS, so a build
declaring `es` got CommonJS and nothing said otherwise — the Kotlin half of
#664. The field is now read, with the same precedence Scala.js uses: flag, then
project, then the default.

`model.KotlinJs` had no reader anywhere in the server before this. All nine of
its fields were dead, so only `moduleKind` is added to `schema.json`; listing
the rest would advertise settings that still do nothing.

**Kotlin/JS test links stay UMD, and now say so.** Unlike Scala.js, where the
adapter picks its `Input` per module kind, bleep runs Kotlin/JS tests by
generating a CommonJS script that installs a QUnit mock as a global and then
`require`s the output. ES modules make that throw; plain and AMD do not export
what the runner reads. So the declaration cannot be honoured there — and a
project that declares one now gets a warning rather than a silent substitution.
A warning and not a failure: those builds' tests pass today, and breaking them
to report a limitation of the runner is a poor trade.

**Honouring `es` uncovered why nobody could have used it.** Kotlin names ES
output `<module>.mjs`; the output lookup only knew `.js`, so it found nothing —
and the caller reported that as "Kotlin/JS linking failed" with an empty
diagnostic list, for a compiler that had exited 0 with nothing to complain
about. Both fixed: `.mjs` is recognised, and a linker that succeeds while
producing no module now says that, and lists what it did write.

**link and test wrote to different directories.** The compile/link path passed
`LinkExecutor` a base of `targetDir/link-output`; the test path passed
`targetDir`. One project linked by both landed in two trees, each with an
up-to-date check blind to the other. `bleep run` reads the first, which is why
nothing noticed. This is #673's shape one level up: that fix stopped every
*suite* linking its own copy, this stops the two *commands* doing the same.

`TaskDag.KotlinJsConfig.outputDir` is gone with it. It had no reader —
`LinkExecutor` computes the directory for every platform — and the two callers
filled it with two different values, which is what made the paths look like they
disagreed when neither was being consulted.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../analysis/LinkDagIntegrationTest.scala     |  2 +-
 .../bleep/analysis/KotlinJsCompiler.scala     |  9 +-
 .../src/scala/bleep/bsp/LinkExecutor.scala    | 16 ++-
 .../bleep/bsp/MultiWorkspaceBspServer.scala   | 70 +++++++++----
 bleep-bsp/src/scala/bleep/bsp/TaskDag.scala   | 10 +-
 .../scala/bleep/KotlinJsModuleKindIT.scala    | 98 +++++++++++++++++++
 .../src/scala/bleep/TestLinkOutputDirIT.scala | 76 ++++++++++++++
 docs/concepts/cross-building.mdx              | 31 ++++++
 schema.json                                   | 20 ++++
 9 files changed, 305 insertions(+), 27 deletions(-)
 create mode 100644 bleep-tests/src/scala/bleep/KotlinJsModuleKindIT.scala
 create mode 100644 bleep-tests/src/scala/bleep/TestLinkOutputDirIT.scala

diff --git a/bleep-bsp-tests/src/scala/bleep/analysis/LinkDagIntegrationTest.scala b/bleep-bsp-tests/src/scala/bleep/analysis/LinkDagIntegrationTest.scala
index 24664a0eb..59fb02108 100644
--- a/bleep-bsp-tests/src/scala/bleep/analysis/LinkDagIntegrationTest.scala
+++ b/bleep-bsp-tests/src/scala/bleep/analysis/LinkDagIntegrationTest.scala
@@ -398,7 +398,7 @@ class LinkDagIntegrationTest extends AnyFunSuite with Matchers {
     LinkPlatform.Jvm shouldBe a[LinkPlatform]
     LinkPlatform.ScalaJs("1.16.0", "3.3.3", ScalaJsLinkConfig.Debug) shouldBe a[LinkPlatform.ScalaJs]
     LinkPlatform.ScalaNative("0.5.6", "3.3.3", ScalaNativeLinkConfig.Debug) shouldBe a[LinkPlatform.ScalaNative]
-    LinkPlatform.KotlinJs("2.0.0", TaskDag.KotlinJsConfig(bleep.model.KotlinJsModuleKind.CommonJS, true, false, java.nio.file.Path.of("."))) shouldBe a[
+    LinkPlatform.KotlinJs("2.0.0", TaskDag.KotlinJsConfig(bleep.model.KotlinJsModuleKind.CommonJS, true, false)) shouldBe a[
       LinkPlatform.KotlinJs
     ]
     LinkPlatform.KotlinNative("2.0.0", TaskDag.KotlinNativeConfig("linux-x64", true, false, false)) shouldBe a[LinkPlatform.KotlinNative]
diff --git a/bleep-bsp/src/scala/bleep/analysis/KotlinJsCompiler.scala b/bleep-bsp/src/scala/bleep/analysis/KotlinJsCompiler.scala
index be2321f65..85cd35505 100644
--- a/bleep-bsp/src/scala/bleep/analysis/KotlinJsCompiler.scala
+++ b/bleep-bsp/src/scala/bleep/analysis/KotlinJsCompiler.scala
@@ -550,9 +550,12 @@ object KotlinJsLinker {
         return KotlinJsLinkResult(outputDir, None, exitCode)
       }
 
-      // Find the JS output file
-      val jsFile = outputDir.resolve(s"${config.moduleName}.js")
-      val jsFileOpt = if (Files.exists(jsFile)) Some(jsFile) else None
+      // Find the JS output file.
+      //
+      // `.mjs` as well as `.js`, because Kotlin names its output after the module kind: `moduleKind = es` emits `<moduleName>.mjs`, every other kind emits
+      // `<moduleName>.js`. Looking only for `.js` meant an ES link that the compiler had completed successfully came back with no file, and the caller reported
+      // that as "Kotlin/JS linking failed" with no diagnostics — the compiler had nothing to complain about.
+      val jsFileOpt = List(".js", ".mjs").map(ext => outputDir.resolve(config.moduleName + ext)).find(Files.exists(_))
 
       KotlinJsLinkResult(outputDir, jsFileOpt, exitCode)
     } catch {
diff --git a/bleep-bsp/src/scala/bleep/bsp/LinkExecutor.scala b/bleep-bsp/src/scala/bleep/bsp/LinkExecutor.scala
index a2b5c4837..a50c49281 100644
--- a/bleep-bsp/src/scala/bleep/bsp/LinkExecutor.scala
+++ b/bleep-bsp/src/scala/bleep/bsp/LinkExecutor.scala
@@ -410,8 +410,20 @@ object LinkExecutor {
                 val sourceMap = allFiles.find(_.toString.endsWith(".map"))
                 (TaskResult.Success, LinkResult.JsSuccess(result.jsFile.get, sourceMap, allFiles, wasUpToDate = false))
               } else {
-                logger.error(s"[LINK] Kotlin/JS linking failed")
-                (TaskResult.Failure("Kotlin/JS linking failed", List.empty), LinkResult.Failure("Linking failed", List.empty))
+                // Two different failures used to share one message and one empty diagnostic list. A compiler that reported errors is one thing; a compiler that
+                // exited 0 while bleep could not find what it wrote is a bleep problem, and saying "linking failed" for it sends the reader to look for a
+                // compile error that was never emitted.
+                val reason =
+                  if (result.exitCode != 0) "Kotlin/JS linking failed"
+                  else {
+                    val found = scala.util
+                      .Using(Files.list(jsOutputDir))(_.iterator().asScala.map(_.getFileName.toString).toList.sorted)
+                      .getOrElse(Nil)
+                    val listed = if (found.isEmpty) "the directory is empty" else found.mkString(", ")
+                    s"Kotlin/JS linker reported success but produced no module in $jsOutputDir ($listed)"
+                  }
+                logger.error(s"[LINK] $reason")
+                (TaskResult.Failure(reason, List.empty), LinkResult.Failure(reason, List.empty))
               }
             case Outcome.ThreadOutcome.Cancelled(reason) =>
               (TaskResult.Killed(reason), LinkResult.Cancelled)
diff --git a/bleep-bsp/src/scala/bleep/bsp/MultiWorkspaceBspServer.scala b/bleep-bsp/src/scala/bleep/bsp/MultiWorkspaceBspServer.scala
index f2fcb441b..d76bd292a 100644
--- a/bleep-bsp/src/scala/bleep/bsp/MultiWorkspaceBspServer.scala
+++ b/bleep-bsp/src/scala/bleep/bsp/MultiWorkspaceBspServer.scala
@@ -1818,20 +1818,11 @@ class MultiWorkspaceBspServer(
           (platformOpt, isKotlin) match {
             case (Some(model.PlatformId.Js), true) =>
               // Kotlin/JS
-              val projectPaths = started.projectPaths(crossName)
-              val outputDir = projectPaths.targetDir.resolve("link-output").resolve("js")
-              val moduleKind = linkOpts.moduleKind
-                .map {
-                  case "esmodule" => model.KotlinJsModuleKind.ESModule
-                  case "nomodule" => model.KotlinJsModuleKind.Plain
-                  case _          => model.KotlinJsModuleKind.CommonJS
-                }
-                .getOrElse(model.KotlinJsModuleKind.CommonJS)
+              val moduleKind = kotlinJsModuleKind(project, linkOpts.moduleKind)
               val config = TaskDag.KotlinJsConfig(
                 moduleKind = moduleKind,
                 sourceMap = linkOpts.sourceMaps.getOrElse(!isRelease),
-                dce = linkOpts.optimize.getOrElse(isRelease),
-                outputDir = outputDir
+                dce = linkOpts.optimize.getOrElse(isRelease)
               )
               Some(crossName -> TaskDag.LinkPlatform.KotlinJs(kotlinVersion, config))
 
@@ -2355,14 +2346,14 @@ class MultiWorkspaceBspServer(
 
         (platformOpt, isKotlin) match {
           case (Some(model.PlatformId.Js), true) =>
-            // Kotlin/JS - don't add "js" here; executeKotlinJs adds it
-            val projectPaths = started.projectPaths(crossName)
-            val outputDir = projectPaths.targetDir
+            // Kotlin/JS. UMD is not an arbitrary default here, and not the project's to choose: bleep runs Kotlin/JS tests by generating a CommonJS script that
+            // installs a QUnit mock as a global and then `require`s the linked output. UMD is what satisfies that — an ES module makes `require` throw
+            // `ERR_REQUIRE_ESM`, and a plain or AMD module does not export what the runner reads. A project declaring one of those is warned rather than
+            // silently linked as something else; see `kotlinJsTestModuleKind`.
             val config = TaskDag.KotlinJsConfig(
-              moduleKind = model.KotlinJsModuleKind.UMD,
+              moduleKind = kotlinJsTestModuleKind(started, crossName, project),
               sourceMap = false,
-              dce = false, // Tests run without DCE
-              outputDir = outputDir
+              dce = false // Tests run without DCE
             )
             Some(crossName -> TaskDag.LinkPlatform.KotlinJs(kotlinVersion, config))
 
@@ -2639,7 +2630,9 @@ class MultiWorkspaceBspServer(
               IO.blocking(getTestClasspath(started, linkTask.project)).flatMap { classpath =>
                 val projectPaths = started.projectPaths(linkTask.project)
                 val logger = createLinkLogger()
-                val outputDir = projectPaths.targetDir
+                // The same base directory the compile/link path uses. These were `targetDir/link-output` and `targetDir`, so `bleep link mytest` and `bleep
+                // test mytest` linked the same project into two trees, each with its own up-to-date check that could not see the other's output.
+                val outputDir = projectPaths.targetDir.resolve("link-output")
                 withLinkMetrics(linkTask, started.buildPaths.buildDir.toString) {
                   LinkExecutor.execute(linkTask, classpath.map(_.toAbsolutePath), None, outputDir, logger, killSignal)
                 }
@@ -3580,6 +3573,47 @@ class MultiWorkspaceBspServer(
       })
       .getOrElse(fallback)
 
+  /** The module kind a Kotlin/JS link emits for `project`: an explicit `--module-kind` first, then the project's own `kotlin.js.moduleKind`, and only then
+    * CommonJS.
+    *
+    * The project was never consulted. `model.KotlinJs.moduleKind` has been in the build model — and in the schema, and presumably in someone's `bleep.yaml` —
+    * with no reader anywhere in the server, so a build declaring `es` got CommonJS and nothing said otherwise. This is the Kotlin half of the same defect
+    * `scalaJsModuleKind` fixes on the Scala.js side.
+    *
+    * The flag speaks the Scala.js vocabulary because it is one flag across both, so `nomodule` maps to Kotlin's `plain`.
+    */
+  private def kotlinJsModuleKind(project: model.Project, fromFlag: Option[String]): model.KotlinJsModuleKind =
+    fromFlag
+      .map {
+        case "esmodule" => model.KotlinJsModuleKind.ESModule
+        case "nomodule" => model.KotlinJsModuleKind.Plain
+        case _          => model.KotlinJsModuleKind.CommonJS
+      }
+      .orElse(project.kotlin.flatMap(_.js).flatMap(_.moduleKind))
+      .getOrElse(model.KotlinJsModuleKind.CommonJS)
+
+  /** UMD, and a warning when the project asked for something else.
+    *
+    * Unlike a Scala.js test link — where the adapter picks its `Input` per module kind and all three work — the Kotlin/JS test path has exactly one shape it
+    * can load. `KotlinTestRunner.Js` generates a CommonJS script that installs a QUnit mock as a global and then `require`s the linked output. `ESModule` makes
+    * that `require` throw, and `Plain` and `AMD` do not put the tests where the runner reads them. UMD satisfies it and is compatible with the rest.
+    *
+    * So the declaration cannot be honoured here, and the honest thing is to say so rather than substitute in silence — which is what the hardcoded constant
+    * did. A warning rather than a failure: these builds' tests run today, and breaking them to report a limitation of the runner would be a poor trade.
+    */
+  private def kotlinJsTestModuleKind(started: Started, crossName: CrossProjectName, project: model.Project): model.KotlinJsModuleKind = {
+    project.kotlin.flatMap(_.js).flatMap(_.moduleKind).filterNot(_ == model.KotlinJsModuleKind.UMD).foreach { declared =>
+      started.logger
+        .withContext("project", crossName.value)
+        .withContext("declared", declared.value)
+        .warn(
+          s"Kotlin/JS tests link as UMD regardless of `kotlin.js.moduleKind: ${declared.value}` — bleep's test runner loads the output with `require`. " +
+            "The main link honours the declaration; only the test link overrides it."
+        )
+    }
+    model.KotlinJsModuleKind.UMD
+  }
+
   /** Run a Scala.js test suite: link → run via Node.js, emit events to DAG queue. */
   private def runScalaJsTestSuite(
       started: Started,
diff --git a/bleep-bsp/src/scala/bleep/bsp/TaskDag.scala b/bleep-bsp/src/scala/bleep/bsp/TaskDag.scala
index 193e39e73..2573090c8 100644
--- a/bleep-bsp/src/scala/bleep/bsp/TaskDag.scala
+++ b/bleep-bsp/src/scala/bleep/bsp/TaskDag.scala
@@ -231,12 +231,16 @@ object TaskDag {
     case object Jvm extends LinkPlatform { val name: LinkPlatformName = LinkPlatformName.Jvm }
   }
 
-  /** Kotlin/JS configuration */
+  /** Kotlin/JS configuration.
+    *
+    * No `outputDir`: the field that used to be here had no reader. `LinkExecutor.execute` computes the output directory for every platform the same way, from
+    * the base directory it is handed plus the mode suffix, and Kotlin/JS was no exception — but the two callers filled this field with two *different*
+    * directories, which made the compile path and the test path look like they disagreed about where a link lands when neither was being consulted.
+    */
   case class KotlinJsConfig(
       moduleKind: KotlinJsModuleKind,
       sourceMap: Boolean,
-      dce: Boolean, // Dead Code Elimination - true = smaller output
-      outputDir: java.nio.file.Path
+      dce: Boolean // Dead Code Elimination - true = smaller output
   )
 
   /** Kotlin/Native configuration */
diff --git a/bleep-tests/src/scala/bleep/KotlinJsModuleKindIT.scala b/bleep-tests/src/scala/bleep/KotlinJsModuleKindIT.scala
new file mode 100644
index 000000000..3b8315851
--- /dev/null
+++ b/bleep-tests/src/scala/bleep/KotlinJsModuleKindIT.scala
@@ -0,0 +1,98 @@
+package bleep
+
+import bleep.commands.LinkOptions
+
+import java.nio.file.{Files, Path}
+import scala.jdk.CollectionConverters.*
+
+/** A Kotlin/JS link has to emit the module kind the build declared.
+  *
+  * This is the Kotlin half of #664. `model.KotlinJs.moduleKind` has been in the build model, and decodable from `bleep.yaml`, with no reader anywhere in the
+  * server — the link path read the `--module-kind` flag and otherwise used a hardcoded CommonJS. A build declaring `moduleKind: es` got CommonJS and nothing
+  * said otherwise.
+  *
+  * Asserted on the emitted JavaScript, for the same reason [[ScalaJsTestModuleKindIT]] is: the constant was consistent, and everything downstream of it agreed.
+  */
+class KotlinJsModuleKindIT extends IntegrationTestHarness {
+
+  private val myapp = model.CrossProjectName(model.ProjectName("myapp"), None)
+
+  private def yamlFor(moduleKind: Option[String]): String = {
+    val jsBlock = moduleKind.map(kind => s"      js:\n        moduleKind: $kind\n").getOrElse("")
+    s"""projects:
+       |  myapp:
+       |    platform:
+       |      name: js
+       |      jsNodeVersion: ${model.Versions.Node}
+       |      mainClass: example.MainKt
+       |    kotlin:
+       |      version: ${model.Versions.Kotlin24}
+       |$jsBlock""".stripMargin
+  }
+
+  private val Source =
+    """package example
+      |
+      |fun greet(name: String): String = "Hello, " + name + "!"
+      |
+      |fun main() {
+      |  println(greet("world"))
+      |}
+      |""".stripMargin
+
+  private def linkedJs(ws: Workspace): Path = {
+    val candidates = Files
+      .walk(ws.root.resolve(".bleep"))
+      .iterator()
+      .asScala
+      .filter(p => p.getFileName.toString.endsWith(".js") || p.getFileName.toString.endsWith(".mjs"))
+      .filter(p => Files.size(p) > 0)
+      .toList
+    if (candidates.isEmpty) fail(s"no linked JavaScript under ${ws.root}")
+    // The main module is the largest output; Kotlin/JS also emits small per-file chunks next to it.
+    val picked = candidates.maxBy(Files.size)
+    info(s"linked: ${candidates.map(p => s"${p.getFileName}=${Files.size(p)}B").mkString(", ")} -> picked ${picked.getFileName}")
+    picked
+  }
+
+  private def link(ws: Workspace): Path = {
+    val (_, commands, _) = ws.start()
+    commands.link(List(myapp), LinkOptions.Debug)
+    linkedJs(ws)
+  }
+
+  integrationTest("a Kotlin/JS link emits the ES module the build declared") { ws =>
+    ws.yaml(yamlFor(Some("es")))
+    ws.file("myapp/src/kotlin/example/Main.kt", Source)
+
+    val linked = link(ws)
+
+    // Asserted on the extension because that is Kotlin's own signal: it names ES output `<module>.mjs` and every other module kind `<module>.js`. Grepping the
+    // body for `export` is the weaker check — half a megabyte of generated JavaScript says many things — and the extension is what node reads to decide how to
+    // load the file.
+    assert(
+      linked.getFileName.toString.endsWith(".mjs"),
+      s"the link produced ${linked.getFileName}, not an .mjs module, so `kotlin.js.moduleKind: es` never reached it"
+    )
+    assert(
+      !Files.readString(linked).contains("module.exports"),
+      s"${linked.getFileName} still assigns to `module.exports`, so it is not really an ES module"
+    )
+    succeed
+  }
+
+  integrationTest("a Kotlin/JS link defaults to CommonJS when the build declares nothing") { ws =>
+    ws.yaml(yamlFor(None))
+    ws.file("myapp/src/kotlin/example/Main.kt", Source)
+
+    // The other direction, so the first test cannot pass by the linker having simply changed its default: with no declaration the output must still be the
+    // CommonJS `.js` it always was.
+    val linked = link(ws)
+    assert(linked.getFileName.toString.endsWith(".js"), s"the default link produced ${linked.getFileName}, expected a .js module")
+    assert(
+      Files.readString(linked).contains("module.exports"),
+      s"${linked.getFileName} does not assign to `module.exports`, so the default is no longer CommonJS"
+    )
+    succeed
+  }
+}
diff --git a/bleep-tests/src/scala/bleep/TestLinkOutputDirIT.scala b/bleep-tests/src/scala/bleep/TestLinkOutputDirIT.scala
new file mode 100644
index 000000000..7a5255282
--- /dev/null
+++ b/bleep-tests/src/scala/bleep/TestLinkOutputDirIT.scala
@@ -0,0 +1,76 @@
+package bleep
+
+import bleep.commands.LinkOptions
+
+import java.nio.file.{Files, Path}
+import scala.jdk.CollectionConverters.*
+
+/** `bleep link` and `bleep test` link a project into the same place.
+  *
+  * They did not. The compile/link path handed `LinkExecutor` a base of `targetDir/link-output`, the test path handed it `targetDir`, and the executor appended
+  * the mode suffix to whichever it got — so one project linked twice landed in two trees, each with an up-to-date check that could not see the other's output.
+  * `bleep run` reads the first of those, which is why the split was invisible: nothing ever looked in both.
+  *
+  * This is #673's shape surviving in the one spot #673's fix did not reach. That fix stopped every *suite* from linking its own copy; this stops the two
+  * *commands* from doing the same thing one level up.
+  */
+class TestLinkOutputDirIT extends IntegrationTestHarness {
+
+  private val mytest = model.CrossProjectName(model.ProjectName("mytest"), None)
+
+  private val Yaml =
+    s"""projects:
+       |  mytest:
+       |    dependencies:
+       |      - org.scalameta::munit:${model.Versions.Munit}
+       |    isTestProject: true
+       |    platform:
+       |      name: js
+       |      jsVersion: ${model.Versions.ScalaJs1}
+       |      jsNodeVersion: ${model.Versions.Node}
+       |      jsKind: commonjs
+       |    scala:
+       |      version: ${model.Versions.Scala3}
+       |""".stripMargin
+
+  private val Source =
+    """package example
+      |
+      |class OutputDirSuite extends munit.FunSuite {
+      |  test("runs") { assertEquals(1 + 1, 2) }
+      |}
+      |""".stripMargin
+
+  private def linkedModules(ws: Workspace): List[Path] =
+    Files
+      .walk(ws.root.resolve(".bleep"))
+      .iterator()
+      .asScala
+      .filter(p => p.getFileName.toString == "main.js")
+      .toList
+
+  integrationTest("linking a test project and testing it produce one output, not two") { ws =>
+    ws.yaml(Yaml)
+    ws.file("mytest/src/scala/example/OutputDirSuite.scala", Source)
+    val (_, commands, _) = ws.start()
+
+    commands.link(List(mytest), LinkOptions.Debug)
+    val afterLink = linkedModules(ws)
+    assert(afterLink.size == 1, s"expected one linked module after link, found ${afterLink.size}: ${afterLink.mkString(", ")}")
+
+    commands.test(List(mytest), watch = false, only = None, exclude = None, includeTags = None, excludeTags = None)
+    val afterTest = linkedModules(ws)
+
+    // The assertion that matters. With the two paths disagreeing this is 2 — one under `link-output/debug/js`, one under `debug/js` — and neither run can tell
+    // that the other already did the work.
+    assert(
+      afterTest.size == 1,
+      s"link and test wrote separate outputs:\n${afterTest.map(p => ws.root.relativize(p).toString).sorted.mkString("\n")}"
+    )
+    assert(
+      afterTest.head.toString.contains("link-output"),
+      s"the test link did not land under link-output, where `bleep link` and `bleep run` look: ${ws.root.relativize(afterTest.head)}"
+    )
+    succeed
+  }
+}
diff --git a/docs/concepts/cross-building.mdx b/docs/concepts/cross-building.mdx
index 596db494c..dc05f2437 100644
--- a/docs/concepts/cross-building.mdx
+++ b/docs/concepts/cross-building.mdx
@@ -128,6 +128,37 @@ projects:
           - platform-js
 ```
 
+## Choosing the JavaScript module format
+
+Both JS toolchains take the module format from the project, and both default to
+CommonJS:
+
+```yaml
+projects:
+  # Scala.js
+  frontend:
+    platform:
+      name: js
+      jsKind: esmodule        # none | commonjs | esmodule
+
+  # Kotlin/JS
+  widget:
+    kotlin:
+      version: 2.4.10
+      js:
+        moduleKind: es        # plain | amd | commonjs | umd | es
+```
+
+`bleep link --module-kind <kind>` overrides either one for a single run.
+
+Test links are the exception, and differ between the two. A Scala.js test link
+uses whatever the project declares, because the test adapter loads each module
+format correctly. A Kotlin/JS test link is always UMD: bleep runs those tests by
+`require`-ing the linked output from a generated script, which an ES module
+cannot satisfy. Declaring something else on a Kotlin/JS test project logs a
+warning and links UMD anyway rather than producing output the runner cannot
+load. The main link still honours the declaration.
+
 ## Per-cross customization
 
 Anything settable at the project level can be overridden inside a `cross:` entry, dependencies, scalac/javac options, source layouts, platform settings. The cross block wins for that variant; everything outside it is shared.
diff --git a/schema.json b/schema.json
index afc1c880e..793c68875 100644
--- a/schema.json
+++ b/schema.json
@@ -196,6 +196,23 @@
         }
       }
     },
+    "KotlinJs": {
+      "type": "object",
+      "description": "Kotlin/JS settings. Only `moduleKind` is read; the other fields on this block in bleep's model are not wired to anything yet and are deliberately not listed here.",
+      "properties": {
+        "moduleKind": {
+          "type": "string",
+          "enum": [
+            "plain",
+            "amd",
+            "commonjs",
+            "umd",
+            "es"
+          ],
+          "description": "Module format the Kotlin/JS linker emits. Default `commonjs`; `--module-kind` on `bleep link` overrides it. Not honoured for test links, which are always `umd` because bleep's Kotlin/JS test runner loads the output with `require`."
+        }
+      }
+    },
     "Kotlin": {
       "type": "object",
       "properties": {
@@ -210,6 +227,9 @@
           "type": "string",
           "description": "JVM bytecode target version (e.g., \"11\", \"17\", \"21\")"
         },
+        "js": {
+          "$ref": "#/$defs/KotlinJs"
+        },
         "kspVersion": {
           "type": "string",
           "description": "KSP-side version suffix (e.g. \"1.0.29\"). Bleep concatenates with `version` to form the full coord `com.google.devtools.ksp:symbol-processing-aa-embeddable:<kotlin>-<ksp>`. Required when `symbolProcessors` is non-empty or `scanForSymbolProcessors` is true."

From ad141457d0473c158187ba3e07f5800cc946a5e7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=98yvind=20Raddum=20Berg?= <elacin@gmail.com>
Date: Tue, 1 Sep 2026 22:14:38 +0200
Subject: [PATCH 08/13] =?UTF-8?q?tests:=20a=20link=20matrix=20=E2=80=94=20?=
 =?UTF-8?q?every=20target=20and=20mode,=20linked=20and=20then=20run?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`bleep test` has had a matrix since #682: every framework on every target, run
end to end, asserted on the JUnit XML. `bleep link` had per-piece tests — a
release link minifies, a test link honours `jsKind` — and nothing that took a
declaration, linked it, and ran the result.

That gap is where three defects sat at once, all found in the last few days: a
`--release` Scala.js link never called `withMinify`, a Kotlin/JS `es` link
reported "linking failed" because the output lookup only knew `.js`, and a test
link and a main link wrote into two different directories.

13 cases across four targets:

| target | cases |
|---|---|
| Scala.js | jsKind none / commonjs / esmodule, plus release |
| Kotlin/JS | default, umd, plain, es, amd |
| Scala Native | debug, release |
| Kotlin/Native | debug, release |

Each links, asserts on the artifact, and then **runs it and checks what it
printed**. Running is the part the per-piece tests could not do: a linked
program that is the wrong module kind still exists and still has plausible
bytes, and only node or the loader says otherwise.

Two details worth stating rather than leaving to be rediscovered:

- Every case asserts the path bleep *reported* — `BuildSummary.linkedOutputs`,
  new in this branch — rather than one the test reconstructed. A link that
  writes somewhere unexpected fails here instead of being quietly found by a
  directory walk.
- The AMD case is shape-only and says so. An AMD module defines itself into a
  loader node does not have, so "we did not run it" is recorded in the output
  rather than looking like coverage.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../src/scala/bleep/LinkMatrixCases.scala     | 247 ++++++++++++++++++
 .../src/scala/bleep/LinkMatrixIT.scala        |  95 +++++++
 2 files changed, 342 insertions(+)
 create mode 100644 bleep-tests/src/scala/bleep/LinkMatrixCases.scala
 create mode 100644 bleep-tests/src/scala/bleep/LinkMatrixIT.scala

diff --git a/bleep-tests/src/scala/bleep/LinkMatrixCases.scala b/bleep-tests/src/scala/bleep/LinkMatrixCases.scala
new file mode 100644
index 000000000..d53a3082b
--- /dev/null
+++ b/bleep-tests/src/scala/bleep/LinkMatrixCases.scala
@@ -0,0 +1,247 @@
+package bleep
+
+import bleep.commands.LinkOptions
+
+/** The concrete link matrix: one suite per target, one case per (mode, module kind) that target supports. */
+object LinkMatrixCases {
+
+  private def scalaJsProject(jsKind: String): String =
+    s"""  myapp:
+       |    platform:
+       |      name: js
+       |      jsVersion: ${model.Versions.ScalaJs1}
+       |      jsNodeVersion: ${model.Versions.Node}
+       |      jsKind: $jsKind
+       |      mainClass: example.Main
+       |    scala:
+       |      version: ${model.Versions.Scala3}
+       |""".stripMargin
+
+  private def kotlinJsProject(moduleKind: Option[String]): String = {
+    val js = moduleKind.map(kind => s"      js:\n        moduleKind: $kind\n").getOrElse("")
+    s"""  myapp:
+       |    platform:
+       |      name: js
+       |      jsNodeVersion: ${model.Versions.Node}
+       |      mainClass: example.MainKt
+       |    kotlin:
+       |      version: ${model.Versions.Kotlin24}
+       |$js""".stripMargin
+  }
+
+  private val scalaNativeProject: String =
+    s"""  myapp:
+       |    platform:
+       |      name: native
+       |      nativeVersion: ${model.Versions.ScalaNative05}
+       |      nativeGc: immix
+       |      mainClass: example.Main
+       |    scala:
+       |      version: ${model.Versions.Scala3}
+       |""".stripMargin
+
+  // `mainClass` is not decoration here: bleep derives Kotlin/Native's entry point from it (`example.MainKt` -> `example.main`), and without one the linker
+  // looks for `/main` in the root package and fails with "could not find '/main' function".
+  private val kotlinNativeProject: String =
+    s"""  myapp:
+       |    platform:
+       |      name: native
+       |      mainClass: example.MainKt
+       |    kotlin:
+       |      version: ${model.Versions.Kotlin24}
+       |""".stripMargin
+
+  private val isJs: String => Boolean = _.endsWith(".js")
+  private val isMjs: String => Boolean = _.endsWith(".mjs")
+  private val isBinary: String => Boolean = name => !name.endsWith(".js") && !name.endsWith(".mjs")
+
+  /** Scala.js. `jsKind` decides how the program leaves the module, and `--release` decides whether Closure and the minifier ran. */
+  val scalaJs: List[LinkCase] = List(
+    LinkCase(
+      name = "debug / jsKind none",
+      projectYaml = scalaJsProject("none"),
+      options = LinkOptions.Debug,
+      expectedFileName = isJs,
+      fileNameDescription = "main.js",
+      // A NoModule program is wrapped in `(function(){ ... }).call(this)`; the other kinds are a bare sequence of top-level statements.
+      mustContain = List(").call(this)"),
+      mustNotContain = Nil,
+      runnable = true
+    ),
+    LinkCase(
+      name = "debug / jsKind commonjs",
+      projectYaml = scalaJsProject("commonjs"),
+      options = LinkOptions.Debug,
+      expectedFileName = isJs,
+      fileNameDescription = "main.js",
+      mustContain = Nil,
+      mustNotContain = List(").call(this)"),
+      runnable = true
+    ),
+    LinkCase(
+      name = "debug / jsKind esmodule",
+      projectYaml = scalaJsProject("esmodule"),
+      options = LinkOptions.Debug,
+      expectedFileName = isJs,
+      fileNameDescription = "main.js",
+      mustContain = Nil,
+      mustNotContain = List(").call(this)"),
+      runnable = true
+    ),
+    LinkCase(
+      name = "release / jsKind commonjs",
+      projectYaml = scalaJsProject("commonjs"),
+      options = LinkOptions.Release,
+      expectedFileName = isJs,
+      fileNameDescription = "main.js",
+      mustContain = Nil,
+      // A release link minifies: the fully qualified Scala name survives a fast link and not an optimized one.
+      mustNotContain = List("example_Main"),
+      runnable = true
+    )
+  )
+
+  val scalaJsSource: (String, String) = (
+    "myapp/src/scala/example/Main.scala",
+    """package example
+      |
+      |object Main {
+      |  def main(args: Array[String]): Unit = println("linked-and-ran")
+      |}
+      |""".stripMargin
+  )
+
+  /** Kotlin/JS. Kotlin names ES output `.mjs` and everything else `.js`, which is the toolchain stating the module kind in the file name. */
+  val kotlinJs: List[LinkCase] = List(
+    LinkCase(
+      name = "debug / no declaration defaults to commonjs",
+      projectYaml = kotlinJsProject(None),
+      options = LinkOptions.Debug,
+      expectedFileName = isJs,
+      fileNameDescription = "a .js module",
+      mustContain = List("module.exports"),
+      mustNotContain = Nil,
+      runnable = true
+    ),
+    LinkCase(
+      name = "debug / moduleKind umd",
+      projectYaml = kotlinJsProject(Some("umd")),
+      options = LinkOptions.Debug,
+      expectedFileName = isJs,
+      fileNameDescription = "a .js module",
+      // UMD probes for both loaders before falling back to a global; that probe is the shape that distinguishes it from plain CommonJS.
+      mustContain = List("define.amd"),
+      mustNotContain = Nil,
+      runnable = true
+    ),
+    LinkCase(
+      name = "debug / moduleKind plain",
+      projectYaml = kotlinJsProject(Some("plain")),
+      options = LinkOptions.Debug,
+      expectedFileName = isJs,
+      fileNameDescription = "a .js module",
+      mustContain = Nil,
+      mustNotContain = List("module.exports"),
+      runnable = true
+    ),
+    LinkCase(
+      name = "debug / moduleKind es",
+      projectYaml = kotlinJsProject(Some("es")),
+      options = LinkOptions.Debug,
+      expectedFileName = isMjs,
+      fileNameDescription = "an .mjs module",
+      mustContain = Nil,
+      mustNotContain = List("module.exports"),
+      runnable = true
+    ),
+    LinkCase(
+      name = "debug / moduleKind amd",
+      projectYaml = kotlinJsProject(Some("amd")),
+      options = LinkOptions.Debug,
+      expectedFileName = isJs,
+      fileNameDescription = "a .js module",
+      mustContain = List("define("),
+      mustNotContain = Nil,
+      // An AMD module defines itself into a loader that node does not have.
+      runnable = false
+    )
+  )
+
+  val kotlinJsSource: (String, String) = (
+    "myapp/src/kotlin/example/Main.kt",
+    """package example
+      |
+      |fun main() {
+      |  println("linked-and-ran")
+      |}
+      |""".stripMargin
+  )
+
+  val scalaNative: List[LinkCase] = List(
+    LinkCase(
+      name = "debug",
+      projectYaml = scalaNativeProject,
+      options = LinkOptions.Debug,
+      expectedFileName = isBinary,
+      fileNameDescription = "a native binary",
+      mustContain = Nil,
+      mustNotContain = Nil,
+      runnable = true
+    ),
+    LinkCase(
+      name = "release",
+      projectYaml = scalaNativeProject,
+      options = LinkOptions.Release,
+      expectedFileName = isBinary,
+      fileNameDescription = "a native binary",
+      mustContain = Nil,
+      mustNotContain = Nil,
+      runnable = true
+    )
+  )
+
+  val scalaNativeSource: (String, String) = (
+    "myapp/src/scala/example/Main.scala",
+    """package example
+      |
+      |object Main {
+      |  def main(args: Array[String]): Unit = println("linked-and-ran")
+      |}
+      |""".stripMargin
+  )
+
+  val kotlinNative: List[LinkCase] = List(
+    LinkCase(
+      name = "debug",
+      projectYaml = kotlinNativeProject,
+      options = LinkOptions.Debug,
+      expectedFileName = isBinary,
+      fileNameDescription = "a native binary",
+      mustContain = Nil,
+      mustNotContain = Nil,
+      runnable = true
+    ),
+    LinkCase(
+      name = "release",
+      projectYaml = kotlinNativeProject,
+      options = LinkOptions.Release,
+      expectedFileName = isBinary,
+      fileNameDescription = "a native binary",
+      mustContain = Nil,
+      mustNotContain = Nil,
+      runnable = true
+    )
+  )
+
+  val kotlinNativeSource: (String, String) = kotlinJsSource
+}
+
+class ScalaJsLinkMatrixIT extends LinkMatrixIT("scala.js", LinkMatrixCases.scalaJs, LinkMatrixCases.scalaJsSource._1, LinkMatrixCases.scalaJsSource._2)
+
+class KotlinJsLinkMatrixIT extends LinkMatrixIT("kotlin/js", LinkMatrixCases.kotlinJs, LinkMatrixCases.kotlinJsSource._1, LinkMatrixCases.kotlinJsSource._2)
+
+class ScalaNativeLinkMatrixIT
+    extends LinkMatrixIT("scala native", LinkMatrixCases.scalaNative, LinkMatrixCases.scalaNativeSource._1, LinkMatrixCases.scalaNativeSource._2)
+
+class KotlinNativeLinkMatrixIT
+    extends LinkMatrixIT("kotlin/native", LinkMatrixCases.kotlinNative, LinkMatrixCases.kotlinNativeSource._1, LinkMatrixCases.kotlinNativeSource._2)
diff --git a/bleep-tests/src/scala/bleep/LinkMatrixIT.scala b/bleep-tests/src/scala/bleep/LinkMatrixIT.scala
new file mode 100644
index 000000000..86e57c591
--- /dev/null
+++ b/bleep-tests/src/scala/bleep/LinkMatrixIT.scala
@@ -0,0 +1,95 @@
+package bleep
+
+import bleep.commands.LinkOptions
+import org.scalatest.Assertion
+
+import java.nio.file.{Files, Path}
+
+/** One link, described end to end: what to build, how to link it, what the artifact should look like, and what it prints when run. */
+case class LinkCase(
+    name: String,
+    projectYaml: String,
+    options: LinkOptions,
+    /** The artifact's file name has to satisfy this. For JS the extension is the toolchain's own statement of module kind. */
+    expectedFileName: String => Boolean,
+    fileNameDescription: String,
+    mustContain: List[String],
+    mustNotContain: List[String],
+    /** Some outputs cannot be run by `node <file>` alone — AMD needs a loader. Those are asserted on shape only, and say so. */
+    runnable: Boolean
+)
+
+/** `bleep link` run end to end for every target and mode bleep supports, asserting on the artifact and then on what it prints.
+  *
+  * The counterpart to [[TestFrameworkMatrixIT]], which does the same for `bleep test`. Linking had per-piece tests — a release link minifies, a test link
+  * honours `jsKind` — and nothing that took a declaration, linked it, and ran the result. That gap is where three defects lived at once: a `--release` Scala.js
+  * link never ran Closure, a Kotlin/JS `es` link reported "linking failed" because the output lookup only knew `.js`, and a test link and a main link wrote to
+  * two different directories.
+  *
+  * Every case asserts the path bleep *reported* (`BuildSummary.linkedOutputs`), not a path the test reconstructed, so a link that writes somewhere unexpected
+  * fails here rather than being quietly found by a directory walk.
+  */
+abstract class LinkMatrixIT(platformName: String, cases: List[LinkCase], sourcePath: String, source: String) extends IntegrationTestHarness {
+
+  private val myapp = model.CrossProjectName(model.ProjectName("myapp"), None)
+
+  /** What every fixture prints, so "did it run" is one assertion for every target. */
+  private val Marker = "linked-and-ran"
+
+  cases.foreach { linkCase =>
+    integrationTest(s"$platformName / ${linkCase.name}") { ws =>
+      ws.yaml(s"projects:\n${linkCase.projectYaml}")
+      ws.file(sourcePath, source)
+      val (started, commands, _) = ws.start()
+
+      val summary = commands.link(List(myapp), linkCase.options)
+      val reported = summary.linkedOutputs
+      assert(reported.map(_.project) == List(myapp), s"expected one linked output for myapp, got ${reported.map(_.project.value)}")
+      val artifact = reported.head.mainArtifact
+      assert(Files.exists(artifact), s"bleep reported an artifact that is not there: $artifact")
+
+      val fileName = artifact.getFileName.toString
+      assert(linkCase.expectedFileName(fileName), s"linked artifact is '$fileName', expected ${linkCase.fileNameDescription}")
+
+      if (linkCase.mustContain.nonEmpty || linkCase.mustNotContain.nonEmpty) {
+        val body = Files.readString(artifact)
+        linkCase.mustContain.foreach(marker => assert(body.contains(marker), s"'$fileName' does not contain '$marker'"))
+        linkCase.mustNotContain.foreach(marker => assert(!body.contains(marker), s"'$fileName' contains '$marker' and should not"))
+      }
+
+      if (linkCase.runnable) {
+        val out = LinkMatrixIT.run(started, artifact, ws)
+        assert(out.contains(Marker), s"running '$fileName' did not print '$Marker'. Output:\n$out")
+      } else {
+        info(s"$fileName asserted on shape only — this module kind needs a loader to run")
+      }
+      succeed
+    }
+  }
+}
+
+object LinkMatrixIT {
+
+  /** Run a linked artifact and hand back everything it printed.
+    *
+    * A JS module goes through node; a native binary is executed directly. Scala.js emits ES-module syntax into a file still called `main.js`, and node picks a
+    * module system by extension — so that one case is copied to `.mjs` first, which is what a user deploying it has to do too.
+    */
+  def run(started: Started, artifact: Path, ws: Workspace): String = {
+    val name = artifact.getFileName.toString
+    val cmd =
+      if (name.endsWith(".js") || name.endsWith(".mjs")) {
+        val node = started.pre.fetchNode(model.Versions.Node).toAbsolutePath.toString
+        val body = Files.readString(artifact)
+        val isEsm = name.endsWith(".mjs") || body.linesIterator.exists(l => l.trim.startsWith("import ") || l.trim.startsWith("export "))
+        if (isEsm && name.endsWith(".js")) {
+          val asModule = artifact.resolveSibling(name.stripSuffix(".js") + ".mjs")
+          Files.copy(artifact, asModule, java.nio.file.StandardCopyOption.REPLACE_EXISTING)
+          List(node, asModule.toAbsolutePath.toString)
+        } else List(node, artifact.toAbsolutePath.toString)
+      } else List(artifact.toAbsolutePath.toString)
+
+    val logger = ryddig.Loggers.stdout(ryddig.LogPatterns.logFile, disableProgress = true).acquire().value
+    cli(action = "run linked", cwd = ws.root, cmd = cmd, logger = logger, out = cli.Out.ViaLogger(logger)).stdout.mkString("\n")
+  }
+}

From 06a2dc7abc839c55a6102cbfef02095a58c4bf1b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=98yvind=20Raddum=20Berg?= <elacin@gmail.com>
Date: Tue, 1 Sep 2026 22:44:45 +0200
Subject: [PATCH 09/13] kotlin/js: the rest of the block either works or is
 gone
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`model.KotlinJs` had nine fields and, until this branch, no reader at all. Now
that one of them is wired, the rest had to be settled either way.

**Threaded through — five.** `moduleName`, `sourceMap`, `sourceMapPrefix`,
`sourceMapEmbedSources`, `generateDts`. This turned out to be nearly free, and
for a reason worth writing down: bleep sets every one of these on the compiler
arguments unconditionally, so the question was never whether to support them but
which constant to hardcode. They now come from the build in the same order the
module kind does — flag, then project, then bleep's default. `sourceMapPrefix`
stays an `Option`, since it is the only one where "unset" is a real state the
compiler is never told about.

**Deleted — three, everywhere they appeared.**

- `target` (browser/nodejs/both) was never passed to kotlinc at all: there is no
  `setField` for it in either the compile or the link path, so it was dead on
  bleep's own `KotlinJsCompilerConfig` too, not just in the build model. It is
  not a compiler flag — in Gradle it selects a runner and a toolchain, which
  bleep does not have. Gone from the model, the schema's vocabulary, the
  compiler config, and its enum. If a browser runner ever lands it comes back
  with something behind it.
- `outputMode` was equally unread at both levels; the paths set `irProduceJs` /
  `irProduceKlibFile` directly, which is bleep deciding per phase, correctly.
- `developmentMode` is the same switch as `dce`, driven by `--optimize` and
  release mode. Two names for one knob is an invitation for them to disagree.

**And `moduleName` did not work when first wired.** The linker identifies the
project's own KLIB by matching file names against `config.moduleName` — fine
while that was always the project name, wrong the moment a build could change
it: the KLIB on disk is named after the project, so nothing matched, `includes`
was never set, and the link failed. One string was doing two jobs, and only one
of them is the user's to choose; the lookup now takes the project's name
explicitly.

Six link-matrix cases, one per field, each asserting on what the compiler
produced — a `.d.ts` appears, the artifact is `custom_name.js`, the map carries
`sourcesContent`, its sources are prefixed — rather than on the configuration it
was handed. Schema and the cross-building docs list the six that do something.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../CrossPlatformIntegrationTest.scala        |  3 -
 .../analysis/KotlinJsIntegrationTest.scala    | 17 +---
 .../analysis/LinkDagIntegrationTest.scala     |  5 +-
 .../analysis/PlatformCancellationTest.scala   |  4 -
 .../bleep/analysis/KotlinJsCompiler.scala     | 14 ++-
 .../analysis/KotlinJsCompilerConfig.scala     | 22 -----
 .../bleep/analysis/ProjectCompiler.scala      |  4 +-
 .../src/scala/bleep/bsp/LinkExecutor.scala    | 21 ++--
 .../bleep/bsp/MultiWorkspaceBspServer.scala   | 39 +++++++-
 bleep-bsp/src/scala/bleep/bsp/TaskDag.scala   |  6 +-
 .../src/scala/bleep/model/KotlinJs.scala      | 53 +---------
 .../src/scala/bleep/LinkMatrixCases.scala     | 98 ++++++++++++++++++-
 .../src/scala/bleep/LinkMatrixIT.scala        | 15 +++
 docs/concepts/cross-building.mdx              | 10 ++
 schema.json                                   | 25 +++++
 15 files changed, 219 insertions(+), 117 deletions(-)

diff --git a/bleep-bsp-tests/src/scala/bleep/analysis/CrossPlatformIntegrationTest.scala b/bleep-bsp-tests/src/scala/bleep/analysis/CrossPlatformIntegrationTest.scala
index d18f716c9..683438c3e 100644
--- a/bleep-bsp-tests/src/scala/bleep/analysis/CrossPlatformIntegrationTest.scala
+++ b/bleep-bsp-tests/src/scala/bleep/analysis/CrossPlatformIntegrationTest.scala
@@ -192,12 +192,9 @@ class CrossPlatformIntegrationTest extends AnyFunSuite with Matchers {
         KotlinJs(
           moduleKind = Some(KotlinJsModuleKind.ESModule),
           moduleName = Some("mymodule"),
-          outputMode = Some(KotlinJsOutputMode.JsExecutable),
           sourceMap = Some(true),
           sourceMapPrefix = None,
           sourceMapEmbedSources = None,
-          target = Some(KotlinJsTarget.Node),
-          developmentMode = Some(false),
           generateDts = Some(true)
         )
       ),
diff --git a/bleep-bsp-tests/src/scala/bleep/analysis/KotlinJsIntegrationTest.scala b/bleep-bsp-tests/src/scala/bleep/analysis/KotlinJsIntegrationTest.scala
index 4eb3dc5e7..98e14901f 100644
--- a/bleep-bsp-tests/src/scala/bleep/analysis/KotlinJsIntegrationTest.scala
+++ b/bleep-bsp-tests/src/scala/bleep/analysis/KotlinJsIntegrationTest.scala
@@ -65,7 +65,6 @@ class KotlinJsIntegrationTest extends AnyFunSuite with Matchers {
     val config = KotlinJsCompilerConfig.ForTests
     config.kotlinVersion shouldBe bleep.model.Versions.Kotlin23
     config.moduleKind shouldBe KotlinJsCompilerConfig.ModuleKind.CommonJS
-    config.outputMode shouldBe KotlinJsCompilerConfig.OutputMode.JsExecutable
     config.sourceMap shouldBe true
     config.developmentMode shouldBe true
     config.generateDts shouldBe false
@@ -79,22 +78,12 @@ class KotlinJsIntegrationTest extends AnyFunSuite with Matchers {
     KotlinJsCompilerConfig.ModuleKind.ESModule.name shouldBe "es"
   }
 
-  test("KotlinJsCompilerConfig: output modes") {
-    KotlinJsCompilerConfig.OutputMode.Klib.name shouldBe "klib"
-    KotlinJsCompilerConfig.OutputMode.JsExecutable.name shouldBe "js"
-  }
-
   test("KotlinJsCompilerConfig: source map embed sources") {
     KotlinJsCompilerConfig.SourceMapEmbedSources.Never.name shouldBe "never"
     KotlinJsCompilerConfig.SourceMapEmbedSources.Always.name shouldBe "always"
     KotlinJsCompilerConfig.SourceMapEmbedSources.Inlining.name shouldBe "inlining"
   }
 
-  test("KotlinJsCompilerConfig: targets") {
-    KotlinJsCompilerConfig.Target.Browser.name shouldBe "browser"
-    KotlinJsCompilerConfig.Target.Node.name shouldBe "nodejs"
-  }
-
   // ============================================================================
   // KotlinJsCompileResult Tests
   // ============================================================================
@@ -176,8 +165,7 @@ class KotlinJsAdvancedIntegrationTest extends AnyFunSuite with Matchers with Pla
       )
 
       val config = KotlinJsCompilerConfig.ForTests.copy(
-        moduleName = "hello",
-        outputMode = KotlinJsCompilerConfig.OutputMode.JsExecutable
+        moduleName = "hello"
       )
 
       val errors = scala.collection.mutable.ListBuffer[CompilerError]()
@@ -258,8 +246,7 @@ class KotlinJsAdvancedIntegrationTest extends AnyFunSuite with Matchers with Pla
       )
 
       val config = KotlinJsCompilerConfig.ForTests.copy(
-        moduleName = "mylib",
-        outputMode = KotlinJsCompilerConfig.OutputMode.Klib
+        moduleName = "mylib"
       )
 
       val listener = new DiagnosticListener {
diff --git a/bleep-bsp-tests/src/scala/bleep/analysis/LinkDagIntegrationTest.scala b/bleep-bsp-tests/src/scala/bleep/analysis/LinkDagIntegrationTest.scala
index 59fb02108..c5ae08a37 100644
--- a/bleep-bsp-tests/src/scala/bleep/analysis/LinkDagIntegrationTest.scala
+++ b/bleep-bsp-tests/src/scala/bleep/analysis/LinkDagIntegrationTest.scala
@@ -398,7 +398,10 @@ class LinkDagIntegrationTest extends AnyFunSuite with Matchers {
     LinkPlatform.Jvm shouldBe a[LinkPlatform]
     LinkPlatform.ScalaJs("1.16.0", "3.3.3", ScalaJsLinkConfig.Debug) shouldBe a[LinkPlatform.ScalaJs]
     LinkPlatform.ScalaNative("0.5.6", "3.3.3", ScalaNativeLinkConfig.Debug) shouldBe a[LinkPlatform.ScalaNative]
-    LinkPlatform.KotlinJs("2.0.0", TaskDag.KotlinJsConfig(bleep.model.KotlinJsModuleKind.CommonJS, true, false)) shouldBe a[
+    LinkPlatform.KotlinJs(
+      "2.0.0",
+      TaskDag.KotlinJsConfig(bleep.model.KotlinJsModuleKind.CommonJS, None, true, None, bleep.model.KotlinJsSourceMapEmbedSources.Never, false, false)
+    ) shouldBe a[
       LinkPlatform.KotlinJs
     ]
     LinkPlatform.KotlinNative("2.0.0", TaskDag.KotlinNativeConfig("linux-x64", true, false, false)) shouldBe a[LinkPlatform.KotlinNative]
diff --git a/bleep-bsp-tests/src/scala/bleep/analysis/PlatformCancellationTest.scala b/bleep-bsp-tests/src/scala/bleep/analysis/PlatformCancellationTest.scala
index 1b3b39215..fd18be3b4 100644
--- a/bleep-bsp-tests/src/scala/bleep/analysis/PlatformCancellationTest.scala
+++ b/bleep-bsp-tests/src/scala/bleep/analysis/PlatformCancellationTest.scala
@@ -60,11 +60,9 @@ class PlatformCancellationTest extends AnyFunSuite with Matchers {
         kotlinVersion = "2.3.0",
         moduleName = "test-module",
         moduleKind = KotlinJsCompilerConfig.ModuleKind.CommonJS,
-        outputMode = KotlinJsCompilerConfig.OutputMode.JsExecutable,
         sourceMap = false,
         sourceMapPrefix = None,
         sourceMapEmbedSources = KotlinJsCompilerConfig.SourceMapEmbedSources.Never,
-        target = KotlinJsCompilerConfig.Target.Node,
         developmentMode = true,
         generateDts = false,
         additionalOptions = Seq.empty
@@ -111,11 +109,9 @@ class PlatformCancellationTest extends AnyFunSuite with Matchers {
         kotlinVersion = "2.3.0",
         moduleName = "test-module",
         moduleKind = KotlinJsCompilerConfig.ModuleKind.CommonJS,
-        outputMode = KotlinJsCompilerConfig.OutputMode.JsExecutable,
         sourceMap = false,
         sourceMapPrefix = None,
         sourceMapEmbedSources = KotlinJsCompilerConfig.SourceMapEmbedSources.Never,
-        target = KotlinJsCompilerConfig.Target.Node,
         developmentMode = true,
         generateDts = false,
         additionalOptions = Seq.empty
diff --git a/bleep-bsp/src/scala/bleep/analysis/KotlinJsCompiler.scala b/bleep-bsp/src/scala/bleep/analysis/KotlinJsCompiler.scala
index 85cd35505..6ce349f1e 100644
--- a/bleep-bsp/src/scala/bleep/analysis/KotlinJsCompiler.scala
+++ b/bleep-bsp/src/scala/bleep/analysis/KotlinJsCompiler.scala
@@ -413,17 +413,19 @@ object KotlinJsLinker {
       klibs: Seq[Path],
       outputDir: Path,
       config: KotlinJsCompilerConfig,
+      projectKlibName: String,
       diagnosticListener: DiagnosticListener,
       cancellation: CancellationToken
   ): IO[bleep.bsp.Outcome.ThreadOutcome[KotlinJsLinkResult]] =
     bleep.bsp.Outcome.runInFreshThread[KotlinJsLinkResult](name = "kotlin-js-linker", contextClassLoader = None, cancellation = cancellation) {
-      linkBlocking(klibs, outputDir, config, diagnosticListener, cancellation)
+      linkBlocking(klibs, outputDir, config, projectKlibName, diagnosticListener, cancellation)
     }
 
   private def linkBlocking(
       klibs: Seq[Path],
       outputDir: Path,
       config: KotlinJsCompilerConfig,
+      projectKlibName: String,
       diagnosticListener: DiagnosticListener,
       cancellation: CancellationToken
   ): KotlinJsLinkResult = {
@@ -448,10 +450,14 @@ object KotlinJsLinker {
 
       // For linking, we pass KLIBs via includes field (the main KLIB to link) and libraries (dependencies)
       // The first KLIB is the main one to link, others are dependencies
+      // Which of these is the project's own KLIB, matched on the *project's* name rather than on `config.moduleName`.
+      //
+      // Those were the same string until `kotlin.js.moduleName` became a setting a build can change, and then they were not: the KLIB on disk is named after
+      // the project, so a project naming its module something else matched nothing, `includes` was never set, and the link failed with no diagnostic. One
+      // string was doing two jobs — naming the output, and identifying a file — and only one of them is the user's to choose.
       val (mainKlib, depKlibs) = klibs.partition { p =>
-        // The main KLIB is typically the one matching the module name
-        p.getFileName.toString.contains(config.moduleName.replace("_", "-")) ||
-        p.getFileName.toString.contains(config.moduleName)
+        p.getFileName.toString.contains(projectKlibName.replace("_", "-")) ||
+        p.getFileName.toString.contains(projectKlibName)
       }
 
       // Set main KLIB via includes field (not freeArgs which is interpreted as sources)
diff --git a/bleep-bsp/src/scala/bleep/analysis/KotlinJsCompilerConfig.scala b/bleep-bsp/src/scala/bleep/analysis/KotlinJsCompilerConfig.scala
index cc5ae6db5..59ba1814f 100644
--- a/bleep-bsp/src/scala/bleep/analysis/KotlinJsCompilerConfig.scala
+++ b/bleep-bsp/src/scala/bleep/analysis/KotlinJsCompilerConfig.scala
@@ -10,11 +10,9 @@ case class KotlinJsCompilerConfig(
     kotlinVersion: String,
     moduleKind: KotlinJsCompilerConfig.ModuleKind,
     moduleName: String,
-    outputMode: KotlinJsCompilerConfig.OutputMode,
     sourceMap: Boolean,
     sourceMapPrefix: Option[String],
     sourceMapEmbedSources: KotlinJsCompilerConfig.SourceMapEmbedSources,
-    target: KotlinJsCompilerConfig.Target,
     developmentMode: Boolean,
     generateDts: Boolean,
     additionalOptions: Seq[String]
@@ -34,15 +32,6 @@ object KotlinJsCompilerConfig {
     case object ESModule extends ModuleKind { val name = "es" }
   }
 
-  /** Output mode. */
-  sealed trait OutputMode {
-    def name: String
-  }
-  object OutputMode {
-    case object Klib extends OutputMode { val name = "klib" }
-    case object JsExecutable extends OutputMode { val name = "js" }
-  }
-
   /** Source map embedding. */
   sealed trait SourceMapEmbedSources {
     def name: String
@@ -53,15 +42,6 @@ object KotlinJsCompilerConfig {
     case object Inlining extends SourceMapEmbedSources { val name = "inlining" }
   }
 
-  /** Target environment. */
-  sealed trait Target {
-    def name: String
-  }
-  object Target {
-    case object Browser extends Target { val name = "browser" }
-    case object Node extends Target { val name = "nodejs" }
-  }
-
   /** A ready-made config for tests, not a default anything reads at build time. Production builds this explicitly in `ProjectCompiler` from the project's own
     * `kotlin.version`; nothing here is consulted. It was called `Default` and sat next to real defaults, which reads as "what a project gets when it says
     * nothing" — it is not, and that misreading is easy to act on.
@@ -70,11 +50,9 @@ object KotlinJsCompilerConfig {
     kotlinVersion = bleep.model.Versions.Kotlin23,
     moduleKind = ModuleKind.CommonJS,
     moduleName = "main",
-    outputMode = OutputMode.JsExecutable,
     sourceMap = true,
     sourceMapPrefix = None,
     sourceMapEmbedSources = SourceMapEmbedSources.Never,
-    target = Target.Node,
     developmentMode = true,
     generateDts = false,
     additionalOptions = Seq.empty
diff --git a/bleep-bsp/src/scala/bleep/analysis/ProjectCompiler.scala b/bleep-bsp/src/scala/bleep/analysis/ProjectCompiler.scala
index 16df1a25c..0458dac49 100644
--- a/bleep-bsp/src/scala/bleep/analysis/ProjectCompiler.scala
+++ b/bleep-bsp/src/scala/bleep/analysis/ProjectCompiler.scala
@@ -571,13 +571,13 @@ object KotlinJsProjectCompiler extends ProjectCompiler {
 
     val jsConfig = KotlinJsCompilerConfig(
       kotlinVersion = kt.kotlinVersion,
+      // The compile phase produces a KLIB, not a program: module kind, source-map shape and `.d.ts` generation are decided at link time, where the project's
+      // `kotlin.js` settings are read. Nothing here is a user-facing choice.
       moduleKind = KotlinJsCompilerConfig.ModuleKind.CommonJS,
       moduleName = config.name.replace("-", "_"),
-      outputMode = KotlinJsCompilerConfig.OutputMode.JsExecutable,
       sourceMap = true,
       sourceMapPrefix = None,
       sourceMapEmbedSources = KotlinJsCompilerConfig.SourceMapEmbedSources.Never,
-      target = KotlinJsCompilerConfig.Target.Node,
       developmentMode = true,
       generateDts = false,
       additionalOptions = kt.kotlinOptions
diff --git a/bleep-bsp/src/scala/bleep/bsp/LinkExecutor.scala b/bleep-bsp/src/scala/bleep/bsp/LinkExecutor.scala
index a50c49281..ece88946e 100644
--- a/bleep-bsp/src/scala/bleep/bsp/LinkExecutor.scala
+++ b/bleep-bsp/src/scala/bleep/bsp/LinkExecutor.scala
@@ -4,7 +4,7 @@ import bleep.analysis._
 import bleep.bsp.protocol.KillReason
 import bleep.bsp.TaskDag._
 import bleep.bsp.protocol.ProcessExit
-import bleep.model.KotlinJsModuleKind
+import bleep.model.{KotlinJsModuleKind, KotlinJsSourceMapEmbedSources}
 import cats.effect.{Deferred, IO}
 import java.nio.file.{Files, Path}
 import scala.jdk.CollectionConverters._
@@ -371,17 +371,22 @@ object LinkExecutor {
           case KotlinJsModuleKind.Plain    => KotlinJsCompilerConfig.ModuleKind.Plain
         }
 
+        val embedSources = platform.config.sourceMapEmbedSources match {
+          case KotlinJsSourceMapEmbedSources.Never    => KotlinJsCompilerConfig.SourceMapEmbedSources.Never
+          case KotlinJsSourceMapEmbedSources.Always   => KotlinJsCompilerConfig.SourceMapEmbedSources.Always
+          case KotlinJsSourceMapEmbedSources.Inlining => KotlinJsCompilerConfig.SourceMapEmbedSources.Inlining
+        }
+
         val config = KotlinJsCompilerConfig(
           kotlinVersion = platform.version,
-          moduleName = moduleName,
+          // The project's name for the module when it gave one; otherwise the project's own name, which is what it has always been.
+          moduleName = platform.config.moduleName.getOrElse(moduleName),
           moduleKind = moduleKind,
-          outputMode = KotlinJsCompilerConfig.OutputMode.JsExecutable,
           sourceMap = platform.config.sourceMap,
-          sourceMapPrefix = None,
-          sourceMapEmbedSources = KotlinJsCompilerConfig.SourceMapEmbedSources.Never,
-          target = KotlinJsCompilerConfig.Target.Node,
+          sourceMapPrefix = platform.config.sourceMapPrefix,
+          sourceMapEmbedSources = embedSources,
           developmentMode = !platform.config.dce, // DCE requires production mode
-          generateDts = false,
+          generateDts = platform.config.generateDts,
           additionalOptions = Seq.empty
         )
 
@@ -395,7 +400,7 @@ object LinkExecutor {
         }
 
         KotlinJsLinker
-          .link(klibs, jsOutputDir, config, diagnosticListener, cancellation)
+          .link(klibs, jsOutputDir, config, projectKlibName = moduleName, diagnosticListener, cancellation)
           .map {
             case Outcome.ThreadOutcome.Completed(result) =>
               logger.debug(s"[LINK] Kotlin/JS link result: isSuccess=${result.isSuccess}, jsFile=${result.jsFile}")
diff --git a/bleep-bsp/src/scala/bleep/bsp/MultiWorkspaceBspServer.scala b/bleep-bsp/src/scala/bleep/bsp/MultiWorkspaceBspServer.scala
index d76bd292a..b25763ef4 100644
--- a/bleep-bsp/src/scala/bleep/bsp/MultiWorkspaceBspServer.scala
+++ b/bleep-bsp/src/scala/bleep/bsp/MultiWorkspaceBspServer.scala
@@ -1819,9 +1819,11 @@ class MultiWorkspaceBspServer(
             case (Some(model.PlatformId.Js), true) =>
               // Kotlin/JS
               val moduleKind = kotlinJsModuleKind(project, linkOpts.moduleKind)
-              val config = TaskDag.KotlinJsConfig(
+              val config = kotlinJsConfig(
+                project,
                 moduleKind = moduleKind,
-                sourceMap = linkOpts.sourceMaps.getOrElse(!isRelease),
+                sourceMap = linkOpts.sourceMaps,
+                sourceMapDefault = !isRelease,
                 dce = linkOpts.optimize.getOrElse(isRelease)
               )
               Some(crossName -> TaskDag.LinkPlatform.KotlinJs(kotlinVersion, config))
@@ -2350,9 +2352,11 @@ class MultiWorkspaceBspServer(
             // installs a QUnit mock as a global and then `require`s the linked output. UMD is what satisfies that — an ES module makes `require` throw
             // `ERR_REQUIRE_ESM`, and a plain or AMD module does not export what the runner reads. A project declaring one of those is warned rather than
             // silently linked as something else; see `kotlinJsTestModuleKind`.
-            val config = TaskDag.KotlinJsConfig(
+            val config = kotlinJsConfig(
+              project,
               moduleKind = kotlinJsTestModuleKind(started, crossName, project),
-              sourceMap = false,
+              sourceMap = None,
+              sourceMapDefault = false,
               dce = false // Tests run without DCE
             )
             Some(crossName -> TaskDag.LinkPlatform.KotlinJs(kotlinVersion, config))
@@ -3592,6 +3596,33 @@ class MultiWorkspaceBspServer(
       .orElse(project.kotlin.flatMap(_.js).flatMap(_.moduleKind))
       .getOrElse(model.KotlinJsModuleKind.CommonJS)
 
+  /** The Kotlin/JS link settings for `project`.
+    *
+    * Every one of these has to have a value — bleep sets each on the compiler arguments unconditionally — so the question was never whether to support them but
+    * which constant to hardcode. They now come from the build where the build says something, in the same order as the module kind: an explicit flag first,
+    * then the project, then bleep's default.
+    *
+    * `sourceMapPrefix` is the one exception, and stays an `Option`: the compiler is only told about it when there is one.
+    */
+  private def kotlinJsConfig(
+      project: model.Project,
+      moduleKind: model.KotlinJsModuleKind,
+      sourceMap: Option[Boolean],
+      sourceMapDefault: Boolean,
+      dce: Boolean
+  ): TaskDag.KotlinJsConfig = {
+    val js = project.kotlin.flatMap(_.js)
+    TaskDag.KotlinJsConfig(
+      moduleKind = moduleKind,
+      moduleName = js.flatMap(_.moduleName),
+      sourceMap = sourceMap.orElse(js.flatMap(_.sourceMap)).getOrElse(sourceMapDefault),
+      sourceMapPrefix = js.flatMap(_.sourceMapPrefix),
+      sourceMapEmbedSources = js.flatMap(_.sourceMapEmbedSources).getOrElse(model.KotlinJsSourceMapEmbedSources.Never),
+      generateDts = js.flatMap(_.generateDts).getOrElse(false),
+      dce = dce
+    )
+  }
+
   /** UMD, and a warning when the project asked for something else.
     *
     * Unlike a Scala.js test link — where the adapter picks its `Input` per module kind and all three work — the Kotlin/JS test path has exactly one shape it
diff --git a/bleep-bsp/src/scala/bleep/bsp/TaskDag.scala b/bleep-bsp/src/scala/bleep/bsp/TaskDag.scala
index 2573090c8..87dcf6e95 100644
--- a/bleep-bsp/src/scala/bleep/bsp/TaskDag.scala
+++ b/bleep-bsp/src/scala/bleep/bsp/TaskDag.scala
@@ -4,7 +4,7 @@ import bleep.MachineResources
 import bleep.bsp.protocol.KillReason
 import bleep.bsp.protocol.{BleepBspProtocol, LinkPlatformName, OutputChannel, ProcessExit, SuiteOutcome, TestStatus}
 import bleep.bsp.protocol.BleepBspProtocol.BuildMode
-import bleep.model.{CrossProjectName, KotlinJsModuleKind, ScriptDef, SuiteName, TestName}
+import bleep.model.{CrossProjectName, KotlinJsModuleKind, KotlinJsSourceMapEmbedSources, ScriptDef, SuiteName, TestName}
 import cats.effect._
 import cats.effect.std.Queue
 import cats.syntax.all._
@@ -239,7 +239,11 @@ object TaskDag {
     */
   case class KotlinJsConfig(
       moduleKind: KotlinJsModuleKind,
+      moduleName: Option[String],
       sourceMap: Boolean,
+      sourceMapPrefix: Option[String],
+      sourceMapEmbedSources: KotlinJsSourceMapEmbedSources,
+      generateDts: Boolean,
       dce: Boolean // Dead Code Elimination - true = smaller output
   )
 
diff --git a/bleep-model/src/scala/bleep/model/KotlinJs.scala b/bleep-model/src/scala/bleep/model/KotlinJs.scala
index d948154de..6fae2cfa8 100644
--- a/bleep-model/src/scala/bleep/model/KotlinJs.scala
+++ b/bleep-model/src/scala/bleep/model/KotlinJs.scala
@@ -10,30 +10,21 @@ import io.circe.{Decoder, Encoder}
   *   The JS module kind (CommonJS, ESModule, UMD, Plain, AMD)
   * @param moduleName
   *   Optional custom module name
-  * @param outputMode
-  *   Output mode (Klib for library, JsExecutable for runnable)
   * @param sourceMap
   *   Whether to generate source maps
   * @param sourceMapPrefix
   *   Optional prefix for source map paths
   * @param sourceMapEmbedSources
   *   Whether/how to embed sources in source maps
-  * @param target
-  *   Target environment (Browser, Node, Both)
-  * @param developmentMode
-  *   If false, enables production optimizations
   * @param generateDts
   *   Whether to generate TypeScript declaration files
   */
 case class KotlinJs(
     moduleKind: Option[KotlinJsModuleKind],
     moduleName: Option[String],
-    outputMode: Option[KotlinJsOutputMode],
     sourceMap: Option[Boolean],
     sourceMapPrefix: Option[String],
     sourceMapEmbedSources: Option[KotlinJsSourceMapEmbedSources],
-    target: Option[KotlinJsTarget],
-    developmentMode: Option[Boolean],
     generateDts: Option[Boolean]
 ) extends SetLike[KotlinJs] {
 
@@ -41,12 +32,9 @@ case class KotlinJs(
     KotlinJs(
       moduleKind = if (moduleKind == other.moduleKind) moduleKind else None,
       moduleName = if (moduleName == other.moduleName) moduleName else None,
-      outputMode = if (outputMode == other.outputMode) outputMode else None,
       sourceMap = if (sourceMap == other.sourceMap) sourceMap else None,
       sourceMapPrefix = if (sourceMapPrefix == other.sourceMapPrefix) sourceMapPrefix else None,
       sourceMapEmbedSources = if (sourceMapEmbedSources == other.sourceMapEmbedSources) sourceMapEmbedSources else None,
-      target = if (target == other.target) target else None,
-      developmentMode = if (developmentMode == other.developmentMode) developmentMode else None,
       generateDts = if (generateDts == other.generateDts) generateDts else None
     )
 
@@ -54,12 +42,9 @@ case class KotlinJs(
     KotlinJs(
       moduleKind = if (moduleKind == other.moduleKind) None else moduleKind,
       moduleName = if (moduleName == other.moduleName) None else moduleName,
-      outputMode = if (outputMode == other.outputMode) None else outputMode,
       sourceMap = if (sourceMap == other.sourceMap) None else sourceMap,
       sourceMapPrefix = if (sourceMapPrefix == other.sourceMapPrefix) None else sourceMapPrefix,
       sourceMapEmbedSources = if (sourceMapEmbedSources == other.sourceMapEmbedSources) None else sourceMapEmbedSources,
-      target = if (target == other.target) None else target,
-      developmentMode = if (developmentMode == other.developmentMode) None else developmentMode,
       generateDts = if (generateDts == other.generateDts) None else generateDts
     )
 
@@ -67,31 +52,24 @@ case class KotlinJs(
     KotlinJs(
       moduleKind = moduleKind.orElse(other.moduleKind),
       moduleName = moduleName.orElse(other.moduleName),
-      outputMode = outputMode.orElse(other.outputMode),
       sourceMap = sourceMap.orElse(other.sourceMap),
       sourceMapPrefix = sourceMapPrefix.orElse(other.sourceMapPrefix),
       sourceMapEmbedSources = sourceMapEmbedSources.orElse(other.sourceMapEmbedSources),
-      target = target.orElse(other.target),
-      developmentMode = developmentMode.orElse(other.developmentMode),
       generateDts = generateDts.orElse(other.generateDts)
     )
 
   override def isEmpty: Boolean =
-    moduleKind.isEmpty && moduleName.isEmpty && outputMode.isEmpty &&
-      sourceMap.isEmpty && sourceMapPrefix.isEmpty && sourceMapEmbedSources.isEmpty &&
-      target.isEmpty && developmentMode.isEmpty && generateDts.isEmpty
+    moduleKind.isEmpty && moduleName.isEmpty && sourceMap.isEmpty &&
+      sourceMapPrefix.isEmpty && sourceMapEmbedSources.isEmpty && generateDts.isEmpty
 }
 
 object KotlinJs {
   val empty: KotlinJs = KotlinJs(
     moduleKind = None,
     moduleName = None,
-    outputMode = None,
     sourceMap = None,
     sourceMapPrefix = None,
     sourceMapEmbedSources = None,
-    target = None,
-    developmentMode = None,
     generateDts = None
   )
 
@@ -115,19 +93,6 @@ object KotlinJsModuleKind {
     EnumCodec.codec(All.map(x => (x.value, x)).toMap)
 }
 
-/** Kotlin/JS output mode. */
-sealed abstract class KotlinJsOutputMode(val value: String)
-
-object KotlinJsOutputMode {
-  case object Klib extends KotlinJsOutputMode("klib")
-  case object JsExecutable extends KotlinJsOutputMode("js")
-
-  val All: List[KotlinJsOutputMode] = List(Klib, JsExecutable)
-
-  implicit val codec: io.circe.Codec[KotlinJsOutputMode] =
-    EnumCodec.codec(All.map(x => (x.value, x)).toMap)
-}
-
 /** Kotlin/JS source map embedding mode. */
 sealed abstract class KotlinJsSourceMapEmbedSources(val value: String)
 
@@ -141,17 +106,3 @@ object KotlinJsSourceMapEmbedSources {
   implicit val codec: io.circe.Codec[KotlinJsSourceMapEmbedSources] =
     EnumCodec.codec(All.map(x => (x.value, x)).toMap)
 }
-
-/** Kotlin/JS target environment. */
-sealed abstract class KotlinJsTarget(val value: String)
-
-object KotlinJsTarget {
-  case object Browser extends KotlinJsTarget("browser")
-  case object Node extends KotlinJsTarget("nodejs")
-  case object Both extends KotlinJsTarget("both")
-
-  val All: List[KotlinJsTarget] = List(Browser, Node, Both)
-
-  implicit val codec: io.circe.Codec[KotlinJsTarget] =
-    EnumCodec.codec(All.map(x => (x.value, x)).toMap)
-}
diff --git a/bleep-tests/src/scala/bleep/LinkMatrixCases.scala b/bleep-tests/src/scala/bleep/LinkMatrixCases.scala
index d53a3082b..935d0e16a 100644
--- a/bleep-tests/src/scala/bleep/LinkMatrixCases.scala
+++ b/bleep-tests/src/scala/bleep/LinkMatrixCases.scala
@@ -17,8 +17,12 @@ object LinkMatrixCases {
        |      version: ${model.Versions.Scala3}
        |""".stripMargin
 
-  private def kotlinJsProject(moduleKind: Option[String]): String = {
-    val js = moduleKind.map(kind => s"      js:\n        moduleKind: $kind\n").getOrElse("")
+  private def kotlinJsProject(moduleKind: Option[String]): String =
+    kotlinJsProjectWith(moduleKind.map(kind => s"        moduleKind: $kind").toList)
+
+  /** A Kotlin/JS project carrying arbitrary `kotlin.js` settings, one per line. */
+  private def kotlinJsProjectWith(jsSettings: List[String]): String = {
+    val js = if (jsSettings.isEmpty) "" else s"      js:\n${jsSettings.mkString("\n")}\n"
     s"""  myapp:
        |    platform:
        |      name: js
@@ -66,6 +70,8 @@ object LinkMatrixCases {
       // A NoModule program is wrapped in `(function(){ ... }).call(this)`; the other kinds are a bare sequence of top-level statements.
       mustContain = List(").call(this)"),
       mustNotContain = Nil,
+      siblings = Nil,
+      siblingMustContain = Nil,
       runnable = true
     ),
     LinkCase(
@@ -76,6 +82,8 @@ object LinkMatrixCases {
       fileNameDescription = "main.js",
       mustContain = Nil,
       mustNotContain = List(").call(this)"),
+      siblings = Nil,
+      siblingMustContain = Nil,
       runnable = true
     ),
     LinkCase(
@@ -86,6 +94,8 @@ object LinkMatrixCases {
       fileNameDescription = "main.js",
       mustContain = Nil,
       mustNotContain = List(").call(this)"),
+      siblings = Nil,
+      siblingMustContain = Nil,
       runnable = true
     ),
     LinkCase(
@@ -97,6 +107,8 @@ object LinkMatrixCases {
       mustContain = Nil,
       // A release link minifies: the fully qualified Scala name survives a fast link and not an optimized one.
       mustNotContain = List("example_Main"),
+      siblings = Nil,
+      siblingMustContain = Nil,
       runnable = true
     )
   )
@@ -121,6 +133,8 @@ object LinkMatrixCases {
       fileNameDescription = "a .js module",
       mustContain = List("module.exports"),
       mustNotContain = Nil,
+      siblings = Nil,
+      siblingMustContain = Nil,
       runnable = true
     ),
     LinkCase(
@@ -132,6 +146,8 @@ object LinkMatrixCases {
       // UMD probes for both loaders before falling back to a global; that probe is the shape that distinguishes it from plain CommonJS.
       mustContain = List("define.amd"),
       mustNotContain = Nil,
+      siblings = Nil,
+      siblingMustContain = Nil,
       runnable = true
     ),
     LinkCase(
@@ -142,6 +158,8 @@ object LinkMatrixCases {
       fileNameDescription = "a .js module",
       mustContain = Nil,
       mustNotContain = List("module.exports"),
+      siblings = Nil,
+      siblingMustContain = Nil,
       runnable = true
     ),
     LinkCase(
@@ -152,6 +170,8 @@ object LinkMatrixCases {
       fileNameDescription = "an .mjs module",
       mustContain = Nil,
       mustNotContain = List("module.exports"),
+      siblings = Nil,
+      siblingMustContain = Nil,
       runnable = true
     ),
     LinkCase(
@@ -162,8 +182,74 @@ object LinkMatrixCases {
       fileNameDescription = "a .js module",
       mustContain = List("define("),
       mustNotContain = Nil,
+      siblings = Nil,
+      siblingMustContain = Nil,
       // An AMD module defines itself into a loader that node does not have.
       runnable = false
+    ),
+    // The rest of the `kotlin.js` block. Each of these was hardcoded until now — bleep set a value on the compiler arguments either way, so the question was
+    // never whether to support them but which constant to pick. One case per field, each asserting on something the compiler produced rather than on the
+    // configuration it was handed.
+    LinkCase(
+      name = "debug / moduleName names the artifact",
+      projectYaml = kotlinJsProjectWith(List("        moduleName: custom_name")),
+      options = LinkOptions.Debug,
+      expectedFileName = _ == "custom_name.js",
+      fileNameDescription = "custom_name.js",
+      mustContain = Nil,
+      mustNotContain = Nil,
+      siblings = Nil,
+      siblingMustContain = Nil,
+      runnable = true
+    ),
+    LinkCase(
+      name = "debug / sourceMap emits a map",
+      projectYaml = kotlinJsProjectWith(List("        sourceMap: true")),
+      options = LinkOptions.Debug,
+      expectedFileName = isJs,
+      fileNameDescription = "a .js module",
+      mustContain = Nil,
+      mustNotContain = Nil,
+      siblings = List(".js.map"),
+      siblingMustContain = Nil,
+      runnable = true
+    ),
+    LinkCase(
+      name = "debug / sourceMapEmbedSources always embeds the sources",
+      projectYaml = kotlinJsProjectWith(List("        sourceMap: true", "        sourceMapEmbedSources: always")),
+      options = LinkOptions.Debug,
+      expectedFileName = isJs,
+      fileNameDescription = "a .js module",
+      mustContain = Nil,
+      mustNotContain = Nil,
+      siblings = List(".js.map"),
+      // `sourcesContent` is the map field that carries the sources themselves, and it is absent under the `never` every link used to get.
+      siblingMustContain = List(".js.map" -> "sourcesContent"),
+      runnable = true
+    ),
+    LinkCase(
+      name = "debug / sourceMapPrefix prefixes the map's sources",
+      projectYaml = kotlinJsProjectWith(List("        sourceMap: true", "        sourceMapPrefix: bleep-prefix/")),
+      options = LinkOptions.Debug,
+      expectedFileName = isJs,
+      fileNameDescription = "a .js module",
+      mustContain = Nil,
+      mustNotContain = Nil,
+      siblings = List(".js.map"),
+      siblingMustContain = List(".js.map" -> "bleep-prefix/"),
+      runnable = true
+    ),
+    LinkCase(
+      name = "debug / generateDts emits TypeScript declarations",
+      projectYaml = kotlinJsProjectWith(List("        generateDts: true")),
+      options = LinkOptions.Debug,
+      expectedFileName = isJs,
+      fileNameDescription = "a .js module",
+      mustContain = Nil,
+      mustNotContain = Nil,
+      siblings = List(".d.ts"),
+      siblingMustContain = Nil,
+      runnable = true
     )
   )
 
@@ -186,6 +272,8 @@ object LinkMatrixCases {
       fileNameDescription = "a native binary",
       mustContain = Nil,
       mustNotContain = Nil,
+      siblings = Nil,
+      siblingMustContain = Nil,
       runnable = true
     ),
     LinkCase(
@@ -196,6 +284,8 @@ object LinkMatrixCases {
       fileNameDescription = "a native binary",
       mustContain = Nil,
       mustNotContain = Nil,
+      siblings = Nil,
+      siblingMustContain = Nil,
       runnable = true
     )
   )
@@ -219,6 +309,8 @@ object LinkMatrixCases {
       fileNameDescription = "a native binary",
       mustContain = Nil,
       mustNotContain = Nil,
+      siblings = Nil,
+      siblingMustContain = Nil,
       runnable = true
     ),
     LinkCase(
@@ -229,6 +321,8 @@ object LinkMatrixCases {
       fileNameDescription = "a native binary",
       mustContain = Nil,
       mustNotContain = Nil,
+      siblings = Nil,
+      siblingMustContain = Nil,
       runnable = true
     )
   )
diff --git a/bleep-tests/src/scala/bleep/LinkMatrixIT.scala b/bleep-tests/src/scala/bleep/LinkMatrixIT.scala
index 86e57c591..5c958b2fe 100644
--- a/bleep-tests/src/scala/bleep/LinkMatrixIT.scala
+++ b/bleep-tests/src/scala/bleep/LinkMatrixIT.scala
@@ -4,6 +4,7 @@ import bleep.commands.LinkOptions
 import org.scalatest.Assertion
 
 import java.nio.file.{Files, Path}
+import scala.jdk.CollectionConverters.*
 
 /** One link, described end to end: what to build, how to link it, what the artifact should look like, and what it prints when run. */
 case class LinkCase(
@@ -15,6 +16,10 @@ case class LinkCase(
     fileNameDescription: String,
     mustContain: List[String],
     mustNotContain: List[String],
+    /** Files that must appear beside the artifact — a source map, a `.d.ts`. Matched on the file name. */
+    siblings: List[String],
+    /** Assertions on a sibling's content, keyed by the same file-name match. */
+    siblingMustContain: List[(String, String)],
     /** Some outputs cannot be run by `node <file>` alone — AMD needs a loader. Those are asserted on shape only, and say so. */
     runnable: Boolean
 )
@@ -57,6 +62,16 @@ abstract class LinkMatrixIT(platformName: String, cases: List[LinkCase], sourceP
         linkCase.mustNotContain.foreach(marker => assert(!body.contains(marker), s"'$fileName' contains '$marker' and should not"))
       }
 
+      val beside = Files.list(artifact.getParent).iterator().asScala.map(_.getFileName.toString).toList.sorted
+      linkCase.siblings.foreach { wanted =>
+        assert(beside.exists(_.endsWith(wanted)), s"expected a '$wanted' beside $fileName, found: ${beside.mkString(", ")}")
+      }
+      linkCase.siblingMustContain.foreach { case (wanted, marker) =>
+        val sibling = beside.find(_.endsWith(wanted)).getOrElse(fail(s"no '$wanted' beside $fileName, found: ${beside.mkString(", ")}"))
+        val body = Files.readString(artifact.resolveSibling(sibling))
+        assert(body.contains(marker), s"'$sibling' does not contain '$marker'")
+      }
+
       if (linkCase.runnable) {
         val out = LinkMatrixIT.run(started, artifact, ws)
         assert(out.contains(Marker), s"running '$fileName' did not print '$Marker'. Output:\n$out")
diff --git a/docs/concepts/cross-building.mdx b/docs/concepts/cross-building.mdx
index dc05f2437..88cd5bb8b 100644
--- a/docs/concepts/cross-building.mdx
+++ b/docs/concepts/cross-building.mdx
@@ -151,6 +151,16 @@ projects:
 
 `bleep link --module-kind <kind>` overrides either one for a single run.
 
+The rest of the Kotlin/JS block:
+
+| setting | default | effect |
+|---|---|---|
+| `moduleName` | project name, `-` as `_` | names the module and the file it lands in |
+| `sourceMap` | on for debug, off for `--release` | emits a `.js.map`; `--source-maps` overrides |
+| `sourceMapPrefix` | unset | prefix for source paths inside the map |
+| `sourceMapEmbedSources` | `never` | `always` or `inlining` put the sources in the map |
+| `generateDts` | `false` | emits TypeScript declarations next to the module |
+
 Test links are the exception, and differ between the two. A Scala.js test link
 uses whatever the project declares, because the test adapter loads each module
 format correctly. A Kotlin/JS test link is always UMD: bleep runs those tests by
diff --git a/schema.json b/schema.json
index 793c68875..52baa9da5 100644
--- a/schema.json
+++ b/schema.json
@@ -210,6 +210,31 @@
             "es"
           ],
           "description": "Module format the Kotlin/JS linker emits. Default `commonjs`; `--module-kind` on `bleep link` overrides it. Not honoured for test links, which are always `umd` because bleep's Kotlin/JS test runner loads the output with `require`."
+        },
+        "moduleName": {
+          "type": "string",
+          "description": "Name of the emitted module, and of the file it lands in. Defaults to the project name with `-` replaced by `_`."
+        },
+        "sourceMap": {
+          "type": "boolean",
+          "description": "Emit a `.js.map` beside the module. Defaults to on for a debug link and off for `--release`; `--source-maps` / `--no-source-maps` override both."
+        },
+        "sourceMapPrefix": {
+          "type": "string",
+          "description": "Prefix prepended to source paths inside the source map. Unset means the compiler is not told about one at all."
+        },
+        "sourceMapEmbedSources": {
+          "type": "string",
+          "enum": [
+            "never",
+            "always",
+            "inlining"
+          ],
+          "description": "Whether the source map carries the sources themselves. Default `never`; `always` embeds every source, `inlining` embeds only sources that were inlined."
+        },
+        "generateDts": {
+          "type": "boolean",
+          "description": "Emit TypeScript declarations (`.d.ts`) next to the module. Default false."
         }
       }
     },

From 20ccc2763d90b2988c0df94ea4dd393aaba009d6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=98yvind=20Raddum=20Berg?= <elacin@gmail.com>
Date: Wed, 2 Sep 2026 00:18:19 +0200
Subject: [PATCH 10/13] tests: the in-process server is given its config and
 shares one governor
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two things the in-process BSP server used to invent for itself, both of which
undid what its caller was trying to say.

**The config.** `handleTest` and `handleCompile` re-read the developer's own
`config.yaml` per request. That is right for the real daemon — `parallelism`,
the heaps and the idle timeout are machine settings, and picking up an edit
without a restart is the point — but there was no way for a caller that already
has a config to be heard. So bleep's own integration tests were carefully
setting `parallelism = 1`, `testRunnerHeap = 512m` and `kspRunnerMaxMemory =
384m`, with a long comment about the explosion of test JVMs those prevent, and
every one of them was ignored in favour of whatever the person running the suite
happened to have in their file. `configOverride` is `None` for the daemon, so
production behaviour is unchanged.

**The governor.** Each connection built `MachineResources.forThisMachine` —
every core, most of the RAM — so a suite running integration tests concurrently
had one governor per connection, each admitting forks as though nothing else
were running. A governor bounds forks *across* clients, which is only true if
there is one of it. The harness now makes one and shares it, deliberately small
at 2 cores and 2GB: this JVM is itself one of several the outer `bleep test`
forked, and those outer forks are governed by a daemon that cannot see anything
started in here.

**And `close` waits.** Closing the pipes is what tells `run()` to return, but
nothing waited for it, so a test could finish and the next one start while the
previous server was still cancelling requests and killing child processes. The
wait is bounded — a server that will not come down must not hang the suite
trying to leave.

`SuiteIdleTimeoutIT` pins both this and the idle-timeout semantics it depends
on: a suite that prints while finishing no test is idle *by design*, and is
killed. Showing that needs a one-minute timeout, which needs the harness's
config to actually arrive — with the override removed the fixture runs to
completion against the developer's own three-minute setting and the test fails
saying so.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../scala/bleep/analysis/BspTestHarness.scala |  3 +-
 .../bleep/bsp/BleepStatusEndpointTest.scala   |  3 +-
 .../bleep/bsp/CopyStateEndpointTest.scala     |  3 +-
 .../src/scala/bleep/bsp/BspServerDaemon.scala |  4 +-
 .../scala/bleep/bsp/InProcessBspServer.scala  | 43 ++++++++---
 .../bleep/bsp/MultiWorkspaceBspServer.scala   | 20 ++++--
 .../scala/bleep/IntegrationTestHarness.scala  | 28 +++++++-
 bleep-tests/src/scala/bleep/Sip51Tests.scala  |  5 +-
 .../src/scala/bleep/SuiteIdleTimeoutIT.scala  | 71 +++++++++++++++++++
 9 files changed, 156 insertions(+), 24 deletions(-)
 create mode 100644 bleep-tests/src/scala/bleep/SuiteIdleTimeoutIT.scala

diff --git a/bleep-bsp-tests/src/scala/bleep/analysis/BspTestHarness.scala b/bleep-bsp-tests/src/scala/bleep/analysis/BspTestHarness.scala
index c0239bcca..f60c79905 100644
--- a/bleep-bsp-tests/src/scala/bleep/analysis/BspTestHarness.scala
+++ b/bleep-bsp-tests/src/scala/bleep/analysis/BspTestHarness.scala
@@ -222,7 +222,8 @@ class BspTestHarness(workspaceRoot: Path, projectConfigs: Option[List[BspTestHar
       buildCache = new BuildCache(bleep.model.BspServerConfig.default.maxCachedWorkspacesFor(Runtime.getRuntime.maxMemory()), harnessAnalysisCache),
       analysisCache = harnessAnalysisCache,
       daemonInfo = DaemonInfo.inProcess(bleep.model.BspServerConfig.default),
-      connId = 1
+      connId = 1,
+      configOverride = None
     )
 
     val buildPayload: Option[BspBuildData.Payload] =
diff --git a/bleep-bsp-tests/src/scala/bleep/bsp/BleepStatusEndpointTest.scala b/bleep-bsp-tests/src/scala/bleep/bsp/BleepStatusEndpointTest.scala
index 73090b98f..f6318c5e5 100644
--- a/bleep-bsp-tests/src/scala/bleep/bsp/BleepStatusEndpointTest.scala
+++ b/bleep-bsp-tests/src/scala/bleep/bsp/BleepStatusEndpointTest.scala
@@ -52,7 +52,8 @@ class BleepStatusEndpointTest extends AnyFunSuite with Matchers {
       buildCache = new BuildCache(4, analysisCache),
       analysisCache = analysisCache,
       daemonInfo = daemonInfo,
-      connId = 17
+      connId = 17,
+      configOverride = None
     )
 
     private val thread = new Thread(() => server.run(), "status-endpoint-test-server")
diff --git a/bleep-bsp-tests/src/scala/bleep/bsp/CopyStateEndpointTest.scala b/bleep-bsp-tests/src/scala/bleep/bsp/CopyStateEndpointTest.scala
index e1eeed937..cba0684e3 100644
--- a/bleep-bsp-tests/src/scala/bleep/bsp/CopyStateEndpointTest.scala
+++ b/bleep-bsp-tests/src/scala/bleep/bsp/CopyStateEndpointTest.scala
@@ -91,7 +91,8 @@ class CopyStateEndpointTest extends AnyFunSuite with Matchers {
       buildCache = new BuildCache(4, analysisCache),
       analysisCache = analysisCache,
       daemonInfo = daemonInfo,
-      connId = 17
+      connId = 17,
+      configOverride = None
     )
 
     private val thread = new Thread(() => server.run(), "copy-state-endpoint-test-server")
diff --git a/bleep-bsp/src/scala/bleep/bsp/BspServerDaemon.scala b/bleep-bsp/src/scala/bleep/bsp/BspServerDaemon.scala
index 470acfaf7..5dc488dd2 100644
--- a/bleep-bsp/src/scala/bleep/bsp/BspServerDaemon.scala
+++ b/bleep-bsp/src/scala/bleep/bsp/BspServerDaemon.scala
@@ -547,7 +547,9 @@ object BspServerDaemon {
         buildCache = buildCache,
         analysisCache = analysisCache,
         daemonInfo = daemonInfo,
-        connId = connId
+        connId = connId,
+        // The real daemon re-reads the user config per request on purpose; see `configOverride`.
+        configOverride = None
       )
 
       // Run server message loop
diff --git a/bleep-bsp/src/scala/bleep/bsp/InProcessBspServer.scala b/bleep-bsp/src/scala/bleep/bsp/InProcessBspServer.scala
index 94c7c63da..1ca640f40 100644
--- a/bleep-bsp/src/scala/bleep/bsp/InProcessBspServer.scala
+++ b/bleep-bsp/src/scala/bleep/bsp/InProcessBspServer.scala
@@ -1,6 +1,8 @@
 package bleep.bsp
 
 import cats.effect.{IO, Resource}
+
+import scala.concurrent.duration.*
 import ryddig.Logger
 
 import java.util.concurrent.CompletableFuture
@@ -11,7 +13,15 @@ import java.util.concurrent.CompletableFuture
   */
 object InProcessBspServer {
 
-  def connect(logger: Logger): Resource[IO, BspConnection] =
+  /** An in-process server, given the config it should use and a governor it should share.
+    *
+    * Both used to be invented here: the config was read from the developer's own `config.yaml` per request, and a `MachineResources` was built `forThisMachine`
+    * — sized for every core and most of the RAM — once per connection. A test suite running many of these concurrently therefore had as many governors as
+    * connections, each admitting forks as though it were the machine's only tenant, which is the opposite of what a governor is for.
+    *
+    * Callers now supply both, so a suite can share one governor across everything it runs and mean what it says about heaps and parallelism.
+    */
+  def connect(config: bleep.model.BleepConfig, machine: bleep.MachineResources)(logger: Logger): Resource[IO, BspConnection] =
     Resource.make(
       IO.blocking {
         // Two pipes carry the two directions. A megabyte of slack keeps a sourcegen run that logs faster than the
@@ -30,8 +40,6 @@ object InProcessBspServer {
           override def run(): Unit = {
             var exitCode: java.lang.Integer = 0
             try {
-              val numCores = Runtime.getRuntime.availableProcessors()
-              val machine = bleep.MachineResources.forThisMachine(totalCpu = numCores, logger = logger)
               val inProcessAnalysisCache = new bleep.analysis.AnalysisCache
               // One server per in-process run, so fresh daemon-scoped state is correct here.
               val server =
@@ -45,8 +53,9 @@ object InProcessBspServer {
                   buildCache =
                     new BuildCache(bleep.model.BspServerConfig.default.maxCachedWorkspacesFor(Runtime.getRuntime.maxMemory()), inProcessAnalysisCache),
                   analysisCache = inProcessAnalysisCache,
-                  daemonInfo = DaemonInfo.inProcess(bleep.model.BspServerConfig.default),
-                  connId = 1
+                  daemonInfo = DaemonInfo.inProcess(config.bspServerConfigOrDefault),
+                  connId = 1,
+                  configOverride = Some(config)
                 )
               server.run()
             } catch {
@@ -74,11 +83,23 @@ object InProcessBspServer {
       exited: CompletableFuture[java.lang.Integer]
   ) extends BspConnection {
     def serverExited: IO[Int] = IO.fromCompletableFuture(IO.pure(exited)).map(_.intValue)
-    def close: IO[Unit] = IO.blocking {
-      try output.close()
-      catch { case _: Exception => () }
-      try input.close()
-      catch { case _: Exception => () }
-    }
+
+    /** Close the transport, then wait for the server thread to finish unwinding.
+      *
+      * Closing the pipes is what tells `run()` to return, but nothing used to wait for it — so a test could finish, and start the next one, while the previous
+      * server was still cancelling requests and killing its child processes. The wait is bounded: a server that will not come down must not hang the suite that
+      * is trying to leave.
+      */
+    def close: IO[Unit] =
+      IO.blocking {
+        try output.close()
+        catch { case _: Exception => () }
+        try input.close()
+        catch { case _: Exception => () }
+      } >> IO
+        .fromCompletableFuture(IO.pure(exited))
+        .timeout(30.seconds)
+        .void
+        .handleError(_ => ())
   }
 }
diff --git a/bleep-bsp/src/scala/bleep/bsp/MultiWorkspaceBspServer.scala b/bleep-bsp/src/scala/bleep/bsp/MultiWorkspaceBspServer.scala
index b25763ef4..6728b4576 100644
--- a/bleep-bsp/src/scala/bleep/bsp/MultiWorkspaceBspServer.scala
+++ b/bleep-bsp/src/scala/bleep/bsp/MultiWorkspaceBspServer.scala
@@ -69,7 +69,15 @@ class MultiWorkspaceBspServer(
     buildCache: BuildCache,
     analysisCache: bleep.analysis.AnalysisCache,
     daemonInfo: DaemonInfo,
-    connId: Int
+    connId: Int,
+    /** The config to use instead of reading the user's `config.yaml`, when a caller already has one.
+      *
+      * Empty for the real daemon, which re-reads the file per request on purpose — `parallelism`, the heaps and the idle timeout are machine settings, and
+      * picking up an edit without a restart is the point. It is set by the in-process server, whose caller has a config it means: bleep's own integration tests
+      * were carefully setting `parallelism`, `testRunnerHeap` and `kspRunnerMaxMemory` and having every one of them ignored in favour of whatever the developer
+      * running the suite happened to have in their own file.
+      */
+    configOverride: Option[model.BleepConfig]
 ) {
   import MultiWorkspaceBspServer.DebugLogging
 
@@ -1008,7 +1016,7 @@ class MultiWorkspaceBspServer(
                     "The server does not resolve builds itself, so there is nothing to compile these from."
                 )
               )
-          bleepConfig <- BleepConfigOps.loadOrDefault(userPaths)
+          bleepConfig <- configOverride.map(Right(_)).getOrElse(BleepConfigOps.loadOrDefault(userPaths))
         } yield {
           val pre = Prebootstrapped(
             logger = logger,
@@ -1775,9 +1783,9 @@ class MultiWorkspaceBspServer(
     val recorder = new TranscriptRecorder
     registerOperation(workspace, taskId, opLabel, projectsToCompile.map(_.value), cancellation, params.originId, recorder)
     IO.defer {
-      // Re-read user config fresh before starting (allows runtime config changes)
+      // Re-read user config fresh before starting (allows runtime config changes), unless a caller handed us one — see `configOverride`.
       val userPaths = UserPaths.fromAppDirs
-      val freshConfig = BleepConfigOps.loadOrDefault(userPaths).getOrElse(model.BleepConfig.default)
+      val freshConfig = configOverride.getOrElse(BleepConfigOps.loadOrDefault(userPaths).getOrElse(model.BleepConfig.default))
       val serverConfig = freshConfig.bspServerConfigOrDefault
       // Sizes are resolved here, once, so a task can declare the same heap the fork is started with.
       val forkHeaps = TaskDag.ForkHeaps(
@@ -2314,9 +2322,9 @@ class MultiWorkspaceBspServer(
     val recorder = new TranscriptRecorder
     registerOperation(workspace, taskId, "test", testProjects.map(_.value), cancellation, params.originId, recorder)
     IO.defer {
-      // Re-read user config fresh before starting (allows runtime config changes)
+      // Re-read user config fresh before starting (allows runtime config changes), unless a caller handed us one — see `configOverride`.
       val userPaths = UserPaths.fromAppDirs
-      val freshConfig = BleepConfigOps.loadOrDefault(userPaths).getOrElse(model.BleepConfig.default)
+      val freshConfig = configOverride.getOrElse(BleepConfigOps.loadOrDefault(userPaths).getOrElse(model.BleepConfig.default))
       val serverConfig = freshConfig.bspServerConfigOrDefault
       val maxParallelism = serverConfig.effectiveParallelism
       val forkHeaps = TaskDag.ForkHeaps(
diff --git a/bleep-tests/src/scala/bleep/IntegrationTestHarness.scala b/bleep-tests/src/scala/bleep/IntegrationTestHarness.scala
index 610c22993..6cac8d43a 100644
--- a/bleep-tests/src/scala/bleep/IntegrationTestHarness.scala
+++ b/bleep-tests/src/scala/bleep/IntegrationTestHarness.scala
@@ -45,7 +45,8 @@ abstract class IntegrationTestHarness extends AnyFunSuite {
       bootstrap.from(pre, ResolveProjects.InMemory, Nil, model.BleepConfig.default, CoursierResolver.Factory.default).orThrow
     }
 
-  protected val testConfig: model.BleepConfig = model.BleepConfig(
+  // A `def` so a suite can override it in terms of `super.testConfig` — `super` cannot reach a `val`.
+  protected def testConfig: model.BleepConfig = model.BleepConfig(
     compileServerMode = Some(model.CompileServerMode.NewEachInvocation),
     authentications = None,
     logTiming = None,
@@ -108,6 +109,26 @@ abstract class IntegrationTestHarness extends AnyFunSuite {
     }
 }
 
+object IntegrationTestHarness {
+
+  /** One governor for every in-process server this test JVM starts, sized for a tenant rather than for the machine.
+    *
+    * Each connection used to build its own `MachineResources.forThisMachine` — all the cores, most of the RAM — so a suite running integration tests
+    * concurrently had one governor per connection, each admitting forks as though nothing else were running. The governor exists to bound forks *across*
+    * clients, and that is only true if there is one of it.
+    *
+    * Small on purpose, and small in two directions: this JVM is itself one of several the outer `bleep test` forked, and those outer forks are governed by a
+    * daemon that cannot see anything started in here. Two cores and 2GB lets an integration test fork a test JVM or a linker without pretending it is alone.
+    */
+  lazy val sharedMachine: MachineResources =
+    MachineResources.create(
+      totalCpu = 2,
+      totalMemoryMb = 2048L,
+      logger = bleepLoggers.silent,
+      longWaitWarnMs = MachineResources.DefaultLongWaitWarnMs
+    )
+}
+
 object Workspace {
 
   /** What generated snippets write instead of a bleep version, resolved to the newest `v*` tag when the site is built.
@@ -193,7 +214,10 @@ class Workspace(
         val rawStarted = bootstrap
           .from(
             Prebootstrapped(storingLogger.zipWith(stdLogger), userPaths, buildPaths, existingBuild, ec),
-            ResolveProjects.ReplaceBleepDependencies(lazyBleepBuild, BspServerClasspathSource.InProcess(InProcessBspServer.connect)),
+            ResolveProjects.ReplaceBleepDependencies(
+              lazyBleepBuild,
+              BspServerClasspathSource.InProcess(InProcessBspServer.connect(effectiveConfig, IntegrationTestHarness.sharedMachine))
+            ),
             Nil,
             effectiveConfig,
             CoursierResolver.Factory.default
diff --git a/bleep-tests/src/scala/bleep/Sip51Tests.scala b/bleep-tests/src/scala/bleep/Sip51Tests.scala
index 44318ce60..8808a44d1 100644
--- a/bleep-tests/src/scala/bleep/Sip51Tests.scala
+++ b/bleep-tests/src/scala/bleep/Sip51Tests.scala
@@ -70,7 +70,10 @@ class Sip51Tests extends AnyFunSuite with TripleEqualsSupport {
       val started = bootstrap
         .from(
           Prebootstrapped(storingLogger.zipWith(stdLogger), userPaths, buildPaths, existingBuild, ec),
-          ResolveProjects.ReplaceBleepDependencies(lazyBleepBuild, BspServerClasspathSource.InProcess(InProcessBspServer.connect)),
+          ResolveProjects.ReplaceBleepDependencies(
+            lazyBleepBuild,
+            BspServerClasspathSource.InProcess(InProcessBspServer.connect(testConfig, IntegrationTestHarness.sharedMachine))
+          ),
           Nil,
           testConfig,
           CoursierResolver.Factory.default
diff --git a/bleep-tests/src/scala/bleep/SuiteIdleTimeoutIT.scala b/bleep-tests/src/scala/bleep/SuiteIdleTimeoutIT.scala
new file mode 100644
index 000000000..1f70bb006
--- /dev/null
+++ b/bleep-tests/src/scala/bleep/SuiteIdleTimeoutIT.scala
@@ -0,0 +1,71 @@
+package bleep
+
+/** Two things at once, because neither can be shown without the other.
+  *
+  * The suite idle timeout counts test events — `TestStarted`, `TestFinished` — and deliberately not output. A suite that prints while finishing no test is idle
+  * by that definition and gets killed, which is the behaviour this pins: it is a decision, not an oversight, and it is easy to "fix" by accident.
+  *
+  * Showing it needs a timeout short enough to test, which needs the harness's config to actually reach the server. It did not until the in-process server was
+  * given a `configOverride`: `handleTest` re-read the developer's own `config.yaml`, so this suite's one-minute timeout was silently whatever that file said,
+  * and this test passed against a daemon that had never heard of it.
+  */
+class SuiteIdleTimeoutIT extends IntegrationTestHarness {
+
+  /** One minute, the smallest the setting allows. The fixture below then talks past it without finishing a test. */
+  override protected def testConfig: model.BleepConfig =
+    super.testConfig.copy(
+      bspServerConfig = super.testConfig.bspServerConfig.map(_.copy(testIdleTimeoutMinutes = Some(1)))
+    )
+
+  private val mytest = model.CrossProjectName(model.ProjectName("mytest"), None)
+
+  integrationTest("a suite that logs but finishes no test is killed at the idle timeout") { ws =>
+    ws.yaml(
+      s"""projects:
+         |  mytest:
+         |    dependencies:
+         |      - org.scalameta::munit:${model.Versions.Munit}
+         |    isTestProject: true
+         |    platform:
+         |      name: jvm
+         |    scala:
+         |      version: ${model.Versions.Scala3}
+         |""".stripMargin
+    )
+    ws.file(
+      "mytest/src/scala/example/TalkativeSuite.scala",
+      """package example
+        |
+        |class TalkativeSuite extends munit.FunSuite {
+        |  override def munitTimeout: scala.concurrent.duration.Duration = scala.concurrent.duration.Duration(5, "min")
+        |
+        |  test("talks past the idle timeout without finishing") {
+        |    val deadline = System.currentTimeMillis() + 90000L
+        |    while (System.currentTimeMillis() < deadline) {
+        |      println("still working")
+        |      Thread.sleep(2000L)
+        |    }
+        |  }
+        |}
+        |""".stripMargin
+    )
+    val (_, commands, _) = ws.start()
+
+    val outcome =
+      try {
+        commands.test(List(mytest), watch = false, only = None, exclude = None, includeTags = None, excludeTags = None)
+        Right(())
+      } catch { case e: BleepException => Left(e) }
+
+    outcome match {
+      case Right(()) => fail("the talkative suite ran to completion — the one-minute idle timeout from this suite's config did not reach the server")
+      case Left(err) =>
+        // Killed, not passed. The message is the run's verdict; the "timed out" wording is what the summary reports for a suite the idle clock stopped.
+        assert(
+          err.message.toLowerCase.contains("timed out") || err.message.toLowerCase.contains("timeout"),
+          s"expected the suite to be stopped by the idle timeout, got: ${err.message}"
+        )
+        succeed
+    }
+  }
+}

From 15d4e6994dbe9ed30a22655de142d4977ac294d7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=98yvind=20Raddum=20Berg?= <elacin@gmail.com>
Date: Wed, 2 Sep 2026 00:38:53 +0200
Subject: [PATCH 11/13] fix: deleteDirectory clears read-only entries instead
 of refusing (windows)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`PublishVersionTest` builds a real git repository in a temp directory and
deletes it afterwards. That passed everywhere except the Windows CI runner,
where all five of its cases failed in cleanup with

    java.nio.file.AccessDeniedException:
      ...\bleep-publish-version-...\.git\objects\07\0774631921...

Windows will not unlink a read-only file at all; POSIX only consults the
containing directory's permissions, so the same tree deletes cleanly there. git
marks every object under `.git/objects` read-only, so a `.git` directory is the
easiest way to meet this — but nothing about it is specific to tests.
`FileUtils.deleteDirectory` is what `bleep clean` uses on Windows, so any
read-only file under a target directory would have refused the same way.

Fixed where the difference is, not in the test that tripped over it: a delete
that hits `AccessDeniedException` clears the attribute and tries once more. The
retry is narrow on purpose — that exception only, once, and the second attempt
is allowed to throw, because a tree that still cannot be emptied is a real
failure rather than something to walk past.

`FileUtilsDeleteTest` asserts the outcome rather than the mechanism, since the
mechanism differs by platform: on Windows it exercises the clear-and-retry, on
POSIX the plain path, and on either one a regression fails it on the platform
that has the problem.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../src/scala/bleep/internal/FileUtils.scala  | 21 +++++++++--
 .../bleep/internal/FileUtilsDeleteTest.scala  | 36 +++++++++++++++++++
 2 files changed, 55 insertions(+), 2 deletions(-)
 create mode 100644 bleep-tests/src/scala/bleep/internal/FileUtilsDeleteTest.scala

diff --git a/bleep-core/src/scala/bleep/internal/FileUtils.scala b/bleep-core/src/scala/bleep/internal/FileUtils.scala
index 255360fd8..773158750 100644
--- a/bleep-core/src/scala/bleep/internal/FileUtils.scala
+++ b/bleep-core/src/scala/bleep/internal/FileUtils.scala
@@ -81,18 +81,35 @@ object FileUtils {
     }
   }
 
+  /** Delete `dir` and everything under it.
+    *
+    * A read-only entry is made writable and deleted rather than refused. Windows will not unlink a read-only file at all, where POSIX only cares about the
+    * containing directory's permissions — so this is a difference in the platform, not in the caller. git marks every object in `.git/objects` read-only, which
+    * is how it showed up: deleting a temporary clone worked everywhere except Windows, and only in CI.
+    *
+    * The retry is narrow on purpose. Only `AccessDeniedException` is handled, only once, and the second attempt is allowed to throw — a directory that still
+    * cannot be emptied after the attribute is cleared is a real failure and not something to walk past.
+    */
   def deleteDirectory(dir: Path): Unit =
     if (FileUtils.exists(dir)) {
+      def deleteClearingReadOnly(path: Path): Unit =
+        try Files.deleteIfExists(path).discard()
+        catch {
+          case _: AccessDeniedException =>
+            path.toFile.setWritable(true).discard()
+            Files.deleteIfExists(path).discard()
+        }
+
       Files.walkFileTree(
         dir,
         new SimpleFileVisitor[Path] {
           override def visitFile(file: Path, attrs: BasicFileAttributes): FileVisitResult = {
-            Files.deleteIfExists(file)
+            deleteClearingReadOnly(file)
             FileVisitResult.CONTINUE
           }
 
           override def postVisitDirectory(dir: Path, exc: IOException): FileVisitResult = {
-            Files.deleteIfExists(dir)
+            deleteClearingReadOnly(dir)
             FileVisitResult.CONTINUE
           }
         }
diff --git a/bleep-tests/src/scala/bleep/internal/FileUtilsDeleteTest.scala b/bleep-tests/src/scala/bleep/internal/FileUtilsDeleteTest.scala
new file mode 100644
index 000000000..59e971727
--- /dev/null
+++ b/bleep-tests/src/scala/bleep/internal/FileUtilsDeleteTest.scala
@@ -0,0 +1,36 @@
+package bleep.internal
+
+import org.scalatest.funsuite.AnyFunSuite
+
+import java.nio.file.{Files, Path}
+
+/** `deleteDirectory` has to cope with read-only entries.
+  *
+  * Windows will not unlink a read-only file at all; POSIX only consults the containing directory, so the same tree deletes cleanly there. git marks every
+  * object under `.git/objects` read-only, which is how this surfaced — `PublishVersionTest` builds a real repository in a temp directory, and its cleanup
+  * failed on the Windows CI runner and nowhere else.
+  *
+  * This test asserts the outcome rather than the mechanism: the tree is gone. On Windows that exercises the clear-and-retry, on POSIX the plain path. Either
+  * way a regression that reintroduces the refusal fails here, on the platform that has it.
+  */
+class FileUtilsDeleteTest extends AnyFunSuite {
+
+  test("a directory containing read-only files is deleted") {
+    val root = Files.createTempDirectory("bleep-delete-readonly-")
+    val nested = Files.createDirectories(root.resolve("objects").resolve("07"))
+    val file: Path = nested.resolve("abcdef")
+    Files.writeString(file, "an object, the way git leaves it")
+    assert(file.toFile.setReadOnly(), s"could not make $file read-only, so this test would prove nothing")
+
+    FileUtils.deleteDirectory(root)
+
+    assert(!FileUtils.exists(root), s"$root survived deletion")
+  }
+
+  test("deleting a directory that is not there is not an error") {
+    val root = Files.createTempDirectory("bleep-delete-absent-")
+    FileUtils.deleteDirectory(root)
+    FileUtils.deleteDirectory(root)
+    assert(!FileUtils.exists(root))
+  }
+}

From 353f330b2752e70c936314a1607db7b798c796ee Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=98yvind=20Raddum=20Berg?= <elacin@gmail.com>
Date: Wed, 2 Sep 2026 00:52:38 +0200
Subject: [PATCH 12/13] tests: the heap test reads the config the server
 actually uses
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fallout from giving the in-process server a `configOverride`, and the good kind:
this test had a workaround for the defect that fix removed, and the workaround
is now the thing that is wrong.

`configuredDefaultMb` read the developer's own `config.yaml`, with a comment
saying it deliberately did not read `IntegrationTestHarness.testConfig` because
"the in-process server does not consult" it. That was accurate — and it meant
the assertions were written against whatever heap the person running the suite
had configured, which is exactly the problem: on this machine the harness asked
for 512m and the fork got 4g, and the test agreed with the fork because it was
reading the same file the server was.

Now that the server uses the config it is handed, the test reads it too. The
assertions stop depending on a file outside the repository, which is what the
old comment was trying to achieve by the only means then available.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../src/scala/bleep/TestHeapPropagationIT.scala        | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/bleep-tests/src/scala/bleep/TestHeapPropagationIT.scala b/bleep-tests/src/scala/bleep/TestHeapPropagationIT.scala
index d9e02711d..187bd57bb 100644
--- a/bleep-tests/src/scala/bleep/TestHeapPropagationIT.scala
+++ b/bleep-tests/src/scala/bleep/TestHeapPropagationIT.scala
@@ -42,12 +42,14 @@ class TestHeapPropagationIT extends IntegrationTestHarness {
 
   /** The default a fork gets here when the build states nothing.
     *
-    * Read from the same place the server reads it — the user config on disk (`MultiWorkspaceBspServer` loads it fresh per request), NOT
-    * [[IntegrationTestHarness.testConfig]], which the in-process server does not consult for this. Computing it rather than hardcoding it is what keeps these
-    * assertions true on a developer machine that has set `testRunnerHeap` and on CI, which has no config file at all.
+    * Read from [[IntegrationTestHarness.testConfig]], which is what the in-process server now uses. It used to read the developer's `config.yaml` instead, with
+    * a comment explaining that the harness's config "the in-process server does not consult" — true at the time, and a workaround for a defect rather than a
+    * property worth having: `handleTest` re-read the user's file per request, so every integration test ran with whatever heap and parallelism the person
+    * running it happened to have configured. The server takes a `configOverride` now, so this reads the value that will actually be used, and these assertions
+    * stop depending on a file outside the repository.
     */
   private val configuredDefaultMb: Long =
-    MachineResources.forkHeapMb(BleepConfigOps.loadOrDefault(userPaths).orThrow.bspServerConfigOrDefault.testRunnerHeap)
+    MachineResources.forkHeapMb(testConfig.bspServerConfigOrDefault.testRunnerHeap)
 
   private def runTests(started: Started, jvmOptions: List[String]): Either[BleepException, Unit] =
     commands.ReactiveBsp

From 1a1cfda32e281e16ec9eb73651d5c69ef01837a8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=98yvind=20Raddum=20Berg?= <elacin@gmail.com>
Date: Wed, 2 Sep 2026 01:00:25 +0200
Subject: [PATCH 13/13] tests: hold only the pinned version to how a
 constructor failure reads
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`munit 1.0.0` on Scala Native failed the version sweep on all three Scala
versions, with one assertion: the constructor failure reached the report without
stack frames. That is true, and it is not a defect. munit 1.0.0 lets the process
die where 1.3.4 reports through the adapter, so the same fixture yields a bleep
process error there and a named cause with frames here.

The expectations it was measured against — `ctorFailureReport` and
`reportsCtorStackFrames` — are keyed on framework and platform. The comment on
the first already says the behaviour "cannot be keyed on the framework alone",
and the same reasoning extends one axis further: it cannot be keyed on the
platform alone either.

Rather than record every framework's reporting shape per version, the sweep
stops asserting it. Its stated job is discovery, runner selection and the fork
protocol — the ways an old release breaks a *user* — and holding a five-year-old
release to today's reporting detail only produces red that has to be explained
away, which is how a matrix stops being read. That file already warns about
exactly this for resolution errors.

What every version is still held to is unchanged and is the part that matters:
the suite whose constructor throws appears in the report, and something about it
is marked failed. A failure that disappears still fails here.

`pinnedVersion` is derived from `pinnedFor` rather than passed in, so it stays
right whichever matrix calls `checkFixture`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../src/scala/bleep/PlatformFrameworkHarness.scala | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/bleep-tests/src/scala/bleep/PlatformFrameworkHarness.scala b/bleep-tests/src/scala/bleep/PlatformFrameworkHarness.scala
index e49b0449d..d60586a58 100644
--- a/bleep-tests/src/scala/bleep/PlatformFrameworkHarness.scala
+++ b/bleep-tests/src/scala/bleep/PlatformFrameworkHarness.scala
@@ -249,6 +249,10 @@ trait PlatformFrameworkHarness { self: IntegrationTestHarness =>
       verdict: Either[BleepException, Unit]
   ): org.scalatest.Assertion = {
     val context = s"${fixture.name} $frameworkVersion on ${platform.describe}"
+    // Whether this run is the version the fixture's recorded behaviour was measured at. Derived rather than passed in, so it stays right no matter which
+    // matrix calls this.
+    val pinnedVersion =
+      TestFrameworkFixture.pinnedFor(platform.id, platform.scalaBinaryVersion).exists { case (f, v) => f.name == fixture.name && v == frameworkVersion }
     // When nothing ran at all the useful information is in the run's own failure, not in the (empty) report — a build that failed to resolve or compile looks
     // exactly like a runner that executed nothing unless the exception is shown.
     val why = verdict match {
@@ -401,13 +405,19 @@ trait PlatformFrameworkHarness { self: IntegrationTestHarness =>
       // test and not an empty suite; where the thrown exception survives, the report must carry it.
       val ctorDetail = ctorSuites.flatMap(_.cases).map(_.detail).mkString("\n")
       // Same for the constructor failure, where frames matter most: without them you are told a class could not be built and nothing about which line threw.
-      if (fixture.reportsCtorStackFrames(platform.id) && fixture.ctorFailureReport(platform.id) == CtorFailureReport.NamesTheCause)
+      if (pinnedVersion && fixture.reportsCtorStackFrames(platform.id) && fixture.ctorFailureReport(platform.id) == CtorFailureReport.NamesTheCause)
         assert(
           PlatformFrameworkHarness.hasStackFrames(ctorDetail),
           s"$context: the constructor failure reached the report but with no stack frames.\nIt said: ${ctorDetail.take(220)}\n$rendered"
         )
 
-      fixture.ctorFailureReport(platform.id) match {
+      // How a construction failure *reads* is measured at the pinned version, and older releases of the same framework legitimately differ: munit 1.0.0 on
+      // Scala Native lets the process die where 1.3.4 reports through the adapter, so the same fixture yields a process error there and a named cause here.
+      //
+      // The sweep is not held to it. Its stated job is discovery, runner selection and the fork protocol — the ways an old release breaks a *user* — and
+      // asserting today's reporting detail against a five-year-old release only produces red that has to be explained away, which is how a matrix stops being
+      // read. What every version still has to do is above: the suite appears, and something about it is marked failed.
+      if (pinnedVersion) fixture.ctorFailureReport(platform.id) match {
         case CtorFailureReport.NamesTheCause =>
           assert(
             ctorDetail.contains("ctor boom"),