PR #252: examples: workspace-lease-guard.sh — out-of-process repo lease for #60475 pattern 4

• Repository: yurukusa/cc-safe-setup
• Author: yurukusa
• State: closed | merged: True
• Link: https://github.com/yurukusa/cc-safe-setup/pull/252

Description (problem / solution / changelog)

• New PreToolUse / SessionStart / Stop hook implementing @kcarriedo's pattern 4 from #60475: a file-based per-repo lease with compare-and-delete release and heartbeat takeover for crashed siblings
• Catches the failure shape where a sub-agent or sibling Claude session destroys the other's uncommitted edits via unscoped worktree mutation primitives
• Distinct from concurrent-edit-lock.sh (per-file, 60s) and max-concurrent-agents.sh (subagent fan-out cap): this is repo-scoped, covers Bash, and survives auto-compact because the lease lives on the filesystem
• README + examples/README hook counts bumped (736 → 737, 9,228+ → 9,241+ tests) Lease file at ${CC_LEASE_DIR}/workspace-<repo_hash>.lease encodes <agent_id>|<acquired_ts>|<heartbeat_ts>.
• SessionStart: claim the lease, or BLOCK if held by a live sibling (heartbeat fresh within CC_LEASE_HEARTBEAT_TTL=180s)
• PreToolUse: refresh the heartbeat on every tool call, or BLOCK if a sibling took over
• Stop: compare-and-delete release (only the holder removes the lease file)
• Stale takeover: leases without a heartbeat in TTL are taken over with a NOTICE rather than a BLOCK, so crashed siblings do not deadlock the next session Disable with CC_LEASE_DISABLE=1.
• 13 cases pass: fresh acquire, idempotent re-acquire, sibling block (SessionStart), stale takeover after TTL, heartbeat refresh, sibling block (PreToolUse), implicit claim on missing lease, compare-and-delete release respects ownership, disable env var, no-workspace no-op, unknown event no-op, empty input
• bash -n passes on the hook
• Tests run in <10s with isolated CC_LEASE_DIR per run via mktemp @kcarriedo's pattern enumeration in #60475 names this gap explicitly: "Once 'this directory is being mutated by agent X' lives only in agent X's session, agent Y has no way to discover that and the orchestrator has no way to enforce it." Two existing hooks (concurrent-edit-lock.sh, max-concurrent-agents.sh) cover adjacent surfaces but neither protects against the full failure shape — git checkout, git reset --hard, or similar in one session clobbering another session's dirty state in the same tree. The lease is the operator-side mechanism that fires at the filesystem layer, independent of whatever in-process drift the model is in. Reply that prompted the implementation: https://github.com/anthropics/claude-code/issues/60475#issuecomment-4490113093
• #60475 — sibling subagent destructive worktree call clobbered active session (this PR's direct origin)
• #60506 — six-day drift inside maximal in-process enforcement (recognition-without-arrest constellation, 9th member)
• #60226 — recognition-without-arrest framework (out-of-process arrest principle)
• #57463 — subagent destructive-recovery family 🤖 Generated with Claude Code

Changed files

• README.md (modified, +1/-1)
• examples/README.md (modified, +1/-1)
• examples/workspace-lease-guard.sh (added, +193/-0)
• tests/workspace-lease-guard.test.sh (added, +144/-0)