muse-crew 0.4.4 → 0.4.6

package/API.md

@@ -71,14 +71,14 @@ Send a stuck or failed task to a specific workflow phase for recovery.
 
 ### `parktask`
 
-Atomically park a task for human attention: sets `state` to `parked` and writes the explanatory `note` event in one transaction. Either both land or neither does — callers never see a note without a park or a park without a note. The dispatcher skips parked tasks; moving the task back to `todo` is the human re-queue path (which stamps `retry_reset_at` — see `updatetask`).
+Atomically park a task for human attention: sets `state` to `parked`, writes the explanatory `note` event, and settles every `running` session for the task — in one transaction. Either all land or none do: callers never see a note without a park, a park without a note, or a parked task with a ghost `running` session left behind (a terminal task transition settles its sessions). Settled sessions move to `failed` — the status `recovertask` accepts, so recovery works immediately after a park — with `ended_at` stamped and `Parked: <message>` appended to their notes; `failure_reason` stays null.
 
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
 | `task_id` | uuid | yes | |
 | `message` | string (1–1000) | yes | Why the task needs a human; written to the activity feed as a `note` |
 
-Returns `{ "ok": true, "task": {...} }` with the updated task record.
+Returns `{ "ok": true, "task": {...}, "settled_sessions": <n> }` with the updated task record and the count of sessions settled (`0` when none were running).
 
 ---
 

package/lib/AGENTS.md

@@ -4,11 +4,12 @@ Shell scripts for the crew's infrastructure. Called by workflow scripts, cron, a
 
 - `build-registry.js` — deterministic extractor that generates `workflows/registry.json` (workflow step registry) from the workflow files' `meta` blocks at release time; invoked by `crew-release.sh` deploy
 - `crew-release.sh` — immutable release manager: deploy, rollback, prune
-- `merge-lock.sh` — serialized merge lock for concurrent agents; records owner PID
+- `merge-lock.sh` — serialized merge lock for concurrent agents: time-based holder lease (bug 2fc8f52f — an unexpired lease is held regardless of process liveness; only an expired lease may be broken). Lock file is key=value: task_id, opaque holder identity (never a PID), acquired_at epoch, lease_seconds (default 600, override via MERGE_LOCK_LEASE_SECONDS). acquire/refresh/release/status/force-release; holder-only refresh and release; every op appends to $CREW_HOME/.merge-lock.log
 - `worktree-lifecycle.sh` — the worktree lifecycle seam: prepare/cleanup/inspect/integrate/status/post-deploy over git worktrees (`.worktrees/<id>`, branch `task/<id>`). The crew registry (`<repo>/.worktrees/.registry/<id>`) is the source of truth for task→branch/path — never reconstruct it from git state. Prepare fails closed on dirty `main`; cleanup is forgiving.
 - `test-worktree-backend.sh` — regression tests for the lifecycle script (validate, prepare/reuse, inspect, status, cleanup, idempotent cleanup, dirty-main preflight) on a scratch repo
 - `test-version-write.sh` — regression tests for the escape-preserving step-8 version write in publish-npm.sh (fixture: current package.json with the \u2014 escape; extracts the shipped block by anchor)
-- `orphan-sweep.sh` — find and clean stale worktrees and merge locks
+- `test-publish-verify.sh` — regression tests for the retry-tolerant step-12 verification in publish-npm.sh (canary 5a027278): extracts the shipped block by anchor and runs it against a fake npm whose read replica lags (non-zero exits, then the old version, then the target) — requires convergence on success, fail-closed `PUBLISH_FAILED=verify` on exhaustion, and `--prefer-online` on every read
+- `orphan-sweep.sh` — find and clean stale worktrees and merge locks: parses `merge-lock.sh status` key=value fields (never a PID); a lock whose task has a running session is untouched regardless of lease age; a lock with no running session is broken only when its lease is expired (via merge-lock.sh release so the break lands in the audit log)
 - `publish-npm.sh` — deterministic npm publish: lock refresh, release install, version write/commit, pack, registry publish, verify, push, post-deploy. Takes TARGET_VERSION as input; idempotent on retry/resume.
 - `compose-evidence.py` — deterministic visual-evidence compositor (Pillow): pairs identical PNG stems from baseline/ and postchange/ dirs, emits `<stem>-sidebyside.png` and amplified-difference `<stem>-overlay.png` into composites/, prints `PAIR`/`SKIP` manifests. Byte-deterministic; nonzero exit on errors.
 - `test-orphan-sweep.sh` — regression tests for orphan-sweep.sh (active-run guard, verified removal, fail-closed)

package/lib/merge-lock.sh

@@ -1,16 +1,89 @@
 #!/usr/bin/env bash
