Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(runio): a run-dir lock belongs to the process that took it — a hold carries the pid that took it, so re-entry, release and exit cleanup act only on this process's holds, and _remove_if_same, still the one way the entry is removed, removes nothing for another pid (a child forked by C code that skips Python's fork hooks included); where os.register_at_fork exists a fork child forgets its parent's holds and exit cleanups and closes, never unlocks, its copies of the run dir's kernel-lock descriptors, which are opened and recorded, and dropped and closed, under one module mutex the fork waits on (the flock wait stays outside it), so a holder killed inside that kernel lock leaves it to no child; run-contract section 7 states the ownership and the C-fork boundary
Soohong Kim88e1712f722d
diff --git a/docs/run-contract.md b/docs/run-contract.mdindex 7e4912a..1f97588 100644--- a/docs/run-contract.md+++ b/docs/run-contract.md@@ -569,7 +569,14 @@ boundary of the run-dir's atomicity and concurrency guarantees. What is **in forit — same device, inode and content, and `release_run_dir_lock` withdraws that lock's exitcleanup — while making, reclaiming and removing the entry queue on a kernel lock on the run diritself, so among sprite-gen processes on one host, on a file system that locks folders, neither a- released writer's exit nor a late reclaimer removes a lock another writer took meanwhile. The pipeline's+ released writer's exit nor a late reclaimer removes a lock another writer took meanwhile. Removing+ and holding belong to the process that made the entry: a hold is bound to the pid that took it, so a+ forked child never re-enters, releases or removes its parent's lock and is refused by it like any+ other writer, and where `os.register_at_fork` exists a child forgets its parent's holds and exit+ cleanups and closes its copies of the run dir's kernel-lock descriptors at the fork — a holder killed+ inside that kernel lock leaves it to no child. The boundary is a child forked by C code that skips+ Python's fork hooks: the pid check still keeps it from removing or re-entering the parent's lock, but it+ keeps any kernel-lock descriptor it inherited until it ends, and a writer waits for it. The pipeline's**one worker owns one character folder** rule (§2, SKILL.md)is what excludes concurrent writers on the same run dir in the first place. Same-processre-entry is intentionally allowed so one interpreter can run prepare → extract → compose indiff --git a/sprite_gen/spec/runio.py b/sprite_gen/spec/runio.pyindex 5157430..ff170d7 100644--- a/sprite_gen/spec/runio.py+++ b/sprite_gen/spec/runio.py@@ -14,7 +14,8 @@ example Claude Code and the Codex app driving the skill in parallel):never followed, read or removed. A process removes only the very entry it made,or judged stale to reclaim, and only while it still holds it; making, reclaimingand removing the entry queue on a kernel lock on the run dir itself (per host,- where the file system locks folders).+ where the file system locks folders). A lock belongs to the process that took+ it: a child it forks neither removes nor holds it.- `atomic_write_text()` / `atomic_save_image()` — temp file in the target dir+ `os.replace`, so a concurrent reader never observes a half-writtenatlas/manifest/frame. `atomic_write_set()` extends the same mechanism to a@@ -48,6 +49,7 @@ import secretsimport statimport sysimport tempfile+import threadingimport timefrom collections.abc import Callablefrom pathlib import Path, PurePath@@ -167,11 +169,49 @@ class _LockEntry(NamedTuple):content: bytes | None-# Lock paths this process holds -> the entry it made there and the exit handler that-# removes it. Re-entry from the same process (for example a long-lived MCP server-# invoking prepare -> extract -> compose against one run dir) must succeed; the-# single-writer rule is against other processes.-_HELD_LOCKS: dict[Path, tuple[_LockEntry, Callable[[], None]]] = {}+class _Held(NamedTuple):+ """쥔 락 하나 — 만든 항목, 그것을 잡은 프로세스(fork 자식은 이 기록을 물려받아도 그 프로세스가 아니다), 그 잡기의 종료 처리."""++ entry: _LockEntry+ pid: int+ at_exit: Callable[[], None]+++# Lock paths held -> the hold. Re-entry from the same process (for example a long-lived+# MCP server invoking prepare -> extract -> compose against one run dir) must succeed;+# the single-writer rule is against other processes, a forked child included.+_HELD_LOCKS: dict[Path, _Held] = {}++# 런 폴더 커널 락(`_entry_guard`)에 이 프로세스가 연 폴더 fd. 열기+기록, 기록 빼기+닫기는 `_FORK_MUTEX` 아래서 하고 fork 는+# 그동안 기다리므로(`_before_fork`), fork 순간 열린 fd 는 모두 여기 있다 — fork 자식이 닫을 사본. flock 기다림은 뮤텍스 밖이다.+_GUARD_FDS: set[int] = set()+_FORK_MUTEX = threading.RLock() # 같은 스레드의 시그널 처리기가 fork 해도 막히지 않게 (CPython logging 의 at-fork 락과 같은 꼴)+++def _before_fork() -> None:+ _FORK_MUTEX.acquire()+++def _after_fork_in_parent() -> None:+ _FORK_MUTEX.release()+++def _after_fork_in_child() -> None:+ """fork 자식은 부모의 런 폴더 락을 하나도 쥐지 않는다 — 물려받은 보유 기록과 그 종료 처리를 버리고, 커널 락 fd 사본을+ 닫는다. 닫기는 이 프로세스의 참조만 놓는다: 부모가 쥔 flock 은 그대로다(LOCK_UN 이면 부모의 것까지 풀린다)."""+ global _FORK_MUTEX+ _FORK_MUTEX = threading.RLock()+ for fd in _GUARD_FDS:+ with contextlib.suppress(OSError):+ os.close(fd)+ _GUARD_FDS.clear()+ for held in _HELD_LOCKS.values():+ atexit.unregister(held.at_exit)+ _HELD_LOCKS.clear()+++if hasattr(os, "register_at_fork"): # Unix — Windows 에는 fork 가 없다+ os.register_at_fork(before=_before_fork, after_in_parent=_after_fork_in_parent, after_in_child=_after_fork_in_child)def relative_posix(path: PurePath, start: PurePath) -> str:@@ -272,11 +312,15 @@ def _entry_guard(folder: Path):"""런 폴더 자체에 거는 커널 락 — 락 항목을 만들고 지우는 일(만들기·회수·해제·종료 처리)이 모두 이 아래서 줄을 서서,판정과 지우기 사이에 다른 sprite-gen 이 그 이름에 만들거나 지우지 못한다. 폴더에 아무것도 만들지 않고, 쥔 프로세스가죽으면 커널이 놓는다. 줄은 한 호스트 안의 프로세스들이 선다(주인이 살았는지도 이 호스트의 pid 로 본다).- macOS·리눅스는 폴더 fd 의 flock(`_lock_fd`). Windows 는 폴더의 장치·파일 번호로 이름 붙인 커널 뮤텍스+ macOS·리눅스는 폴더 fd 의 flock(`_lock_fd`) — 그 fd 는 `_GUARD_FDS` 에 있어 파이썬 fork 훅이 도는 fork 자식은 사본을+ 닫는다(쥔 프로세스가 그 안에서 죽어도 자식이 커널 락을 이어 쥐지 않는다. 훅을 거치지 않는 C fork 자식은 끝날 때까지+ 갖는다 — docs/run-contract.md §7). Windows 는 폴더의 장치·파일 번호로 이름 붙인 커널 뮤텍스(`Global\\` 이름이라 로그온 세션이 달라도 한 줄 — LockFileEx 는 폴더를 잠그지 못한다). Windows 길은 아직 그 기기에서재지 않았다."""if fcntl is not None:- fd = os.open(folder, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))+ with _FORK_MUTEX:+ fd = os.open(folder, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))+ _GUARD_FDS.add(fd)try:try:_lock_fd(fd, exclusive=True)@@ -288,7 +332,9 @@ def _entry_guard(folder: Path):finally:_unlock_fd(fd)finally:- os.close(fd)+ with _FORK_MUTEX:+ _GUARD_FDS.discard(fd)+ os.close(fd)elif _LOCK_IMPL == "LockFileEx": # pragma: no cover - Windows-only backendfound = os.stat(folder)mutex = _CreateMutexW(None, False, f"Global\\sprite-gen-run-dir-{found.st_dev:x}-{found.st_ino:x}")@@ -339,10 +385,13 @@ def _read_entry(lock_path: Path) -> tuple[_LockEntry | None, float]:return _LockEntry(got.st_dev, got.st_ino, b"".join(chunks)), got.st_mtime-def _remove_if_same(lock_path: Path, entry: _LockEntry) -> bool:- """락 이름에 있는 것이 `entry` — 이 프로세스가 만들었거나 회수하려고 판정한 바로 그 항목(일반 파일, 같은 장치·inode,- 같은 내용)일 때만 지운다. 락 항목을 지우는 길은 이것 하나다(해제·종료 처리·회수). 부르는 쪽이 `_entry_guard` 를 쥐고- 있어, 판정과 지우기 사이에 다른 sprite-gen 이 그 이름에 만들거나 지우지 못한다."""+def _remove_if_same(lock_path: Path, entry: _LockEntry, by: int) -> bool:+ """락 이름에 있는 것이 `entry` — 프로세스 `by` 가 만들었거나 회수하려고 판정한 바로 그 항목(일반 파일, 같은 장치·inode,+ 같은 내용)이고 `by` 가 지금 이 프로세스일 때만 지운다. 부모의 기록을 물려받은 fork 자식은(파이썬 fork 훅을 거치지 않는+ C fork 자식도) 같은 항목을 보아도 지우지 않는다. 락 항목을 지우는 길은 이것 하나다(해제·종료 처리·회수). 부르는 쪽이+ `_entry_guard` 를 쥐고 있어, 판정과 지우기 사이에 다른 sprite-gen 이 그 이름에 만들거나 지우지 못한다."""+ if by != os.getpid():+ return Falsetry:if _read_entry(lock_path)[0] != entry:return False@@ -352,17 +401,24 @@ def _remove_if_same(lock_path: Path, entry: _LockEntry) -> bool:return True-def _let_go(lock_path: Path, at_exit: Callable[[], None]) -> None:- """쥔 락을 놓는다 — `at_exit` 를 단 그 잡기가 아직 쥐고 있을 때만(명시 해제 뒤 남은 종료 처리, 다시 잡은 뒤의 옛 종료- 처리는 아무것도 하지 않는다). `_HELD_LOCKS` 에서 빼고, 이름에 있는 것이 만든 그 항목일 때만 지운다. 지우지 못해도(런- 폴더가 사라졌거나 다른 것이 들어섰다) 놓은 것이다."""+def _held_here(lock_path: Path) -> _Held | None:+ """이 프로세스가 쥔 `lock_path` 의 보유 — 기록이 다른 프로세스의 것이면(파이썬 fork 훅을 거치지 않은 C fork 자식이 부모의+ 기록을 물려받았다) 쥔 것이 아니다."""held = _HELD_LOCKS.get(lock_path)- if held is None or held[1] is not at_exit:+ return held if held is not None and held.pid == os.getpid() else None+++def _let_go(lock_path: Path, at_exit: Callable[[], None]) -> None:+ """쥔 락을 놓는다 — `at_exit` 를 단 그 잡기를 이 프로세스가 아직 쥐고 있을 때만(명시 해제 뒤 남은 종료 처리, 다시 잡은+ 뒤의 옛 종료 처리, fork 자식이 물려받은 부모의 종료 처리는 아무것도 하지 않는다). `_HELD_LOCKS` 에서 빼고, 이름에 있는+ 것이 만든 그 항목일 때만 지운다. 지우지 못해도(런 폴더가 사라졌거나 다른 것이 들어섰다) 놓은 것이다."""+ held = _held_here(lock_path)+ if held is None or held.at_exit is not at_exit:returnif _HELD_LOCKS.pop(lock_path, None) is not held: # 같은 프로세스의 다른 스레드가 먼저 놓았다returnwith contextlib.suppress(OSError), _entry_guard(lock_path.parent):- _remove_if_same(lock_path, held[0])+ _remove_if_same(lock_path, held.entry, held.pid)def acquire_run_dir_lock(run_dir: Path, owner: str) -> Path:@@ -386,7 +442,12 @@ def acquire_run_dir_lock(run_dir: Path, owner: str) -> Path:Re-entry from the same process is allowed: the MCP server / freeze binaryruns many pipeline steps in one interpreter against the same run dir, and a- writer must never block itself.+ writer must never block itself. The same process is the pid that took the+ lock: a child it forks is another writer, refused by the parent's live lock,+ and never re-enters, releases or removes it — where os.register_at_fork+ exists the child forgets its parent's holds and exit cleanups at the fork,+ and a child forked by C code that skips Python's fork hooks still has a pid+ of its own.Release runs via atexit (normal return, SystemExit, KeyboardInterrupt) whilethis process still holds the lock, and removes only the entry it made (same@@ -394,8 +455,9 @@ def acquire_run_dir_lock(run_dir: Path, owner: str) -> Path:reclaim above."""lock_path = Path(run_dir).resolve() / LOCK_FILENAME- if lock_path in _HELD_LOCKS:+ if _held_here(lock_path) is not None:return lock_path+ me = os.getpid()with _entry_guard(lock_path.parent):for _ in range(_LOCK_ROUNDS):try: # never follows a link at the name (open(2))@@ -429,13 +491,13 @@ def acquire_run_dir_lock(run_dir: Path, owner: str) -> Path:f" delete the lock file if no sprite-gen process is running")# dead pid, or unverifiable and old: reclaim the entry judged here, then retry the exclusive create- _remove_if_same(lock_path, found)+ _remove_if_same(lock_path, found, me)else:raise SystemExit(f"run dir lock {lock_path} kept changing while sprite-gen read it\n"f" something other than sprite-gen is replacing it; stop that before writing this run dir")- content = json.dumps({"owner": owner, "pid": os.getpid(), "started": time.time()}).encode("utf-8")+ content = json.dumps({"owner": owner, "pid": me, "started": time.time()}).encode("utf-8")made, written = None, 0try:made = os.fstat(fd)@@ -445,14 +507,14 @@ def acquire_run_dir_lock(run_dir: Path, owner: str) -> Path:os.close(fd)if made is not None: # 다 쓰지 못했다(디스크가 찼다) — 만들다 만 그 항목을 거둔다, 남으면 다음 writer 를 막는다with contextlib.suppress(OSError):- _remove_if_same(lock_path, _LockEntry(made.st_dev, made.st_ino, content[:written]))+ _remove_if_same(lock_path, _LockEntry(made.st_dev, made.st_ino, content[:written]), me)raiseos.close(fd)def at_exit() -> None:_let_go(lock_path, at_exit)- _HELD_LOCKS[lock_path] = (_LockEntry(made.st_dev, made.st_ino, content), at_exit)+ _HELD_LOCKS[lock_path] = _Held(_LockEntry(made.st_dev, made.st_ino, content), me, at_exit)atexit.register(at_exit)return lock_path@@ -466,13 +528,14 @@ def release_run_dir_lock(run_dir: Path) -> None:상호배제고, 원자성은 스테이징 통짜 스왑이 보장하므로 작업이 끝나면 놓는 게맞다. 놓으면서 그 잡기의 종료 처리를 거둔다 — 놓은 뒤 이름에 들어선 다음 writer 의락이나 링크를 이 프로세스가 끝날 때 지우지 않는다. 지우는 것은 이 프로세스가 만든- 바로 그 항목뿐이다(`_remove_if_same`). 쥐지 않은 락이면 아무것도 하지 않는다."""+ 바로 그 항목뿐이다(`_remove_if_same`). 쥐지 않은 락이면 — fork 자식에게는 부모의 락도 —+ 아무것도 하지 않는다."""lock_path = Path(run_dir).resolve() / LOCK_FILENAME- held = _HELD_LOCKS.get(lock_path)+ held = _held_here(lock_path)if held is None:return- atexit.unregister(held[1])- _let_go(lock_path, held[1])+ atexit.unregister(held.at_exit)+ _let_go(lock_path, held.at_exit)def _rwlock_path(run_dir: Path) -> Path: