file-lock

name	file-lock
description	Acquire and release file-level locks to prevent concurrent modifications during multi-agent or human+agent workflows

File Lock

Manage per-file advisory locks so that multiple agents (or an agent and a human operator) do not clobber the same file during complex refactors or parallel work sessions.

When to Use

Invoke before modifying any source file when concurrent access is possible. This includes multi-agent orchestration, long-running refactors, and any session where a human may be editing files in the same workspace.

Agents MUST follow the concurrency protocol defined in .github/instructions/concurrency.instructions.md.

Inputs

• filepath: (Required) Path to the target file, relative to the workspace root.
• action: (Required) One of acquire or release.

Output

• On acquire success: lock file created, exit code 0.
• On acquire failure: lock already held by another process, exit code 1.
• On release success: lock file removed, exit code 0.
• On release failure: lock file not found (already released), exit code 0 with warning.

Scripts

Both PowerShell and Bash equivalents are provided for cross-platform compatibility. Use whichever matches the runtime environment.

acquire_lock (.ps1 / .sh)

Acquires a file lock by creating a .{filename}.lock file in the same directory as the target file. Fails if the lock already exists.

PowerShell: scripts/acquire_lock.ps1 <filepath>
Bash:       scripts/acquire_lock.sh <filepath>

The lock file contains:

• Agent or process identifier ($env:AGENT_NAME / $AGENT_NAME or "unknown")
• Timestamp (ISO 8601)
• PID of the calling process

release_lock (.ps1 / .sh)

Releases a file lock by deleting the .{filename}.lock file.

PowerShell: scripts/release_lock.ps1 <filepath>
Bash:       scripts/release_lock.sh <filepath>

Workflow

1. Agent identifies file to modify
2. Agent runs: scripts/acquire_lock.{ps1|sh} <filepath>
   ├─ Exit 0 → lock acquired, proceed to edit
   └─ Exit 1 → lock held, wait or prompt operator
3. Agent modifies the file
4. Agent verifies the modification (compile, test, etc.)
5. Agent runs: scripts/release_lock.{ps1|sh} <filepath>

Lock Hygiene

• Locks are advisory, not enforced at the filesystem level.
• Lock files MUST NOT be committed to version control.
• Lock files older than 1 hour are likely stale: warn the operator.
• Only the operator may force-break a lock they did not create.