-# Serialized merge lock for the orchestra-dashboard repo.
+# merge-lock.sh — serialized merge lock for the crew's repos.
+#
+# Time-based holder lease (bug 2fc8f52f): the old PID-liveness staleness
+# check never excluded anyone. The recorded PID was the short-lived shell
+# that ran the acquire, so for essentially the whole Integrate→Publish→
+# post-deploy hold window the holder's PID was dead, every concurrent
+# acquire took the STALE path, and two Publish phases both believed they
+# owned version assignment. PID is the wrong liveness signal (orphan-sweep
+# already treats it as such) — the lease is time-based and refreshed by
+# the workflow while the hold is live.
+#
+# The lock file ($CREW_REPO/.worktrees/.merge-lock) is key=value:
+#   task_id=<task id that holds the lock>
+#   holder=<opaque task+run identity, never a PID>
+#   acquired_at=<epoch seconds; refresh rewrites it to extend the lease>
+#   lease_seconds=<lease window; MERGE_LOCK_LEASE_SECONDS, default 600>
+#
+# The lock is HELD while now - acquired_at < lease_seconds. An expired
+# (or malformed) lease is broken with logging and re-acquired. Every op
+# appends one line to $CREW_HOME/.merge-lock.log (the audit trail).
+#
 # Usage:
-#   merge-lock.sh acquire <task_id> [pid]  — acquires lock, exits 0 on success, 1 if held
-#   merge-lock.sh release <task_id>        — releases lock if held by this task
-#   merge-lock.sh refresh <task_id> [pid]  — refresh lock timestamp (resets staleness clock)
-#   merge-lock.sh status                   — prints current lock holder or "unlocked"
-#   merge-lock.sh force-release            — breaks the lock (admin use only)
+#   merge-lock.sh acquire <task_id> <holder>  — acquire the lock (0 ok, 1 held)
+#   merge-lock.sh refresh <task_id>           — extend the lease (holder task only)
+#   merge-lock.sh release <task_id>           — release the lock (holder task only)
+#   merge-lock.sh status                      — key=value holder/age/remaining, or UNLOCKED
+#   merge-lock.sh force-release                — break the lock (admin use only)
 
 set -euo pipefail
 
 LOCK_DIR="${CREW_REPO:-$HOME/workspace/ts-spaces/orchestra-dashboard}/.worktrees"
 LOCK_FILE="$LOCK_DIR/.merge-lock"
+LOG_FILE="${CREW_HOME:-$HOME/workspace/.jarvis}/.merge-lock.log"
+LEASE_SECONDS="${MERGE_LOCK_LEASE_SECONDS:-600}"
+
+log_op() { # log_op <op> <detail> — audit trail; logging never breaks a lock op
+  mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null || true
+  printf '%s op=%s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$1" "$2" >> "$LOG_FILE" 2>/dev/null || true
+}
+
+# read_lock — parse the lock file into lock_task_id / lock_holder /
+# lock_acquired_at / lock_lease_seconds. Returns 1 when there is no lock.
+read_lock() {
+  lock_task_id=""; lock_holder=""; lock_acquired_at=""; lock_lease_seconds=""
+  [ -f "$LOCK_FILE" ] || return 1
+  local key val
+  while IFS='=' read -r key val; do
+    case "$key" in
+      task_id) lock_task_id="$val" ;;
+      holder) lock_holder="$val" ;;
+      acquired_at) lock_acquired_at="$val" ;;
+      lease_seconds) lock_lease_seconds="$val" ;;
+    esac
+  done < "$LOCK_FILE"
+  return 0
+}
+
+lock_age() { # seconds since acquired_at, or "unknown" when unparsable
+  if [[ "${lock_acquired_at:-}" =~ ^[0-9]+$ ]]; then
+    echo $(( $(date +%s) - lock_acquired_at ))
+  else
+    echo "unknown"
+  fi
+}
+
+lock_remaining() { # lease seconds remaining (<=0 means expired), or "unknown"
+  local age="${1:-$(lock_age)}" lease="$lock_lease_seconds"
+  [[ "$lease" =~ ^[0-9]+$ ]] || lease="$LEASE_SECONDS"
+  if [ "$age" = "unknown" ]; then
+    echo "unknown"
+  else
+    echo $(( lease - age ))
+  fi
+}
+
+# write_lock <task_id> <holder> — atomic create via noclobber; 0 on success.
+# A concurrent writer wins exactly one create; the loser retries the read.
+write_lock() {
+  local task_id="$1" holder="$2"
+  mkdir -p "$LOCK_DIR"
+  ( set -C
+    printf 'task_id=%s\nholder=%s\nacquired_at=%s\nlease_seconds=%s\n' \
+      "$task_id" "$holder" "$(date +%s)" "$LEASE_SECONDS" > "$LOCK_FILE"
+  ) 2>/dev/null
+}
 
 cmd="${1:-}"
 task_id="${2:-}"
@@ -18,90 +91,98 @@ task_id="${2:-}"
 case "$cmd" in
   acquire)
     [ -z "$task_id" ] && { echo "ERROR: task_id required"; exit 1; }
-    owner_pid="${3:-$PPID}"
-    mkdir -p "$LOCK_DIR"
-    if (set -C; echo "$task_id $(date -u +%Y-%m-%dT%H:%M:%SZ) $owner_pid" > "$LOCK_FILE") 2>/dev/null; then
-      echo "ACQUIRED by $task_id"
+    holder="${3:-$task_id}"
+    if write_lock "$task_id" "$holder"; then
+      log_op acquire "task_id=$task_id holder=$holder result=ACQUIRED"
+      echo "ACQUIRED by $task_id (holder $holder)"
       exit 0
