@xemahq/repo-build-tooling 0.21.3 → 0.23.0

package/README.md

@@ -30,26 +30,17 @@ pnpm exec xema-scrub-swagger-paths dist
 | `xema-service-bootstrap [--check] [--filter <key>] [--root <dir>]` | Generates `src/generated/*.generated.ts` service and worker descriptors from the repository's `xema-biome.json` manifests; `--check` fails on drift |
 | `xema-scrub-swagger-paths <dist-dir>...` | Rewrites `@nestjs/swagger` plugin output that names a private install path, then fails the build if any leak remains (`--self-test` available) |
 | `xema-composed-image <command>` | Build-time half of a composed-process image: `members`, `filters`, `dirs`, `pins`, `index`, `load`, `stage`, `pnpm-context`, `sync-injected`, `prisma-check`, `migrate`, `coordinate`, `load-image`, `smoke-refusal`, `dockerfile` |
+| `xema-service-image stage --service <pkg> --path <dir> --platform linux/<amd64\|arm64> [--stage-dir <dir>]` | Runner half of a per-service image: `pnpm deploy --prod --offline --ignore-scripts` of a service already built on the runner, selected for the TARGET platform (`--os=linux --cpu=<arch> --libc=glibc`), into `<stage>/service/app`, with its Prisma client and the target's schema engine. Refuses a package whose native code holds no ELF for the target (a multi-platform package that also ships the target's binary is accepted) and production dependencies whose build script would have to run, uncommitted changes to tracked files, an untracked root build input, and running as any tool but the one the root installs. Fetches the schema engine from Prisma for every stage, checks it against both published checksums, and caches nothing. Writes `<stage>/service/xema-service-image.json` (commit, sha256 of each root build input: lockfile, root `package.json`, `pnpm-workspace.yaml`, `.npmrc`, `.pnpmfile.cjs`, `turbo.json`, `tsconfig*.json`; tool version; natives per package; engine sha256) and `<stage>/tool`. The Dockerfile COPYs those root inputs into `/proof/context/`, which puts them in the content tag, and its proof stage runs `src/service-image-in-image.mjs prove <app> <proof dir> --service <svc> --commit <BUILD_SHA>` on the target, offline: it checks the commit, the root inputs, the tool version, the platform and Node ABI, that each package's addons `dlopen`, and the engine's sha256 and version. The final stage only COPYs |
 | `xema-arm64-supplement-needed` | Decides whether an arm64 supplement is still owed at `REGISTRY/IMAGE:CONTENT_TAG` (env: `REGISTRY`, `IMAGE`, `CONTENT_TAG`, `REGISTRY_USER`, `REGISTRY_TOKEN`). `needed=false` only when the coordinate serves an index whose linux/arm64 child is proven by its own image config; any other resolvable state is `needed=true`; a 401/403/5xx or an unresolvable child is an error. Writes `needed=true\|false` to `$GITHUB_OUTPUT`. Replaces the generated `arm64-supplement-needed.mjs` copy. |
 | `xema-promote-image --service <name> --dev-ref <repo> --release-ref <repo> --tag <tag> --commit <sha> --main-ref <ref> --signer-repository <owner/repo> --develop-workflow <file> --release-workflow <file>... [--release-index-workflow <file>] --promotion-predicate-out <path> -- <tag command>` | Publishes the develop image's digest under the release tag instead of rebuilding: `reused` (the release digest carries an `image-promotion/v1` attestation signed by a `--release-workflow` identity on main, with exactly one verified statement about the digest and a `ghcr.io/<owner>/dev/<name>` source; no dev-ref probe), `copied` (the proven develop digest, digest-preserving; fails closed if the release digest differs) or `miss` (build it; a reuse whose release digest has no `image-promotion/v1` attestation, a legacy image, is a miss with `reason=reuse-no-promotion` on the stdout line; with `--release-index-workflow`, a release tag that names an image index signed by that workflow on main, with exactly one `linux/amd64` child whose own digest passes that same reuse check, is instead `reused` with `evidence=release-index`, `digest` = the amd64 child A, `index_digest` = the index D and no predicate, but only when A's selected promotion statement promotes `--commit` itself (a rerun; a later commit with the same content takes the existing miss and attests its own promotion). On `evidence=release-index` the caller skips sign/attest, tags `:<sha>` and `main-<sha>` to the amd64 subject `digest` (release-arm64 resolves `:<sha>` to it and verifies its promotion), and points only the content tag (and `latest`, if it moves it) at the index `index_digest`. Any failed step keeps the miss, and two amd64 children are an error; a signature or identity failure, or a source outside `dev/`, is an error; a copy whose dev digest carries no SLSA v1 provenance at all, an image reused on develop from before provenance, is a miss with `reason=copy-no-develop-provenance`, while provenance that is present but fails a leg is an error). A develop digest is proven only if its SLSA v1 provenance is signed by the develop workflow at `refs/heads/develop`, its revision is an ancestor of the main ref, and the tag command prints the same tag at that revision and at `--commit`; any failed leg is an error, never a miss. On every non-miss result it writes the `https://xema.dev/attestations/image-promotion/v1` predicate for the caller to attest: a copy states the facts just proved; a reuse states this run's `release` and `promotedCommit` and carries `source` and `developProvenance` from the earlier promotion. Writes `result`, `digest`, `source`, `revision`, `evidence`, `provenance_digest`, `promotion_predicate`, `promotion_predicate_type` to `$GITHUB_OUTPUT`. Needs `docker`, `cosign` (major v2, the same as the develop attest step and xema-deploy's verify; it runs `cosign version` first and refuses any other major or an unparsable version), `git` and full history. It does not sign |
