muse-crew 0.4.6 → 0.5.0

package/docs/guide.md

@@ -57,7 +57,7 @@ Required arguments:
 Optional arguments:
 - `dashboardName` — display name for the project registration (default: `"Muse Crew"`).
 - `cronId` — polling cron identifier (default: `"crew-poll"`).
-- `sweepCronId` — orphan sweep cron identifier (default: `"crew-sweep"`).
+- `sweepCronId` — orphan sweep cron identifier (default: `"crew-orphan-sweep"`).
 
 ### What init creates
 

package/lib/AGENTS.md

@@ -5,10 +5,11 @@ 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: 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.
+- `worktree-lifecycle.sh` — the worktree lifecycle seam: prepare/cleanup/inspect/integrate/status/post-deploy/refresh-lock/lock-status 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. `lock-status` reports the merge-lock state explicitly (`UNLOCKED`, or `LOCKED by <holder> since <ts> (pid <pid>)`, always exit 0) so Publish can distinguish an empty-diff Integrate (no lock taken) from a refresh failure.
 - `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)
+- `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)
 - `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
+- `test-publish-skip.sh` — regression tests for the no-lock graceful publish skip (park 2026-09-11): `lock-status` returns exact `UNLOCKED`/`LOCKED by <holder> since <ts> (pid <pid>)`; a fake empty-diff integrate takes the MERGED_EMPTY branch and never takes the lock; the shipped step-5 block from publish-npm.sh (extracted by anchor) skips gracefully on UNLOCKED (no park, no `PUBLISH_COMPLETE`), follows the refresh path when a lock is held, and fails closed on a `lock-status` query failure; the gate sits inside the ALREADY_PUBLISHED=0 branch and mutation steps are gated on NO_LOCK_HELD=0
 - `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.

package/lib/publish-npm.sh

@@ -23,6 +23,9 @@
 # On success: print the markers below, exit 0. The final marker is
 # PUBLISH_COMPLETE=<version> — the Publish agent pastes it verbatim into its
 # summary as the script's completion marker.
+# When no merge lock is held (empty-diff Integrate), the publish path is
+# skipped gracefully: PUBLISH_SKIPPED=no-lock-held is printed, no version
+# is written or published, and PUBLISH_COMPLETE is omitted.
 
 set -euo pipefail
 