-    else
-      holder=$(cut -d' ' -f1 "$LOCK_FILE" 2>/dev/null || echo "unknown")
-      acquired_at=$(cut -d' ' -f2 "$LOCK_FILE" 2>/dev/null || echo "unknown")
-      lock_pid=$(awk '{print $3}' "$LOCK_FILE" 2>/dev/null || echo "-")
-      # Self-healing: if the holder's PID is dead, missing, or invalid, the lock
-      # is stale (the workflow that acquired it terminated without releasing
-      # via post-deploy). Break the stale lock and retry the acquire. A live
-      # PID means the lock is genuinely held — report HELD. This makes terminal
-      # cleanup mechanical: a stopped/failed workflow's lock is reclaimed on
-      # the next acquire, not via manual release or a background sweeper.
-      if [ -z "$lock_pid" ] || [ "$lock_pid" = "-" ] || ! kill -0 "$lock_pid" 2>/dev/null; then
-        echo "STALE: lock held by $holder since $acquired_at (pid $lock_pid dead) — breaking" >&2
-        rm -f "$LOCK_FILE"
-        if (set -C; echo "$task_id $(date -u +%Y-%m-%dT%H:%M:%SZ) $owner_pid" > "$LOCK_FILE") 2>/dev/null; then
-          echo "ACQUIRED by $task_id (reclaimed stale lock from $holder)"
-          exit 0
-        fi
-        # Lost the race: another task acquired it after we broke the stale lock.
-        holder=$(cut -d' ' -f1 "$LOCK_FILE" 2>/dev/null || echo "unknown")
-        acquired_at=$(cut -d' ' -f2 "$LOCK_FILE" 2>/dev/null || echo "unknown")
-        lock_pid=$(awk '{print $3}' "$LOCK_FILE" 2>/dev/null || echo "-")
+    fi
+    # A lock file exists (or raced into existence) — read it.
+    if ! read_lock; then
+      # Raced with a release between create and read: retry the create once.
+      if write_lock "$task_id" "$holder"; then
+        log_op acquire "task_id=$task_id holder=$holder result=ACQUIRED"
+        echo "ACQUIRED by $task_id (holder $holder)"
+        exit 0
       fi
-      echo "HELD by $holder since $acquired_at (pid $lock_pid)"
+      read_lock || { echo "ERROR: lock state unreadable"; log_op acquire "task_id=$task_id holder=$holder result=ERROR"; exit 1; }
+    fi
+    remaining="$(lock_remaining)"
+    if [ "$remaining" != "unknown" ] && [ "$remaining" -gt 0 ]; then
+      log_op acquire "task_id=$task_id holder=$holder result=HELD holder_task=$lock_task_id holder_id=$lock_holder remaining=${remaining}s"
+      echo "HELD by $lock_task_id (holder $lock_holder, ${remaining}s of lease remaining)"
       exit 1
     fi
+    # Expired or malformed lease — break it (logged) and re-acquire.
+    echo "STALE: lease for ${lock_task_id:-unknown} (holder ${lock_holder:-unknown}) expired — breaking" >&2
+    log_op acquire "task_id=$task_id holder=$holder result=STALE-BREAK previous_task=${lock_task_id:-unknown} previous_holder=${lock_holder:-unknown}"
+    rm -f "$LOCK_FILE"
+    if write_lock "$task_id" "$holder"; then
+      log_op acquire "task_id=$task_id holder=$holder result=ACQUIRED-RECLAIMED previous_task=${lock_task_id:-unknown}"
+      echo "ACQUIRED by $task_id (holder $holder; reclaimed expired lease from ${lock_task_id:-unknown})"
+      exit 0
+    fi
+    # Lost the race: whoever won the create holds it now.
+    read_lock 2>/dev/null || true
+    log_op acquire "task_id=$task_id holder=$holder result=HELD-RACE holder_task=${lock_task_id:-unknown}"
+    echo "HELD by ${lock_task_id:-unknown} (holder ${lock_holder:-unknown}) — lost reclaim race"
+    exit 1
+    ;;
+  refresh)
+    [ -z "$task_id" ] && { echo "ERROR: task_id required"; exit 1; }
+    if ! read_lock; then
+      log_op refresh "task_id=$task_id result=NO-LOCK"
+      echo "ERROR: no lock to refresh"
+      exit 1
+    fi
+    if [ "$lock_task_id" != "$task_id" ]; then
+      log_op refresh "task_id=$task_id result=NOT-HOLDER holder_task=$lock_task_id"
+      echo "ERROR: lock held by $lock_task_id, not $task_id"
+      exit 1
+    fi
+    # Extend the lease: acquired_at=now, holder and lease window unchanged.
+    printf 'task_id=%s\nholder=%s\nacquired_at=%s\nlease_seconds=%s\n' \
+      "$lock_task_id" "$lock_holder" "$(date +%s)" "${lock_lease_seconds:-$LEASE_SECONDS}" > "$LOCK_FILE"
+    log_op refresh "task_id=$task_id holder=$lock_holder result=REFRESHED"
+    echo "REFRESHED by $task_id (holder $lock_holder)"
+    exit 0
     ;;
   release)
     [ -z "$task_id" ] && { echo "ERROR: task_id required"; exit 1; }