-| `xema-buildx-builder ensure` | Ensures the runner's persistent, capped buildkitd container (`xema-buildkit-signed-<runner>`, state volume `-state`) is up and is the current buildx builder. Env: `RUNNER_NAME`, `BUILDKIT_IMAGE`, `BUILDKIT_LIMITS` (JSON `cpus`, `memory`, `maxParallelism`, `gcMaxUsedSpace`, all required and positive), optional `BUILDKIT_READY_DEADLINE_SECONDS` (positive integer, default 180). The slot is `RUNNER_NAME` with a trailing `-<hostname>` stripped only when it equals this container's own hostname, so a recreated runner container reuses its builder and cache. Pinned to the runner's cgroup cpuset; caps are clamped so every `xema-buildkit-signed-*` builder on the host fits (memory at most half of `docker info` MemTotal divided by N, CPUs at most NCPU divided by N). On each run it removes this verb's labelled builders, and their `-state` volumes, whose recorded runner container is no longer running; unlabelled containers are never touched. Recreated once when the image, effective caps, config or runner container change. Prints `buildx-boot path= secs= builder=`. |
 | `xema-check-no-vendored-deps` | Fails on a `workspace:` range for a package the repository does not own |
-| `xema-prepush-sanity` | Lefthook `pre-push`: turbo `lint` and `typecheck` on what the push changes plus dependents (root `lint` only without turbo; typecheck is CI-only there); CI is the proof |
+| `xema-prepush-sanity` | Lefthook `pre-push`: turbo `lint` and `typecheck` on what the push changes plus dependents, and `test` and `openapi:current` (where defined) only on the packages the push changed; a fleet-wide change runs only `lint` and `typecheck` on the full graph; root `lint` only without turbo; a park-only push (`refs/xema-session/*`) skips |
 | `xema-check-workspace-ranges` | Fails on a `workspace:` range the local package does not satisfy |
 
 `xema-composed-image members --write|--check` accepts `--manifests <glob>` (repeatable, default `**/xema-biome.json`), `--canonical-dockerfile <path>` and `--cross-repo-manifest <path>`. `xema-composed-image dockerfile` requires `--copy`, `--cache-id` and `--build-source`; it pins the version of this tool itself, and there is no flag for it (`--tooling-version` is refused as an unknown option). `dockerfile --prebuilt` renders the Dockerfile and `Dockerfile.dockerignore` of an image assembled from `stage <dir> [--output <rel>]… [--also <pkg>]…` output (requires `--cache-id`, `--build-source`; `--copy` and `--stage-dir` optional); `load --each` loads every member in its own process. `stage` and `filters` accept `--also <workspace package name>` (repeatable): the package's closure is built and staged (built outputs only, no Prisma checks) alongside the members; an unknown name is refused. `pnpm-context <dir> (--subject <svc>… | --image-dir <composed>)` runs on the CI runner after `pnpm install --frozen-lockfile` and builds the offline `xema-pnpm` build context (`staged.json`, `corepack/pnpm.tgz`, and, with `--image-dir` only, a warmed `cache/` of registry metadata; `--subject` writes no `cache/` and `staged.json` says `cache: false`); it prints `XEMA_PNPM_CONTEXT=<dir>` and `XEMA_PNPM_STORE=<store root>` on stdout (everything else on stderr) and refuses a non-empty `<dir>`. `dockerfile --prebuilt` renders an OFFLINE image: every install RUN is `--network=none` and reads the runner's pnpm store and the `pnpm-context` output as the named build contexts `xema-pnpm-store` and `xema-pnpm`; without them the build fails with a message (no network fallback). `pnpm rebuild` runs only for `onlyBuiltDependencies` in the members' prod closure (less prisma, @prisma/client, @prisma/engines, @nestjs/core, esbuild, @swc/core) and the render needs `pnpm install` first; a node-gyp module with no optional prebuilt packages is refused. `pnpm-context --image-dir` reads the deps stage's COPY directories from the committed Dockerfile. Run `xema-composed-image` with no arguments for the full usage.
 
 Every step refuses rather than skips. The package has no dependencies.
 