@@ -65,113 +68,133 @@ if { [ "$HEAD_MSG" = "release: $PKG@$TARGET_VERSION ($TASK_ID)" ] \
   echo "PUBLISH_VERIFIED=$TARGET_VERSION"
 fi
 
+NO_LOCK_HELD=0
 if [ "$ALREADY_PUBLISHED" = "0" ]; then
-  # 5. Refresh the merge lock (held from Integrate through post-deploy).
-  LOCK_OUT="$(CREW_REPO="$REPO_PATH" bash "${LIFECYCLE:?LIFECYCLE is required}" refresh-lock "$TASK_ID" 2>&1)" \
-    || fail "lock-refresh" "$LOCK_OUT"
-
-  # 6. Install/activate the immutable release.
-  REL_OUT="$(bash "${RELEASE_SCRIPT:?RELEASE_SCRIPT is required}" deploy "$REPO_PATH" 2>&1)" \
-    || fail "release-deploy" "$REL_OUT"
-  case "$REL_OUT" in
-    *INSTALLED*ACTIVATED*|*EXISTS*ACTIVATED*) ;;
-    *) fail "release-deploy" "unexpected output: $REL_OUT" ;;
-  esac
-
-  # 7. Read the old version (audit only — TARGET_VERSION stays authoritative).
-  OLD="$(git -C "$REPO_PATH" show "HEAD:package.json" \
-    | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).version")" \
-    || fail "read-base" "could not read version from HEAD:package.json"
-  echo "PUBLISH_BASE=$OLD"
-
-  # 8. Write TARGET_VERSION into package.json (`version` field only) via
-  # byte-preserving text substitution. A JSON.parse/stringify round-trip is
-  # forbidden here: it expands unicode escapes (e.g. the \u2014 escape in
-  # the description field) into literal characters, producing a two-line
-  # diff that trips the preservation check below (canary 5a027278). The
-  # substitution touches exactly one line; a missed substitution yields an
-  # empty diff and fails closed at the numstat check.
-  # STEP-8-ANCHOR: version write (escape-preserving)
-  PKG_JSON="$REPO_PATH/package.json"
-  ESCAPED_VER="$(printf '%s' "$TARGET_VERSION" | sed 's/[&\\]/\\&/g')"
-  sed -i -E 's/^([[:space:]]*"version"[[:space:]]*:[[:space:]]*)"[^"]*"/\1"'"$ESCAPED_VER"'"/' "$PKG_JSON" \
-    || fail "version-write" "sed could not write $TARGET_VERSION into package.json"
-  # Read-only verification: parse package.json and confirm .version equals
-  # TARGET_VERSION. (Parse only — no rewrite, so no clock/randomness.)
-  NEW_VER="$(PKG_JSON="$PKG_JSON" node -p "JSON.parse(require('fs').readFileSync(process.env.PKG_JSON,'utf8')).version")" \
-    || fail "version-write" "could not parse package.json after write"
-  [ "$NEW_VER" = "$TARGET_VERSION" ] \
-    || fail "version-write" "package.json version is $NEW_VER, expected $TARGET_VERSION"
-  echo "PUBLISH_DIFF:"
-  git -C "$REPO_PATH" diff -- package.json
-  ADD_DEL="$(git -C "$REPO_PATH" diff --numstat -- package.json | tr '\t' ' ')"
-  [ "$ADD_DEL" = "1 1 package.json" ] \
-    || fail "version-diff" "expected a single-line version change, got: $ADD_DEL"
-  # STEP-8-END
-
-  # 9. Commit only if changed (retried run leaves the commit in place).
-  if git -C "$REPO_PATH" diff --quiet -- package.json; then
-    echo "PUBLISH_COMMIT_EXISTS"
+  # STEP-5-ANCHOR: lock-state gate (empty-diff Integrate takes no lock).
+  # An empty-diff Integrate (MERGED_EMPTY) intentionally takes no merge
+  # lock: nothing merged, nothing to ship. When no lock is held, Publish
+  # skips the publish path gracefully instead of failing closed on
+  # refresh-lock (park 2026-09-11). UNLOCKED is explicit state, not prose.
+  # The anchor sits inside the ALREADY_PUBLISHED=0 branch, so the skip
+  # marker prints only on a genuinely unheld lock — a resumed run whose
+  # post-deploy already released the lock prints nothing here; its
+  # PUBLISHED_ALREADY/PUBLISH_VERIFIED markers already say it all.
+  LOCK_STATE="$(CREW_REPO="$REPO_PATH" bash "${LIFECYCLE:?LIFECYCLE is required}" lock-status "$TASK_ID" 2>&1)" \
+    || fail "lock-status" "$LOCK_STATE"
+  if [ "$LOCK_STATE" = "UNLOCKED" ]; then
+    NO_LOCK_HELD=1
+    echo "PUBLISH_SKIPPED=no-lock-held"
   else
-    git -C "$REPO_PATH" add package.json \
-      || fail "commit" "git add package.json failed"
-    git -C "$REPO_PATH" commit -m "release: $PKG@$TARGET_VERSION ($TASK_ID)" >/dev/null \
-      || fail "commit" "git commit failed"
-    echo "PUBLISH_COMMIT=$(git -C "$REPO_PATH" rev-parse HEAD)"
+    # 5b. Refresh the merge lock (held from Integrate through post-deploy).
+    LOCK_OUT="$(CREW_REPO="$REPO_PATH" bash "${LIFECYCLE:?LIFECYCLE is required}" refresh-lock "$TASK_ID" 2>&1)" \
+      || fail "lock-refresh" "$LOCK_OUT"
   fi