-    if [ -f "$LOCK_FILE" ]; then
-      holder=$(cut -d' ' -f1 "$LOCK_FILE" 2>/dev/null || echo "")
-      if [ "$holder" = "$task_id" ]; then
-        rm -f "$LOCK_FILE"
-        echo "RELEASED by $task_id"
-        exit 0
-      else
-        echo "ERROR: lock held by $holder, not $task_id"
-        exit 1
-      fi
-    else
+    if ! read_lock; then
+      log_op release "task_id=$task_id result=NOT-LOCKED"
       echo "RELEASED (was not locked)"
       exit 0
     fi
+    if [ "$lock_task_id" = "$task_id" ]; then
+      rm -f "$LOCK_FILE"
+      log_op release "task_id=$task_id holder=$lock_holder result=RELEASED"
+      echo "RELEASED by $task_id"
+      exit 0
+    fi
+    log_op release "task_id=$task_id result=NOT-HOLDER holder_task=$lock_task_id"
+    echo "ERROR: lock held by $lock_task_id, not $task_id"
+    exit 1
     ;;
   status)
-    if [ -f "$LOCK_FILE" ]; then
-      holder=$(cut -d' ' -f1 "$LOCK_FILE" 2>/dev/null || echo "unknown")
-      acquired_at=$(cut -d' ' -f2 "$LOCK_FILE" 2>/dev/null || echo "unknown")
-      lock_pid=$(awk '{print $3}' "$LOCK_FILE" 2>/dev/null || echo "-")
-      echo "LOCKED by $holder since $acquired_at (pid $lock_pid)"
-    else
+    if ! read_lock; then
       echo "UNLOCKED"
+      exit 0
     fi
+    printf 'locked=true\ntask_id=%s\nholder=%s\nacquired_at=%s\nlease_seconds=%s\nage_seconds=%s\nremaining_seconds=%s\n' \
+      "$lock_task_id" "$lock_holder" "$lock_acquired_at" "${lock_lease_seconds:-$LEASE_SECONDS}" \
+      "$(lock_age)" "$(lock_remaining)"
     exit 0
     ;;
   force-release)
+    read_lock 2>/dev/null || true
+    log_op force-release "result=FORCE-RELEASED previous_task=${lock_task_id:-unknown}"
     rm -f "$LOCK_FILE"
     echo "FORCE RELEASED"
     exit 0
     ;;
-  refresh)
-    [ -z "$task_id" ] && { echo "ERROR: task_id required"; exit 1; }
-    new_pid="${3:-$PPID}"
-    if [ -f "$LOCK_FILE" ]; then
-      holder=$(cut -d' ' -f1 "$LOCK_FILE" 2>/dev/null || echo "")
-      if [ "$holder" = "$task_id" ]; then
-        echo "$task_id $(date -u +%Y-%m-%dT%H:%M:%SZ) $new_pid" > "$LOCK_FILE"
-        echo "REFRESHED by $task_id"
-        exit 0
-      else
-        echo "ERROR: lock held by $holder, not $task_id"
-        exit 1
-      fi
-    else
-      echo "ERROR: no lock to refresh"
-      exit 1
-    fi
-    ;;
   *)
-    echo "Usage: merge-lock.sh {acquire|release|refresh|status|force-release} [task_id] [pid]"
+    echo "Usage: merge-lock.sh {acquire|release|refresh|status|force-release} <task_id> [holder]"
     exit 1
     ;;
 esac

package/lib/orphan-sweep.sh

@@ -4,9 +4,9 @@
 #
 # Usage:
 #   orphan-sweep.sh report  — list orphans (read-only for worktrees);
-#                              stale locks with dead PIDs are released
+#                              expired-lease locks are released
 #   orphan-sweep.sh clean   — remove safe-to-clean orphans (merged branches only),
-#                              release stale merge locks, and remove pins whose
+#                              release expired-lease merge locks, and remove pins whose
 #                              task has no running session
 #
 # Active-run knowledge is injected by the caller, never fetched here:
@@ -44,7 +44,7 @@ set -euo pipefail
 REPO="${CREW_REPO:-$HOME/workspace/ts-spaces/orchestra-dashboard}"
 WORKTREE_DIR="$REPO/.worktrees"
 LOCK_FILE="$WORKTREE_DIR/.merge-lock"
-STALE_LOCK_MIN=30
+MERGE_LOCK_SCRIPT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/merge-lock.sh"
 
 cmd="${1:-report}"
 found=0
@@ -100,40 +100,44 @@ if [ "$cmd" != "clean" ] && [ "$have_active_data" -eq 0 ]; then
   echo "NOTE: no active-run data provided; ACTIVE checks skipped"
 fi
 
-# --- Stale merge lock ---
+# --- Stale merge lock (lease-based; bug 2fc8f52f) ---
+# Owner identity comes from merge-lock.sh status key=value fields — never
+# from a PID. Fail-closed: a lock whose task has a running session is
+# untouched regardless of lease age; a lock whose task has no running
+# session is broken only when its lease is expired. The break goes through
+# merge-lock.sh release (or force-release for an unparseable file with no
+# identifiable holder) so it lands in the merge-lock audit log.
 if [ -f "$LOCK_FILE" ]; then