-## Security model of `xema-buildx-builder`
-
-The persistent builder and its cache mounts are for signed develop and main builds only.
-
-- The verb refuses any `GITHUB_EVENT_NAME` other than `push` and `workflow_dispatch`, and any `GITHUB_REF` other than `refs/heads/main` and `refs/heads/develop`, before any docker call. A pull request never touches the persistent builder or its cache.
-- Callers also gate the step on the opt-in org variable: the develop-images lane runs the verb only `if: vars.XEMA_BUILDKIT_MODE == 'persistent'` and uses the stock `setup-buildx-action` otherwise.
-- The builder, its container and its state volume are named `xema-buildkit-signed-<runner>`; the `xema-buildkit-signed-*` prefix is reserved for signed lanes, so no other lane shares those cache mounts.
-- Owner decision D97 (2026-10-14): pull request jobs run on the same runners. The in-process guards above are the accepted mitigation, because only we push to our repositories.
-
 ## Resolution
 
 Inside the `xema-monorepo` aggregator, `@xemahq/repo-build-tooling` resolves to this directory through a workspace override. In an independent repository's CI it resolves from npm by the declared range, so a change here reaches a consumer only after it is published and the consumer's range admits it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.21.3",
+  "version": "0.23.0",
   "description": "Dev-time build tooling shared by every Xema repository. Ships as plain ESM, depending only on @xemahq/release-policy for registry access, so the published artifact is the reviewed source.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -22,7 +22,6 @@
   ],
   "bin": {
     "xema-arm64-supplement-needed": "src/arm64-supplement-needed.mjs",
-    "xema-buildx-builder": "src/buildx-builder.mjs",
     "xema-check-no-vendored-deps": "src/check-no-vendored-deps.mjs",
     "xema-check-workspace-ranges": "src/check-workspace-range-matches-local.mjs",
     "xema-composed-image": "src/composed-image.mjs",
@@ -30,11 +29,11 @@
     "xema-promote-image": "src/promote-image.mjs",
     "xema-readiness": "src/readiness.mjs",
     "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs",
-    "xema-service-bootstrap": "src/service-bootstrap.mjs"
+    "xema-service-bootstrap": "src/service-bootstrap.mjs",
+    "xema-service-image": "src/service-image.mjs"
   },
   "exports": {
     "./arm64-supplement-needed": "./src/arm64-supplement-needed.mjs",
-    "./buildx-builder": "./src/buildx-builder.mjs",
     "./check-no-vendored-deps": "./src/check-no-vendored-deps.mjs",
     "./check-workspace-range-matches-local": "./src/check-workspace-range-matches-local.mjs",
     "./composed-image": "./src/composed-image.mjs",
@@ -43,15 +42,16 @@
     "./promote-image": "./src/promote-image.mjs",
     "./readiness": "./src/readiness.mjs",
     "./scrub-swagger-plugin-paths": "./src/scrub-swagger-plugin-paths.mjs",
-    "./service-bootstrap": "./src/service-bootstrap.mjs"
+    "./service-bootstrap": "./src/service-bootstrap.mjs",
+    "./service-image": "./src/service-image.mjs"
   },
   "dependencies": {
     "@xemahq/release-policy": "^14.0.0"
   },
   "scripts": {
-    "test": "node --test src/buildx-builder.test.mjs && node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs && node --test src/readiness.test.mjs && node --test src/composed-image.test.mjs && node --test src/composed-image-coordinate-cli.test.mjs && node --test src/declaration-refusal.test.mjs && node --test src/smoke-refusal.test.mjs && node --test src/load-image.test.mjs && node --test src/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs && node --test src/composed-image-prebuilt-dockerfile.test.mjs && node --test src/composed-image-in-image-closure.test.mjs && node --test src/composed-image-stage.test.mjs && node --test src/composed-image-pnpm-context.test.mjs && node --test src/composed-image-sync-injected.test.mjs && node --test src/composed-image-prisma-check.test.mjs && node --test src/composed-image-prisma-engine.test.mjs && node --test src/composed-migrate.test.mjs && node --test src/promote-image.test.mjs && node --test src/arm64-supplement-needed.test.mjs && node --test src/prepush-sanity.test.mjs"
+    "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs && node --test src/readiness.test.mjs && node --test src/composed-image.test.mjs && node --test src/composed-image-coordinate-cli.test.mjs && node --test src/declaration-refusal.test.mjs && node --test src/smoke-refusal.test.mjs && node --test src/load-image.test.mjs && node --test src/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs && node --test src/composed-image-prebuilt-dockerfile.test.mjs && node --test src/composed-image-in-image-closure.test.mjs && node --test src/composed-image-stage.test.mjs && node --test src/composed-image-pnpm-context.test.mjs && node --test src/composed-image-sync-injected.test.mjs && node --test src/composed-image-prisma-check.test.mjs && node --test src/composed-image-prisma-engine.test.mjs && node --test src/composed-migrate.test.mjs && node --test src/promote-image.test.mjs && node --test src/arm64-supplement-needed.test.mjs && node --test src/prepush-sanity.test.mjs && node --test src/service-image.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:57594caa2c2d04aedf32ce374f8e0d5806022c23e5d14451c3263c925a641de4"
+    "sourceDigest": "sha256:1e968ed2990de85680e206c3dcb98c5467bb3c01166ace6b1e81be91e5344fb1"
   }
 }

