@jenga-ai/agent 1.0.1 → 1.1.1

package/scripts/install-worktree-commit-guard.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# scripts/install-worktree-commit-guard.sh — install a branch-guard pre-commit
+# hook into a given git worktree.
+#
+# Usage:
+#   scripts/install-worktree-commit-guard.sh <worktree-path> <branch-name>
+#
+# Writes a `pre-commit` hook that rejects any commit attempted while HEAD is
+# on a branch other than <branch-name>. This exists because a tester once
+# committed its verification of a task to `main` instead of the branch it was
+# actually verifying, from inside the worktree created for that task —
+# nothing mechanically prevented it (see E37's Purpose / E37_S02). Written
+# rules alone have a documented track record of drifting in this project
+# (E17 rollup note: two of its own stories were marked complete without the
+# underlying change landing), so this is a real guard, not just a documented
+# rule.
+#
+# IMPORTANT — why this does NOT just write to `git rev-parse --git-path
+# hooks`: that path resolves to the *shared* `hooks` directory common to the
+# main repository and every one of its linked worktrees (verified against
+# git 2.39: `git -C <any-worktree> rev-parse --git-path hooks` returns the
+# same common path for every worktree of the same repo, including the main
+# one). A naive install there would mean each new worktree's guard silently
+# clobbers every other worktree's guard (only the most-recently-created
+# worktree's branch would ever be accepted), and every *other* worktree would
+# then have its commits blocked outright, since the current branch would
+# never match the last-installed expected branch. That is worse than doing
+# nothing: it defeats the isolation this task exists to provide.
+#
+# The actual fix is git's per-worktree config file
+# (`$GIT_DIR/worktrees/<name>/config.worktree`, gated behind the
+# `extensions.worktreeConfig` repo extension) combined with the `core.hooksPath`
+# setting, which git DOES resolve per-worktree when scoped that way. This
+# script:
+#   1. enables `extensions.worktreeConfig` on the repo if not already set
+#      (idempotent, additive, does not disturb any existing config value —
+#      it only enables the *possibility* of per-worktree config overrides)
+#   2. resolves this worktree's own private git-dir via
+#      `git -C <worktree-path> rev-parse --absolute-git-dir` (this IS
+#      genuinely private per worktree — `.git/worktrees/<name>` for a linked
+#      worktree, verified distinct per worktree in the same test)
+#   3. points `core.hooksPath`, set with `git config --worktree` (so it lands
+#      in that worktree's own config.worktree file, not the shared config),
+#      at a private `hooks-guard` directory under that private git-dir
+#   4. writes the branch-guard `pre-commit` hook there
+#
+# This was manually verified end-to-end against a scratch repo with two
+# worktrees: installing the guard for worktree A blocked wrong-branch commits
+# in A and had zero effect on worktree B or the main repo, both of which kept
+# using the shared default hooks directory untouched.
+#
+# This script is intended to be called automatically at the end of the
+# `WorktreeCreate` hook in the canonical root `settings.json`, immediately
+# after `git worktree add "$DIR" -b "$NAME"` — see that file for the wiring.
+# It can also be run manually against any existing worktree, and is safe to
+# re-run against the same worktree (idempotent — simply overwrites the hook).
+#
+# Exit codes:
+#   0   hook installed successfully
+#   1   invalid usage (wrong argument count)
+#   2   <worktree-path> is not a valid git working tree
+
+set -u
+
+usage() {
+  echo "Usage: $0 <worktree-path> <branch-name>" >&2
+  exit 1
+}
+
+[ "$#" -eq 2 ] || usage
+WORKTREE_PATH="$1"
+BRANCH_NAME="$2"
+
+[ -n "$WORKTREE_PATH" ] || usage
+[ -n "$BRANCH_NAME" ] || usage
+
+if ! git -C "$WORKTREE_PATH" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "install-worktree-commit-guard: '$WORKTREE_PATH' is not a valid git working tree" >&2
+  exit 2
+fi
+
+# Enable per-worktree config overrides on the repo, if not already enabled.
+# This is a one-time, repo-wide, additive flag — it does not move or change
+# any existing config value, it only makes `git config --worktree` (used
+# below) actually take effect instead of silently writing to a file git
+# never reads.
+if [ "$(git -C "$WORKTREE_PATH" config --get extensions.worktreeConfig 2>/dev/null)" != "true" ]; then
+  git -C "$WORKTREE_PATH" config extensions.worktreeConfig true
+fi
+
+# This worktree's own private git-dir. For a linked worktree this resolves to
+# `.git/worktrees/<name>` (private to this worktree); for the main working
+# tree it resolves to the common `.git` dir itself. Either way it is safe to
+# scope a private hooks directory under it.
+PRIVATE_GIT_DIR="$(git -C "$WORKTREE_PATH" rev-parse --absolute-git-dir)"
+
+# A distinctly-named directory (not the default `hooks`) so this never
+# collides with, or gets confused for, whatever the shared default hooks
+# directory may already contain.
+HOOKS_DIR="$PRIVATE_GIT_DIR/hooks-guard"
+mkdir -p "$HOOKS_DIR"
+
+# Scope the override to THIS worktree only, via its private config.worktree
+# file — not the shared/common config, which would affect every worktree.
+git -C "$WORKTREE_PATH" config --worktree core.hooksPath "$HOOKS_DIR"
+
+HOOK_FILE="$HOOKS_DIR/pre-commit"
+
+# The expected branch name is baked into the generated hook as a literal
+# comparison value (it is fixed at install time — the branch this worktree
+# was created for). The *actual* branch is always re-checked live, at commit
+# time, via `git rev-parse --abbrev-ref HEAD`.
+cat > "$HOOK_FILE" <<EOF
+#!/usr/bin/env bash
+# Installed by scripts/install-worktree-commit-guard.sh — do not edit by hand.
+# Rejects any commit made while this worktree is not checked out on its
+# assigned branch: '$BRANCH_NAME'.
+set -u
+
+expected_branch="$BRANCH_NAME"
+current_branch="\$(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
+
+if [ "\$current_branch" != "\$expected_branch" ]; then
+  echo "pre-commit: commit blocked — this worktree is assigned to branch '\$expected_branch' but HEAD is currently on '\$current_branch'." >&2
+  echo "pre-commit: verification/implementation commits for this worktree must land on '\$expected_branch', never on any other branch (including main)." >&2
+  exit 1
+fi
+
+exit 0
+EOF
+
+chmod +x "$HOOK_FILE"
+
+echo "install-worktree-commit-guard: installed branch guard for '$BRANCH_NAME' at $HOOK_FILE (core.hooksPath scoped to this worktree only)"