-
-  # 10. Pack and sanity-check the tarball's embedded version.
-  cd "$REPO_PATH" || fail "pack" "cannot cd to $REPO_PATH"
-  npm pack >/dev/null 2>&1 || fail "pack" "npm pack failed"
-  TGZ="$REPO_PATH/$PKG-$TARGET_VERSION.tgz"
-  [ -f "$TGZ" ] || fail "pack" "expected tarball $TGZ not produced"
-  TGZ_VER="$(tar -xzOf "$TGZ" package/package.json \
-    | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).version")" \
-    || fail "pack-version-mismatch" "could not read version from tarball $TGZ"
-  [ "$TGZ_VER" = "$TARGET_VERSION" ] \
-    || fail "pack-version-mismatch" "tarball has $TGZ_VER, expected $TARGET_VERSION"
-
-  # 11. Publish. "previously published versions" means a retried Publish
-  # already landed this version (the merge lock guarantees no other task
-  # picked it) — continue. Any other failure is fatal.
-  if PUB_OUT="$(python3 "$NPM_PUBLISH_PY" "$TGZ" 2>&1)"; then
-    echo "PUBLISHED=$TARGET_VERSION"
-  else
-    case "$PUB_OUT" in
-      *"previously published versions"*)
-        echo "PUBLISHED_ALREADY=$TARGET_VERSION"
-        ;;
-      *)
-        rm -f "$TGZ"
-        fail "publish" "$(printf '%s\n' "$PUB_OUT" | tail -5)"
-        ;;
+  # STEP-5-END
+
+    if [ "$NO_LOCK_HELD" = "0" ]; then
+    # 6. Install/activate the immutable release.
+    REL_OUT="$(bash "${RELEASE_SCRIPT:?RELEASE_SCRIPT is required}" deploy "$REPO_PATH" 2>&1)" \
+      || fail "release-deploy" "$REL_OUT"
+    case "$REL_OUT" in
+      *INSTALLED*ACTIVATED*|*EXISTS*ACTIVATED*) ;;
+      *) fail "release-deploy" "unexpected output: $REL_OUT" ;;
     esac
-  fi
-  rm -f "$TGZ"
-
-  # 12. Verify: ground truth is the registry, not any agent's summary.
-  # 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 after $VERIFY_ATTEMPTS attempts"
-  echo "PUBLISH_VERIFIED=$TARGET_VERSION"
-  # STEP-12-END
+
+    # 7. Read the old version (audit only — TARGET_VERSION stays authoritative).
+    OLD="$(git -C "$REPO_PATH" show "HEAD:package.json" \
+      | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).version")" \
+      || fail "read-base" "could not read version from HEAD:package.json"
+    echo "PUBLISH_BASE=$OLD"
+
+    # 8. Write TARGET_VERSION into package.json (`version` field only) via
+    # byte-preserving text substitution. A JSON.parse/stringify round-trip is
+    # forbidden here: it expands unicode escapes (e.g. the \u2014 escape in
+    # the description field) into literal characters, producing a two-line
+    # diff that trips the preservation check below (canary 5a027278). The
+    # substitution touches exactly one line; a missed substitution yields an
+    # empty diff and fails closed at the numstat check.
+    # STEP-8-ANCHOR: version write (escape-preserving)
+    PKG_JSON="$REPO_PATH/package.json"
+    ESCAPED_VER="$(printf '%s' "$TARGET_VERSION" | sed 's/[&\\]/\\&/g')"
+    sed -i -E 's/^([[:space:]]*"version"[[:space:]]*:[[:space:]]*)"[^"]*"/\1"'"$ESCAPED_VER"'"/' "$PKG_JSON" \
+      || fail "version-write" "sed could not write $TARGET_VERSION into package.json"
+    # Read-only verification: parse package.json and confirm .version equals
+    # TARGET_VERSION. (Parse only — no rewrite, so no clock/randomness.)
+    NEW_VER="$(PKG_JSON="$PKG_JSON" node -p "JSON.parse(require('fs').readFileSync(process.env.PKG_JSON,'utf8')).version")" \
+      || fail "version-write" "could not parse package.json after write"
+    [ "$NEW_VER" = "$TARGET_VERSION" ] \
+      || fail "version-write" "package.json version is $NEW_VER, expected $TARGET_VERSION"
+    echo "PUBLISH_DIFF:"
+    git -C "$REPO_PATH" diff -- package.json
+    ADD_DEL="$(git -C "$REPO_PATH" diff --numstat -- package.json | tr '\t' ' ')"
+    [ "$ADD_DEL" = "1 1 package.json" ] \
+      || fail "version-diff" "expected a single-line version change, got: $ADD_DEL"
+    # STEP-8-END
+
+    # 9. Commit only if changed (retried run leaves the commit in place).
+    if git -C "$REPO_PATH" diff --quiet -- package.json; then
+      echo "PUBLISH_COMMIT_EXISTS"
+    else
+      git -C "$REPO_PATH" add package.json \
+        || fail "commit" "git add package.json failed"
+      git -C "$REPO_PATH" commit -m "release: $PKG@$TARGET_VERSION ($TASK_ID)" >/dev/null \
+        || fail "commit" "git commit failed"
+      echo "PUBLISH_COMMIT=$(git -C "$REPO_PATH" rev-parse HEAD)"
+    fi
+
+    # 10. Pack and sanity-check the tarball's embedded version.
+    cd "$REPO_PATH" || fail "pack" "cannot cd to $REPO_PATH"
+    npm pack >/dev/null 2>&1 || fail "pack" "npm pack failed"
+    TGZ="$REPO_PATH/$PKG-$TARGET_VERSION.tgz"
+    [ -f "$TGZ" ] || fail "pack" "expected tarball $TGZ not produced"
+    TGZ_VER="$(tar -xzOf "$TGZ" package/package.json \
+      | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).version")" \
+      || fail "pack-version-mismatch" "could not read version from tarball $TGZ"
+    [ "$TGZ_VER" = "$TARGET_VERSION" ] \
+      || fail "pack-version-mismatch" "tarball has $TGZ_VER, expected $TARGET_VERSION"
+
+    # 11. Publish. "previously published versions" means a retried Publish
+    # already landed this version (the merge lock guarantees no other task
+    # picked it) — continue. Any other failure is fatal.
+    if PUB_OUT="$(python3 "$NPM_PUBLISH_PY" "$TGZ" 2>&1)"; then
+      echo "PUBLISHED=$TARGET_VERSION"
+    else
+      case "$PUB_OUT" in
+        *"previously published versions"*)
+          echo "PUBLISHED_ALREADY=$TARGET_VERSION"
+          ;;
+        *)
+          rm -f "$TGZ"
+          fail "publish" "$(printf '%s\n' "$PUB_OUT" | tail -5)"
+          ;;
+      esac
+    fi
+    rm -f "$TGZ"
+
+    # 12. Verify: ground truth is the registry, not any agent's summary.
+    # 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 after $VERIFY_ATTEMPTS attempts"
+    echo "PUBLISH_VERIFIED=$TARGET_VERSION"
+    # STEP-12-END
+  fi  # NO_LOCK_HELD=0: skip the mutation path when no lock is held
 fi
 
 # 12b. Refresh the merge lock again — release-deploy, pack, publish, and the
@@ -195,5 +218,10 @@ case "$FIN_OUT" in
   *) fail "post-deploy" "missing DEPLOYED marker: $FIN_OUT" ;;
 esac
 
-# Final marker: the full publish path completed.
-echo "PUBLISH_COMPLETE=$TARGET_VERSION"
+# Final marker. On the skip path (no lock held) there was nothing to
+# publish: PUBLISH_SKIPPED=no-lock-held is the completion marker and
+# PUBLISH_COMPLETE is deliberately not printed — the phase completed,
+# the publish did not happen.
+if [ "$NO_LOCK_HELD" = "0" ]; then
+  echo "PUBLISH_COMPLETE=$TARGET_VERSION"
+fi

package/lib/test-publish-skip.sh

@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+# test-publish-skip.sh — regression test for the graceful no-lock publish
+# skip (park 2026-09-11: empty-diff Integrate takes no merge lock, but
+# Publish ran refresh-lock unconditionally and failed closed).
+#
+# Covers:
+#   - worktree-lifecycle.sh lock-status: UNLOCKED (exit 0) with no lock;
+#     LOCKED by <holder> since <ts> (pid <pid>) when held (exit 0).
+#   - fake empty-diff integrate -> lock-status reports UNLOCKED (the lock
+#     is intentionally never taken on the MERGED_EMPTY path).
+#   - the shipped step-5 block of publish-npm.sh (extracted by anchor):
+#       * UNLOCKED -> NO_LOCK_HELD=1, PUBLISH_SKIPPED=no-lock-held, exit 0
+#       * LOCKED (self) -> refresh path runs, NO_LOCK_HELD=0, exit 0
+#       * lock-status query failure -> fail "lock-status", exit 1 (fail-closed)
+#   - structural: the step-5 anchor sits inside the ALREADY_PUBLISHED=0
+#     branch (a resumed run whose post-deploy released the lock prints
+#     nothing), and the mutation steps are gated on NO_LOCK_HELD=0.
+#
+# Anchors: `# STEP-5-ANCHOR` ... `# STEP-5-END` in lib/publish-npm.sh.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIFECYCLE="$SCRIPT_DIR/worktree-lifecycle.sh"
+MERGE_LOCK="$SCRIPT_DIR/merge-lock.sh"
+PUBLISH="$SCRIPT_DIR/publish-npm.sh"
+
+pass=0
+fail_count=0
+ok() { echo "PASS: $1"; pass=$((pass + 1)); }
+no() { echo "FAIL: $1"; fail_count=$((fail_count + 1)); }
+
+TMPBASE="$(mktemp -d)"
+trap 'rm -rf "$TMPBASE"' EXIT
+
+# --- Scratch repo ---
+SCRATCH="$TMPBASE/repo"
+git init -q -b main "$SCRATCH"
+git -C "$SCRATCH" config user.email "test@crew"
+git -C "$SCRATCH" config user.name "crew-test"
+echo ".worktrees/" > "$SCRATCH/.gitignore"
+echo x > "$SCRATCH/f.txt"
+git -C "$SCRATCH" add -A && git -C "$SCRATCH" commit -qm init
+
+export CREW_REPO="$SCRATCH" CREW_LIB="$SCRIPT_DIR"
+
+TASK="skiptest-task-1"
+
+# --- lock-status with no lock held ---
+OUT="$(bash "$LIFECYCLE" lock-status "$TASK" 2>&1)"
+CODE=$?
+if [ $CODE -eq 0 ] && [ "$OUT" = "UNLOCKED" ]; then
+  ok "lock-status reports UNLOCKED with no lock held (exit 0)"
+else
+  no "lock-status UNLOCKED: code=$CODE out='$OUT'"
+fi
+
+# --- lock-status with a lock held ---
+bash "$MERGE_LOCK" acquire "$TASK" "$$" >/dev/null
+OUT="$(bash "$LIFECYCLE" lock-status "$TASK" 2>&1)"
+CODE=$?
+if [ $CODE -eq 0 ] && printf '%s' "$OUT" | grep -Eq "^LOCKED by $TASK since .+ \(pid [0-9]+\)$"; then
+  ok "lock-status reports LOCKED by <holder> since <ts> (pid <pid>) (exit 0)"
+else
+  no "lock-status LOCKED: code=$CODE out='$OUT'"
+fi
+bash "$MERGE_LOCK" release "$TASK" >/dev/null
+
+# --- fake empty-diff integrate: MERGED_EMPTY takes no lock ---
+bash "$LIFECYCLE" prepare "$TASK" >/dev/null 2>&1
+INTEG="$(bash "$LIFECYCLE" integrate "$TASK" "merge: $TASK" 2>&1)"
+if [[ "$INTEG" == MERGED_EMPTY* ]]; then
+  ok "fake empty-diff integrate takes the MERGED_EMPTY branch"
+else
+  no "empty-diff integrate: '$INTEG'"
+fi
+OUT="$(bash "$LIFECYCLE" lock-status "$TASK" 2>&1)"
+if [ "$OUT" = "UNLOCKED" ]; then
+  ok "after MERGED_EMPTY integrate the lock is still UNLOCKED (never taken)"
+else
+  no "lock held after empty-diff integrate: '$OUT'"
+fi
+bash "$LIFECYCLE" cleanup "$TASK" >/dev/null 2>&1
+
+# --- Extract the shipped step-5 block by anchor ---
+BLOCK="$TMPBASE/step5.sh"
+sed -n '/# STEP-5-ANCHOR/,/# STEP-5-END/p' "$PUBLISH" > "$BLOCK"
+if grep -q 'lock-status' "$BLOCK" && grep -q 'PUBLISH_SKIPPED=no-lock-held' "$BLOCK" \
+   && grep -q 'fail "lock-status"' "$BLOCK" && grep -q 'NO_LOCK_HELD=1' "$BLOCK"; then
+  ok "extracted step-5 block from publish-npm.sh"
+else
+  no "step-5 extraction failed (anchors missing)"
+fi
+
+# Runner: provides fail(), env, sources the extracted block, then reports
+# NO_LOCK_HELD and the exit code. Never calls fail = never parks.
+run_block() { # run_block <lock_setup: none|held|broken>
+  local mode="$1"
+  local run="$TMPBASE/run-$mode"
+  mkdir -p "$run"
+  case "$mode" in
+    none) : ;;
+    held) bash "$MERGE_LOCK" acquire "$TASK" "$$" >/dev/null ;;
+    broken) : ;;
+  esac
+  (
+    set -euo pipefail
+    export CREW_REPO="$SCRATCH" TASK_ID="$TASK" REPO_PATH="$SCRATCH"
+    if [ "$mode" = "broken" ]; then
+      export LIFECYCLE="/nonexistent/lifecycle.sh"
+    else
+      export LIFECYCLE="$LIFECYCLE"
+    fi
+    fail() { echo "PUBLISH_FAILED=$1"; [ $# -ge 2 ] && echo "$2"; exit 1; }
+    NO_LOCK_HELD=0
+    # shellcheck disable=SC1090
+    source "$BLOCK"
+    echo "RESULT_NO_LOCK_HELD=$NO_LOCK_HELD"
+  ) > "$run/out" 2>&1
+  local code=$?
+  echo "$code" > "$run/code"
+  case "$mode" in
+    held) bash "$MERGE_LOCK" release "$TASK" >/dev/null 2>&1 || true ;;
+  esac
+}
+
+# --- UNLOCKED: skip gracefully, never park ---
+run_block none
+CODE="$(cat "$TMPBASE/run-none/code")"
+OUT="$(cat "$TMPBASE/run-none/out")"
+if [ "$CODE" -eq 0 ] && [[ "$OUT" == *"PUBLISH_SKIPPED=no-lock-held"* ]] \
+   && [[ "$OUT" == *"RESULT_NO_LOCK_HELD=1"* ]] && [[ "$OUT" != *"PUBLISH_FAILED"* ]]; then
+  ok "step-5 on UNLOCKED: skips gracefully (NO_LOCK_HELD=1, marker printed, exit 0)"
+else
+  no "step-5 UNLOCKED: code=$CODE out='$OUT'"
+fi
+
+# --- LOCKED by self: refresh path runs, no skip ---
+run_block held
+CODE="$(cat "$TMPBASE/run-held/code")"
+OUT="$(cat "$TMPBASE/run-held/out")"
+if [ "$CODE" -eq 0 ] && [[ "$OUT" != *"PUBLISH_SKIPPED"* ]] \
+   && [[ "$OUT" == *"RESULT_NO_LOCK_HELD=0"* ]] && [[ "$OUT" != *"PUBLISH_FAILED"* ]]; then
+  ok "step-5 on LOCKED (self): refresh path runs, no skip marker, exit 0"
+else
+  no "step-5 LOCKED: code=$CODE out='$OUT'"
+fi
+
+# --- lock-status query failure: fail closed ---
+run_block broken
+CODE="$(cat "$TMPBASE/run-broken/code")"
+OUT="$(cat "$TMPBASE/run-broken/out")"
+if [ "$CODE" -ne 0 ] && [[ "$OUT" == *"PUBLISH_FAILED=lock-status"* ]]; then
+  ok "step-5 on lock-status failure: fail-closed PUBLISH_FAILED=lock-status"
+else
+  no "step-5 broken query: code=$CODE out='$OUT'"
+fi
+
+# --- Structural: the gate sits inside the ALREADY_PUBLISHED=0 branch ---
+# (a resumed run whose post-deploy already released the lock must print
+# nothing — its PUBLISHED_ALREADY/PUBLISH_VERIFIED markers say it all).
+AP_LINE="$(grep -n 'if \[ "\$ALREADY_PUBLISHED" = "0" \]; then' "$PUBLISH" | head -1 | cut -d: -f1)"
+ANCHOR_LINE="$(grep -n '# STEP-5-ANCHOR' "$PUBLISH" | head -1 | cut -d: -f1)"
+END_LINE="$(grep -n '# STEP-5-END' "$PUBLISH" | head -1 | cut -d: -f1)"
+if [ -n "$AP_LINE" ] && [ -n "$ANCHOR_LINE" ] && [ -n "$END_LINE" ] \
+   && [ "$AP_LINE" -lt "$ANCHOR_LINE" ] && [ "$ANCHOR_LINE" -lt "$END_LINE" ]; then
+  ok "step-5 anchor sits inside the ALREADY_PUBLISHED=0 branch"
+else
+  no "step-5 anchor placement wrong (ap=$AP_LINE anchor=$ANCHOR_LINE end=$END_LINE)"
+fi
+
+# --- Structural: mutation steps are gated on NO_LOCK_HELD=0 ---
+if grep -q 'if \[ "\$NO_LOCK_HELD" = "0" \]; then' "$PUBLISH" \
+   && grep -q 'fi  # NO_LOCK_HELD=0' "$PUBLISH"; then
+  ok "mutation path is gated on NO_LOCK_HELD=0"
+else
+  no "NO_LOCK_HELD gate missing in publish-npm.sh"
+fi
+
+# --- Structural: PUBLISH_COMPLETE is omitted on the skip path ---
+if grep -q 'PUBLISH_COMPLETE is deliberately not printed' "$PUBLISH"; then
+  ok "skip path omits PUBLISH_COMPLETE (no false publish claim)"
+else
+  no "PUBLISH_COMPLETE skip-path handling missing"
+fi
+
+bash -n "$LIFECYCLE" && ok "worktree-lifecycle.sh syntax OK" || no "worktree-lifecycle.sh syntax"
+bash -n "$PUBLISH" && ok "publish-npm.sh syntax OK" || no "publish-npm.sh syntax"
+
+echo ""
+echo "$pass passed, $fail_count failed"
+exit $((fail_count > 0))

