fix(runtime): publish migration gate atomically

Cause:
The final state-migration lock pathname was created before owner metadata was fully written. A concurrent Node 22 process could observe the empty publication window, or the lock could disappear between EEXIST and inspection, and report RUNTIME_STATE_NOT_QUIESCENT.

Scope:
Write and fsync ownership metadata in an exclusive candidate inode, publish it with an atomic hard link, retry a legitimate disappearance race, and preserve fail-closed handling for stable malformed locks. Release version 0.25.1.

Verification:
- Node 22 migration race stress: 30/30
- Node 22 State suite: 637/637
- npm run verify:release: 637 State, 156 Orchestrator, 262 host/package, 55 Hook, 0 audit vulnerabilities
- npm pack --dry-run --json: 207 files, no tests or cache artifacts

Residual risk:
The lock protocol requires filesystem hard-link support; unsupported filesystems fail closed rather than falling back to a torn pathname publication.

Rollback:
Revert this commit and reinstall 0.25.0; no database schema or persisted semantic authority changes are included.

Author: rocky2431

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.25.1] — 2026-07-31
+
+### Fixed
+
+- Published state-migration lock ownership atomically from a fully written and
+  synchronized candidate inode, so concurrent Node 22 processes cannot mistake a
+  valid publication or release window for a malformed lock. Stable malformed locks
+  remain fail-closed.
+
 ## [0.25.0] — 2026-07-31
 
 ### Added

mcp-server/lib/runtime-paths.cjs