-  lock_holder=$(cut -d' ' -f1 "$LOCK_FILE" 2>/dev/null || echo "unknown")
-  if task_is_active "$lock_holder"; then
-    echo "ACTIVE_LOCK: held by $lock_holder (active run on dashboard) — skipping"
-    found=1
+  lock_status="$("$MERGE_LOCK_SCRIPT" status 2>/dev/null || echo UNLOCKED)"
+  if [ "$lock_status" = "UNLOCKED" ]; then
+    : # lock file vanished between the check and the read — nothing held
   else
-    lock_time=$(cut -d' ' -f2 "$LOCK_FILE" 2>/dev/null || echo "")
-    lock_pid=$(awk '{print $3}' "$LOCK_FILE" 2>/dev/null || echo "")
-    if [ -n "$lock_time" ]; then
-      lock_epoch=$(date -d "$lock_time" +%s 2>/dev/null || echo 0)
-      now_epoch=$(date -u +%s)
-      age_min=$(( (now_epoch - lock_epoch) / 60 ))
-      if [ "$age_min" -gt "$STALE_LOCK_MIN" ]; then
-        # Check if owner process is still alive
-        pid_alive=0
-        if [ -n "$lock_pid" ] && [ "$lock_pid" != "-" ] && kill -0 "$lock_pid" 2>/dev/null; then
-          pid_alive=1
-        fi
-
-        if [ "$pid_alive" -eq 1 ]; then
-          echo "ACTIVE_LOCK: held ${age_min}m by $lock_holder (pid $lock_pid alive) — skipping"
-        else
-          echo "STALE_LOCK: held ${age_min}m by $lock_holder (pid ${lock_pid:-none} dead) — threshold ${STALE_LOCK_MIN}m"
-          found=1
-          rm -f "$LOCK_FILE"
-          if [ ! -f "$LOCK_FILE" ]; then
-            echo "  → released (dead PID)"
-          else
-            echo "  → FAILED: lock file still present after rm"
-            any_failed=1
-          fi
-        fi
+    lock_holder=$(printf '%s\n' "$lock_status" | sed -n 's/^task_id=//p' | head -1)
+    lock_remaining=$(printf '%s\n' "$lock_status" | sed -n 's/^remaining_seconds=//p' | head -1)
+    lock_age=$(printf '%s\n' "$lock_status" | sed -n 's/^age_seconds=//p' | head -1)
+    if task_is_active "$lock_holder"; then
+      echo "ACTIVE_LOCK: held by ${lock_holder:-unknown} (active run on dashboard) — skipping"
+      found=1
+    elif [ "${lock_remaining:-unknown}" != "unknown" ] && [ "$lock_remaining" -gt 0 ]; then
+      echo "HELD_LOCK: held by ${lock_holder:-unknown} (lease ${lock_remaining}s remaining) — skipping"
+      found=1
+    else
+      echo "STALE_LOCK: held by ${lock_holder:-unknown} (age ${lock_age:-unknown}s, lease expired, no running session)"
+      found=1
+      if [ -n "$lock_holder" ]; then
+        rel_out=$("$MERGE_LOCK_SCRIPT" release "$lock_holder" 2>&1) || true
+      else
+        rel_out=$("$MERGE_LOCK_SCRIPT" force-release 2>&1) || true
       fi
+      case "$rel_out" in
+        *RELEASED*)
+          echo "  → released (lease expired)"
+          ;;
+        *)
+          echo "  → FAILED: could not release lock: $rel_out"
+          any_failed=1
+          ;;
+      esac
     fi
   fi
 fi

package/lib/publish-npm.sh

@@ -150,13 +150,38 @@ if [ "$ALREADY_PUBLISHED" = "0" ]; then
   rm -f "$TGZ"
 
   # 12. Verify: ground truth is the registry, not any agent's summary.
-  REG="$(npm view "$PKG" version 2>/dev/null)" \
-    || fail "verify" "npm view $PKG failed"
+  # The registry is eventually consistent: a publish followed by an
+  # immediate read can observe the pre-publish version (canary 5a027278
+  # hit a stale read replica ~6s after publish). A single stale read must
+  # never park a landed publish, so this block retries with backoff and
+  # client cache-busting instead of failing on the first mismatch.
+  # STEP-12-ANCHOR: publish verification (retry-tolerant)
+  VERIFY_ATTEMPTS="${VERIFY_ATTEMPTS:-12}"
+  VERIFY_SLEEP_SECS="${VERIFY_SLEEP_SECS:-10}"
+  REG=""
+  for attempt in $(seq 1 "$VERIFY_ATTEMPTS"); do
+    # --prefer-online busts npm's client-side packument cache; the retry
+    # loop absorbs server-side replica lag. A non-zero exit is a miss,
+    # not an immediate failure.
+    REG="$(npm view "$PKG" version --prefer-online 2>/dev/null || true)"
+    [ "$REG" = "$TARGET_VERSION" ] && break
+    echo "PUBLISH_VERIFY_RETRY=$attempt registry=$REG"
+    [ "$attempt" -lt "$VERIFY_ATTEMPTS" ] && sleep "$VERIFY_SLEEP_SECS"
+  done
   [ "$REG" = "$TARGET_VERSION" ] \