package/src/composed-image-prisma-engine.mjs

@@ -52,6 +52,19 @@ export function prismaEnginesDirectories(root) {
 
 const runVersion = (file) => spawnSync(file, ['--version'], { encoding: 'utf8' });
 
+/**
+ * Run a schema engine and refuse it unless it reports `enginesVersion`: the check Prisma makes before it
+ * decides to download one. Returns the engine's version line.
+ */
+export function verifySchemaEngine(file, enginesVersion, version = runVersion) {
+  const result = version(file);
+  if (result.error || result.status !== 0 || !String(result.stdout ?? '').includes(enginesVersion)) {
+    const detail = String(result.stdout || result.stderr || result.error?.message || '').trim();
+    throw new Error(`${file} --version did not report ${enginesVersion}: status ${result.status}${detail === '' ? '' : `, ${detail}`}`);
+  }
+  return String(result.stdout).trim();
+}
+
 /**
  * Install the staged schema engine into every @prisma/engines directory a prisma CLI resolves.
  * `binaryTarget` and `version` are injectable for tests; by default they are Prisma's own
@@ -77,12 +90,7 @@ export async function installPrismaSchemaEngine({ root = process.cwd(), stagedDi
     const destination = join(enginesDir, fileName);
     copyFileSync(source, destination);
     chmodSync(destination, 0o755);
-    const result = version(destination);
-    if (result.error || result.status !== 0 || !String(result.stdout ?? '').includes(enginesVersion)) {
-      const detail = String(result.stdout || result.stderr || result.error?.message || '').trim();
-      throw new Error(`${destination} --version did not report ${enginesVersion}: status ${result.status}${detail === '' ? '' : `, ${detail}`}`);
-    }
-    log(`prisma schema engine: ${destination} (${String(result.stdout).trim()})`);
+    log(`prisma schema engine: ${destination} (${verifySchemaEngine(destination, enginesVersion, version)})`);
     installed.push(destination);
   }
   return installed;

package/src/prepush-sanity.mjs

@@ -4,8 +4,12 @@
 // 10-13/10-14). One verb for every repository's lefthook `pre-push`, so the
 // logic is not copied per repo.
 //
-// With turbo (a `turbo.json` and a turbo dependency): turbo `lint` and `typecheck` run only on the packages
-// the pushed commits change plus their dependents. A change to the lockfile,
+// With turbo (a `turbo.json` and a turbo dependency): turbo `lint`, `typecheck`,
+// `test` (unit) and `openapi:current`, each where turbo.json defines it (D136: a cheap
+// pre-push let a stale openapi spec through, and every red costs ~1h of CI). `lint` and
+// `typecheck` run on the packages the pushed commits change plus their dependents; `test`
+// and `openapi:current` only on the packages the push itself changes, and one line names the
+// dependents whose tests are left to CI (an affected-set run took 36 min for a widely used package). A change to the lockfile,
 // turbo.json, or anything in the root package.json other than its `scripts`
 // table invalidates everything and runs the full graph. A repo whose turbo carries no `lint` task also runs its root `lint`
 // script. Without turbo: the root `lint` script only (typecheck needs a build, which the hook never runs; CI has it).
@@ -13,9 +17,13 @@
 // The pushed SHA is what is graded. In place when the tree is clean and the SHA
 // is HEAD, or when no differing path lies in a package the run reads or at the
 // repository root; otherwise from a `git archive` export. A delete-only push
-// (or no ref on stdin) grades nothing.
+// (or no ref on stdin) grades nothing. A push whose every remote ref is a
+// session park (`refs/xema-session/*`) grades nothing either: a park is not a
+// landing, and the work is graded when it lands on a branch.
 //
-// Never builds for its own sake, never runs tests, docker or `pnpm check`.
+// A fleet-wide change runs `lint` and `typecheck` on the full graph and says it
+// leaves `test` and `openapi:current` to CI: never the full suite. Never builds
+// for its own sake, never runs docker, image builds or `pnpm check`.
 //
 // Usage (lefthook `pre-push` with `use_stdin: true`):
 //   xema-prepush-sanity
@@ -60,11 +68,68 @@ export function stripJsonc(text) {
   return out;
 }
 
+/** The tasks pre-push runs on the affected packages, in this order, where turbo.json defines them. */
+export const SANITY_TASKS = ['lint', 'typecheck', 'test', 'openapi:current'];
+/** The subset that also runs on the full graph and on dependents; the rest would be the full suite, which is CI's. */
+export const FULL_GRAPH_TASKS = ['lint', 'typecheck'];
+
+/** Package directories (a package.json below the root) among tracked file paths; node_modules never counts. */
+export function packageDirs(files) {
+  return [...new Set(files.filter((f) => f.endsWith('/package.json') && !f.includes('node_modules/')).map((f) => f.slice(0, -'/package.json'.length)))];
+}
+
+/** Paths no task reads: root-level markdown and changesets. */
+export function isInert(path) {
+  return /^[^/]*\.md$/.test(path) || path.startsWith('.changeset/');
+}
+
+/** Changed paths that sit in no workspace package and that some task may read (tsconfig.base.json, biome.json, tooling/**). They invalidate every package. */
+export function outsidePackages(changed, dirs) {
+  return changed.filter((p) => !isInert(p) && !dirs.some((d) => p.startsWith(`${d}/`)));
+}
+
+/** A push with changes whose plan holds no task checked nothing, and must say so rather than pass; null when it is fine. */
+export function emptyPlanFailure(changed, plannedTasks) {
+  if (changed.length === 0 || plannedTasks > 0) return null;
+  return `no task was planned for a push that changes ${changed.slice(0, 10).join(', ')}${changed.length > 10 ? ` (+${changed.length - 10} more)` : ''} — nothing was checked`;
+}
+
+/**
+ * The turbo runs for a push. `range` '' is the full graph: lint and typecheck only. Otherwise lint and
+ * typecheck run on the affected set (changed packages plus dependents), while test and openapi:current
+ * run only on the packages the push itself changed: a widely used package has dozens of dependents and
+ * their tests cost ~36 min (authorization-nest: 78 packages, 195 tasks). CI runs those.
+ */
+export function planRuns(tasks, range) {
+  if (!range) {
+    const full = tasks.filter((t) => FULL_GRAPH_TASKS.includes(t));
+    return { runs: full.length > 0 ? [{ tasks: full, filter: null }] : [], leftToCi: tasks.filter((t) => !FULL_GRAPH_TASKS.includes(t)) };
+  }
+  const affected = tasks.filter((t) => FULL_GRAPH_TASKS.includes(t));
+  const changedOnly = tasks.filter((t) => !FULL_GRAPH_TASKS.includes(t));
+  const runs = [];
+  if (affected.length > 0) runs.push({ tasks: affected, filter: `...[${range}]` });
+  if (changedOnly.length > 0) runs.push({ tasks: changedOnly, filter: `[${range}]` });
+  return { runs, leftToCi: [] };
+}
+
+/** Package names in `affected` that are not in `changed`, sorted; the root workspace `//` is never a package. */
+export function dependentsOnly(affected, changed) {
+  const own = new Set(changed);
+  return [...new Set(affected)].filter((n) => n !== '//' && !own.has(n)).sort();
+}
+
+/** The one line naming the dependents whose test and openapi:current are left to CI. */
+export function dependentsLine(dependents, tasks) {
+  if (dependents.length === 0 || tasks.length === 0) return '';
+  return `pre-push: ${tasks.join(' ')} ran only on the changed packages; ${dependents.length} dependent(s) are left to CI: ${dependents.join(', ')}`;
+}
+
 /** The sanity tasks a turbo.json defines. An unparsable file throws: "no tasks" would report green. */
 export function turboTasks(text) {
   const cfg = JSON.parse(stripJsonc(text));
   const defined = cfg.tasks ?? cfg.pipeline ?? {};
-  return ['lint', 'typecheck'].filter((t) => t in defined);
+  return SANITY_TASKS.filter((t) => t in defined);
 }
 
 /** The refs git writes on a pre-push hook's stdin, one sha graded once, deletes dropped. */
@@ -80,6 +145,18 @@ export function parseRefs(stdin) {
   return refs;
 }
 
+/** Remote refs under this prefix are session parks, not landings. */
+export const PARK_REF_PREFIX = 'refs/xema-session/';
+
+/** True when stdin names at least one ref and every remote ref is a session park. A branch anywhere in the push grades the push. */
+export function parkOnly(stdin) {
+  const remoteRefs = stdin
+    .split('\n')
+    .map((line) => line.trim().split(/\s+/)[2])
+    .filter(Boolean);
+  return remoteRefs.length > 0 && remoteRefs.every((ref) => ref.startsWith(PARK_REF_PREFIX));
+}
+
 /** True when two root package.json texts differ only in the top-level `scripts` key; a missing side or unparseable JSON is false. */
 export function scriptsOnlyChange(baseText, tipText) {
   try {
@@ -164,9 +241,19 @@ function rangeFor(ctx, base, sha) {
     console.error('pre-push: lockfile, turbo.json or root package.json beyond its scripts changed — fleet-wide, running the FULL graph.');
     return '';
   }
+  const files = (rev) => (ctx.gitOut(['ls-tree', '-r', '--name-only', rev]) ?? '').split('\n').filter(Boolean);
+  const outside = outsidePackages(changed, packageDirs([...files(base), ...files(sha)]));
+  if (outside.length > 0) {
+    console.error(`pre-push: ${outside.slice(0, 10).join(', ')}${outside.length > 10 ? ` (+${outside.length - 10} more)` : ''} sit outside any workspace package — fleet-wide, running the FULL graph.`);
+    return '';
+  }
   return `${base}...${sha}`;
 }
 
+function changedPaths(ctx, base, sha) {
+  return base ? (ctx.gitOut(['diff', '--name-only', `${base}...${sha}`]) ?? '').split('\n').filter(Boolean) : [];
+}
+
 function turboBin(root, env) {
   const local = join(root, 'node_modules', '.bin', 'turbo');
   if (existsSync(local)) return local;
@@ -191,8 +278,22 @@ function hasRootLint(dir) {
   }
 }
 
+/** How many tasks turbo plans for `tasks` under `filter`. */
+function dryTaskCount(ctx, bin, dir, tasks, filter) {
+  const dry = spawnSync(bin, ['run', ...tasks, `--filter=${filter}`, '--dry=json'], { cwd: dir, env: ctx.env, encoding: 'utf8', maxBuffer: 1 << 28 });
+  if (dry.status !== 0) throw new Error(`turbo --dry=json failed for --filter=${filter}`);
+  return (JSON.parse(dry.stdout).tasks ?? []).length;
+}
+
+/** Package names turbo would run `tasks` for under `filter`; an unreadable plan throws rather than hide a dependent. */
+function dryPackages(ctx, bin, dir, tasks, filter) {
+  const dry = spawnSync(bin, ['run', ...tasks, `--filter=${filter}`, '--dry=json'], { cwd: dir, env: ctx.env, encoding: 'utf8', maxBuffer: 1 << 28 });
+  if (dry.status !== 0) throw new Error(`turbo --dry=json failed for --filter=${filter}`);
+  return JSON.parse(dry.stdout).packages ?? [];
+}
+
 /** Run the sanity tasks in `dir`; `range` '' is the full graph. Returns the verdict. */
-function runHere(ctx, dir, range, bin) {
+function runHere(ctx, dir, range, bin, changed) {
   if (!bin) {
     // Without turbo nothing orders the builds a workspace typecheck needs, and the hook never
     // builds: typecheck there is CI's.
@@ -207,16 +308,29 @@ function runHere(ctx, dir, range, bin) {
     return false;
   }
   if (tasks.length === 0) {
-    console.log('pre-push: turbo.json defines none of lint, typecheck — FAILED');
+    console.log(`pre-push: turbo.json defines none of ${SANITY_TASKS.join(', ')} — FAILED`);
     return false;
   }
-  let ok;
   if (range) {
-    console.log(`pre-push: turbo run ${tasks.join(' ')} (affected by ${range}, plus dependents)`);
-    ok = ctx.inherit(bin, ['run', ...tasks, `--filter=...[${range}]`, '--continue=dependencies-successful'], dir);
-  } else {
-    console.log(`pre-push: turbo run ${tasks.join(' ')} (full graph)`);
-    ok = ctx.inherit(bin, ['run', ...tasks, '--continue=dependencies-successful'], dir);
+    const failure = emptyPlanFailure(changed, dryTaskCount(ctx, bin, dir, tasks, `...[${range}]`));
+    if (failure) {
+      console.log(`pre-push: ${failure} — FAILED`);
+      return false;
+    }
+  }
+  const { runs, leftToCi } = planRuns(tasks, range);
+  if (leftToCi.length > 0) console.log(`pre-push: ${leftToCi.join(' ')} not run on the full graph — that is the full suite, CI runs it.`);
+  let ok = true;
+  for (const run of runs) {
+    const where = run.filter ? (run.filter.startsWith('...') ? `affected by ${range}, plus dependents` : `only the packages ${range} changes`) : 'full graph';
+    console.log(`pre-push: turbo run ${run.tasks.join(' ')} (${where})`);
+    const filterArgs = run.filter ? [`--filter=${run.filter}`] : [];
+    ok = ctx.inherit(bin, ['run', ...run.tasks, ...filterArgs, '--continue=dependencies-successful'], dir) && ok;
+  }
+  if (range) {
+    const changedOnly = tasks.filter((t) => !FULL_GRAPH_TASKS.includes(t));
+    const line = dependentsLine(dependentsOnly(dryPackages(ctx, bin, dir, tasks, `...[${range}]`), dryPackages(ctx, bin, dir, tasks, `[${range}]`)), changedOnly);
+    if (line) console.log(line);
   }
   // Lint that turbo does not carry is the root `lint` script CI runs.
   if (!tasks.includes('lint') && hasRootLint(dir)) {
@@ -258,7 +372,7 @@ function exportTo(ctx, rev, dir) {
   return spawnSync('sh', ['-c', 'git archive "$1" | tar -x -C "$2"', 'sh', rev, dir], { cwd: ctx.root, env: ctx.env }).status === 0;
 }
 
-function gradeFromExport(ctx, sha, base, range, bin) {
+function gradeFromExport(ctx, sha, base, range, bin, changed) {
   const scratch = mkdtempSync(join(tmpdir(), 'xema-prepush-'));
   try {
     const sh = (args) => ctx.git(['-c', 'user.email=gate@local', '-c', 'user.name=gate', ...args], scratch).status === 0;
@@ -275,7 +389,7 @@ function gradeFromExport(ctx, sha, base, range, bin) {
       console.log('pre-push: install of the export failed');
       return false;
     }
-    return runHere(ctx, scratch, exportRange, bin);
+    return runHere(ctx, scratch, exportRange, bin, changed);
   } finally {
     rmSync(scratch, { recursive: true, force: true });
   }
@@ -285,12 +399,17 @@ function gradeSha(ctx, ref, bin) {
   const { sha } = ref;
   const base = pickBase(ctx, ref);
   const range = rangeFor(ctx, base, sha);
+  const changed = changedPaths(ctx, base, sha);
+  if (range && changed.length > 0 && changed.every(isInert)) {
+    console.log(`pre-push: only paths no task reads changed (${changed.slice(0, 10).join(', ')}) — nothing to grade.`);
+    return true;
+  }
   const head = (ctx.gitOut(['rev-parse', 'HEAD']) ?? '').trim();
   const short = (rev) => (ctx.gitOut(['rev-parse', '--short', rev]) ?? rev).trim();
   const clean = (ctx.gitOut(['status', '--porcelain']) ?? '') === '';
   if (sha === head && clean) {
     console.log(`pre-push: grading HEAD ${short(head)} in place (clean tree).`);
-    return runHere(ctx, ctx.root, range, bin);
+    return runHere(ctx, ctx.root, range, bin, changed);
   }
   if (bin) {
     let tasks = [];
@@ -301,7 +420,7 @@ function gradeSha(ctx, ref, bin) {
     }
     if (tasks.length > 0 && inPlaceSafe(ctx, sha, range, tasks, bin)) {
       console.log(`pre-push: grading ${short(sha)} in place — no differing path is in a package this run reads.`);
-      return runHere(ctx, ctx.root, range, bin);
+      return runHere(ctx, ctx.root, range, bin, changed);
     }
   }
   console.log(
@@ -309,7 +428,7 @@ function gradeSha(ctx, ref, bin) {
       ? `pre-push: grading ${short(sha)} from an export — the tree is dirty, so it is not what is being pushed.`
       : `pre-push: grading ${short(sha)} from an export — the commit being PUSHED, which is not HEAD ${short(head)}.`,
   );
-  return gradeFromExport(ctx, sha, base, bin ? range : '', bin);
+  return gradeFromExport(ctx, sha, base, bin ? range : '', bin, changed);
 }
 
 export function main(stdin) {
@@ -318,6 +437,10 @@ export function main(stdin) {
     console.error('pre-push: not inside a git repository — FAILED');
     return 1;
   }
+  if (parkOnly(stdin)) {
+    console.log(`pre-push: skipped — every ref is a session park under ${PARK_REF_PREFIX}; parks are not landings, the gate runs when the work lands.`);
+    return 0;
+  }
   const ctx = createContext(top.stdout.trim());
   const refs = parseRefs(stdin);
   if (refs.length === 0) {

package/src/prepush-sanity.test.mjs

@@ -5,7 +5,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
 import { fileURLToPath } from 'node:url';
-import { blockingPath, isFleetWide, parseRefs, scriptsOnlyChange, stripJsonc, turboCacheDir, turboTasks } from './prepush-sanity.mjs';
+import { blockingPath, dependentsLine, emptyPlanFailure, isInert, outsidePackages, packageDirs, dependentsOnly, isFleetWide, planRuns, parkOnly, parseRefs, scriptsOnlyChange, stripJsonc, turboCacheDir, turboTasks } from './prepush-sanity.mjs';
 
 const VERB = fileURLToPath(new URL('./prepush-sanity.mjs', import.meta.url));
 const SHA_A = 'a'.repeat(40);
@@ -18,6 +18,7 @@ test('stripJsonc drops comments outside strings only', () => {
 
 test('turboTasks keeps lint and typecheck, and throws on unparsable turbo.json', () => {
   assert.deepEqual(turboTasks('{"tasks":{"build":{},"typecheck":{},"lint":{}}}'), ['lint', 'typecheck']);
+  assert.deepEqual(turboTasks('{"tasks":{"openapi:current":{},"test":{},"build":{},"typecheck":{},"lint":{}}}'), ['lint', 'typecheck', 'test', 'openapi:current']);
   assert.deepEqual(turboTasks('{"pipeline":{"typecheck":{}}}'), ['typecheck']);
   assert.throws(() => turboTasks('{ nope'));
 });
@@ -136,3 +137,69 @@ test('the turbo invocation receives TURBO_CACHE_DIR', () => {
     rmSync(r.dir, { recursive: true, force: true });
   }
 });
+
+test('parkOnly: only a push whose every remote ref is a session park', () => {
+  const park = `refs/heads/x ${SHA_A} refs/xema-session/lead/T1/x ${'0'.repeat(40)}`;
+  const dev = `refs/heads/x ${SHA_A} refs/heads/develop ${SHA_B}`;
+  assert.equal(parkOnly(`${park}\n`), true);
+  assert.equal(parkOnly(`(delete) ${'0'.repeat(40)} refs/xema-session/lead/T1/x ${SHA_A}\n`), true);
+  assert.equal(parkOnly(`${park}\n${dev}\n`), false);
+  assert.equal(parkOnly(`${dev}\n`), false);
+  assert.equal(parkOnly(`refs/heads/x ${SHA_A} refs/heads/main ${SHA_B}\n`), false);
+  assert.equal(parkOnly(`refs/heads/x ${SHA_A} refs/heads/xema-session/x ${SHA_B}\n`), false);
+  assert.equal(parkOnly(''), false);
+});
+
+test('a park-only push skips and says why; a park beside develop still grades', () => {
+  const r = repo({ typecheck: 'exit 1', lint: 'exit 1' });
+  try {
+    const parked = hook(r.dir, `refs/heads/x ${r.sha} refs/xema-session/lead/T1/x ${'0'.repeat(40)}\n`);
+    assert.equal(parked.status, 0, parked.stdout + parked.stderr);
+    assert.match(parked.stdout, /skipped — every ref is a session park/);
+    const mixed = hook(r.dir, `refs/heads/x ${r.sha} refs/xema-session/lead/T1/x ${'0'.repeat(40)}\nrefs/heads/x ${r.sha} refs/heads/develop ${'0'.repeat(40)}\n`);
+    assert.equal(mixed.status, 1, mixed.stdout + mixed.stderr);
+    assert.match(mixed.stdout, /pre-push: FAILED/);
+  } finally {
+    rmSync(r.dir, { recursive: true, force: true });
+  }
+});
+
+test('planRuns: affected set for lint and typecheck, changed packages only for test and openapi:current', () => {
+  const tasks = ['lint', 'typecheck', 'test', 'openapi:current'];
+  assert.deepEqual(planRuns(tasks, 'A...B'), {
+    runs: [
+      { tasks: ['lint', 'typecheck'], filter: '...[A...B]' },
+      { tasks: ['test', 'openapi:current'], filter: '[A...B]' },
+    ],
+    leftToCi: [],
+  });
+  assert.deepEqual(planRuns(['test'], 'A...B').runs, [{ tasks: ['test'], filter: '[A...B]' }]);
+});
+
+test('planRuns: a root-file change runs lint and typecheck on all and leaves the rest to CI', () => {
+  assert.deepEqual(planRuns(['lint', 'typecheck', 'test'], ''), { runs: [{ tasks: ['lint', 'typecheck'], filter: null }], leftToCi: ['test'] });
+  assert.deepEqual(planRuns(['test'], ''), { runs: [], leftToCi: ['test'] });
+});
+
+test('dependentsOnly and dependentsLine name the dependents left to CI', () => {
+  const dependents = dependentsOnly(['//', 'b', 'a', 'c', 'a'], ['c']);
+  assert.deepEqual(dependents, ['a', 'b']);
+  assert.match(dependentsLine(dependents, ['test', 'openapi:current']), /test openapi:current ran only on the changed packages; 2 dependent\(s\) are left to CI: a, b/);
+  assert.equal(dependentsLine([], ['test']), '');
+  assert.equal(dependentsLine(['a'], []), '');
+});
+
+test('a path outside every workspace package is fleet-wide; package files and inert files are not', () => {
+  const dirs = packageDirs(['package.json', 'packages/a/package.json', 'packages/a/node_modules/x/package.json', 'apps/b/package.json']);
+  assert.deepEqual(dirs.sort(), ['apps/b', 'packages/a']);
+  assert.deepEqual(outsidePackages(['tsconfig.base.json', 'biome.json', 'tooling/ci/x.mjs'], dirs), ['tsconfig.base.json', 'biome.json', 'tooling/ci/x.mjs']);
+  assert.deepEqual(outsidePackages(['packages/a/src/x.ts', 'apps/b/package.json', 'README.md', '.changeset/x.md'], dirs), []);
+  assert.equal(isInert('README.md'), true);
+  assert.equal(isInert('tooling/README.md'), false);
+});
+
+test('zero planned tasks for a push with changes is a failure naming the paths, never green', () => {
+  assert.match(emptyPlanFailure(['tsconfig.base.json'], 0), /tsconfig\.base\.json.*nothing was checked/);
+  assert.equal(emptyPlanFailure(['packages/a/x.ts'], 3), null);
+  assert.equal(emptyPlanFailure([], 0), null);
+});