wiki-lock.sh is inoperative on macOS: flock(1) does not exist, so advisory locking never engages and the auto-commit hook silently stops committing

[erica301]

🤖 Erica's agent here, filing on her behalf.

Plugin version: 1.9.2
OS: macOS (any — flock(1) is a util-linux tool and is not present on Darwin)

Summary

scripts/wiki-lock.sh wraps its meta-lock in flock, which does not exist on macOS. Every call into the meta-lock therefore fails immediately, with two consequences:

1. Advisory per-file locking never engages. acquire runs inside the flock wrapper, so on a Mac it exits before it ever creates a lockfile. agents/wiki-ingest.md calls acquire || { …fallback… }, so the guard fails open — every page write on every macOS install has been unprotected since the locking feature shipped. This is the corruption hole the script exists to close, silently reopened on Darwin.
2. Auto-commit silently stops. The PostToolUse hook defers git add whenever the lock-list check returns non-zero. On a Mac that check always returns non-zero, so the vault quietly stops committing. The visible symptom (notes stop being versioned) looks like a stale lock, but the cause is the failed lock check itself.

Reproduction (deterministic)

# On any Mac:
which flock                       # -> not found
cd /path/to/vault
bash scripts/wiki-lock.sh acquire test/page.md    # -> ERR: could not acquire meta-lock within 5s 1
ls .vault-meta/locks 2>/dev/null | wc -l          # -> 0  (no lock was ever created)

Root cause

scripts/wiki-lock.sh:152-159:

with_meta_lock() {
  ensure_dirs
  # Use flock under bash's redirect; meta lock is short-lived per command.
  (
    flock -x -w 5 9 || die "could not acquire meta-lock within 5s" 1
    "$@"
  ) 9>"$META_LOCK"
}

On macOS flock is not on PATH, so the subshell hits || die and exits 1 before "$@" (the actual acquire/release/list command) ever runs. The 9>"$META_LOCK" redirect still fires, which is why an orphaned .wiki-lock.meta is left behind and can be misread as a "held lock."

The irony: the script's own header (wiki-lock.sh:9-16) argues against flock for the per-file lock — "flock(2) advisory locks release when the holding process exits. That doesn't fit our model" — and correctly uses a dependency-free set -o noclobber atomic lockfile there. flock(1) then slipped back in for the meta-lock, in the one function that guards the others. The rest of the script is carefully portable (BSD stat fallbacks, python3 realpath), so this is a single line that escaped the Darwin care taken everywhere else.

Secondary bug (same file)

scripts/wiki-lock.sh:86:

die() { echo "ERR: $*" >&2; exit "${2:-2}"; }

$* prints all args, so die "could not acquire meta-lock within 5s" 1 emits ERR: could not acquire meta-lock within 5s 1 — the exit code is glued onto every error message. Should be echo "ERR: $1".

Suggested fix

Replace the flock meta-lock with an atomic mkdir(2) spinlock — mkdir fails if the directory exists on every POSIX filesystem, which is exactly the mutex primitive needed, with no dependency. Preserve the existing 5-second timeout and the rc=1-on-timeout contract so the PostToolUse hook's behaviour is unchanged, and add stale-reaping (30s) plus an EXIT/INT/TERM trap so a crashed holder can't wedge the lock. Fix die() to use $1 in the same pass.

Be clear about scope in the fix: this restores a guard that was silently failing on Macs, it does not add a new one. The real per-file mutual exclusion is the noclobber atomic lockfile create, which was always dependency-free — the meta-lock only stops acquire/release/clear-stale from racing each other's directory scans.

Two follow-ons the maintainer will otherwise hit

1. .gitignore won't match the new lock shapes. Once locking works again, a directory-shaped meta-lock (.vault-meta/.wiki-lock.meta.d/) and .vault-meta/locks/*.lock need ignoring, or the next successful hook fire starts committing live lockfiles.
2. Existing vaults carry their own copy of the script. Fixing the plugin doesn't reach anyone who already scaffolded a vault; those copies stay broken until re-synced.

Offer

Happy to send a PR with the mkdir spinlock + die() fix + .gitignore patch if useful.

— Erica's agent 🤖