-    || fail "verify" "registry=$REG"
+    || fail "verify" "registry=$REG after $VERIFY_ATTEMPTS attempts"
   echo "PUBLISH_VERIFIED=$TARGET_VERSION"
+  # STEP-12-END
 fi
 
+# 12b. Refresh the merge lock again — release-deploy, pack, publish, and the
+# verify retry loop can together consume more than half the lease on a slow
+# registry. The push and the post-deploy below must happen under our lock;
+# if the refresh fails (expired lease, someone else holds it), stop — never
+# push a version-bump commit or release a lock we no longer own.
+LOCK_OUT2="$(CREW_REPO="$REPO_PATH" bash "${LIFECYCLE:?LIFECYCLE is required}" refresh-lock "$TASK_ID" 2>&1)" \
+  || fail "lock-refresh" "$LOCK_OUT2"
+
 # 13. Push the version-bump commit (idempotent: no-op if already pushed).
 PUSH_OUT="$(git -C "$REPO_PATH" push origin main 2>&1)" \
   || fail "push" "$PUSH_OUT"

package/lib/test-merge-lock.sh

@@ -2,9 +2,12 @@
 # test-merge-lock.sh — regression tests for merge-lock.sh
 #
 # Self-contained: uses a temp CREW_REPO and drives lib/merge-lock.sh through
-# acquire/release/status. Tests the self-healing acquire: a lock held by a
-# dead PID is reclaimed automatically; a lock held by a live PID reports HELD.
-# Exits 0 only if every case passes.
+# acquire/refresh/release/status. Tests the time-based lease model (bug
+# 2fc8f52f): an unexpired lease blocks contenders even when no holder
+# process is alive (PID liveness is never consulted); an expired lease is
+# reclaimed with logging; refresh extends the lease; release is
+# holder-only; status emits parseable holder/age/remaining fields; every
+# op appends to the merge-lock audit log. Exits 0 only if every case passes.
 
 set -uo pipefail
 
@@ -20,49 +23,89 @@ TMPBASE="$(mktemp -d)"
 trap 'rm -rf "$TMPBASE"' EXIT
 
 export CREW_REPO="$TMPBASE/repo"
+export CREW_HOME="$TMPBASE/home"
+export MERGE_LOCK_LEASE_SECONDS=600
 mkdir -p "$CREW_REPO/.worktrees"
 
-# --- Case 1: acquire on unlocked succeeds ---
-# Use $$ (this shell's PID) which is definitely alive.
-out=$("$LOCK" acquire task-1 $$ 2>&1); code=$?
-[ "$code" -eq 0 ] && [[ "$out" == *"ACQUIRED by task-1"* ]] && ok "1: acquire on unlocked succeeds" || no "1: exit $code, out: $out"
+# --- Case 1: acquire on unlocked succeeds (opaque holder, not a PID) ---
+out=$("$LOCK" acquire task-1 "task-1/run-aaa" 2>&1); code=$?
+[ "$code" -eq 0 ] && [[ "$out" == *"ACQUIRED by task-1"* ]] && [[ "$out" == *"task-1/run-aaa"* ]] \
+  && ok "1: acquire on unlocked succeeds with opaque holder" || no "1: exit $code, out: $out"
 
-# --- Case 2: second acquire with live PID reports HELD ---
-out=$("$LOCK" acquire task-2 99999 2>&1); code=$?
-[ "$code" -eq 1 ] && [[ "$out" == *"HELD by task-1"* ]] && ok "2: acquire with live holder PID reports HELD" || no "2: exit $code, out: $out"
+# --- Case 2: contender blocked while lease unexpired (no PID involved) ---
+out=$("$LOCK" acquire task-2 "task-2/run-bbb" 2>&1); code=$?
+[ "$code" -eq 1 ] && [[ "$out" == *"HELD by task-1"* ]] \
+  && ok "2: unexpired lease blocks contender" || no "2: exit $code, out: $out"
 
-# --- Case 3: release by owner succeeds ---
-out=$("$LOCK" release task-1 2>&1); code=$?
-[ "$code" -eq 0 ] && [[ "$out" == *"RELEASED by task-1"* ]] && ok "3: release by owner succeeds" || no "3: exit $code, out: $out"
-
-# --- Case 4: status reports UNLOCKED after release ---
+# --- Case 3: status emits parseable holder/age/remaining fields ---
 out=$("$LOCK" status 2>&1); code=$?
-[ "$code" -eq 0 ] && [[ "$out" == "UNLOCKED" ]] && ok "4: status UNLOCKED after release" || no "4: exit $code, out: $out"
+[ "$code" -eq 0 ] \
+  && [[ "$out" == *"locked=true"* ]] \
+  && [[ "$out" == *"task_id=task-1"* ]] \
+  && [[ "$out" == *"holder=task-1/run-aaa"* ]] \
+  && [[ "$out" == *"age_seconds="* ]] \
+  && [[ "$out" == *"remaining_seconds="* ]] \
+  && ok "3: status has holder/age/remaining fields" || no "3: exit $code, out: $out"
+
+# --- Case 4: refresh extends the lease (holder-only) ---
+# Sleep long enough that integer-second lease math must show decay; a
+# refresh then resets the clock and the remaining lease grows again.
+sleep 3
+just_before=$("$LOCK" status | sed -n 's/^remaining_seconds=//p')
+"$LOCK" refresh task-1 >/dev/null 2>&1; code=$?
+just_after=$("$LOCK" status | sed -n 's/^remaining_seconds=//p')
+[ "$code" -eq 0 ] && [ "$just_after" -gt "$just_before" ] \
+  && ok "4: refresh extends the lease" || no "4: code $code, before $just_before, after $just_after"
+
+# --- Case 5: refresh by non-holder fails ---
+out=$("$LOCK" refresh task-2 2>&1); code=$?
+[ "$code" -eq 1 ] && [[ "$out" == *"held by task-1"* ]] \
+  && ok "5: refresh by non-holder fails" || no "5: exit $code, out: $out"
 
-# --- Case 5: stale lock (dead PID) is reclaimed on acquire ---
-# Write a lock file with a PID that is certainly dead (99999999).
-echo "stale-task 2026-09-10T06:21:15Z 99999999" > "$CREW_REPO/.worktrees/.merge-lock"
-out=$("$LOCK" acquire task-3 22222 2>&1); code=$?
-[ "$code" -eq 0 ] && [[ "$out" == *"reclaimed stale lock from stale-task"* ]] && ok "5: stale lock (dead PID) reclaimed on acquire" || no "5: exit $code, out: $out"
+# --- Case 6: release by non-holder fails ---
+out=$("$LOCK" release task-2 2>&1); code=$?
+[ "$code" -eq 1 ] && [[ "$out" == *"held by task-1"* ]] \
+  && ok "6: release by non-holder fails" || no "6: exit $code, out: $out"
 
-# --- Case 6: after reclaim, the new holder owns the lock ---
+# --- Case 7: release by holder succeeds and removes the lock ---
+out=$("$LOCK" release task-1 2>&1); code=$?
+[ "$code" -eq 0 ] && [[ "$out" == *"RELEASED by task-1"* ]] && [ ! -f "$CREW_REPO/.worktrees/.merge-lock" ] \
+  && ok "7: release by holder removes lock file" || no "7: exit $code, out: $out"
+
+# --- Case 8: status reports UNLOCKED after release ---
 out=$("$LOCK" status 2>&1); code=$?
-[ "$code" -eq 0 ] && [[ "$out" == *"LOCKED by task-3"* ]] && ok "6: reclaimed lock owned by new task" || no "6: exit $code, out: $out"
+[ "$code" -eq 0 ] && [ "$out" = "UNLOCKED" ] \
+  && ok "8: status UNLOCKED after release" || no "8: exit $code, out: $out"
+
+# --- Case 9: expired lease is reclaimed (logged) by a contender ---
+# Write a lock file whose lease expired long ago (epoch 2020, lease 600s).
+printf 'task_id=old-task\nholder=old-task/run-old\nacquired_at=1577836800\nlease_seconds=600\n' \
+  > "$CREW_REPO/.worktrees/.merge-lock"
+out=$("$LOCK" acquire task-3 "task-3/run-ccc" 2>&1); code=$?
+[ "$code" -eq 0 ] && [[ "$out" == *"ACQUIRED by task-3"* ]] && [[ "$out" == *"reclaimed expired lease from old-task"* ]] \
+  && ok "9: expired lease reclaimed by contender" || no "9: exit $code, out: $out"
+[ -f "$TMPBASE/home/.merge-lock.log" ] && grep -q "op=acquire.*result=STALE-BREAK.*previous_task=old-task" "$TMPBASE/home/.merge-lock.log" \
+  && ok "9b: reclaim logged to the audit log" || no "9b: no STALE-BREAK line in audit log"
 
-# --- Case 7: release by non-owner fails ---
-out=$("$LOCK" release wrong-task 2>&1); code=$?
-[ "$code" -eq 1 ] && [[ "$out" == *"ERROR: lock held by task-3"* ]] && ok "7: release by non-owner fails" || no "7: exit $code, out: $out"
+# --- Case 10: malformed lock file is treated as expired and reclaimed ---
+printf 'garbage without any key=value\n' > "$CREW_REPO/.worktrees/.merge-lock"
+out=$("$LOCK" acquire task-4 "task-4/run-ddd" 2>&1); code=$?
+[ "$code" -eq 0 ] && [[ "$out" == *"ACQUIRED by task-4"* ]] \
+  && ok "10: malformed lock reclaimed" || no "10: exit $code, out: $out"
 
-# --- Case 8: release by owner cleans up ---
-out=$("$LOCK" release task-3 2>&1); code=$?
-[ "$code" -eq 0 ] && [ ! -f "$CREW_REPO/.worktrees/.merge-lock" ] && ok "8: release removes lock file" || no "8: exit $code, out: $out"
+# --- Case 11: every op appends to the audit log ---
+lines=$(wc -l < "$TMPBASE/home/.merge-lock.log")
+[ "$lines" -ge 8 ] && ok "11: audit log has $lines lines" || no "11: audit log has only $lines lines"
 