package/scripts/jenga-permission-level-switch.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# scripts/jenga-permission-level-switch.sh — switch the current session's
+# 5-tier permission level by copying the matching template into
+# .claude/settings.json and .agents/settings.json, and recording the level
+# in .jenga-permission-level.json at the repo root.
+#
+# Usage: bash scripts/jenga-permission-level-switch.sh <n>
+#   <n> must be an integer 1-5.
+#
+# Behavior:
+#   - Templates live at templates/permission-levels/level-<n>-<name>.json
+#     and are COMPLETE settings.json documents (defaultMode, env,
+#     permissions, hooks). The copy is a whole-file overwrite of the
+#     destination, not a merge — this intentionally drops any extra
+#     top-level blocks (e.g. autoMode) present in the destination but
+#     absent from the template. autoMode is never used at any permission
+#     level (see PROJECT_SUMMARY.md, epic E33).
+#   - Both destination writes use a temp-file-then-atomic-rename pattern.
+#   - .jenga-permission-level.json is only written after BOTH settings.json
+#     copies succeed. If the .claude/ copy succeeds but the .agents/ copy
+#     fails, the script fails loud (no rollback of the .claude/ copy, no
+#     write to .jenga-permission-level.json) and instructs the user to
+#     re-run — re-running with the same <n> is idempotent and self-heals
+#     the inconsistency, since every copy is an unconditional overwrite.
+#   - Invalid input (missing/extra args, non-integer, out of range 1-5)
+#     exits non-zero and makes zero file changes.
+#
+# Exit codes:
+#   0  Success — all three files updated consistently.
+#   1  Invalid usage/argument — no files changed.
+#   2  Mapped template file missing — no files changed.
+#   3  Failed to copy template to .claude/settings.json — no files changed.
+#   4  Failed to copy template to .agents/settings.json — .claude/settings.json
+#      WAS updated (inconsistent state); re-run the script to repair.
+#   5  Failed to write .jenga-permission-level.json — both settings.json
+#      files WERE updated (inconsistent state); re-run the script to repair.
+
+set -euo pipefail
+
+usage() {
+  echo "Usage: $(basename "$0") <n>   (n must be an integer 1-5)" >&2
+}
+
+if [[ $# -ne 1 ]]; then
+  echo "Error: expected exactly one argument, got $#." >&2
+  usage
+  exit 1
+fi
+
+LEVEL="$1"
+
+if ! [[ "$LEVEL" =~ ^[1-5]$ ]]; then
+  echo "Error: permission level must be an integer between 1 and 5, got '$LEVEL'." >&2
+  usage
+  exit 1
+fi
+
+case "$LEVEL" in
+  1) NAME="locked" ;;
+  2) NAME="guarded" ;;
+  3) NAME="standard" ;;
+  4) NAME="elevated" ;;
+  5) NAME="unrestricted" ;;
+esac
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+TEMPLATE="$REPO_ROOT/templates/permission-levels/level-${LEVEL}-${NAME}.json"
+CLAUDE_SETTINGS="$REPO_ROOT/.claude/settings.json"
+AGENTS_SETTINGS="$REPO_ROOT/.agents/settings.json"
+LEVEL_FILE="$REPO_ROOT/.jenga-permission-level.json"
+
+if [[ ! -f "$TEMPLATE" ]]; then
+  echo "Error: template file not found for level $LEVEL: $TEMPLATE" >&2
+  exit 2
+fi
+
+# Whole-file overwrite of destination via temp-file + atomic rename.
+copy_template() {
+  local dest="$1"
+  local tmp="${dest}.tmp"
+  mkdir -p "$(dirname "$dest")"
+  cp "$TEMPLATE" "$tmp" && mv "$tmp" "$dest"
+}
+
+if ! copy_template "$CLAUDE_SETTINGS"; then
+  echo "Error: failed to copy template to $CLAUDE_SETTINGS. No files changed." >&2
+  rm -f "${CLAUDE_SETTINGS}.tmp"
+  exit 3
+fi
+
+if ! copy_template "$AGENTS_SETTINGS"; then
+  echo "Error: failed to copy template to $AGENTS_SETTINGS." >&2
+  echo "State is now INCONSISTENT: $CLAUDE_SETTINGS was updated to level $LEVEL but $AGENTS_SETTINGS was not." >&2
+  echo ".jenga-permission-level.json was NOT updated. Re-run this script to repair (it is idempotent)." >&2
+  rm -f "${AGENTS_SETTINGS}.tmp"
+  exit 4
+fi
+
+# Only write the metadata file after both settings.json copies succeeded.
+LEVEL_TMP="${LEVEL_FILE}.tmp"
+if ! jq -n --argjson n "$LEVEL" '{"session_level": $n}' > "$LEVEL_TMP" || ! mv "$LEVEL_TMP" "$LEVEL_FILE"; then
+  echo "Error: failed to write $LEVEL_FILE." >&2
+  echo "State is now INCONSISTENT: both settings.json files were updated to level $LEVEL but .jenga-permission-level.json was not. Re-run this script to repair (it is idempotent)." >&2
+  rm -f "$LEVEL_TMP"
+  exit 5
+fi
+
+echo "Switched to level $LEVEL ($NAME)."
+exit 0

