simbo1905 · August 22, 2026 23:43
diff --git a/README.md b/README.md
diff --git a/lock_folder_util.py b/lock_folder_util.py
 #!/usr/bin/env python3
 """Serialise a shared resource across parallel agents with an mkdir lock.

 One resource, many agents: every use of the resource must hold the lock.
 The lock is an empty directory created atomically with os.mkdir, which
 fails if it already exists. Acquisition order is nondeterministic but
 mutual exclusion is guaranteed. The lock must never be given children;
 release is always rmdir.

 Usage:
    lock_folder_util.py acquire --slug worker-1 [--poll 15] [--stale 600] [--timeout 1800]
    lock_folder_util.py release --slug worker-1
    lock_folder_util.py run --slug worker-1 [--poll 15] [--stale 600] -- <command...>

 acquire: take the lock or poll until free; break locks older than --stale
 seconds (a crashed holder); give up after --timeout seconds. Every
 transition is logged as one line (UTC timestamp, slug, event) to
 <lockdir>.log next to the lock, so contention is auditable after the fact.

 run: acquire, exec the command, always release, exit with its status. This
 is the form agents should use: a crash between acquire and release leaves a
 stale lock that the next agent breaks after --stale seconds.

 Lock directory: defaults to .tmp under the current directory and is
 overridden by the env var LOCK_FOLDER_DIR (absolute, or relative to the
 current directory). The script fails fast at startup unless the lock
 directory exists, is a directory, and is writable. The env override exists
 for testing and for co-located projects that want an isolated lock;
 agents doing real work should leave the default in place so every user
 contends on the one lock.

 Sizing guidance from the 2026-08-22 batch runs: typical agent critical
 sections run 3 to 5 minutes, so the default stale break is 600 seconds
 (generous but bounded); poll every 15 seconds with one initial 60 second
 sleep so a burst of simultaneous agents does not thrash the check. Keep
 the critical section as short a burst as possible: do all reading,
 planning, and file patching outside the lock and hold it only for the
 resource commands themselves.
 """

 import argparse
 import os
 import subprocess
 import sys
 import time
 from datetime import datetime, timezone
 from pathlib import Path

 LOCK_DIR = Path(os.environ.get("LOCK_FOLDER_DIR", ".tmp"))
 LOCK = LOCK_DIR / "lock.lock"
 LOG = LOCK_DIR / "lock.log"

 if not (LOCK_DIR.is_dir() and os.access(LOCK_DIR, os.W_OK)):
    sys.exit(
        f"lock_folder_util: lock dir {LOCK_DIR} is not a writable directory; "
        "set LOCK_FOLDER_DIR or create it first"
    )


 def _log(slug: str, msg: str) -> None:
    ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
    with LOG.open("a", encoding="utf-8") as f:
        f.write(f"{ts} {slug} {msg}\n")


 def _lock_age() -> float:
    return time.time() - LOCK.stat().st_mtime


 def acquire(slug: str, poll: float, stale: float, timeout: float) -> None:
    deadline = time.monotonic() + timeout
    while True:
        try:
            os.mkdir(LOCK)
            _log(slug, "acquired")
            return
        except FileExistsError:
            pass
        try:
            age = _lock_age()
            if age > stale:
                try:
                    os.rmdir(LOCK)
                    _log(slug, f"broke stale lock (age {age:.0f}s)")
                    continue
                except OSError:
                    pass
        except FileNotFoundError:
            pass
        if time.monotonic() > deadline:
            _log(slug, "gave up")
            sys.exit(f"lock_folder_util: timed out after {timeout}s waiting for {LOCK}")
        time.sleep(poll)


 def release(slug: str) -> None:
    try:
        os.rmdir(LOCK)
        _log(slug, "released")
    except FileNotFoundError:
        _log(slug, "release: lock already gone")


 def main() -> None:
    p = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    sub = p.add_subparsers(dest="cmd", required=True)

    a = sub.add_parser("acquire")
    a.add_argument("--slug", required=True)
    a.add_argument("--poll", type=float, default=15.0)
    a.add_argument("--stale", type=float, default=600.0)
    a.add_argument("--timeout", type=float, default=1800.0)

    r = sub.add_parser("release")
    r.add_argument("--slug", required=True)

    run = sub.add_parser("run")
    run.add_argument("--slug", required=True)
    run.add_argument("--poll", type=float, default=15.0)
    run.add_argument("--stale", type=float, default=600.0)
    run.add_argument("--timeout", type=float, default=1800.0)
    run.add_argument("command", nargs=argparse.REMAINDER)

    args = p.parse_args()
    if args.cmd == "release":
        release(args.slug)
        return
    acquire(args.slug, args.poll, args.stale, args.timeout)
    if args.cmd == "acquire":
        return
    command = list(args.command)
    if command and command[0] == "--":
        command = command[1:]
    if not command:
        release(args.slug)
        sys.exit("lock_folder_util: run: no command given")
    try:
        rc = subprocess.call(command)
    finally:
        release(args.slug)
    sys.exit(rc)


 if __name__ == "__main__":
    main()
	#!/usr/bin/env python3
	"""Serialise a shared resource across parallel agents with an mkdir lock.

	One resource, many agents: every use of the resource must hold the lock.
	The lock is an empty directory created atomically with os.mkdir, which
	fails if it already exists. Acquisition order is nondeterministic but
	mutual exclusion is guaranteed. The lock must never be given children;
	release is always rmdir.

	Usage:
	lock_folder_util.py acquire --slug worker-1 [--poll 15] [--stale 600] [--timeout 1800]
	lock_folder_util.py release --slug worker-1
	lock_folder_util.py run --slug worker-1 [--poll 15] [--stale 600] -- <command...>

	acquire: take the lock or poll until free; break locks older than --stale
	seconds (a crashed holder); give up after --timeout seconds. Every
	transition is logged as one line (UTC timestamp, slug, event) to
	<lockdir>.log next to the lock, so contention is auditable after the fact.

	run: acquire, exec the command, always release, exit with its status. This
	is the form agents should use: a crash between acquire and release leaves a
	stale lock that the next agent breaks after --stale seconds.

	Lock directory: defaults to .tmp under the current directory and is
	overridden by the env var LOCK_FOLDER_DIR (absolute, or relative to the
	current directory). The script fails fast at startup unless the lock
	directory exists, is a directory, and is writable. The env override exists
	for testing and for co-located projects that want an isolated lock;
	agents doing real work should leave the default in place so every user
	contends on the one lock.

	Sizing guidance from the 2026-08-22 batch runs: typical agent critical
	sections run 3 to 5 minutes, so the default stale break is 600 seconds
	(generous but bounded); poll every 15 seconds with one initial 60 second
	sleep so a burst of simultaneous agents does not thrash the check. Keep
	the critical section as short a burst as possible: do all reading,
	planning, and file patching outside the lock and hold it only for the
	resource commands themselves.
	"""

	import argparse
	import os
	import subprocess
	import sys
	import time
	from datetime import datetime, timezone
	from pathlib import Path

	LOCK_DIR = Path(os.environ.get("LOCK_FOLDER_DIR", ".tmp"))
	LOCK = LOCK_DIR / "lock.lock"
	LOG = LOCK_DIR / "lock.log"

	if not (LOCK_DIR.is_dir() and os.access(LOCK_DIR, os.W_OK)):
	sys.exit(
	f"lock_folder_util: lock dir {LOCK_DIR} is not a writable directory; "
	"set LOCK_FOLDER_DIR or create it first"
	)


	def _log(slug: str, msg: str) -> None:
	ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
	with LOG.open("a", encoding="utf-8") as f:
	f.write(f"{ts} {slug} {msg}\n")


	def _lock_age() -> float:
	return time.time() - LOCK.stat().st_mtime


	def acquire(slug: str, poll: float, stale: float, timeout: float) -> None:
	deadline = time.monotonic() + timeout
	while True:
	try:
	os.mkdir(LOCK)
	_log(slug, "acquired")
	return
	except FileExistsError:
	pass
	try:
	age = _lock_age()
	if age > stale:
	try:
	os.rmdir(LOCK)
	_log(slug, f"broke stale lock (age {age:.0f}s)")
	continue
	except OSError:
	pass
	except FileNotFoundError:
	pass
	if time.monotonic() > deadline:
	_log(slug, "gave up")
	sys.exit(f"lock_folder_util: timed out after {timeout}s waiting for {LOCK}")
	time.sleep(poll)


	def release(slug: str) -> None:
	try:
	os.rmdir(LOCK)
	_log(slug, "released")
	except FileNotFoundError:
	_log(slug, "release: lock already gone")


	def main() -> None:
	p = argparse.ArgumentParser(
	description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
	)
	sub = p.add_subparsers(dest="cmd", required=True)

	a = sub.add_parser("acquire")
	a.add_argument("--slug", required=True)
	a.add_argument("--poll", type=float, default=15.0)
	a.add_argument("--stale", type=float, default=600.0)
	a.add_argument("--timeout", type=float, default=1800.0)

	r = sub.add_parser("release")
	r.add_argument("--slug", required=True)

	run = sub.add_parser("run")
	run.add_argument("--slug", required=True)
	run.add_argument("--poll", type=float, default=15.0)
	run.add_argument("--stale", type=float, default=600.0)
	run.add_argument("--timeout", type=float, default=1800.0)
	run.add_argument("command", nargs=argparse.REMAINDER)

	args = p.parse_args()
	if args.cmd == "release":
	release(args.slug)
	return
	acquire(args.slug, args.poll, args.stale, args.timeout)
	if args.cmd == "acquire":
	return
	command = list(args.command)
	if command and command[0] == "--":
	command = command[1:]
	if not command:
	release(args.slug)
	sys.exit("lock_folder_util: run: no command given")
	try:
	rc = subprocess.call(command)
	finally:
	release(args.slug)
	sys.exit(rc)


	if __name__ == "__main__":
	main()
No results found