@tech-leads-club/harness-toolkit 0.3.1 → 0.3.3

package/bin/tlc-build.mjs

@@ -37,6 +37,18 @@ function sourcesIn(dir) {
     .map((entry) => ({ name: basename(entry.name, ".ts"), source: join(dir, entry.name) }));
 }
 
+/**
+ * hazard: this built every entry in ONE invocation with `--splitting`, which cut `dist/` from 5.0 MB to 548 KB —
+ * and shipped a broken CLI. A shared chunk carries the module body of anything two entries both import, including
+ * `bin/tlc-cli.ts`, and its `if (import.meta.main)` guard evaluates **true** inside that chunk. So running
+ * `install-runtime`, which imports the CLI for `NPM_MARKER` and `wireRuntime`, ran the CLI's `main` instead:
+ * `tlc harness install` printed `unknown:` and installed nothing. Published as 0.3.2 and caught by installing it
+ * ([/decisions/ad-098.md](/decisions/ad-098.md)).
+ *
+ * invariant: one bundle per entry, so a module that self-executes behind `import.meta.main` is inlined into the
+ * one program that is allowed to run it. Splitting can come back when no library module carries that guard, and
+ * not before — the size win is real and it is not worth a CLI that cannot install.
+ */
 function buildOne(source, out) {
   const result = spawnSync(
     "bun",
@@ -44,7 +56,7 @@ function buildOne(source, out) {
     { stdio: "inherit" },
   );
   if (result.error?.code === "ENOENT") {
-    console.error("tlc-build: Bun is not on PATH, and dist/ is committed so the bundler is part of the artefact.");
+    console.error("tlc-build: Bun is not on PATH, and it is the only bundler this builds with.");
     console.error("  curl -fsSL https://bun.sh/install | bash");
     process.exit(1);
   }
@@ -61,6 +73,9 @@ const targets = [
 
 mkdirSync(dist, { recursive: true });
 console.log(`tlc-build → ${dist}`);
+
+// invariant: a leftover chunk directory from the split build would ship for ever, referenced by nothing.
+rmSync(join(dist, "chunks"), { recursive: true, force: true });
 for (const target of targets) {
   buildOne(target.source, join(dist, `${target.name}.mjs`));
 }

package/bin/tlc-cli.ts

@@ -904,6 +904,61 @@ export function resolveHarnessRoot(): string {
   }
 }
 
+/**
+ * Where npm put the package this command was installed from.
+ *
+ * hazard: `update` spawned `install-runtime` through the **runtime home's** launcher, so the tool resolved its
+ * source and its destination to the same directory and reported "already at … — nothing to copy". Measured on a
+ * scratch machine: `npm i -g` moved the package from 0.3.0 to 0.3.2 and the runtime the hooks execute stayed on
+ * 0.3.0. Every npm install that ever ran `update` bumped a package and kept its old code, while `doctor` said
+ * update "re-materialises this directory" ([/decisions/ad-098.md](/decisions/ad-098.md)).
+ *
+ * invariant: asked of npm rather than derived from this process. The CLI can be running from the runtime home,
+ * from the package, or from a linked clone, and only npm knows where it installs globally.
+ */
+export function globalPackageRoot(
+  probe = {
+    npmRoot: () => spawnSync("npm", ["root", "-g"], { encoding: "utf8", shell: true }).stdout ?? "",
+    exists: existsSync,
+  },
+): string | null {
+  // invariant: trimmed here rather than in the probe. `npm root -g` ends in a newline, and a path with a newline
+  // in it fails as a directory while reading as a plausible string in an error message.
+  const root = probe.npmRoot().trim();
+  if (root.length === 0) {
+    return null;
+  }
+  const candidate = join(root, ...NPM_PACKAGE.split("/"));
+  return probe.exists(candidate) ? candidate : null;
+}
+
+/**
+ * invariant: the *package's* launcher runs the materialisation, not the runtime home's. A release that fixes
+ * `install` has to be able to deliver that fix, and the old code cannot do it.
+ *
+ * invariant: both ends are named explicitly — `TLC_ORIGIN` is where the code comes from and `TLC_INSTALL_DEST` is
+ * where it goes — because each of them defaults to the same conventional home when left unsaid, which is exactly
+ * how this became a no-op.
+ */
+export function npmSyncPlan(
+  packageRoot: string,
+  dest: string,
+): { command: string; args: string[]; env: Record<string, string> } {
+  return {
+    command: process.execPath,
+    args: [join(packageRoot, "bin", "tlc-exec.mjs"), "install-runtime"],
+    env: { TLC_ORIGIN: packageRoot, TLC_INSTALL_DEST: dest },
+  };
+}
+
+export function npmRootFailureMessage(home: string): string {
+  return [
+    `update: npm reported no global root, so the package it just installed cannot be found.`,
+    `  The runtime at ${home} is unchanged — nothing was half-written.`,
+    `  Run \`npm root -g\` yourself; then \`npm i -g ${NPM_PACKAGE}@latest\` and \`tlc harness install\`.`,
+  ].join("\n");
+}
+
 /**
  * Everything an install has to put in place outside the runtime directory itself: the init skill where each
  * provider reads it, the user-level hooks, and a seeded config.
@@ -1293,9 +1348,15 @@ function runUpdate(root: string): never {
       console.error(npmUpdateFailureMessage());
       process.exit(bump.status ?? 1);
     }
-    const sync = spawnSync(process.execPath, [execBinPath(), "install-runtime"], {
+    const packageRoot = globalPackageRoot();
+    if (packageRoot === null) {
+      console.error(npmRootFailureMessage(home));
+      process.exit(1);
+    }
+    const plan = npmSyncPlan(packageRoot, home);
+    const sync = spawnSync(plan.command, plan.args, {
       stdio: "inherit",
-      env: process.env,
+      env: { ...process.env, ...plan.env },
     });
     if ((sync.status ?? 1) !== 0) {
       process.exit(sync.status ?? 1);

package/dist/tlc-cli.mjs

@@ -7706,6 +7706,32 @@ function resolveHarnessRoot() {
     return home;
   }
 }
+function globalPackageRoot(probe = {
+  npmRoot: () => spawnSync("npm", ["root", "-g"], { encoding: "utf8", shell: true }).stdout ?? "",
+  exists: existsSync26
+}) {
+  const root = probe.npmRoot().trim();
+  if (root.length === 0) {
+    return null;
+  }
+  const candidate = join27(root, ...NPM_PACKAGE.split("/"));
+  return probe.exists(candidate) ? candidate : null;
+}
+function npmSyncPlan(packageRoot, dest) {
+  return {
+    command: process.execPath,
+    args: [join27(packageRoot, "bin", "tlc-exec.mjs"), "install-runtime"],
+    env: { TLC_ORIGIN: packageRoot, TLC_INSTALL_DEST: dest }
+  };
+}
+function npmRootFailureMessage(home) {
+  return [
+    `update: npm reported no global root, so the package it just installed cannot be found.`,
+    `  The runtime at ${home} is unchanged — nothing was half-written.`,
+    `  Run \`npm root -g\` yourself; then \`npm i -g ${NPM_PACKAGE}@latest\` and \`tlc harness install\`.`
+  ].join(`
+`);
+}
 function wireRuntime(dest, home) {
   const lines = [];
   const seeded = seedConfig(dest);
@@ -7960,9 +7986,15 @@ function runUpdate(root) {
       console.error(npmUpdateFailureMessage());
       process.exit(bump.status ?? 1);
     }
-    const sync = spawnSync(process.execPath, [execBinPath(), "install-runtime"], {
+    const packageRoot = globalPackageRoot();
+    if (packageRoot === null) {
+      console.error(npmRootFailureMessage(home));
+      process.exit(1);
+    }
+    const plan = npmSyncPlan(packageRoot, home);
+    const sync = spawnSync(plan.command, plan.args, {
       stdio: "inherit",
-      env: process.env
+      env: { ...process.env, ...plan.env }
     });
     if ((sync.status ?? 1) !== 0) {
       process.exit(sync.status ?? 1);
@@ -8233,6 +8265,8 @@ export {
   pendingScreen,
   pairedFlagPath,
   npmUpdateFailureMessage,
+  npmSyncPlan,
+  npmRootFailureMessage,
   modeFilePath,
   missingBundles,
   linkedRuntimeMessage,
@@ -8243,6 +8277,7 @@ export {
   handoffJson,
   grindOn,
   grindFlagPath,
+  globalPackageRoot,
   gatesPaused,
   focusFlagPath,
   fetchFailureMessage,

package/docs/log.md

@@ -13,6 +13,10 @@ Generated from `docs/decisions/` — do not edit by hand. Run `node tools/render
 A reserved file of the [OKF v0.1](/decisions/ad-013.md) bundle: entries grouped under ISO 8601 headings,
 newest first. For what landed in which npm release, see `CHANGELOG.md` at the repository root.
 
+## 2026-08-20
+
+- **AD-098** — Splitting is reverted: a shared chunk ran the CLI's main ([/decisions/ad-098.md](/decisions/ad-098.md))
+
 ## 2026-08-19
 
 - **AD-081** — The manifest npm publishes is checked here, because the release runner was the only thing reading it ([/decisions/ad-081.md](/decisions/ad-081.md))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tech-leads-club/harness-toolkit",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "Multi-provider agent steering: gates, follow-up, handoff, policy",
   "keywords": [

package/src/core/release/release.version.ts

@@ -54,12 +54,18 @@ const SUBJECT = /^(?<type>[a-z]+)(?:\((?<scope>[^)]*)\))?(?<breaking>!)?:\s*(?<r
 const BREAKING_FOOTER = /^BREAKING[ -]CHANGE:/m;
 
 /**
- * invariant: `feat` and `fix` are the only types that release. Everything else — `docs`, `chore`, `refactor`,
- * `test`, `ci`, `build`, `perf`, `style` — lands without moving the version. That is what stops the release's own
- * commit from earning the next version and looping, which this pipeline did six times in nine minutes.
+ * invariant: `feat`, `fix` and `perf` release. Everything else — `docs`, `chore`, `refactor`, `test`, `ci`,
+ * `build`, `style` — lands without moving the version, which together with the inert scopes is what stops the
+ * release's own `chore(release):` commit from earning the next version and looping, as this pipeline did six times
+ * in nine minutes ([/decisions/ad-087.md](/decisions/ad-087.md)).
+ *
+ * hazard: `perf` was excluded with the loop as the stated reason, and the loop had nothing to do with it — `chore`
+ * and the inert scopes cover that on their own. The cost was measured: a change that cut the published package
+ * from 1.6 MB to 426 kB and about 4 ms from every hook sat on `main` unreleased, waiting for an unrelated `fix` to
+ * carry it to anybody ([/decisions/ad-098.md](/decisions/ad-098.md)).
  */
 export const MINOR_TYPES: ReadonlySet<string> = new Set(["feat"]);
-export const PATCH_TYPES: ReadonlySet<string> = new Set(["fix"]);
+export const PATCH_TYPES: ReadonlySet<string> = new Set(["fix", "perf"]);
 
 /**
  * invariant: a scope on this list never releases, whatever the type. `fix(ci)` and `fix(gate)` are repository