package/lib/worktree-lifecycle.sh

@@ -19,6 +19,7 @@
 #   cleanup   <task_id>                  — remove worktree + branch (no lock)
 #   status    <task_id>                  — report worktree state
 #   refresh-lock <task_id>               — refresh merge lock timestamp (resets staleness clock)
+#   lock-status <task_id>                — report merge lock state: UNLOCKED or LOCKED by <holder> since <ts> (pid <pid>)
 #   sweep     [report|clean]             — find/clean orphans + stale locks
 #
 # Exit codes:
@@ -367,6 +368,16 @@ cmd_refresh_lock() {
   "$MERGE_LOCK" refresh "$task_id"
 }
 
+cmd_lock_status() {
+  local task_id="$1"
+  validate_task_id "$task_id"
+  # Passthrough to the lock's own status readout. Scripts never call
+  # merge-lock.sh directly — this keeps the seam. Always exits 0:
+  # UNLOCKED is explicit state (an empty-diff Integrate intentionally
+  # takes no lock), never an error.
+  "$MERGE_LOCK" status
+}
+
 # --- dispatch ---
 
 cmd="${1:-}"
@@ -381,10 +392,11 @@ case "$cmd" in
   cleanup)      cmd_cleanup "${1:?task_id required}" ;;
   status)       cmd_status "${1:?task_id required}" ;;
   refresh-lock) cmd_refresh_lock "${1:?task_id required}" ;;