package/scripts/smoke-harness.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# smoke-harness.sh — Per-repository smoke test harness for inline-scoped task execution
+#
+# Usage:
+#   bash scripts/smoke-harness.sh [changed_file ...]
+#
+# If changed files are supplied as positional arguments, those are used directly.
+# If no arguments are given, the harness infers changed files from:
+#   git diff --name-only HEAD
+#
+# Discovery algorithm (in priority order):
+#   1. scripts/smoke.sh   — if present, delegate and return its exit code
+#   2. npm test           — if package.json has a .scripts.test entry and jq is available
+#   3. pytest             — if pytest is in PATH and setup.py/pyproject.toml exists
+#   4. go test ./...      — if go.mod exists
+#   5. No runner found    — pass if all changed files are config/docs; fail otherwise
+#
+# Exit codes:
+#   0 — smoke test passed (or structural-only change with no runner available)
+#   1 — smoke test failed (or logic files changed with no runner available)
+
+set -uo pipefail
+
+# ---------------------------------------------------------------------------
+# Resolve repo root
+# ---------------------------------------------------------------------------
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+
+# ---------------------------------------------------------------------------
+# Collect changed files
+# ---------------------------------------------------------------------------
+# Accept changed files as positional arguments; if none given, infer from git.
+# Uses a portable loop rather than mapfile/readarray (bash 3.x safe for macOS).
+if [[ $# -gt 0 ]]; then
+  CHANGED_FILES=("$@")
+else
+  CHANGED_FILES=()
+  while IFS= read -r line; do
+    [[ -n "$line" ]] && CHANGED_FILES+=("$line")
+  done < <(git diff --name-only HEAD 2>/dev/null || true)
+fi
+
+# ---------------------------------------------------------------------------
+# Step 1: Delegate to scripts/smoke.sh if it exists
+# ---------------------------------------------------------------------------
+if [[ -f "$REPO_ROOT/scripts/smoke.sh" ]]; then
+  echo "INFO: Found scripts/smoke.sh — delegating to project smoke test."
+  bash "$REPO_ROOT/scripts/smoke.sh"
+  exit $?
+fi
+
+# ---------------------------------------------------------------------------
+# Step 2: Infer npm test
+# Requires: package.json with a non-null .scripts.test field, and jq in PATH.
+# ---------------------------------------------------------------------------
+if [[ -f "$REPO_ROOT/package.json" ]]; then
+  if command -v jq > /dev/null 2>&1; then
+    if jq -e '.scripts.test // empty' "$REPO_ROOT/package.json" > /dev/null 2>&1; then
+      echo "INFO: Detected npm project with test script — running npm test."
+      cd "$REPO_ROOT" && npm test
+      exit $?
+    else
+      echo "INFO: package.json found but no .scripts.test entry — skipping npm test inference."
+    fi
+  else
+    echo "INFO: package.json found but jq is not available — skipping npm test inference."
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Step 3: Infer pytest
+# Requires: pytest in PATH, and setup.py or pyproject.toml at repo root.
+# ---------------------------------------------------------------------------
+if command -v pytest > /dev/null 2>&1; then
+  if [[ -f "$REPO_ROOT/setup.py" || -f "$REPO_ROOT/pyproject.toml" ]]; then
+    echo "INFO: Detected Python project — running pytest."
+    cd "$REPO_ROOT" && pytest
+    exit $?
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Step 4: Infer go test
+# Requires: go.mod at repo root.
+# ---------------------------------------------------------------------------
+if [[ -f "$REPO_ROOT/go.mod" ]]; then
+  echo "INFO: Detected Go project — running go test ./..."
+  cd "$REPO_ROOT" && go test ./...
+  exit $?
+fi
+
+# ---------------------------------------------------------------------------
+# Step 5: No test runner found — classify changed files
+#
+# Files are considered config/documentation if they match one of:
+#   - Extension: .json .yaml .yml .md .txt .toml .ini .cfg
+#   - Path prefix: docs/ project/ templates/
+#   - Shell scripts in scripts/: scripts/*.sh (structural scaffolding, not logic)
+# All other files are treated as logic/source files requiring a real test.
+# ---------------------------------------------------------------------------
+CONFIG_DOC_PATTERN='\.(json|yaml|yml|md|txt|toml|ini|cfg)$'
+STRUCTURAL_SCRIPT_PATTERN='^scripts/[^/]+\.sh$'
+STRUCTURAL_PATH_PATTERN='^(docs|project|templates)/'
+
+NON_CONFIG_FILES=()
+for f in "${CHANGED_FILES[@]}"; do
+  is_config=false
+
+  # Check extension pattern
+  if echo "$f" | grep -qE "$CONFIG_DOC_PATTERN"; then
+    is_config=true
+  fi
+
+  # Check structural script pattern (scripts/*.sh)
+  if echo "$f" | grep -qE "$STRUCTURAL_SCRIPT_PATTERN"; then
+    is_config=true
+  fi
+
+  # Check structural path prefix
+  if echo "$f" | grep -qE "$STRUCTURAL_PATH_PATTERN"; then
+    is_config=true
+  fi
+
+  if [[ "$is_config" == "false" ]]; then
+    NON_CONFIG_FILES+=("$f")
+  fi
+done
+
+if [[ ${#NON_CONFIG_FILES[@]} -gt 0 ]]; then
+  echo "ERROR: No smoke test runner found and the task touches logic/source files:" >&2
+  for f in "${NON_CONFIG_FILES[@]}"; do
+    echo "  - $f" >&2
+  done
+  echo "Add a test runner (scripts/smoke.sh, npm test, pytest, or go test) before marking this task complete." >&2
+  exit 1
+fi
+
+echo "INFO: No test runner discoverable; all changed files are config/docs/structural. Smoke test passes."
+exit 0

package/scripts/validate-board.sh

@@ -27,18 +27,76 @@ STATUS_VALUES = {
     "Done",
 }
 
+# E39 tiered item-level caution/escalation. crucial_level is OPTIONAL — absence means no
+# elevated caution. When present it must be one of these three values (see
+# templates/SCRUM_BOARD_SCHEMA.md). crucial_set_by / crucial_note are free-text fields that are
+# only recognised (not enum-validated) here; their "required when crucial_level is set" rule is
+# an authoring discipline documented in the schema, not mechanically enforced by this script —
+# the same treatment given to scope_rationale's "required when execution_scope is set" rule.
+CRUCIAL_LEVEL_VALUES = {
+    "advisory",
+    "gated",
+    "locked",
+}
+
+# Base keys shared by every item type, plus the E32 adaptive-execution-scope fields.
+#
+# The execution-scope fields are all OPTIONAL — a board file that omits them is valid and is
+# treated as execution_scope: task / needs_docs: true (see the backward-compatibility rule in
+# templates/SCRUM_BOARD_SCHEMA.md). They are listed here so that files which DO carry them are
+# not rejected as unknown.
+#
+# Two groups, distinguished by who writes them:
+#   - assigned at breakdown time by the scrum-master (execution_scope … epic_scope_approval)
+#   - written at runtime by /close-story and /do (actual_files_changed … divergence_flag)
+# Runtime fields appear only after a task has executed, so most task files will lack them.
+# task_changed_files is deliberately absent: it lives in the bundle manifest JSON
+# (project/queue/bundle-<E##_S##>.json), not in task frontmatter.
+EXECUTION_SCOPE_KEYS = {
+    "execution_scope", "needs_docs", "scope_rationale",
+    "jenga_assigned", "override_justification", "epic_scope_approval",
+}
+
+CLOSE_STORY_KEYS = {
+    "actual_files_changed", "actual_lines_delta", "scope_divergence_flag", "divergence_flag",
+}
+
+# E39 tiered item-level caution/escalation fields. OPTIONAL and story/task-only — epics do not
+# carry these; an epic's risk gating is already handled by epic_scope_approval. See
+# templates/SCRUM_BOARD_SCHEMA.md.
+#
+# crucial_declined / crucial_declined_note (E39_S02_T03) are a separate optional pair recording
+# that a scrum-master-proposed crucial_level was explicitly declined by the user for this item —
+# the durable decline-tracking mechanism that stops the breakdown step from re-proposing on a
+# later pass. Like crucial_set_by / crucial_note, they are free-text/recognised-not-enum-validated
+# here; their "required when crucial_declined: true" rule is an authoring discipline documented in
+# the schema, not mechanically enforced by this script.
+CRUCIAL_KEYS = {
+    "crucial_level", "crucial_set_by", "crucial_note",
+    "crucial_declined", "crucial_declined_note",
+}
+
 ALLOWED_KEYS = {
     "epic": {
         "id", "title", "status", "date_created", "date_started", "date_completed",
         "dates_previously_completed", "reopened_on", "reopened_reason", "stories", "docs",
+        "epic_scope_approval",
+        # OPTIONAL. Marks how the epic came to exist; only written by `/uncharted onboard`
+        # (value: backfilled). Absence means the epic was authored normally, so every existing
+        # epic that omits it stays valid. See templates/SCRUM_BOARD_SCHEMA.md.
+        "provenance",
     },
     "story": {
         "id", "epic_id", "title", "status", "date_created", "date_started", "date_completed",
         "dates_previously_completed", "reopened_on", "reopened_reason", "tasks", "docs",
+        "priority", "depends_on",
+        *CRUCIAL_KEYS,
     },
     "task": {
         "id", "story_id", "epic_id", "title", "status", "date_created", "date_started", "date_completed",
         "dates_previously_completed", "reopened_on", "reopened_reason", "assigned_to", "docs",
+        "depends_on",
+        *EXECUTION_SCOPE_KEYS, *CLOSE_STORY_KEYS, *CRUCIAL_KEYS,
     },
 }
 
@@ -152,6 +210,10 @@ def validate_file(source: Path):
     if status and status not in STATUS_VALUES:
         raise ValueError(f"{source}: invalid status '{status}'")
 
+    crucial_level = data.get("crucial_level")
+    if crucial_level and crucial_level not in CRUCIAL_LEVEL_VALUES:
+        raise ValueError(f"{source}: invalid crucial_level '{crucial_level}'")
+
     docs = data.get("docs", None)
     if docs is not None:
         validate_docs(source, docs)

package/scripts/with-lock.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# scripts/with-lock.sh — atomic, cross-platform exclusive file lock wrapper
+#
+# Usage:
+#   scripts/with-lock.sh <target-file> -- <command> [args...]
+#
+# Acquires an exclusive lock keyed to <target-file> before running <command>,
+# and always releases the lock afterward — on success, on failure, and on
+# signal (INT/TERM sent to this script are forwarded to the wrapped command,
+# which is then waited on before the lock is released — see the signal
+# handling note further down). The wrapped command's exit code is preserved
+# as this script's own exit code.
+#
+# This replaces the purely advisory "check for a .lock file, wait, retry,
+# then create/delete it yourself" convention previously described in
+# templates/SCRUM_BOARD_SCHEMA.md. That convention relied on every caller
+# implementing check-wait-retry-cleanup correctly, including on error paths,
+# with nothing to mechanically stop two writers from both deciding the lock
+# is free at the same time. This script enforces exclusivity instead.
+#
+# Lock primitive: `mkdir` on a lock directory, NOT `flock`. `flock` is a
+# Linux-only (util-linux) utility and is not present by default on macOS/BSD
+# (this repo runs on Darwin). POSIX `mkdir` is atomic on every platform this
+# repo targets: the kernel guarantees that when multiple processes race to
+# create the same directory, exactly one succeeds and every other call fails
+# with EEXIST. That atomicity — not any cooperative check beforehand — is
+# what makes this a real mutual-exclusion lock instead of advisory prose.
+#
+# Environment overrides (all optional):
+#   WITH_LOCK_TIMEOUT_SECONDS   Max time to wait for a held lock (default: 30)
+#   WITH_LOCK_POLL_SECONDS      Poll interval while waiting (default: 0.2)
+#   WITH_LOCK_STALE_SECONDS     Age after which a still-held lock is treated
+#                               as abandoned (crashed holder) and reclaimed
+#                               (default: 60)
+#
+# Exit codes:
+#   0    lock acquired, command ran, exit code is the command's own
+#   1    invalid usage
+#   2    could not acquire the lock within the timeout — the command was
+#        NEVER run (fail safe; no partial or silently-clobbered write)
+#   *    otherwise, the wrapped command's own exit code
+
+set -u
+
+usage() {
+  echo "Usage: $0 <target-file> -- <command> [args...]" >&2
+  exit 1
+}
+
+[ "$#" -ge 1 ] || usage
+TARGET_FILE="$1"
+shift
+
+[ "${1:-}" = "--" ] || usage
+shift
+
+[ "$#" -ge 1 ] || usage
+
+TIMEOUT_SECONDS="${WITH_LOCK_TIMEOUT_SECONDS:-30}"
+POLL_SECONDS="${WITH_LOCK_POLL_SECONDS:-0.2}"
+STALE_SECONDS="${WITH_LOCK_STALE_SECONDS:-60}"
+
+LOCK_DIR="${TARGET_FILE}.lock.d"
+LOCK_PID_FILE="${LOCK_DIR}/pid"
+
+now_epoch() {
+  date +%s
+}
+
+# Portable mtime lookup: GNU stat (Linux) uses -c, BSD stat (macOS) uses -f.
+# Try GNU form first, fall back to BSD form. Echoes nothing (and returns
+# non-zero) if the directory vanished in the meantime.
+lock_mtime_epoch() {
+  stat -c %Y "$LOCK_DIR" 2>/dev/null || stat -f %m "$LOCK_DIR" 2>/dev/null
+}
+
+# If the held lock looks abandoned (older than STALE_SECONDS), reclaim it.
+# This does NOT grant the lock by itself — it only clears the way. The next
+# mkdir attempt in the polling loop is still the sole arbiter of who
+# proceeds, so simultaneous reclaim attempts by multiple waiters never let
+# more than one of them through.
+maybe_reclaim_stale_lock() {
+  local mtime now age
+  mtime="$(lock_mtime_epoch)" || return 0
+  now="$(now_epoch)"
+  age=$(( now - mtime ))
+  if [ "$age" -ge "$STALE_SECONDS" ]; then
+    echo "with-lock: reclaiming stale lock '$LOCK_DIR' (age ${age}s >= ${STALE_SECONDS}s)" >&2
+    rm -rf "$LOCK_DIR" 2>/dev/null
+  fi
+}
+
+acquire_lock() {
+  local start now elapsed
+  start="$(now_epoch)"
+  while true; do
+    if mkdir "$LOCK_DIR" 2>/dev/null; then
+      echo "$$" > "$LOCK_PID_FILE" 2>/dev/null || true
+      return 0
+    fi
+
+    maybe_reclaim_stale_lock
+
+    now="$(now_epoch)"
+    elapsed=$(( now - start ))
+    if [ "$elapsed" -ge "$TIMEOUT_SECONDS" ]; then
+      return 1
+    fi
+    sleep "$POLL_SECONDS" 2>/dev/null || sleep 1
+  done
+}
+
+release_lock() {
+  rm -rf "$LOCK_DIR" 2>/dev/null
+}
+
+if ! acquire_lock; then
+  echo "with-lock: failed to acquire lock on '$TARGET_FILE' within ${TIMEOUT_SECONDS}s (lock dir: $LOCK_DIR) — command was not run" >&2
+  exit 2
+fi
+
+# Always release the lock on exit, regardless of how the wrapped command
+# (or this script itself) terminates.
+trap release_lock EXIT
+
+# Signal handling note: the wrapped command is run in the background and
+# waited on explicitly (rather than exec'd directly in the foreground) so
+# that INT/TERM delivered to this script are handled promptly. Bash defers
+# non-EXIT traps until a foreground command completes, so a script that
+# instead ran `"$@"` directly in the foreground would not react to a signal
+# sent to its own PID until the wrapped command finished on its own —
+# release would then only happen once the command exited naturally (or, in
+# the worst case, once WITH_LOCK_STALE_SECONDS elapsed and another waiter
+# reclaimed the lock). Backgrounding + `wait` avoids that: the trap fires as
+# soon as the signal arrives, forwards it to the child, waits for the child
+# to actually exit, then this script exits (triggering the EXIT trap above,
+# which releases the lock).
+CHILD_PID=""
+
+forward_signal_and_exit() {
+  local sig="$1" exit_code="$2"
+  if [ -n "$CHILD_PID" ]; then
+    kill -s "$sig" "$CHILD_PID" 2>/dev/null
+    wait "$CHILD_PID" 2>/dev/null
+  fi
+  exit "$exit_code"
+}
+
+trap 'forward_signal_and_exit TERM 143' TERM
+trap 'forward_signal_and_exit INT 130' INT
+
+"$@" &
+CHILD_PID=$!
+wait "$CHILD_PID"
+status=$?
+CHILD_PID=""
+
+exit "$status"