auto-device-lock

/auto-device-lock

Claim a physical device before you touch it, hold it for as long as you need it, and give it back — so that five windows working on five apps can share three phones without corrupting each other's tests, and so the ESP32 that one project is flashing is not opened by another project mid-write.

The standing law: no device operation without a lease you have verified in this same command. Not "I claimed it earlier in this session" — earlier is not now. The gap between those two is where another session's flash lands in your board.

Everything here is built on one fact about how agent sessions run: every Bash call is a fresh bash -c that exits within milliseconds, while the session itself lives for hours. A lock held by the shell dies instantly; an environment variable exported in one call is gone by the next. So the lease is bound to the session's own long-lived process, and the shell bindings are re-established on every call that uses them.

The helper is devlock, shipped in this skill's directory. If it is missing — a user may have installed only SKILL.md — say so and fall back to Step 8 rather than inventing a lock format.

It is not on PATH by default. Resolve it once at the top of the session and reuse that path, or offer the user the one-time symlink:

DEVLOCK="$(ls -d ~/.claude/skills/auto-device-lock/devlock \
              ~/.agents/skills/auto-device-lock/devlock 2>/dev/null | head -1)"
ln -sfn "$DEVLOCK" ~/.local/bin/devlock     # optional, once, if ~/.local/bin is on PATH

The examples below say devlock; use "$DEVLOCK" if you did not make the link.

Subagents never claim and never release. This rule is load-bearing, so it comes before the mechanism. Every in-process subagent runs under the same claude process as its parent, so the lease's owner triple is identical for all of them — it proves the session is alive, and it cannot tell two subagents apart. The practical consequence: one subagent's release --all frees a device another subagent is mid-flash on, and the registry will agree that was legitimate. The foreground session claims and hands each subagent the serial to use; a subagent that believes it needs a device it was not given should say so and stop, not claim one.

A nested claude -p spawned from a Bash call is the opposite case — it is its own process, so the ancestry walk stops at the inner claude and it becomes a separate holder that contends with its own parent. Pass the device down and let it use -s.