+  lock-status)  cmd_lock_status "${1:?task_id required}" ;;
   sweep)        cmd_sweep "${1:-report}" ;;
   *)
     echo "Usage: worktree-lifecycle.sh <command> [args]"
-    echo "Commands: validate, prepare, inspect, integrate, post-deploy, cleanup, status, refresh-lock, sweep"
+    echo "Commands: validate, prepare, inspect, integrate, post-deploy, cleanup, status, refresh-lock, lock-status, sweep"
     exit 1
     ;;
 esac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muse-crew",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "description": "Opinionated orchestration for Muse \u2014 workflows, identities, and tooling for autonomous software development.",
   "license": "UNLICENSED",
   "private": false,

package/seed/AGENTS.md

@@ -3,6 +3,7 @@
 Init source data. Everything `crew-init.js` reads when setting up a new crew instance on a Muse account.
 
 - `cron-body-template.md` — template for creating the dispatch cron job
+- `cron-sweep-body-template.md` — template for creating the orphan-sweep cron job
 - `posture.md` — PM posture that shapes the user's assistant for crew interaction
 - `feedback/` — feedback feature placeholder
 - `workflows/` — human-readable workflow definitions, copied to `$CREW_HOME/.orchestration/workflows/` during init

package/seed/cron-sweep-body-template.md

@@ -0,0 +1,11 @@
+## Muse Crew Orphan Sweep
+
+1. Call artifact_invoke_action on slug "{dashboardSlug}", action "getdispatchstate", args {}.
+2. From the response, extract the `id` field of each `ready_tasks` entry whose
+   latest_session.status is "running", verbatim — copy the full ID exactly
+   as it appears; do not shorten, truncate, or reformat it. Return them as a
+   JSON array of strings. Do NOT reproduce any other part of the response.
+   (Sessions older than 1h are already reclassified as timed_out by the dashboard — no extra math.)
+3. Run: CREW_ACTIVE_TASKS="<space-separated ids>" {crewHome}/lib/orphan-sweep.sh clean
+   If the list is empty, pass an empty string — do NOT omit the variable (the sweep fails closed without it).
+4. Report the output. If it says CLEAN, no action was needed.