oh-my-customcode 1.1.101 → 1.1.103

package/dist/cli/index.js

@@ -335,7 +335,7 @@ var init_package = __esm(() => {
     workspaces: [
       "packages/*"
     ],
-    version: "1.1.101",
+    version: "1.1.103",
     description: "Batteries-included agent harness for Claude Code",
     type: "module",
     bin: {
@@ -7331,7 +7331,7 @@ var require_public_api = __commonJS(function(exports) {
 });
 
 // src/utils/fs.ts
-import { dirname as dirname3, isAbsolute as isAbsolute2, join as join4, relative, resolve as resolve2, sep as sep3 } from "node:path";
+import { dirname as dirname3, isAbsolute as isAbsolute3, join as join4, relative, resolve as resolve2, sep as sep3 } from "node:path";
 import { fileURLToPath } from "node:url";
 function validatePreserveFilePath(filePath, projectRoot) {
   if (!filePath || filePath.trim() === "") {
@@ -7340,7 +7340,7 @@ function validatePreserveFilePath(filePath, projectRoot) {
       reason: "Path cannot be empty"
     };
   }
-  if (isAbsolute2(filePath)) {
+  if (isAbsolute3(filePath)) {
     return {
       valid: false,
       reason: "Absolute paths are not allowed"
@@ -7348,7 +7348,7 @@ function validatePreserveFilePath(filePath, projectRoot) {
   }
   const resolvedPath = resolve2(projectRoot, filePath);
   const relativePath = relative(projectRoot, resolvedPath);
-  if (relativePath.startsWith("..") || isAbsolute2(relativePath)) {
+  if (relativePath.startsWith("..") || isAbsolute3(relativePath)) {
     return {
       valid: false,
       reason: "Path cannot traverse outside project root"
@@ -11972,8 +11972,7 @@ init_registry();
 init_package();
 import { execSync as execSync2, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir as homedir2 } from "node:os";
-import { dirname as dirname2, join as join3 } from "node:path";
+import { dirname as dirname2, isAbsolute as isAbsolute2, join as join3 } from "node:path";
 import { createInterface } from "node:readline/promises";
 
 // node_modules/.bun/i18next@26.0.2+ff0372d108591aba/node_modules/i18next/dist/esm/i18next.js
@@ -14665,7 +14664,9 @@ var en_default = {
         openOption: "Open browser automatically after start",
         foregroundOption: "Run in foreground (not detached)",
         started: "Web UI started: http://localhost:{{port}}",
-        failed: "Failed to start Web UI server"
+        failed: "Failed to start Web UI server",
+        homeUnresolved: "Cannot start the Web UI server: the home directory cannot be resolved, either because HOME is a relative path or because HOME, the OS-reported home and the passwd entry are all empty, so the PID file location cannot be determined. Set HOME to an absolute path.",
+        pidNotWritable: "Cannot start the Web UI server: the PID file {{path}} cannot be written ({{error}}). Check the PID file path and its parent directory."
       },
       stop: {
         description: "Stop the Web UI server",
@@ -15083,7 +15084,9 @@ var ko_default = {
         openOption: "시작 후 브라우저 자동 열기",
         foregroundOption: "포그라운드 실행 (백그라운드 분리 안 함)",
         started: "Web UI 시작됨: http://localhost:{{port}}",
-        failed: "Web UI 서버 시작 실패"
+        failed: "Web UI 서버 시작 실패",
+        homeUnresolved: "Web UI 서버를 시작할 수 없습니다: 홈 디렉토리를 확인할 수 없어 PID 파일 위치를 정할 수 없습니다. HOME이 상대 경로이거나, HOME·OS 보고 홈·passwd 항목이 모두 비어 있는 경우입니다. HOME을 절대 경로로 설정하세요.",
+        pidNotWritable: "Web UI 서버를 시작할 수 없습니다: PID 파일 {{path}}에 쓸 수 없습니다 ({{error}}). PID 파일 경로와 그 상위 디렉토리를 확인하세요."
       },
       stop: {
         description: "Web UI 서버 중지",
@@ -15269,9 +15272,18 @@ var i18n = {
 };
 
 // src/core/self-update.ts
+init_home();
 var DEFAULT_PACKAGE_NAME = "oh-my-customcode";
 var DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
-var DEFAULT_CACHE_PATH = join3(homedir2(), ".oh-my-customcode", "self-update-cache.json");
+var CACHE_DIR_NAME = ".oh-my-customcode";
+var CACHE_FILE_NAME = "self-update-cache.json";
+function resolveSelfUpdateCachePath(sources) {
+  const home = resolveHomeDir(sources);
+  if (!isAbsolute2(home)) {
+    return null;
+  }
+  return join3(home, CACHE_DIR_NAME, CACHE_FILE_NAME);
+}
 var MS_EPOCH_THRESHOLD = 1000000000000;
 function normalizeVersion(version) {
   return version.trim().replace(/^v/i, "").split("-")[0] || "";
@@ -15367,20 +15379,36 @@ function readSelfUpdateCache(cachePath) {
   }
   return null;
 }
+function readCacheAt(cachePath) {
+  return cachePath === null ? null : readSelfUpdateCache(cachePath);
+}
+function isFileSystemError(error) {
+  const { code, errno } = error ?? {};
+  return typeof code === "string" && typeof errno === "number";
+}
 function writeCache(cachePath, latestVersion, now) {
-  const dir = dirname2(cachePath);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
+  if (cachePath === null) {
+    return;
   }
-  const payload = {
-    checkedAt: new Date(now).toISOString(),
-    latestVersion,
-    version: latestVersion,
-    timestamp: Math.floor(now / 1000),
-    source: "omcustom-cli"
-  };
-  writeFileSync(cachePath, `${JSON.stringify(payload, null, 2)}
+  try {
+    const dir = dirname2(cachePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    const payload = {
+      checkedAt: new Date(now).toISOString(),
+      latestVersion,
+      version: latestVersion,
+      timestamp: Math.floor(now / 1000),
+      source: "omcustom-cli"
+    };
+    writeFileSync(cachePath, `${JSON.stringify(payload, null, 2)}
 `, "utf-8");
+  } catch (error) {
+    if (!isFileSystemError(error)) {
+      throw error;
+    }
+  }
 }
 function isCacheFresh(cache, now, cacheTtlMs) {
   const checkedAt = new Date(cache.checkedAt).getTime();
@@ -15520,7 +15548,7 @@ function executeSelfUpdate(options = {}) {
 }
 function checkSelfUpdate(options) {
   const packageName = options.packageName || DEFAULT_PACKAGE_NAME;
-  const cachePath = options.cachePath || DEFAULT_CACHE_PATH;
+  const cachePath = options.cachePath || resolveSelfUpdateCachePath();
   const cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
   const fetchLatestVersion = options.fetchLatestVersion || fetchLatestVersionFromNpm;
   const now = options.now ?? Date.now();
@@ -15536,7 +15564,7 @@ function checkSelfUpdate(options) {
   }
   let latestVersion = null;
   let usedCache = false;
-  const cache = readSelfUpdateCache(cachePath);
+  const cache = readCacheAt(cachePath);
   if (cache && isCacheFresh(cache, now, cacheTtlMs)) {
     const cachedVersion = normalizeVersion(cache.latestVersion);
     if (isVersionPlausible(currentVersion, cachedVersion)) {
@@ -15758,6 +15786,7 @@ var MESSAGES = {
     "lockfile.component_dir_missing": "Component directory missing: {{path}}",
     "lockfile.hash_failed": "Failed to hash file: {{path}} — {{error}}",
     "lockfile.entry_added": "Lockfile entry added: {{path}} ({{component}})",
+    "lockfile.entry_git_excluded": "Lockfile entry skipped (not in git listing): {{path}}",
     "update.start": "Checking for updates...",
     "update.success": "Updated from {{from}} to {{to}}",
     "update.components_synced": "Components synced (version {{version}}): {{components}}",
@@ -15879,6 +15908,7 @@ var MESSAGES = {
     "lockfile.component_dir_missing": "컴포넌트 디렉토리 없음: {{path}}",
     "lockfile.hash_failed": "파일 해시 실패: {{path}} — {{error}}",
     "lockfile.entry_added": "잠금 파일 항목 추가: {{path}} ({{component}})",
+    "lockfile.entry_git_excluded": "잠금 파일 항목 제외 (git 목록에 없음): {{path}}",
     "update.start": "업데이트 확인 중...",
     "update.success": "{{from}}에서 {{to}}로 업데이트 완료",
     "update.components_synced": "컴포넌트 동기화 완료 (버전 {{version}}): {{components}}",
@@ -16334,10 +16364,12 @@ function getComponentPath(component) {
 
 // src/core/lockfile.ts
 init_fs();
+import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
-import { readdir, stat } from "node:fs/promises";
+import { readdir, realpath, stat } from "node:fs/promises";
 import { join as join7, relative as relative2 } from "node:path";
+import { promisify } from "node:util";
 var LOCKFILE_NAME = ".omcustom.lock.json";
 var LOCKFILE_VERSION = 1;
 var LOCKFILE_COMPONENTS = [
@@ -16350,6 +16382,87 @@ var LOCKFILE_COMPONENTS = [
   "guides"
 ];
 var COMPONENT_PATHS = LOCKFILE_COMPONENTS.map((component) => [getComponentPath(component), component]);
+var execFileAsync = promisify(execFile);
+var GIT_LOCATION_ENV_KEYS = [
+  "GIT_DIR",
+  "GIT_WORK_TREE",
+  "GIT_INDEX_FILE",
+  "GIT_PREFIX",
+  "GIT_COMMON_DIR"
+];
+var GIT_INJECTED_CONFIG_ENV_KEYS = ["GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT"];
+var GIT_INJECTED_CONFIG_ENV_PREFIXES = ["GIT_CONFIG_KEY_", "GIT_CONFIG_VALUE_"];
+var GIT_REQUIRED_HINT = "build from a git checkout: excluding ignored local files from the lockfile requires git (#1819)";
+function gitChildEnv() {
+  const env = { ...process.env };
+  for (const key of [...GIT_LOCATION_ENV_KEYS, ...GIT_INJECTED_CONFIG_ENV_KEYS]) {
+    delete env[key];
+  }
+  for (const key of Object.keys(env)) {
+    if (GIT_INJECTED_CONFIG_ENV_PREFIXES.some((prefix) => key.startsWith(prefix))) {
+      delete env[key];
+    }
+  }
+  return env;
+}
+async function runGit(targetDir, args, env) {
+  try {
+    const { stdout } = await execFileAsync("git", args, {
+      cwd: targetDir,
+      env,
+      encoding: "utf-8",
+      maxBuffer: 256 * 1024 * 1024
+    });
+    return stdout;
+  } catch (err) {
+    const detail = err instanceof Error ? err.message.trim() : String(err);
+    throw new Error(`git ${args[0]} failed in ${targetDir}: ${detail} — ${GIT_REQUIRED_HINT}`);
+  }
+}
+function foldCase(nfcPath) {
+  return nfcPath.toLowerCase();
+}
+function isGitVisible(visible, relativePath) {
+  if (visible.exact.has(relativePath)) {
+    return true;
+  }
+  const nfc = relativePath.normalize("NFC");
+  if (visible.nfc.has(nfc)) {
+    return true;
+  }
+  return visible.folded?.has(foldCase(nfc)) ?? false;
+}
+function stripFinalNewline(output) {
+  return output.endsWith(`
+`) ? output.slice(0, -1) : output;
+}
+async function assertGitWorkTreeRoot(targetDir, env) {
+  const topLevel = stripFinalNewline(await runGit(targetDir, ["rev-parse", "--show-toplevel"], env));
+  let realTop;
+  let realTarget;
+  try {
+    [realTop, realTarget] = await Promise.all([realpath(topLevel), realpath(targetDir)]);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(`cannot resolve the git work tree root of ${targetDir}: ${detail} — ${GIT_REQUIRED_HINT}`);
+  }
+  if (realTop !== realTarget) {
+    throw new Error(`${targetDir} is not the root of its git work tree (root: ${topLevel}) — ${GIT_REQUIRED_HINT}`);
+  }
+}
+async function listGitVisiblePaths(targetDir) {
+  const env = gitChildEnv();
+  await assertGitWorkTreeRoot(targetDir, env);
+  const pathspecs = COMPONENT_PATHS.map(([prefix]) => prefix);
+  const [listing, ignoreCase] = await Promise.all([
+    runGit(targetDir, ["ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", ...pathspecs], env),
+    runGit(targetDir, ["config", "--type=bool", "--default=false", "--get", "core.ignorecase"], env)
+  ]);
+  const exact = new Set(listing.split("\x00").filter((entry) => entry.length > 0));
+  const nfc = new Set([...exact].map((entry) => entry.normalize("NFC")));
+  const folded = stripFinalNewline(ignoreCase) === "true" ? new Set([...nfc].map(foldCase)) : null;
+  return { exact, nfc, folded };
+}
 function computeFileHash(filePath) {
   return new Promise((resolve, reject) => {
     const hash = createHash("sha256");
@@ -16431,8 +16544,13 @@ async function collectFiles(dir, projectRoot, isTopLevel) {
   }
   return results;
 }
-async function generateLockfile(targetDir, generatorVersion, templateVersion) {
+function sortFilesByPath(files) {
+  const sorted = Object.keys(files).sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+  return Object.fromEntries(sorted.map((key) => [key, files[key]]));
+}
+async function generateLockfile(targetDir, generatorVersion, templateVersion, options = {}) {
   const files = {};
+  const gitVisible = options.excludeGitIgnored ? await listGitVisiblePaths(targetDir) : null;
   const componentRoots = COMPONENT_PATHS.map(([prefix]) => join7(targetDir, prefix));
   for (const componentRoot of componentRoots) {
     const exists = await fileExists(componentRoot);
@@ -16443,6 +16561,10 @@ async function generateLockfile(targetDir, generatorVersion, templateVersion) {
     const allFiles = await collectFiles(componentRoot, targetDir, false);
     for (const absolutePath of allFiles) {
       const relativePath = relative2(targetDir, absolutePath).replace(/\\/g, "/");
+      if (gitVisible !== null && !isGitVisible(gitVisible, relativePath)) {
+        debug("lockfile.entry_git_excluded", { path: relativePath });
+        continue;
+      }
       let hash;
       let size;
       try {
@@ -16467,15 +16589,50 @@ async function generateLockfile(targetDir, generatorVersion, templateVersion) {
     generatorVersion,
     generatedAt: new Date().toISOString(),
     templateVersion,
-    files
+    files: sortFilesByPath(files)
   };
 }
-async function generateAndWriteLockfileForDir(targetDir) {
+function hasSameLockfileContent(next, previous) {
+  if (next.lockfileVersion !== previous.lockfileVersion || next.generatorVersion !== previous.generatorVersion || next.templateVersion !== previous.templateVersion) {
+    return false;
+  }
+  const nextKeys = Object.keys(next.files);
+  if (nextKeys.length !== Object.keys(previous.files).length) {
+    return false;
+  }
+  return nextKeys.every((key) => {
+    if (!Object.hasOwn(previous.files, key)) {
+      return false;
+    }
+    const before = previous.files[key];
+    const after = next.files[key];
+    return typeof before === "object" && before !== null && before.templateHash === after.templateHash && before.size === after.size && before.component === after.component;
+  });
+}
+function isIsoTimestamp(value) {
+  if (typeof value !== "string") {
+    return false;
+  }
+  const time = new Date(value).getTime();
+  return !Number.isNaN(time) && new Date(time).toISOString() === value;
+}
+function preserveGeneratedAt(next, previous) {
+  if (previous === null || !isIsoTimestamp(previous.generatedAt)) {
+    return next;
+  }
+  if (!hasSameLockfileContent(next, previous)) {
+    return next;
+  }
+  return { ...next, generatedAt: previous.generatedAt };
+}
+async function generateAndWriteLockfileForDir(targetDir, options = {}) {
   try {
     const packageRoot = getPackageRoot();
     const manifest = await readJsonFile(join7(packageRoot, "templates", "manifest.json"));
     const { version: generatorVersion } = await readJsonFile(join7(packageRoot, "package.json"));
-    const lockfile = await generateLockfile(targetDir, generatorVersion, manifest.version);
+    const generated = await generateLockfile(targetDir, generatorVersion, manifest.version, options);
+    const previous = await readLockfile(targetDir);
+    const lockfile = preserveGeneratedAt(generated, previous);
     await writeLockfile(targetDir, lockfile);
     return { fileCount: Object.keys(lockfile.files).length };
   } catch (err) {
@@ -20869,12 +21026,50 @@ import { spawnSync as spawnSync2 } from "node:child_process";
 import { join as join17 } from "node:path";
 
 // src/cli/serve.ts
+init_home();
 import { spawn } from "node:child_process";
-import { existsSync as existsSync3 } from "node:fs";
-import { readFile as readFile3, unlink, writeFile as writeFile3 } from "node:fs/promises";
-import { join as join16 } from "node:path";
+import { randomUUID } from "node:crypto";
+import { constants as constants3, existsSync as existsSync3 } from "node:fs";
+import {
+  access,
+  link,
+  readdir as readdir3,
+  readFile as readFile3,
+  readlink,
+  rename as rename2,
+  stat as stat3,
+  unlink,
+  writeFile as writeFile3
+} from "node:fs/promises";
+import { dirname as dirname7, isAbsolute as isAbsolute4, join as join16 } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 var DEFAULT_PORT = 4321;
-var PID_FILE = join16(process.env.HOME ?? "~", ".omcustom-serve.pid");
+var PID_FILE_NAME = ".omcustom-serve.pid";
+var STARTING_RECORD = /^starting:(\d+):/;
+var MAX_CLAIM_ATTEMPTS = 3;
+var CLAIM_MAX_AGE_MS = 60000;
+var PARTIAL_RECORD_GRACE_MS = 1e4;
+var ABSENT_RETRY_DELAY_MS = 10;
+var HARD_LINK_UNSUPPORTED = new Set(["ENOTSUP", "EOPNOTSUPP", "EPERM", "EXDEV"]);
+var SIBLING_REMNANT = /^\.omcustom-serve\.pid\.(\d+)\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.(?:tmp|taken)$/;
+
+class ServePidFileError extends Error {
+  reason;
+  pidFile;
+  constructor(reason, pidFile, options) {
+    super(reason === "home-unresolved" ? "Cannot resolve the serve PID file: the home directory is empty or relative" : `Cannot write the serve PID file: ${pidFile}`, options);
+    this.name = "ServePidFileError";
+    this.reason = reason;
+    this.pidFile = pidFile;
+  }
+}
+function resolveServePidFile(sources) {
+  const home = resolveHomeDir(sources);
+  if (!isAbsolute4(home)) {
+    return null;
+  }
+  return join16(home, PID_FILE_NAME);
+}
 function findServeBuildDir(projectRoot, options) {
   const localBuild = join16(projectRoot, "packages", "serve", "build");
   if (existsSync3(join16(localBuild, "index.js")))
@@ -20886,29 +21081,94 @@ function findServeBuildDir(projectRoot, options) {
   }
   return null;
 }
-async function isServeRunning() {
+function parsePidRecord(raw) {
+  const text = raw.trim();
+  const match = STARTING_RECORD.exec(text);
+  const pid = Number(match === null ? text : match[1]);
+  if (!Number.isFinite(pid) || pid <= 0) {
+    return null;
+  }
+  return { pid, starting: match !== null };
+}
+function isProcessAlive(pid) {
   try {
-    const raw = await readFile3(PID_FILE, "utf-8");
-    const pid = Number(raw.trim());
-    if (!Number.isFinite(pid) || pid <= 0) {
-      await cleanupPidFile();
-      return false;
-    }
     process.kill(pid, 0);
     return true;
   } catch {
-    await cleanupPidFile();
     return false;
   }
 }
+function errorCode(error) {
+  return error?.code;
+}
+async function isOlderThan(path, ms) {
+  try {
+    const { mtimeMs } = await stat3(path);
+    return Date.now() - mtimeMs >= ms;
+  } catch {
+    return false;
+  }
+}
+async function isRecordLive(pidFile, record) {
+  if (!isProcessAlive(record.pid)) {
+    return false;
+  }
+  return !record.starting || !await isOlderThan(pidFile, CLAIM_MAX_AGE_MS);
+}
+async function readPidFileSettled(pidFile) {
+  try {
+    return await readFile3(pidFile, "utf-8");
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") {
+      throw error;
+    }
+  }
+  await delay(ABSENT_RETRY_DELAY_MS);
+  return readFile3(pidFile, "utf-8");
+}
+async function isServeRunning() {
+  const pidFile = resolveServePidFile();
+  if (pidFile === null) {
+    return false;
+  }
+  return isServeRunningAt(pidFile);
+}
+async function isServeRunningAt(pidFile) {
+  let raw;
+  try {
+    raw = await readPidFileSettled(pidFile);
+  } catch {
+    return false;
+  }
+  const record = parsePidRecord(raw);
+  return record !== null && await isRecordLive(pidFile, record);
+}
 async function startServeBackground(projectRoot, port = DEFAULT_PORT, buildDirOpts) {
-  if (await isServeRunning()) {
+  const pidFile = resolveServePidFile();
+  if (pidFile === null) {
+    throw new ServePidFileError("home-unresolved", null);
+  }
+  if (await isServeRunningAt(pidFile)) {
     return;
   }
   const buildDir = findServeBuildDir(projectRoot, buildDirOpts);
   if (buildDir === null) {
     return;
   }
+  try {
+    await access(dirname7(pidFile), constants3.W_OK);
+  } catch (error) {
+    throw new ServePidFileError("pid-not-writable", pidFile, { cause: error });
+  }
+  let claim;
+  try {
+    claim = await claimPidFile(pidFile);
+  } catch (error) {
+    throw new ServePidFileError("pid-not-writable", pidFile, { cause: error });
+  }
+  if (claim === null) {
+    return;
+  }
   const child = spawn("node", [join16(buildDir, "index.js")], {
     env: {
       ...process.env,
@@ -20920,30 +21180,220 @@ async function startServeBackground(projectRoot, port = DEFAULT_PORT, buildDirOp
     stdio: "ignore",
     detached: true
   });
+  child.on("error", () => {});
   child.unref();
-  if (child.pid !== undefined) {
-    await writeFile3(PID_FILE, String(child.pid), "utf-8");
+  if (child.pid === undefined) {
+    await removePidFileIf(pidFile, claim);
+    return;
+  }
+  let recorded;
+  try {
+    recorded = await recordServerPid(pidFile, claim, String(child.pid));
+  } catch (error) {
+    child.kill("SIGTERM");
+    await removePidFileIf(pidFile, claim);
+    throw new ServePidFileError("pid-not-writable", pidFile, { cause: error });
+  }
+  if (!recorded) {
+    child.kill("SIGTERM");
   }
 }
+async function recordServerPid(pidFile, claim, pid) {
+  for (let attempt = 0;attempt < MAX_CLAIM_ATTEMPTS; attempt++) {
+    if (await createPidFileExclusive(pidFile, pid)) {
+      return true;
+    }
+    let current;
+    try {
+      current = await readFile3(pidFile, "utf-8");
+    } catch (error) {
+      if (errorCode(error) === "ENOENT") {
+        continue;
+      }
+      throw error;
+    }
+    if (current !== claim) {
+      return false;
+    }
+    await replacePidFile(pidFile, pid);
+    return true;
+  }
+  return false;
+}
 async function stopServe() {
+  const pidFile = resolveServePidFile();
+  if (pidFile === null) {
+    return false;
+  }
+  let raw;
   try {
-    const raw = await readFile3(PID_FILE, "utf-8");
-    const pid = Number(raw.trim());
-    if (!Number.isFinite(pid) || pid <= 0) {
-      await cleanupPidFile();
-      return false;
+    raw = await readPidFileSettled(pidFile);
+  } catch {
+    return false;
+  }
+  const record = parsePidRecord(raw);
+  if (record === null || record.starting) {
+    return false;
+  }
+  try {
+    process.kill(record.pid, "SIGTERM");
+  } catch {
+    return false;
+  }
+  await removePidFileIf(pidFile, raw);
+  return true;
+}
+function siblingPath(pidFile, suffix) {
+  return `${pidFile}.${process.pid}.${randomUUID()}.${suffix}`;
+}
+async function claimPidFile(pidFile) {
+  await removeDeadSiblings(pidFile);
+  const claim = `starting:${process.pid}:${randomUUID()}`;
+  for (let attempt = 0;attempt < MAX_CLAIM_ATTEMPTS; attempt++) {
+    if (await createPidFileExclusive(pidFile, claim)) {
+      return claim;
+    }
+    let raw;
+    try {
+      raw = await readFile3(pidFile, "utf-8");
+    } catch (error) {
+      if (errorCode(error) === "ENOENT") {
+        await removeDanglingLink(pidFile);
+        continue;
+      }
+      throw error;
+    }
+    if (await isRecordHeld(pidFile, raw)) {
+      return null;
     }
-    process.kill(pid, "SIGTERM");
-    await cleanupPidFile();
+    await removePidFileIf(pidFile, raw);
+  }
+  return null;
+}
+async function isRecordHeld(pidFile, raw) {
+  const record = parsePidRecord(raw);
+  if (record === null) {
+    return isPossiblyPartialRecord(raw) && !await isOlderThan(pidFile, PARTIAL_RECORD_GRACE_MS);
+  }
+  return isRecordLive(pidFile, record);
+}
+function isPossiblyPartialRecord(raw) {
+  return "starting:".startsWith(raw) || /^starting:\d*$/.test(raw);
+}
+async function removeDeadSiblings(pidFile) {
+  const dir = dirname7(pidFile);
+  let names;
+  try {
+    names = await readdir3(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    const match = SIBLING_REMNANT.exec(name);
+    if (match !== null && isProcessGone(Number(match[1]))) {
+      await unlinkQuietly(join16(dir, name));
+    }
+  }
+}
+function isProcessGone(pid) {
+  try {
+    process.kill(pid, 0);
+    return false;
+  } catch (error) {
+    return errorCode(error) === "ESRCH";
+  }
+}
+async function createPidFileExclusive(pidFile, content) {
+  const staged = siblingPath(pidFile, "tmp");
+  try {
+    await writeFile3(staged, content, { encoding: "utf-8", flag: "wx" });
+    await linkExclusive(staged, pidFile, content);
     return true;
+  } catch (error) {
+    if (errorCode(error) === "EEXIST") {
+      return false;
+    }
+    throw error;
+  } finally {
+    await unlinkQuietly(staged);
+  }
+}
+async function linkExclusive(source, target, content) {
+  try {
+    await link(source, target);
+  } catch (error) {
+    if (!HARD_LINK_UNSUPPORTED.has(errorCode(error) ?? "")) {
+      throw error;
+    }
+    await writeFile3(target, content, { encoding: "utf-8", flag: "wx" });
+  }
+}
+async function replacePidFile(pidFile, content) {
+  const staged = siblingPath(pidFile, "tmp");
+  try {
+    await writeFile3(staged, content, { encoding: "utf-8", flag: "wx" });
+    await rename2(staged, pidFile);
+  } catch (error) {
+    await unlinkQuietly(staged);
+    throw error;
+  }
+}
+async function removePidFileIf(pidFile, expected) {
+  await removePidFileWhen(pidFile, async (taken) => {
+    try {
+      return await readFile3(taken, "utf-8") === expected;
+    } catch {
+      return false;
+    }
+  });
+}
+async function removeDanglingLink(pidFile) {
+  if (!await isDanglingLink(pidFile)) {
+    return;
+  }
+  await removePidFileWhen(pidFile, isDanglingLink);
+}
+async function isDanglingLink(path) {
+  try {
+    await readlink(path);
   } catch {
-    await cleanupPidFile();
     return false;
   }
+  try {
+    await stat3(path);
+    return false;
+  } catch {
+    return true;
+  }
+}
+async function removePidFileWhen(pidFile, isExpected) {
+  const taken = siblingPath(pidFile, "taken");
+  try {
+    await rename2(pidFile, taken);
+  } catch {
+    return;
+  }
+  if (!await isExpected(taken)) {
+    await putBack(taken, pidFile);
+  }
+  await unlinkQuietly(taken);
+}
+async function putBack(taken, pidFile) {
+  try {
+    await link(taken, pidFile);
+    return;
+  } catch (error) {
+    if (!HARD_LINK_UNSUPPORTED.has(errorCode(error) ?? "")) {
+      return;
+    }
+  }
+  try {
+    await writeFile3(pidFile, await readFile3(taken, "utf-8"), { encoding: "utf-8", flag: "wx" });
+  } catch {}
 }
-async function cleanupPidFile() {
+async function unlinkQuietly(path) {
   try {
-    await unlink(PID_FILE);
+    await unlink(path);
   } catch {}
 }
 
@@ -20962,7 +21412,15 @@ async function serveCommand(options) {
     runForeground(cwd, port, buildDirOpts);
     return;
   }
-  await startServeBackground(cwd, port, buildDirOpts);
+  try {
+    await startServeBackground(cwd, port, buildDirOpts);
+  } catch (error) {
+    if (!(error instanceof ServePidFileError)) {
+      throw error;
+    }
+    console.error(describePidFileError(error));
+    process.exit(1);
+  }
   const running = await isServeRunning();
   if (running) {
     console.log(i18n.t("cli.web.start.started", { port }));
@@ -20971,6 +21429,13 @@ async function serveCommand(options) {
     process.exit(1);
   }
 }
+function describePidFileError(error) {
+  if (error.reason === "home-unresolved") {
+    return i18n.t("cli.web.start.homeUnresolved");
+  }
+  const cause = error.cause instanceof Error ? error.cause.message : String(error.cause);
+  return i18n.t("cli.web.start.pidNotWritable", { path: String(error.pidFile), error: cause });
+}
 async function serveStopCommand() {
   const stopped = await stopServe();
   if (stopped) {