@massu/core 1.4.0 → 1.5.0

package/src/detect/adapters/spring.ts

@@ -0,0 +1,284 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3c — Phase 7: Spring (Spring Boot / Spring MVC) AST adapter.
+ *
+ * Sixth and final Phase 7 framework after go-chi + Flask + Rails + Phoenix
+ * + ASP.NET. First to consume the `java` Tree-sitter grammar entry from
+ * GRAMMAR_MANIFEST (commit fbb8aa9). All four queries verified against
+ * actual tree-sitter-java AST shape via probe (R-011) BEFORE writing the
+ * adapter — same discipline as phoenix + aspnet.
+ *
+ * Spring uses annotation-based routing per the Spring MVC reference
+ * (https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-controller.html):
+ *   - `@RestController` / `@Controller` at the class level
+ *   - `@RequestMapping("/api/users")` at class level for path prefix
+ *   - `@GetMapping("/{id}")` / `@PostMapping` / etc. on methods for verb +
+ *     optional sub-path
+ *
+ * Extracts:
+ *   - route_method: most-common HTTP verb captured from
+ *     `@<Verb>Mapping` annotations. Normalized: `GetMapping` → `Get`,
+ *     `PostMapping` → `Post`, etc. Mirrors aspnet's MapGet/HttpGet
+ *     normalization for downstream consumer consistency.
+ *   - route_prefix_base: first segment of the first class-level
+ *     `@RequestMapping("/api/...")` template, normalized to a leading-
+ *     slash path. Mirrors aspnet route_prefix_base / phoenix
+ *     scope_prefix_base.
+ *   - controller_class: name of the first class annotated with
+ *     `@RestController` or `@Controller`. Mirrors aspnet controller_class
+ *     / phoenix router_module.
+ *
+ * Confidence rules (mirror phoenix / rails / aspnet):
+ *   - 'high'   if exactly ONE distinct route_method seen.
+ *   - 'low'    if multiple distinct route_methods seen.
+ *   - 'medium' if route_prefix_base or controller_class found but no
+ *              route_method.
+ *   - 'none'   if no Spring signals at all.
+ *
+ * Tree-sitter-java AST shape (verified via probe 2026-05-07):
+ *   - Annotations come in TWO node-type flavors:
+ *       - `(marker_annotation name: (identifier))` for parameterless
+ *         annotations like `@PostMapping`, `@RestController`.
+ *       - `(annotation name: (identifier) arguments: (annotation_argument_list
+ *         (string_literal) ...))` for parameterized annotations like
+ *         `@GetMapping("/{id}")`, `@RequestMapping("/api/users")`.
+ *     Adapter queries cover BOTH where applicable.
+ *   - Class declarations: `(class_declaration (modifiers (annotation ...) /
+ *     (marker_annotation ...)) name: (identifier) body: (class_body ...))`.
+ *   - String literals are `(string_literal (string_fragment))`; node.text
+ *     returns the quoted source verbatim.
+ *
+ * Does NOT use regex on file content — only Tree-sitter S-expression queries
+ * compiled via query-helpers.ts.
+ */
+
+import { Parser } from 'web-tree-sitter';
+import type { CodebaseAdapter, AdapterResult, DetectionSignals, Provenance, SourceFile } from './types.ts';
+import { runQuery, InvalidQueryError } from './query-helpers.ts';
+import { loadGrammar } from './tree-sitter-loader.ts';
+import { isParsableSource, MAX_AST_FILE_BYTES } from './parse-guard.ts';
+
+// ============================================================
+// Tree-sitter S-expression queries (Java grammar)
+// ============================================================
+
+/**
+ * Parameterized HTTP mapping annotations: `@GetMapping("/{id}")`,
+ * `@PostMapping("/login")`, etc. Captures both the verb (from the
+ * annotation name) AND the path string for prefix-base extraction.
+ *
+ * Per Spring docs:
+ * https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-controller/ann-requestmapping.html
+ */
+const HTTP_MAPPING_QUERY = `
+(annotation
+  name: (identifier) @method (#match? @method "^(Get|Post|Put|Patch|Delete|Head|Options)Mapping$")
+  arguments: (annotation_argument_list
+    (string_literal) @route_path))
+`;
+
+/**
+ * Parameterless HTTP mapping annotations: `@PostMapping`, `@DeleteMapping`,
+ * etc. The tree-sitter-java grammar uses a separate `marker_annotation`
+ * node for annotations without an argument list — distinct from the
+ * parameterized `annotation` node above.
+ */
+const HTTP_MAPPING_NO_ARGS_QUERY = `
+(marker_annotation
+  name: (identifier) @method (#match? @method "^(Get|Post|Put|Patch|Delete|Head|Options)Mapping$"))
+`;
+
+/**
+ * Class-level `@RequestMapping("/api/users")`. Captures the path template
+ * so we can extract its first segment.
+ */
+const REQUEST_MAPPING_QUERY = `
+(annotation
+  name: (identifier) @_name (#eq? @_name "RequestMapping")
+  arguments: (annotation_argument_list
+    (string_literal) @route_template))
+`;
+
+/**
+ * Class declarations annotated with `@RestController` or `@Controller`.
+ * Both annotation flavors (marker + parameterized) are captured because
+ * Spring controllers usually use parameterless `@RestController` /
+ * `@Controller` but some use `@Controller(value = "name")`.
+ */
+const CONTROLLER_CLASS_QUERY = `
+(class_declaration
+  (modifiers
+    (marker_annotation
+      name: (identifier) @_anno (#match? @_anno "^(RestController|Controller)$")))
+  name: (identifier) @class_name)
+
+(class_declaration
+  (modifiers
+    (annotation
+      name: (identifier) @_anno (#match? @_anno "^(RestController|Controller)$")))
+  name: (identifier) @class_name)
+`;
+
+// ============================================================
+// Adapter
+// ============================================================
+
+export const springAdapter: CodebaseAdapter = {
+  id: 'spring',
+  languages: ['java'],
+
+  matches(signals: DetectionSignals): boolean {
+    // Cheap signal-only check. No file IO. The canonical Spring Boot
+    // declaration is the `spring-boot-starter-web` artifact (Maven) or
+    // dependency string (Gradle), per the Spring Boot reference:
+    // https://docs.spring.io/spring-boot/reference/using/build-systems.html
+    if (signals.pomXml && /\bspring-boot-starter[\w-]*\b/.test(signals.pomXml)) {
+      return true;
+    }
+    if (signals.gradleBuild && /\bspring-boot-starter[\w-]*\b/.test(signals.gradleBuild)) {
+      return true;
+    }
+    // Fallback: explicit `spring-webmvc` or `org.springframework` references
+    // catch projects that use Spring without Spring Boot (rare today but
+    // canonical Spring MVC pre-Boot apps).
+    if (signals.pomXml && /\borg\.springframework\b/.test(signals.pomXml)) {
+      return true;
+    }
+    if (signals.gradleBuild && /\borg\.springframework\b/.test(signals.gradleBuild)) {
+      return true;
+    }
+    return false;
+  },
+
+  async introspect(files: SourceFile[], _rootDir: string): Promise<AdapterResult> {
+    if (files.length === 0) {
+      return { conventions: {}, provenance: [], confidence: 'none' };
+    }
+
+    let language;
+    try {
+      language = await loadGrammar('java');
+    } catch (e) {
+      return { conventions: {}, provenance: [], confidence: 'none' };
+    }
+
+    const parser = new Parser();
+    parser.setLanguage(language);
+
+    const routeMethods = new Map<string, { line: number; file: string }>();
+    const prefixBases = new Map<string, { line: number; file: string }>();
+    const controllerClasses = new Map<string, { line: number; file: string }>();
+
+    try {
+      for (const file of files) {
+        const skip = isParsableSource(file.content, file.size);
+        if (skip) {
+          process.stderr.write(
+            `[massu/ast] WARN: spring skipping ${file.path}: ${skip.reason} (${skip.detail}). Cap=${MAX_AST_FILE_BYTES}. (Phase 3.5 mitigation)\n`,
+          );
+          continue;
+        }
+        try {
+          // Parameterized @<Verb>Mapping("/path")
+          for (const hit of runQuery(parser, file.content, HTTP_MAPPING_QUERY, 'spring-http-mapping', file.path)) {
+            const methodRaw = hit.captures.method;
+            if (!methodRaw) continue;
+            const verb = methodRaw.replace(/Mapping$/, ''); // GetMapping → Get
+            if (!routeMethods.has(verb)) {
+              routeMethods.set(verb, { line: hit.line, file: file.path });
+            }
+          }
+          // Parameterless @<Verb>Mapping
+          for (const hit of runQuery(parser, file.content, HTTP_MAPPING_NO_ARGS_QUERY, 'spring-http-mapping-marker', file.path)) {
+            const methodRaw = hit.captures.method;
+            if (!methodRaw) continue;
+            const verb = methodRaw.replace(/Mapping$/, '');
+            if (!routeMethods.has(verb)) {
+              routeMethods.set(verb, { line: hit.line, file: file.path });
+            }
+          }
+          // @RequestMapping("/api/...")
+          for (const hit of runQuery(parser, file.content, REQUEST_MAPPING_QUERY, 'spring-request-mapping', file.path)) {
+            const tplRaw = hit.captures.route_template;
+            if (!tplRaw) continue;
+            const literal = tplRaw.replace(/^["']/, '').replace(/["']$/, '');
+            const base = extractPrefixBase(literal);
+            if (base && !prefixBases.has(base)) {
+              prefixBases.set(base, { line: hit.line, file: file.path });
+            }
+          }
+          // @RestController / @Controller class
+          for (const hit of runQuery(parser, file.content, CONTROLLER_CLASS_QUERY, 'spring-controller-class', file.path)) {
+            const name = hit.captures.class_name;
+            if (name && !controllerClasses.has(name)) {
+              controllerClasses.set(name, { line: hit.line, file: file.path });
+            }
+          }
+        } catch (e) {
+          if (e instanceof InvalidQueryError) {
+            throw e;
+          }
+          continue;
+        }
+      }
+    } finally {
+      try { parser.delete(); } catch { /* ignore */ }
+    }
+
+    const conventions: Record<string, unknown> = {};
+    const provenance: Provenance[] = [];
+
+    if (routeMethods.size === 1) {
+      const [name, { line, file }] = routeMethods.entries().next().value as [string, { line: number; file: string }];
+      conventions.route_method = name;
+      provenance.push({ field: 'route_method', sourceFile: file, line, query: 'spring-http-mapping' });
+    } else if (routeMethods.size >= 2) {
+      const [name, { line, file }] = routeMethods.entries().next().value as [string, { line: number; file: string }];
+      conventions.route_method = name;
+      provenance.push({ field: 'route_method', sourceFile: file, line, query: 'spring-http-mapping' });
+    }
+
+    if (prefixBases.size >= 1) {
+      const [base, { line, file }] = prefixBases.entries().next().value as [string, { line: number; file: string }];
+      conventions.route_prefix_base = base;
+      provenance.push({ field: 'route_prefix_base', sourceFile: file, line, query: 'spring-request-mapping' });
+    }
+
+    if (controllerClasses.size >= 1) {
+      const [name, { line, file }] = controllerClasses.entries().next().value as [string, { line: number; file: string }];
+      conventions.controller_class = name;
+      provenance.push({ field: 'controller_class', sourceFile: file, line, query: 'spring-controller-class' });
+    }
+
+    let confidence: AdapterResult['confidence'];
+    if (Object.keys(conventions).length === 0) {
+      confidence = 'none';
+    } else if (routeMethods.size === 1) {
+      confidence = 'high';
+    } else if (routeMethods.size >= 2) {
+      confidence = 'low';
+    } else {
+      confidence = 'medium';
+    }
+
+    return { conventions, provenance, confidence };
+  },
+};
+
+// ============================================================
+// Helpers
+// ============================================================
+
+/**
+ * Extract the first path segment of a Spring `@RequestMapping` template.
+ * Mirrors aspnet/phoenix/rails/python-flask/go-chi extractors. Returns
+ * null if input is empty or `/`-only.
+ */
+function extractPrefixBase(prefix: string): string | null {
+  const stripped = prefix.replace(/^\/+/, '');
+  const firstSeg = stripped.split('/')[0];
+  if (!firstSeg) return null;
+  return '/' + firstSeg;
+}

package/src/detect/adapters/tree-sitter-loader.ts

@@ -161,6 +161,56 @@ export const GRAMMAR_MANIFEST: Partial<Record<TreeSitterLanguage, ManifestEntry>
     sha256: '41c4fdb2249a3aa6d87eed0d383081ff09725c2248b4977043a43825980ffcc7',
     version: '0.1.13',
   },
+  // ----------------------------------------------------------------
+  // Plan 3c Phase 7 expansion (2026-05-07):
+  //
+  // Six additional grammars to support the registry-verified framework
+  // adapters (go-chi, rails, aspnet, spring, ktor, phoenix) plus the
+  // bundled adapters in the same language families (gin/echo/fiber,
+  // sinatra, etc.). All entries use the SAME pinned tree-sitter-wasms
+  // version (0.1.13) as the v1 four to keep the dependency surface
+  // single-source.
+  //
+  // SHA-256s computed 2026-05-07 via:
+  //   curl -fsSL <url> | shasum -a 256
+  //
+  // The unpkg filename for C# uses an underscore (`c_sharp`) while the
+  // TreeSitterLanguage identifier uses no separator (`csharp`); the map
+  // key is the type identifier, the URL is the storage path — they do
+  // NOT need to match, the same as how `python` maps to `tree-sitter-
+  // python.wasm`. This is intentional and validated by the manifest
+  // shape test in tree-sitter-loader-manifest.test.ts.
+  // ----------------------------------------------------------------
+  go: {
+    url: 'https://unpkg.com/tree-sitter-wasms@0.1.13/out/tree-sitter-go.wasm',
+    sha256: '9963ca89b616eaf04b08a43bc1fb0f07b85395bec313330851f1f1ead2f755b6',
+    version: '0.1.13',
+  },
+  ruby: {
+    url: 'https://unpkg.com/tree-sitter-wasms@0.1.13/out/tree-sitter-ruby.wasm',
+    sha256: '93a5022855314cdb45458c7bb026a24a0ebc3a5ff6439e542e881f14dfa13a39',
+    version: '0.1.13',
+  },
+  csharp: {
+    url: 'https://unpkg.com/tree-sitter-wasms@0.1.13/out/tree-sitter-c_sharp.wasm',
+    sha256: '6266a7e32d68a3459104d994dc848df15d5672b0ea8e86d327274b694f8e6991',
+    version: '0.1.13',
+  },
+  java: {
+    url: 'https://unpkg.com/tree-sitter-wasms@0.1.13/out/tree-sitter-java.wasm',
+    sha256: '637aac4415fb39a211a4f4292d63c66b5ce9c32fa2cd35464af4f681d91b9a1f',
+    version: '0.1.13',
+  },
+  kotlin: {
+    url: 'https://unpkg.com/tree-sitter-wasms@0.1.13/out/tree-sitter-kotlin.wasm',
+    sha256: 'b5cb00c8d06ed0f10f1dbe497205b437809d7e87db1f638721a8cfb30e044449',
+    version: '0.1.13',
+  },
+  elixir: {
+    url: 'https://unpkg.com/tree-sitter-wasms@0.1.13/out/tree-sitter-elixir.wasm',
+    sha256: '82e91b9759ddca30d8978ebbfa8e347b4451b64c931f9ae62112e6db9b8fac20',
+    version: '0.1.13',
+  },
 };
 
 // ============================================================