@@ -599,15 +599,37 @@ function processIsAlive(pid) {
 
 function readMigrationGate(gatePath) {
   const stat = lstatOrNull(gatePath);
-  if (!stat || stat.isSymbolicLink() || !stat.isFile()) return null;
+  if (!stat) return { missing: true };
+  if (stat.isSymbolicLink() || !stat.isFile()) return null;
   try {
     const owner = JSON.parse(fs.readFileSync(gatePath, 'utf8'));
     return { owner, stat };
-  } catch {
+  } catch (error) {
+    if (error.code === 'ENOENT') return { missing: true };
     return null;
   }
 }
 
+function createMigrationGateCandidate(gatePath, owner) {
+  while (true) {
+    const candidatePath = `${gatePath}.candidate-${process.pid}-${randomUUID()}`;
+    let descriptor;
+    try {
+      descriptor = fs.openSync(candidatePath, 'wx', 0o600);
+      fs.writeFileSync(descriptor, `${JSON.stringify(owner)}\n`);
+      fs.fsyncSync(descriptor);
+      return { candidatePath, descriptor };
+    } catch (error) {
+      if (descriptor !== undefined) {
+        try { fs.closeSync(descriptor); } catch { /* best effort */ }
+      }
+      fs.rmSync(candidatePath, { force: true });
+      if (error.code === 'EEXIST') continue;
+      throw error;
+    }
+  }
+}
+
 function reclaimDeadMigrationGate(gatePath, observed) {
   const quarantine = `${gatePath}.stale-${process.pid}-${randomUUID()}`;
   fs.renameSync(gatePath, quarantine);
@@ -635,28 +657,28 @@ function acquireStateMigrationGate(paths, {
 } = {}) {
   const gatePath = path.join(paths.runtimeDir, 'state-migration.lock');
   const token = randomUUID();
+  const owner = {
+    version: 2,
+    pid: process.pid,
+    owner_started_at: processStartMarker(process.pid),
+    token,
+    legacy_state_db: paths.legacyStateDbPath,
+    runtime_state_db: paths.stateDbPath,
+  };
   const deadline = Date.now() + timeoutMs;
   let descriptor;
   while (descriptor === undefined) {
+    const candidate = createMigrationGateCandidate(gatePath, owner);
+    let published = false;
     try {
-      descriptor = fs.openSync(gatePath, 'wx', 0o600);
-      fs.writeFileSync(descriptor, `${JSON.stringify({
-        version: 2,
-        pid: process.pid,
-        owner_started_at: processStartMarker(process.pid),
-        token,
-        legacy_state_db: paths.legacyStateDbPath,
-        runtime_state_db: paths.stateDbPath,
-      })}\n`);
-      fs.fsyncSync(descriptor);
+      fs.linkSync(candidate.candidatePath, gatePath);
+      descriptor = candidate.descriptor;
+      published = true;
       break;
     } catch (error) {
-      if (descriptor !== undefined) {
-        try { fs.closeSync(descriptor); } catch { /* best effort */ }
-        descriptor = undefined;
-      }
       if (error.code !== 'EEXIST') throw error;
       const observed = readMigrationGate(gatePath);
+      if (observed?.missing) continue;
       const ownerPid = Number(observed?.owner?.pid);
       const live = processIsAlive(ownerPid);
       const currentStart = live ? processStartMarker(ownerPid) : null;
@@ -684,6 +706,11 @@ function acquireStateMigrationGate(paths, {
         continue;
       }
       reclaimDeadMigrationGate(gatePath, observed);
+    } finally {
+      fs.rmSync(candidate.candidatePath, { force: true });
+      if (!published) {
+        try { fs.closeSync(candidate.descriptor); } catch { /* best effort */ }
+      }
     }
   }
   return () => {

mcp-server/lib/runtime-paths.test.cjs

@@ -883,6 +883,116 @@ test('state migration reclaims a gate whose owner was killed', async () => {
   }
 });
 
+test('state migration publishes complete gate metadata before competitors can observe it', async () => {
+  const rootDir = mkRoot();
+  let first;
+  let second;
+  try {
+    const paths = runtimePaths.pathsFor(rootDir);
+    fs.mkdirSync(paths.runtimeDir, { recursive: true });
+    const writerReady = path.join(rootDir, 'gate-writer-ready');
+    const releaseWriter = path.join(rootDir, 'release-gate-writer');
+    const modulePath = path.join(__dirname, 'runtime-paths.cjs');
+    const firstScript = [
+      "const fs = require('node:fs');",
+      'const runtimePaths = require(process.argv[1]);',
+      'const paths = runtimePaths.pathsFor(process.argv[2]);',
+      'const ready = process.argv[3];',
+      'const release = process.argv[4];',
+      'const originalOpen = fs.openSync.bind(fs);',
+      'const originalWrite = fs.writeFileSync.bind(fs);',
+      'let gateDescriptor = null;',
+      'let delayed = false;',
+      'fs.openSync = (target, flags, mode) => {',
+      '  const descriptor = originalOpen(target, flags, mode);',
+      "  if (String(target).includes('state-migration.lock') && flags === 'wx') {",
+      '    gateDescriptor = descriptor;',
+      '  }',
+      '  return descriptor;',
+      '};',
+      'fs.writeFileSync = (target, ...args) => {',
+      '  if (target === gateDescriptor && !delayed) {',
+      '    delayed = true;',
+      "    originalWrite(ready, 'ready');",
+      '    while (!fs.existsSync(release)) {',
+      '      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);',
+      '    }',
+      '  }',
+      '  return originalWrite(target, ...args);',
+      '};',
+      'try {',
+      '  const releaseGate = runtimePaths._internal.acquireStateMigrationGate(paths);',
+      '  releaseGate();',
+      '  process.stdout.write(JSON.stringify({ acquired: true }));',
+      '} catch (error) {',
+      '  process.stdout.write(JSON.stringify({ acquired: false, code: error.code || null }));',
+      '}',
+    ].join('\n');
+    const secondScript = [
+      'const runtimePaths = require(process.argv[1]);',
+      'const paths = runtimePaths.pathsFor(process.argv[2]);',
+      'try {',
+      '  const releaseGate = runtimePaths._internal.acquireStateMigrationGate(paths);',
+      '  releaseGate();',
+      '  process.stdout.write(JSON.stringify({ acquired: true }));',
+      '} catch (error) {',
+      '  process.stdout.write(JSON.stringify({ acquired: false, code: error.code || null }));',
+      '}',
+    ].join('\n');
+
+    first = spawn(
+      process.execPath,
+      ['-e', firstScript, modulePath, rootDir, writerReady, releaseWriter],
+      { cwd: path.resolve(__dirname, '..', '..'), stdio: ['ignore', 'pipe', 'pipe'] },
+    );
+    const firstDone = collectChild(first, 'delayed migration gate writer');
+    await waitForFile(writerReady, 'migration gate writer');
+
+    second = spawn(
+      process.execPath,
+      ['-e', secondScript, modulePath, rootDir],
+      { cwd: path.resolve(__dirname, '..', '..'), stdio: ['ignore', 'pipe', 'pipe'] },
+    );
+    const secondResult = await collectChild(second, 'migration gate competitor');
+    fs.writeFileSync(releaseWriter, 'release');
+    const firstResult = await firstDone;
+
+    assert.deepEqual(secondResult, { acquired: true });
+    assert.deepEqual(firstResult, { acquired: true });
+    assert.equal(
+      fs.existsSync(path.join(paths.runtimeDir, 'state-migration.lock')),
+      false,
+    );
+  } finally {
+    if (first?.exitCode === null) first.kill('SIGKILL');
+    if (second?.exitCode === null) second.kill('SIGKILL');
+    cleanup(rootDir);
+  }
+});
+
+test('state migration rejects a stable malformed gate', () => {
+  const rootDir = mkRoot();
+  try {
+    const paths = runtimePaths.pathsFor(rootDir);
+    const initialized = initStateDb(paths.legacyStateDbPath);
+    closeStateDb(initialized.db);
+    fs.mkdirSync(paths.runtimeDir, { recursive: true });
+    const gatePath = path.join(paths.runtimeDir, 'state-migration.lock');
+    fs.writeFileSync(gatePath, '{"version":');
+
+    assert.throws(
+      () => runtimePaths.ensureRuntimeState(rootDir),
+      (error) => error instanceof runtimePaths.RuntimePathError
+        && error.code === 'RUNTIME_STATE_NOT_QUIESCENT'
+        && /malformed or unsafe/.test(error.message),
+    );
+    assert.equal(fs.readFileSync(gatePath, 'utf8'), '{"version":');
+    assert.equal(fs.existsSync(paths.stateDbPath), false);
+  } finally {
+    cleanup(rootDir);
+  }
+});
+
 test('state migration leaves a gate owned by a live process fail-closed', () => {
   const rootDir = mkRoot();
   try {

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "Explicitly invoked Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, Kimi Code, and Grok Build, with a project-local MCP persistence and safety kernel.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",