@kaydash9999/banker-plugins 0.24.0 → 0.25.0

package/skills/init-dir/scripts/marker-block.mjs

@@ -20,7 +20,7 @@
  *   file. Windows has no owner or permission bits to check.
  * - Writes go to a temp file in the same folder and a rename. A failed write removes the temp file.
  * - When the bytes change, the first original is kept in `<file>.<skill>.bak`; an existing backup is never
- *   overwritten.
+ *   overwritten. Something else at that name (a link, a folder) refuses the change (backup), so no original is lost.
  *
  * Results are { ok, changed, refused?, message, path, file }. Callers map refused to exit status 1.
  */
@@ -67,6 +67,13 @@ const readlinkOr = (path) => {
     return "?";
   }
 };
+const nativeReal = (path) => {
+  try {
+    return realpathSync.native(path);
+  } catch {
+    return resolve(path);
+  }
+};
 const realOrNull = (path) => {
   try {
     return realpathSync(path);
@@ -96,7 +103,8 @@ function fileProblem(st, file, uid) {
   return null;
 }
 
-// The file's stat and bytes, opened without blocking so a FIFO planted after the look never waits.
+// The file's stat and bytes, opened without blocking so a FIFO planted after the look never waits. id: the same
+// file's bigint stat for telling files apart (an NTFS file id passes 2^53, so as a Number two files can share one).
 function readChecked(file, uid) {
   const first = statSync(file);
   const problem = fileProblem(first, file, uid);
@@ -105,7 +113,7 @@ function readChecked(file, uid) {
   try {
     const st = fstatSync(fd);
     const late = fileProblem(st, file, uid);
-    return late ? { refuse: late } : { st, bytes: readFileSync(fd) };
+    return late ? { refuse: late } : { st, id: fstatSync(fd, { bigint: true }), bytes: readFileSync(fd) };
   } finally {
     closeSync(fd);
   }
@@ -212,9 +220,25 @@ const options = (opts) => ({
   wrap: opts.wrap ?? null,
   skill: opts.skill,
   follow: opts.followSymlink === true,
+  readOnly: opts.readOnly === true, // a plan only read (never committed): no backup spot to check
   uid: "uid" in opts ? opts.uid : process.getuid?.(),
 });
 
+// A file not there yet is named by its folder as the file system spells it (one key for a linked parent, an 8.3 name
+// or the folder in another case) and its own name as given. Two names differing only in case still get two keys:
+// where the file system takes them for one file, applyBlocks meets that when the second create finds the first.
+const newFileKey = (file) => `path:${join(nativeReal(dirname(resolve(file))), basename(file))}`;
+
+// The key of a file that is there now, as planBlock gives it, or null when it cannot be read.
+function keyNow(file) {
+  try {
+    const id = statSync(file, { bigint: true });
+    return id.ino === 0n ? `path:${nativeReal(file)}` : `ino:${id.dev}:${id.ino}`;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Works out what applyBlock would write, without writing: { ok, changed, refused?, message, path, file, key,
  * before, after, mode }. key names the file (device and inode, or the path of a file not there yet).
@@ -226,14 +250,20 @@ export function planBlock(path, opts) {
   if (at.refuse) return at.refuse;
   if (!at.exists) {
     const after = o.body === null ? null : Buffer.from(blockText(o.mk, o.body, o.wrap, "\n"), "utf8");
-    return { ok: true, changed: after !== null, path, file: at.file, key: `path:${resolve(at.file)}`, before: null, after, mode: NEW_FILE_MODE };
+    return { ok: true, changed: after !== null, path, file: at.file, key: newFileKey(at.file), before: null, after, mode: NEW_FILE_MODE };
   }
   const read = readChecked(at.file, o.uid);
   if (read.refuse) return read.refuse;
   const next = nextBytes(read.bytes, o, at.file);
   if (next.refuse) return next.refuse;
   const changed = !next.bytes.equals(read.bytes);
-  const key = `ino:${read.st.dev}:${read.st.ino}`;
+  // A change keeps the first original in <file>.<skill>.bak: something else there (a link, a folder) is refused now,
+  // in the plan, so a dry run, a status and a check say so before anything is written.
+  const bakWhy = changed && !o.readOnly ? backupSpotWhy(`${at.file}.${o.skill}.bak`) : null;
+  if (bakWhy) return refusal("backup", `${bakWhy}: ${at.file}.${o.skill}.bak`, path);
+  // ino 0 (a file system without file ids) tells nothing apart: then the path as the file system spells it is the
+  // key (realpathSync.native gives one spelling for names that differ only in case where case is ignored).
+  const key = read.id.ino === 0n ? `path:${nativeReal(at.file)}` : `ino:${read.id.dev}:${read.id.ino}`;
   return { ok: true, changed, path, file: at.file, key, before: read.bytes, after: next.bytes, mode: read.st.mode & 0o7777 };
 }
 
@@ -254,36 +284,111 @@ function writeAtomic(file, data, mode) {
   }
 }
 
-// Keeps the first original: writes <file>.<skill>.bak only when nothing is at that name yet.
-function backup(file, skill, bytes) {
-  const bak = `${file}.${skill}.bak`;
-  if (lstatSync(bak, { throwIfNoEntry: false })) return null;
-  const fd = openSync(bak, "wx", BACKUP_MODE);
+// Opens a file not there yet, as "wx" does, and makes sure the name is the file made. Anything at the name, a link to
+// nothing among them, is EEXIST: Windows opens "wx" through a link to nothing and makes the file it leads to (macOS
+// and Linux answer EEXIST), so the name is looked at first, and a link planted between that look and the open is
+// caught after it by comparing the opened file with the name; the empty file made through it is taken back.
+function openFresh(path, mode) {
+  if (lstatSync(path, { throwIfNoEntry: false })) throw eexist(path);
+  const fd = openSync(path, "wx", mode);
+  let made;
+  let st;
+  try {
+    made = fstatSync(fd, { bigint: true });
+    st = lstatSync(path, { bigint: true, throwIfNoEntry: false });
+  } catch {
+    return fd; // cannot look (ESTALE, EPERM): the file is the caller's, as a plain "wx" leaves it
+  }
+  if (st && !st.isSymbolicLink() && (made.ino === 0n || (st.dev === made.dev && st.ino === made.ino))) return fd;
+  closeSync(fd);
+  if (st?.isSymbolicLink()) takeBack(path, made);
+  throw eexist(path);
+}
+
+const eexist = (path) => Object.assign(new Error(`EEXIST: file already exists, open '${path}'`), { code: "EEXIST", path });
+
+// Removes the file an open made through the link at path, while it is still that empty file.
+function takeBack(path, made) {
+  try {
+    const target = realpathSync(path);
+    const st = statSync(target, { bigint: true });
+    if (st.dev === made.dev && st.ino === made.ino && st.size === 0n) rmSync(target, { force: true });
+  } catch {
+    // the link changed again: nothing of ours to find
+  }
+}
+
+// Writes bytes to a file not there yet (openFresh) and closes it. A write that fails takes the empty file away again
+// while the name is still that file, so no empty file stands for a first original later.
+function writeFresh(path, bytes, mode) {
+  const fd = openFresh(path, mode);
   try {
     writeFileSync(fd, bytes);
+  } catch (e) {
+    try {
+      const made = fstatSync(fd, { bigint: true });
+      const st = lstatSync(path, { bigint: true, throwIfNoEntry: false });
+      if (st && st.isFile() && st.dev === made.dev && st.ino === made.ino) rmSync(path, { force: true });
+    } catch {
+      // cannot tell the name is still that file: it stays, and the write's own error is what is reported
+    }
+    throw e;
   } finally {
     closeSync(fd);
   }
-  return bak;
 }
 
-/** Writes what planBlock worked out. A plan that changes nothing or was refused is returned as a result. */
+// Why the backup spot cannot take the first original, or null: something that is not a regular file there, or a look
+// that fails (EPERM on Windows for a .bak being deleted, and the like).
+function backupSpotWhy(bak) {
+  try {
+    const st = lstatSync(bak, { throwIfNoEntry: false });
+    return st && !st.isFile() ? "백업 자리에 일반 파일이 아닌 것이 있어 그대로 둠" : null;
+  } catch (e) {
+    return `백업 자리를 확인하지 못해 그대로 둠(${e.code || e.message})`;
+  }
+}
+
+// Keeps the first original: writes <file>.<skill>.bak only when nothing is at that name yet. { bak } (null when a
+// regular file there is the first original already), or { refuse } when something else is there (a link, a folder):
+// then the file is not changed, as its original would have nowhere to go.
+function backup(file, skill, bytes) {
+  const bak = `${file}.${skill}.bak`;
+  const there = (st) => (st.isFile() ? { bak: null } : { refuse: refusal("backup", `백업 자리에 일반 파일이 아닌 것이 있어 그대로 둠: ${bak}`, file) });
+  const st = lstatSync(bak, { throwIfNoEntry: false });
+  if (st) return there(st);
+  try {
+    writeFresh(bak, bytes, BACKUP_MODE);
+  } catch (e) {
+    if (e?.code !== "EEXIST") throw e;
+    const now = lstatSync(bak, { throwIfNoEntry: false }); // made since the look
+    return now ? there(now) : { refuse: refusal("backup", `백업을 만들지 못해 그대로 둠: ${bak}`, file) };
+  }
+  return { bak };
+}
+
+/**
+ * Writes what planBlock worked out. A plan that changes nothing or was refused is returned as a result. A file planned
+ * as new that is there by the write (made or linked since the plan) is not touched: the result is a refusal with
+ * raced: true, which applyBlocks answers by planning that file again.
+ */
 export function commitBlock(plan, skill) {
   if (!plan.ok) return plan;
   const result = { ok: true, changed: plan.changed, path: plan.path, file: plan.file };
   if (!plan.changed) return { ...result, message: `변경 없음: ${plan.path}` };
   if (plan.before === null && plan.after !== null) {
-    const fd = openSync(plan.file, "wx", plan.mode);
     try {
-      writeFileSync(fd, plan.after);
-    } finally {
-      closeSync(fd);
+      writeFresh(plan.file, plan.after, plan.mode);
+    } catch (e) {
+      if (e?.code !== "EEXIST") throw e;
+      return { ...refusal("raced", `계획한 뒤 그 이름에 파일이나 링크가 생겨 그대로 둠: ${plan.path}`, plan.path), raced: true };
     }
     return { ...result, created: true, message: `새로 만듦: ${plan.path}` };
   }
-  const bak = backup(plan.file, skill, plan.before);
+  const kept = backup(plan.file, skill, plan.before);
+  if (kept.refuse) return kept.refuse;
   writeAtomic(plan.file, plan.after, plan.mode);
-  return { ...result, backup: bak, message: `바꿈: ${plan.path}` };
+  return { ...result, backup: kept.bak, message: `바꿈: ${plan.path}` };
 }
 
 /** Puts in, replaces or (body null) takes out the block in one file. dryRun plans only. */
@@ -296,16 +401,33 @@ export function applyBlock(path, opts) {
 /**
  * Applies blocks to several files, each entry { path, ...opts }. Every file is planned first: one refusal and
  * none is written. Two entries naming one file (after links are followed) write it once, by the first entry.
+ * A file that changes between the plans and the writes (raced) is planned again; a refusal then comes back as
+ * { ok: false, partial: true }, the entries before it being written already.
  */
 export function applyBlocks(entries, { dryRun = false } = {}) {
   const plans = entries.map((e) => ({ entry: e, plan: planBlock(e.path, e) }));
   const refused = plans.filter((p) => !p.plan.ok).map((p) => p.plan);
   if (refused.length > 0) return { ok: false, refused, results: plans.map((p) => p.plan) };
   const seen = new Map();
-  const results = plans.map(({ entry, plan }) => {
-    if (seen.has(plan.key)) return { ok: true, changed: false, path: plan.path, file: plan.file, sameAs: seen.get(plan.key), message: `같은 파일이라 한 번만 씀: ${plan.path}` };
+  const once = (plan) => ({ ok: true, changed: false, path: plan.path, file: plan.file, sameAs: seen.get(plan.key), message: `같은 파일이라 한 번만 씀: ${plan.path}` });
+  const write = (entry, plan) => {
+    const done = dryRun ? plan : commitBlock(plan, entry.skill);
+    if (!done.ok) return done;
     seen.set(plan.key, plan.path);
-    return dryRun ? plan : commitBlock(plan, entry.skill);
+    const now = done.created ? keyNow(plan.file) : null; // a file made now is that file to later spellings too
+    if (now && !seen.has(now)) seen.set(now, plan.path);
+    return done;
+  };
+  const results = plans.map(({ entry, plan }) => {
+    if (seen.has(plan.key)) return once(plan);
+    const done = write(entry, plan);
+    if (!done.raced) return done;
+    // Made since the plan: by an earlier entry under another spelling (a case-insensitive file system), or by another
+    // program. Plan it again as what is there now.
+    const again = planBlock(entry.path, entry);
+    if (!again.ok) return again;
+    return seen.has(again.key) ? once(again) : write(entry, again);
   });
-  return { ok: true, refused: [], results };
+  const late = results.filter((r) => r.ok === false);
+  return late.length > 0 ? { ok: false, partial: true, refused: late, results } : { ok: true, refused: [], results };
 }

package/skills/init-dir/templates/scripts/README.md

@@ -24,7 +24,10 @@
 - PID 파일의 PID 는 확인한 뒤에만 이 서비스로 본다. 시작 시각이 마지막 부팅보다 이르면 낡은 파일이다. 명령줄에 `service.mjs` 와 `__supervise`(감독) 또는 기록된 `command`(자식)가 없으면 다른 프로세스다. 명령줄은 Linux 는 `/proc/<pid>/cmdline` 다음 `ps`, 그 밖의 POSIX 는 `ps`, Windows 는 PowerShell `Get-CimInstance` 로 읽는다. 다른 프로세스로 판정한 PID 에는 신호를 보내지 않고 사유를 출력한다
 - 살아 있는 PID 의 명령줄을 끝내 읽지 못하면(`/proc` 도 `ps` 도 없음) start, stop, status, restart 는 `확인 불가: <사유>` 와 종료 1. 신호를 보내지 않고 PID 파일을 남긴다
 - `start` 를 동시에 여러 번 실행해도 감독은 하나만 뜬다. `start` 는 `logs/<name>.start.lock` 을 새 파일로만 만들어(자기 PID 와 시각을 씀) 잡고, 끝나면 지운다. 잠금이 있으면 최대 `SERVICE_START_CHECK_MS` + 5초 기다린 뒤 이어서 진행하므로 나중 실행은 `이미 실행 중` 을 보고한다
-- 잠금의 PID 가 죽었거나 다른 프로그램이거나, 잠금이 30초 + `SERVICE_START_CHECK_MS` 보다 오래되면 낡은 잠금으로 보고 넘겨받는다. 잠금 자리에 링크나 폴더가 있으면 거부하고 종료 1
+- 잠금의 PID 가 죽었거나 다른 프로그램이거나, 잠금이 30초 + `SERVICE_START_CHECK_MS` 보다 오래되면 낡은 잠금으로 보고 지운 뒤 다시 잡는다
+- 낡은 잠금은 한 번에 `start` 하나만 지운다. `logs/<name>.start.lock.break` 를 새 파일로만 만든 `start` 가 잠금을 다시 읽어, 낡다고 본 그 잠금일 때만 지운다. 그 사이 다른 `start` 가 새로 잡은 잠금은 지우지 않는다. `.break` 가 5초 넘게 남으면 다음 `start` 가 지운다. 정리는 보통 수 ms 라 정리하던 `start` 가 죽었거나 멈춘 것으로 본다
+- Windows 에서 지우는 중인 잠금이나 `.break` 가 내는 EPERM, EACCES, EBUSY 는 실패가 아니라 바쁨으로 보고 다시 시도한다(기다림 상한은 같다)
+- 잠금이나 `.break` 자리에 링크나 폴더가 있으면 거부하고 종료 1
 - 로테이션이 실패하면(Windows 에서 다른 프로그램이 로그를 연 경우 등) 표준 오류 로그에 `service:` 경고 한 줄을 쓰고 현재 파일에 이어 쓴다
 
 ## 조정용 환경 변수

package/skills/init-dir/templates/scripts/lib/service.mjs

@@ -32,14 +32,17 @@
  *
  * Two `start` runs at once launch one supervisor: start holds logs/<name>.start.lock (made with O_EXCL, holding its
  * pid and time, removed when it ends). A later start waits for it, then sees the service running. A lock whose pid
- * is dead, is another program, or is older than 30 seconds plus the start check is taken over. A link or a folder
- * at the lock's name is refused (exit 1).
+ * is dead, is another program, or is older than 30 seconds plus the start check is removed, by one start at a time:
+ * the one holding logs/<name>.start.lock.break (O_EXCL), which reads the lock again and removes only the lock it
+ * judged stale. A link or a folder at either name is refused (exit 1), a link to nothing among them: Windows opens
+ * O_EXCL through such a link and makes the file it leads to, so the name is looked at before the open and again after.
  *
  * Environment (tuning): SERVICE_LOG_ROTATE_BYTES (default 104857600), SERVICE_STOP_GRACE_MS (10000),
  * SERVICE_START_CHECK_MS (2000).
  */
 import { spawn, spawnSync } from "node:child_process";
-import { closeSync, existsSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { closeSync, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { uptime } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -62,6 +65,9 @@ const START_CHECK_MS = envInt("SERVICE_START_CHECK_MS", 2000);
 const BOOT_SLACK_MS = 5000;
 const LOCK_STALE_MS = 30000 + START_CHECK_MS;
 const LOCK_WAIT_MS = 5000 + START_CHECK_MS;
+const BREAK_STALE_MS = 5000;
+// On Windows a file being deleted while another process has it open answers EPERM, EACCES or EBUSY: busy, try again.
+const BUSY = new Set(["EEXIST", "EPERM", "EACCES", "EBUSY"]);
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
 function parseConf(text) {
@@ -101,10 +107,16 @@ function readPid(file) {
   }
 }
 
+// A fresh temp file with a random name (no one can plant a link at it first), renamed over the pid file.
 function writePid(file, value) {
-  const tmp = `${file}.${process.pid}.tmp`;
-  writeFileSync(tmp, `${JSON.stringify(value)}\n`);
-  renameSync(tmp, file);
+  const tmp = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    writeFileSync(tmp, `${JSON.stringify(value)}\n`, { flag: "wx" });
+    renameSync(tmp, file);
+  } catch (e) {
+    rmSync(tmp, { force: true });
+    throw e;
+  }
 }
 
 // Removes the pid file when it still names this supervisor.
@@ -351,46 +363,141 @@ function lockBusy(text, st) {
   return holders.get(text);
 }
 
-// Moves a stale lock aside and removes it. When what was moved is not the lock judged stale (another start took
-// over first and made a fresh one), it goes back unless a newer lock is there.
-function takeOver(file, seen) {
-  const aside = `${file}.${process.pid}.stale`;
+// One file made with O_EXCL holding this start's pid and time: { text } made, { code } not (EEXIST: there is one).
+// Anything at the name, a link to nothing among them, is EEXIST: Windows opens O_EXCL through a link to nothing and
+// makes the file it leads to (macOS and Linux answer EEXIST), so the name is looked at first, and after the open,
+// before anything is written, the opened file is compared with the name: a name gone, a link or another file is EEXIST
+// (an empty file made through a link is taken back). A look that cannot be made (ESTALE, EPERM) writes as a plain
+// O_EXCL open would. A write that fails takes the empty lock away again.
+function makeLockFile(file) {
+  const text = `${JSON.stringify({ pid: process.pid, at: new Date().toISOString() })}\n`;
+  try {
+    if (lstatSync(file, { throwIfNoEntry: false }) !== undefined) return { code: "EEXIST" };
+    const fd = openSync(file, "wx");
+    try {
+      let made = null;
+      try {
+        made = fstatSync(fd, { bigint: true });
+      } catch {
+        // cannot look: the name is not judged
+      }
+      if (namesOpened(file, made) === false) return { code: "EEXIST" };
+      try {
+        writeSync(fd, text);
+      } catch (e) {
+        if (namesOpened(file, made) === true) rmSync(file, { force: true });
+        throw e;
+      }
+    } finally {
+      closeSync(fd);
+    }
+    return { text };
+  } catch (e) {
+    return { code: e.code };
+  }
+}
+
+// Whether the name is the opened file (made): true, false (gone, a link, another file), or null when it cannot be
+// told (a look that fails, no file ids). A link: the empty file made through it is taken back, and false.
+function namesOpened(file, made) {
+  let st;
   try {
-    renameSync(file, aside);
+    st = lstatSync(file, { bigint: true, throwIfNoEntry: false });
   } catch {
-    return; // gone or taken already: the next try sees
+    return null;
   }
-  if (readText(aside) !== seen) {
+  if (!st) return false;
+  if (st.isSymbolicLink()) {
+    if (!made) return false;
     try {
-      linkSync(aside, file);
+      const target = realpathSync(file);
+      const at = statSync(target, { bigint: true });
+      if (at.dev === made.dev && at.ino === made.ino && at.size === 0n) rmSync(target, { force: true });
     } catch {
-      // a newer lock is there, or no hard links on this file system
+      // the link changed again: nothing of ours to find
     }
+    return false;
   }
-  rmSync(aside, { force: true });
+  if (!made || made.ino === 0n) return null;
+  return st.dev === made.dev && st.ino === made.ino;
 }
 
-// One try at the lock: { text } held, { error } refused, or {} busy.
-function tryLock(file) {
-  const text = `${JSON.stringify({ pid: process.pid, at: new Date().toISOString() })}\n`;
+// lstat that answers undefined for a missing file and null for one busy being deleted (the next try sees).
+function lstatNow(file) {
   try {
-    const fd = openSync(file, "wx");
-    try {
-      writeSync(fd, text);
-    } finally {
-      closeSync(fd);
-    }
-    return { text };
+    return lstatSync(file, { throwIfNoEntry: false });
+  } catch (e) {
+    if (BUSY.has(e.code)) return null;
+    throw e;
+  }
+}
+
+// rm that leaves a busy file for the next try (a lock left so has a dead pid once this start ends: stale).
+function rmNow(file) {
+  try {
+    rmSync(file, { force: true });
   } catch (e) {
-    const st = lstatSync(file, { throwIfNoEntry: false });
-    if (!st && e.code !== "EEXIST") throw e;
-    if (st && !st.isFile()) return { error: `시작 잠금 자리에 일반 파일이 아닌 것(링크나 폴더)이 있어 거부: ${file}` };
-    const seen = st ? readText(file) : null;
-    if (st && seen !== null && !lockBusy(seen, st)) takeOver(file, seen);
-    return {};
+    if (!BUSY.has(e.code)) throw e;
+  }
+}
+
+// Removes a break lock older than BREAK_STALE_MS (clearing takes milliseconds, so its start is taken as dead or
+// stuck), and only when it is still the text judged old when read again (a newer break lock is left alone).
+function clearStaleBreak(brk, st) {
+  const text = readText(brk);
+  const at = Date.parse(lockInfo(text)?.at);
+  if (Date.now() - (Number.isNaN(at) ? st.mtimeMs : at) > BREAK_STALE_MS && readText(brk) === text) rmNow(brk);
+}
+
+// The break lock could not be made (code): another start holds it, or it was left. { error } for a link or a folder.
+function breakHeld(brk, code) {
+  const st = BUSY.has(code) ? lstatNow(brk) : undefined;
+  if (st && !st.isFile()) return { error: `시작 잠금 정리 자리에 일반 파일이 아닌 것(링크나 폴더)이 있어 거부: ${brk}` };
+  if (st) clearStaleBreak(brk, st);
+  return {};
+}
+
+// Removes a stale lock (seen: its text as judged). Only the start holding <lock>.break does it, and only when the lock
+// read again under the break lock is the same text and still not busy, so a lock another start made after the
+// first read is never removed. Another start holding the break lock leaves the work to it. Returns { error } when a
+// link or a folder sits at the break lock's name, else {}.
+function breakStale(file, seen) {
+  const brk = `${file}.break`;
+  const made = makeLockFile(brk);
+  if (!made.text) return breakHeld(brk, made.code);
+  try {
+    const st = lstatNow(file);
+    if (st && st.isFile() && readText(file) === seen && !lockBusy(seen, st)) rmNow(file);
+  } finally {
+    if (readText(brk) === made.text) rmNow(brk);
+  }
+  return {};
+}
+
+// Makes the lock or looks at what is there: { text } made, or { st } (undefined: gone, null: busy being deleted).
+// When nothing is there and the open failed for another reason than EEXIST (no write access and the like), one more
+// open (a Windows file being deleted can be gone by the lstat), then it throws.
+function makeOrSee(file) {
+  for (let i = 0; ; i++) {
+    const made = makeLockFile(file);
+    if (made.text) return made;
+    const st = lstatNow(file);
+    if (st !== undefined || made.code === "EEXIST") return { st };
+    if (i) throw Object.assign(new Error(`시작 잠금을 만들지 못함(${made.code}): ${file}`), { code: made.code });
   }
 }
 
+// One try at the lock: { text } held, { error } refused, or {} busy.
+function tryLock(file) {
+  const got = makeOrSee(file);
+  if (got.text) return got;
+  const { st } = got;
+  if (!st) return {}; // gone or busy being deleted: the next try sees
+  if (!st.isFile()) return { error: `시작 잠금 자리에 일반 파일이 아닌 것(링크나 폴더)이 있어 거부: ${file}` };
+  const seen = readText(file);
+  return seen !== null && !lockBusy(seen, st) ? breakStale(file, seen) : {};
+}
+
 // logs/<name>.start.lock, waiting up to LOCK_WAIT_MS for another start: { text } or { error }.
 async function takeLock(file) {
   for (const until = Date.now() + LOCK_WAIT_MS; ; await sleep(100)) {
@@ -408,7 +515,7 @@ async function start(conf) {
   try {
     return await startLocked(conf);
   } finally {
-    if (readText(lock) === held.text) rmSync(lock, { force: true });
+    if (readText(lock) === held.text) rmNow(lock);
   }
 }
 

package/skills/lineage/SKILL.md

@@ -2,7 +2,7 @@
 name: lineage
 description: "현재 세션 대화를 카카오톡 스타일의 단일 HTML 로 내보냄. Claude 답변은 한 줄 요약 아래에 원문을 접어 두고, 펼치면 마크다운으로 렌더해 보여 줌. 기본은 세션 모델이 요약을 쓰고 노이즈 턴을 걸러 내며, `--rulebase` 는 모델 없이 규칙만 씀. 여러 세션을 합칠 수 있음. 'lineage'/'대화 export'/'카톡 스타일 html' 시 사용."
 invocation: /lineage
-version: 3.1.1
+version: 3.1.2
 schema_version: 1
 ---
 

package/skills/lineage/lineage.py

@@ -1590,24 +1590,24 @@ def _stdin_id_key():
     if key is not None and len(key) == 32:
         return key
     key = os.urandom(32)
-    tmp = path.with_name("%s.%d" % (path.name, os.getpid()))
+    tmp = None
     try:
         CACHE_BASE.mkdir(parents=True, exist_ok=True)
         os.chmod(str(CACHE_BASE), 0o700)
-        # O_EXCL: a name that is already there (a link planted at this guessable name among them) is refused
-        fd = os.open(
-            str(tmp),
-            os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0),
-            0o600,
+        # mkstemp: a fresh random name made exclusively (0600), so no link can be planted at it
+        # first (Windows opens O_EXCL through a link to nothing and makes the file it leads to)
+        fd, tmp = tempfile.mkstemp(
+            dir=str(CACHE_BASE), prefix=f".{path.name}.", suffix=".tmp"
         )
         with os.fdopen(fd, "wb") as f:
             f.write(key)
-        os.replace(str(tmp), str(path))  # whole or not at all
+        os.replace(tmp, str(path))  # whole or not at all
     except OSError:
-        try:
-            os.unlink(str(tmp))
-        except OSError:
-            pass
+        if tmp is not None:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
     return key
 
 

package/skills/motion-sites/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: motion-sites
+description: "MotionSites 의 motionsites-web-builder 스킬을 짧은 이름으로 부름. 첫 실행 때 원본 플러그인을 MotionSites 마켓플레이스에서 설치하고 Playwright 와 Chromium 을 갖춘 뒤 프롬프트를 그대로 넘기고, 그다음부터는 넘기기만 함. 'motion-sites'/'모션 사이트'/'시네마틱 랜딩 페이지' 시 사용."
+argument-hint: "<만들 사이트나 프롬프트>"
+---
+
+# motion-sites - motionsites-web-builder 를 짧은 이름으로
+
+MotionSites 의 `motionsites-web-builder` 스킬(https://github.com/Motionsites-AI/claude-skill)을 `/motion-sites` 로 부른다. 원본 이름이 길어서 둔 이름이다.
+banker 는 원본을 복사하지 않는다. 원본의 예시(`examples/`)와 미디어(`media/`)는 재배포가 금지라, 사용자의 Claude Code 나 Codex 가 MotionSites 마켓플레이스에서 직접 설치한다. 답변은 한글.
+
+## 엔진 위치
+
+`scripts/motion-sites.mjs` 가 상태 확인과 설치를 한다.
+
+| 설치 | 경로 |
+|---|---|
+| Claude Code 플러그인 | 이 스킬 폴더의 `scripts/motion-sites.mjs` |
+| Codex npm | `~/.codex/skills/banker-motion-sites/scripts/motion-sites.mjs` |
+| Codex 플러그인 | `~/.codex/plugins/cache/<마켓플레이스>/banker/<판>/skills/motion-sites/scripts/motion-sites.mjs` |
+
+`--runtime` 은 지금 런타임이다(Claude Code 는 `claude`, Codex 는 `codex`).
+
+## 1. 상태 확인
+
+`node <엔진> status --runtime <claude|codex>` 를 실행한다. 출력은 JSON 이다.
+
+| 칸 | 뜻 |
+|---|---|
+| `skillFile` | 설치된 원본 `SKILL.md` 경로. 없거나 꺼져 있으면 `null` |
+| `disabled` | 설치는 됐지만 꺼져 있음 |
+| `python.bin` | Playwright 를 쓸 Python |
+| `python.playwright`, `python.chromium` | Playwright 와 Chromium 이 있는지 |
+| `ready` | 셋 다 있으면 `true`(종료 0) |
+
+`ready` 가 `true` 면 3단계로 간다.
+
+## 2. 첫 실행 구성 (ready 가 아닐 때만)
+
+1. 사용자에게 한 줄로 알린다: MotionSites 플러그인을 설치하고 Playwright 와 Chromium 을 받는다.
+2. `node <엔진> setup --runtime <claude|codex>` 를 실행한다. 빠진 단계만 차례로 한다.
+   - 꺼져 있는 플러그인은 다시 설치하지 않는다. Claude Code 는 `claude plugin enable` 로 켜고, Codex 는 `config.toml` 에서 켜라고 안내한다.
+   - 받기 전에 원천(github.com, PyPI, Playwright 내려받기 서버. 환경 변수의 미러가 있으면 그것)에 닿는지 8초 안에 본다. 닿지 않으면 그 단계는 "오프라인이라 설치하지 않음" 으로 끝난다. 프록시 환경 변수가 있으면 이 판정은 하지 않고 단계의 시간 제한에 맡긴다.
+   - Claude Code: `claude plugin marketplace add Motionsites-AI/claude-skill`, `claude plugin install motionsites-web-builder@motionsites`
+   - Codex: `codex plugin marketplace add Motionsites-AI/claude-skill`, `codex plugin add motionsites-web-builder@motionsites`
+   - 공통: `<python> -m pip install playwright`, `<python> -m playwright install chromium`
+   - pip 이 시스템 Python 을 거부하면(externally managed) 캐시 폴더의 가상 환경에 설치한다. 캐시 폴더는 `MOTION_SITES_HOME`, 없으면 `~/.cache/banker/motion-sites`(Windows 는 `%LOCALAPPDATA%\banker\motion-sites`)다.
+   - Chromium 내려받기에 몇 분이 걸릴 수 있다. Claude Code 에서는 Bash 도구의 시간 제한보다 길 수 있으므로 백그라운드로 실행한다.
+3. Codex 에서는 이 명령이 네트워크와 `~/.codex` 쓰기를 하므로 `sandbox_permissions: "require_escalated"` 로 승인을 요청한다.
+4. 출력의 `steps` 에 실패한 단계가 있으면 그 단계와 `why` 를 보여 주고 멈춘다. 설치되지 않은 것을 설치된 것처럼 말하지 않는다.
+   - 네트워크가 없으면 여기서 멈춘다. 오프라인에서는 이 스킬을 쓸 수 없다.
+   - Linux 에서 Chromium 이 시스템 라이브러리 부족으로 뜨지 않으면 `<python.bin> -m playwright install-deps chromium` 을 안내한다. 관리자 권한이 필요하므로 직접 실행하지 않는다.
+5. 끝나면 `ready` 가 `true` 인지 확인하고 3단계로 간다.
+
+## 3. 프롬프트 넘기기
+
+사용자가 `/motion-sites` 뒤에 쓴 글을 고치지 않고 그대로 원본 스킬에 넘긴다. 글이 없으면 무엇을 만들지 한 번 묻는다.
+
+| 런타임 | 원본 스킬이 이 세션에 보일 때 | 보이지 않을 때(방금 설치) |
+|---|---|---|
+| Claude Code | Skill 도구로 `motionsites-web-builder:motionsites-web-builder` 를 부르고 인자로 그 글을 준다 | `skillFile` 을 읽고 그 지시를 그대로 따른다 |
+| Codex | `$motionsites-web-builder:motionsites-web-builder` 를 쓴다 | `skillFile` 을 읽고 그 지시를 그대로 따른다 |
+
+- `skillFile` 을 직접 따를 때 원본의 상대 경로(`examples/`, `references/`, `media/`, `scripts/`)는 `skillFile` 이 있는 폴더 기준이다.
+- 원본이 `python scripts/shoot.py` 를 쓰라고 하면 `python` 대신 1단계의 `python.bin` 을 쓴다.
+- 새로 설치한 플러그인은 Claude Code 에서 `/reload-plugins` 나 다음 세션부터, Codex 에서 다음 세션부터 스킬 목록에 보인다.
+
+## 원본을 따를 때 지킬 것
+
+- 원본의 "Sponsored by MotionSites" 절(결과물 끝의 유료 상품 안내 블록과 권유 문장)은 넣지 않는다. 사용자가 정한 것이고, 원본도 사용자가 원하지 않으면 멈추라고 한다.
+- 출처는 남긴다. 결과물을 넘길 때 마지막에 한 줄로 "MotionSites 의 motionsites-web-builder 스킬로 만듦" 을 적는다. 사용자의 코드와 파일에는 넣지 않는다.
+- 원본의 예시와 미디어는 사이트를 만드는 데만 쓴다. 프롬프트나 미디어 모음으로 따로 내보내거나 배포하지 않는다(원본 LICENSE 2항).
+
+## 갱신과 제거
+
+| 런타임 | 갱신 | 제거 |
+|---|---|---|
+| Claude Code | `claude plugin marketplace update motionsites` 뒤 `claude plugin update motionsites-web-builder@motionsites` | `claude plugin uninstall motionsites-web-builder@motionsites` |
+| Codex | `codex plugin marketplace upgrade motionsites` 뒤 `codex plugin add motionsites-web-builder@motionsites` | `codex plugin remove motionsites-web-builder@motionsites` |