package/src/detect/adapters/types.ts

@@ -68,6 +68,24 @@ export interface DetectionSignals {
   cargoToml?: Record<string, unknown>;
   /** Raw `go.mod` text — undefined if absent. */
   goMod?: string;
+  /** Raw `mix.exs` text — undefined if absent. Elixir/Mix manifest. */
+  mixExs?: string;
+  /**
+   * Raw text of the FIRST `.csproj` file found at the project root —
+   * undefined if absent. .NET project file (XML). Adapters that need to
+   * inspect more than one csproj (multi-project solutions) can re-scan from
+   * `presentFiles`.
+   */
+  csproj?: string;
+  /** Raw `pom.xml` text — undefined if absent. Maven build manifest. */
+  pomXml?: string;
+  /**
+   * Raw text of `build.gradle` OR `build.gradle.kts` — whichever exists at
+   * the project root, with `.kts` (Kotlin DSL) preferred when both are
+   * present (Kotlin DSL is the modern default per Gradle 7+ docs).
+   * Undefined if neither exists.
+   */
+  gradleBuild?: string;
   /** Set of present directory names directly under the project root (one level). */
   presentDirs: Set<string>;
   /** Set of present file basenames directly under the project root (one level). */

package/src/detect/monorepo-detector.ts

@@ -232,6 +232,7 @@ function detectPnpmWorkspaces(root: string): WorkspacePackage[] | null {
   const raw = safeReadText(join(root, 'pnpm-workspace.yaml'));
   if (!raw) return null;
   try {
+    // pattern-scanner-allow: yaml-parse — reason: Phase 1 auto-detection parses pnpm-workspace.yaml to discover workspace packages BEFORE any massu config exists. This runs PRE-getConfig in the init flow, so getConfig() is unavailable by definition.
     const parsed = parseYaml(raw) as { packages?: unknown } | null;
     const list = Array.isArray(parsed?.packages)
       ? (parsed!.packages as unknown[]).filter((x) => typeof x === 'string') as string[]

package/src/hooks/post-tool-use.ts

@@ -245,6 +245,7 @@ function readConventions(cwd?: string): {
     const configPath = join(projectRoot, 'massu.config.yaml');
     if (!existsSync(configPath)) return defaults;
     const content = readFileSync(configPath, 'utf-8');
+    // pattern-scanner-allow: yaml-parse — reason: compiled standalone hook (esbuild bundle). Per P2-023a, hooks cannot import getConfig() — they run in the Claude Code subprocess context with no module resolution path back to packages/core. Direct YAML parse is the only available access pattern.
     const parsed = parseYaml(content) as Record<string, unknown> | null;
     if (!parsed || typeof parsed !== 'object') return defaults;
     const conventions = parsed.conventions as Record<string, unknown> | undefined;

package/src/hooks/session-start.ts

@@ -279,6 +279,7 @@ async function buildDriftBanner(): Promise<string> {
     const configPath = resolve(process.cwd(), 'massu.config.yaml');
     if (!existsSync(configPath)) return '';
     const content = readFileSync(configPath, 'utf-8');
+    // pattern-scanner-allow: yaml-parse — reason: compiled standalone hook (esbuild bundle). Per P2-023a, hooks cannot import getConfig() — they run in the Claude Code subprocess context with no module resolution path back to packages/core. Direct YAML parse is the only available access pattern.
     const parsed = parseYaml(content) as Record<string, unknown> | null;
     if (!parsed || typeof parsed !== 'object') return '';
     const det = parsed.detection as Record<string, unknown> | undefined;

package/src/lib/fileLock.ts

@@ -0,0 +1,203 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Generic synchronous file-lock primitive built on `proper-lockfile`.
+ *
+ * Plan 3c gap-59 deliverable. Single source of truth for "acquire-lock,
+ * run fn, release on every exit path" across the codebase. Both
+ * `lib/installLock.ts:withInstallLock` (Plan 3a installAll serialization)
+ * AND `security/manifest-cache.ts:refreshManifest` (Plan 3c manifest
+ * cache writes) MUST delegate to `withFileLockSync` here — there is NO
+ * parallel lock implementation in the codebase per CR-46 / Rule 0
+ * (single-source-of-truth for lock semantics).
+ *
+ * What this primitive provides:
+ * 1. mkdirSync the lock parent dir if absent (fresh-repo / fresh-home case).
+ * 2. proper-lockfile.lockSync acquires the lock; we wrap the manual retry
+ *    loop because lockSync rejects retries>0 (`Cannot use retries with
+ *    the sync api` per node_modules/proper-lockfile/lib/adapter.js).
+ * 3. Surface ELOCKED (POSIX) and EBUSY (Windows) as the same FileLockBusyError.
+ * 4. Persist the lock-holder PID alongside the lock as `<lockPath>.pid` so
+ *    the next contender can include it in a user-friendly error message.
+ * 5. Default 30s block-then-bail per Plan 3a §190; configurable per-callsite.
+ * 6. `errorFactory` opt lets callers customize the busy-error class so
+ *    domain-specific helpers (`InstallLockBusyError`, future Phase 5
+ *    `ManifestCacheBusyError`) can extend the base type without each
+ *    re-implementing the lock logic.
+ *
+ * NOT provided by this primitive:
+ * - Async variant (`withFileLockAsync`). The current Phase 5 cache-write
+ *   path resolves the async fetch BEFORE acquiring the lock, so the lock
+ *   is held only during the brief sync atomicWrite. Async-while-holding-
+ *   the-lock would deadlock under contention; the design is "fetch first,
+ *   then lock-for-write only".
+ * - Reentrancy. `proper-lockfile.lockSync` is non-reentrant; calling
+ *   withFileLockSync recursively from inside its own `fn` will fail with
+ *   ELOCKED. Plan 3a observed and documented this in
+ *   __tests__/watch/config-refresh-autoyes.test.ts:129.
+ */
+
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+import * as lockfile from 'proper-lockfile';
+
+export interface FileLockOpts {
+  /** Default 30s — proper-lockfile considers a lock stale after this elapses. */
+  staleMs?: number;
+  /**
+   * How long the manual retry loop should block waiting for the holder to
+   * release before bailing with the busy error. Default 30s.
+   * Pass `0` to bail immediately (used in tests).
+   */
+  blockMs?: number;
+  /** Sleep granularity inside the retry loop. Default 100ms. */
+  pollIntervalMs?: number;
+  /**
+   * Backwards-compat: legacy callers pass `retries: 0` to mean "do not
+   * block". When set to a positive integer, used by tests that want to
+   * exercise a specific retry count instead of the default time-based loop.
+   */
+  retries?: number;
+  /** Override clock (test seam). */
+  now?: () => number;
+  /** Override sleep (test seam). Defaults to a busy-wait spinloop. */
+  sleep?: (ms: number) => void;
+  /**
+   * Optional custom busy-error factory. When provided, the default
+   * FileLockBusyError throw is replaced with whatever this factory returns.
+   * Domain-specific callers (installLock, manifest-cache) use this to
+   * keep their own user-facing error types and messages.
+   */
+  errorFactory?: (
+    lockPath: string,
+    holderPid: number | null,
+    retryAfterSeconds: number,
+    causeCode: string | undefined,
+  ) => Error;
+}
+
+export class FileLockBusyError extends Error {
+  constructor(
+    public lockPath: string,
+    public holderPid: number | null,
+    public retryAfterSeconds: number,
+    public causeCode?: string,
+  ) {
+    const pidPart = holderPid != null ? `(PID=${holderPid})` : '(PID=unknown)';
+    super(`File lock at ${lockPath} held by another process ${pidPart} — try again in ${retryAfterSeconds}s`);
+    this.name = 'FileLockBusyError';
+  }
+}
+
+/**
+ * Best-effort: read the PID of the current lock holder from the
+ * `<lockPath>.pid` sidecar file. Returns null on any read error.
+ */
+export function readLockHolderPid(lockPath: string): number | null {
+  try {
+    const raw = readFileSync(`${lockPath}.pid`, 'utf-8').trim();
+    const pid = Number.parseInt(raw, 10);
+    if (!Number.isFinite(pid) || pid <= 0) return null;
+    return pid;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * CR-9 audit L3 fix: REQUIRES SharedArrayBuffer + Atomics for the sync
+ * wait. The prior fallback (a tight `while (Date.now() < end)` spinloop)
+ * burned 100% CPU on environments without Atomics — typically sandboxed
+ * serverless runtimes — making contended manifest refreshes a DoS
+ * surface against the host. With this throw, callers running on
+ * Atomics-less environments fail loudly + early instead of silently
+ * spinning.
+ */
+export function busyWaitSync(ms: number): void {
+  if (typeof SharedArrayBuffer === 'undefined' || typeof Atomics === 'undefined') {
+    throw new Error(
+      `withFileLockSync requires SharedArrayBuffer + Atomics for its retry-loop wait. ` +
+      `This Node runtime does not provide them — refusing to fall back to a CPU spinloop. ` +
+      `If you hit this in a sandboxed serverless env, the fix is to perform the ` +
+      `lock-protected operation in a host runtime that supports Atomics.`,
+    );
+  }
+  const sab = new SharedArrayBuffer(4);
+  const view = new Int32Array(sab);
+  Atomics.wait(view, 0, 0, ms);
+}
+
+/**
+ * Acquire the lock at `lockPath`, run `fn`, release on every exit path.
+ * Synchronous all the way through. See module-level doc for guarantees.
+ *
+ * Throws:
+ * - The result of `opts.errorFactory(...)` if provided AND lock is busy
+ *   beyond `blockMs`. Otherwise throws FileLockBusyError.
+ * - Any non-ELOCKED/EBUSY filesystem error from proper-lockfile is
+ *   re-thrown unchanged.
+ */
+export function withFileLockSync<T>(lockPath: string, fn: () => T, opts: FileLockOpts = {}): T {
+  // Ensure the lock's parent directory exists. Fresh repos / fresh user-home
+  // .massu/ may not have the parent yet.
+  mkdirSync(dirname(lockPath), { recursive: true });
+
+  const staleMs = opts.staleMs ?? 30_000;
+  const blockMs = opts.retries === 0 ? 0 : (opts.blockMs ?? 30_000);
+  const pollIntervalMs = opts.pollIntervalMs ?? 100;
+  const now = opts.now ?? Date.now;
+  const sleep = opts.sleep ?? busyWaitSync;
+  const makeBusyError =
+    opts.errorFactory ??
+    ((path, pid, retrySeconds, code) => new FileLockBusyError(path, pid, retrySeconds, code));
+
+  let release: (() => void) | null = null;
+  const deadline = now() + blockMs;
+
+  for (;;) {
+    try {
+      release = lockfile.lockSync(lockPath, {
+        stale: staleMs,
+        retries: 0,
+        realpath: false,
+      });
+      try {
+        writeFileSync(`${lockPath}.pid`, String(process.pid), 'utf-8');
+      } catch {
+        // best-effort
+      }
+      break;
+    } catch (err) {
+      const e = err as NodeJS.ErrnoException;
+      const code = e.code;
+      if (code !== 'ELOCKED' && code !== 'EBUSY') {
+        throw err;
+      }
+      if (now() >= deadline) {
+        const holderPid = readLockHolderPid(lockPath);
+        const remainingMs = Math.max(0, deadline - now());
+        const retryAfterSeconds = blockMs === 0
+          ? Math.round(staleMs / 1000)
+          : Math.round(remainingMs / 1000);
+        throw makeBusyError(lockPath, holderPid, retryAfterSeconds, code);
+      }
+      sleep(pollIntervalMs);
+    }
+  }
+
+  try {
+    return fn();
+  } finally {
+    try {
+      if (release) release();
+    } catch {
+      // best-effort
+    }
+    try {
+      rmSync(`${lockPath}.pid`, { force: true });
+    } catch {
+      // best-effort
+    }
+  }
+}