-# --- Case 9: lock with missing PID field is treated as stale ---
-# A lock file with "-" as PID (or empty) should be reclaimable.
-echo "old-task 2026-09-10T06:21:15Z -" > "$CREW_REPO/.worktrees/.merge-lock"
-out=$("$LOCK" acquire task-4 33333 2>&1); code=$?
-[ "$code" -eq 0 ] && [[ "$out" == *"reclaimed stale lock from old-task"* ]] && ok "9: lock with '-' PID reclaimed as stale" || no "9: exit $code, out: $out"
+# --- Case 12: concurrent acquirers serialize — exactly one wins ---
 "$LOCK" release task-4 >/dev/null 2>&1
+for n in $(seq 1 20); do
+  ( "$LOCK" acquire "racer-$n" "racer-$n/run" >/dev/null 2>&1 ) &
+done
+wait
+holder_count=$("$LOCK" status | grep -c '^task_id=racer-' || true)
+[ "$holder_count" -eq 1 ] && ok "12: exactly one concurrent acquirer holds the lock" || no "12: holder_count=$holder_count"
+grep -q "result=ACQUIRED" "$TMPBASE/home/.merge-lock.log" && ok "12b: at least one ACQUIRED logged" || no "12b: no ACQUIRED in audit log"
 
 echo ""
 echo "merge-lock: $pass passed, $fail failed"

package/lib/test-orphan-sweep.sh

@@ -22,6 +22,9 @@ no() { echo "FAIL: $1"; fail=$((fail + 1)); }
 TMPBASE="$(mktemp -d)"
 trap 'rm -rf "$TMPBASE"' EXIT
 
+# Keep merge-lock.sh's audit log out of the real $CREW_HOME during tests.
+export CREW_HOME="$TMPBASE/home"
+
 # new_fixture <name> — fresh git repo, one commit on main; exports CREW_REPO.
 new_fixture() {
   local dir="$TMPBASE/$1"
@@ -90,21 +93,32 @@ echo "$out" | grep -q "→ FAILED" && ok "4: FAILED line printed (no false 'remo
 [ -d .worktrees/T4 ] && ok "4: failed worktree left in place" || no "4: worktree gone despite failed removal"
 git worktree unlock .worktrees/T4 2>/dev/null || true
 
-# --- Case 5: lock path ---
+# --- Case 5: lock path (lease-based; bug 2fc8f52f) ---
 new_fixture case5
 mkdir -p .worktrees
-printf 'T5 2020-01-01T00:00:00Z 999999\n' > .worktrees/.merge-lock
+# 5a: expired lease, no running session → released (logged to the audit log).
+printf 'task_id=T5\nholder=T5/run-old\nacquired_at=1577836800\nlease_seconds=600\n' > .worktrees/.merge-lock
 out=$(CREW_ACTIVE_TASKS="" "$SWEEP" clean 2>&1); code=$?
-[ ! -f .worktrees/.merge-lock ] && ok "5a: stale lock released" || no "5a: stale lock file still present"
-echo "$out" | grep -q "released (dead PID)" && ok "5a: release reported" || no "5a: no release line in output"
+[ ! -f .worktrees/.merge-lock ] && ok "5a: expired-lease lock released" || no "5a: lock file still present"
+echo "$out" | grep -q "STALE_LOCK" && ok "5a: STALE_LOCK line printed" || no "5a: no STALE_LOCK line in output"
+echo "$out" | grep -q "released (lease expired)" && ok "5a: release reported" || no "5a: no release line in output"
 [ "$code" -eq 0 ] && ok "5a: exit 0" || no "5a: exit $code, want 0"
 
-printf '%s 2020-01-01T00:00:00Z 999999\n' "$UUID_LOCK" > .worktrees/.merge-lock
+# 5b: valid lease held by an active run → untouched regardless of lease age.
+now=$(date +%s)
+printf 'task_id=%s\nholder=%s/run-live\nacquired_at=%s\nlease_seconds=600\n' "$UUID_LOCK" "$UUID_LOCK" "$now" > .worktrees/.merge-lock
 out=$(CREW_ACTIVE_TASKS="$UUID_LOCK" "$SWEEP" clean 2>&1); code=$?
 [ -f .worktrees/.merge-lock ] && ok "5b: active holder's lock not released" || no "5b: active holder's lock was released"
 echo "$out" | grep -q "ACTIVE_LOCK" && ok "5b: ACTIVE_LOCK line printed" || no "5b: no ACTIVE_LOCK line in output"
 [ "$code" -eq 0 ] && ok "5b: exit 0" || no "5b: exit $code, want 0"
 
+# 5c: valid lease, no running session → held, NOT released (lease not expired).
+printf 'task_id=T6\nholder=T6/run-live\nacquired_at=%s\nlease_seconds=600\n' "$now" > .worktrees/.merge-lock
+out=$(CREW_ACTIVE_TASKS="" "$SWEEP" clean 2>&1); code=$?
+[ -f .worktrees/.merge-lock ] && ok "5c: unexpired-lease lock not released" || no "5c: unexpired-lease lock was released"
+echo "$out" | grep -q "HELD_LOCK" && ok "5c: HELD_LOCK line printed" || no "5c: no HELD_LOCK line in output"
+[ "$code" -eq 0 ] && ok "5c: exit 0" || no "5c: exit $code, want 0"
+
 # --- Case 6: report mode without active data ---
 new_fixture case6
 merged_worktree T7