muse-crew 0.4.2 → 0.4.4

package/lib/compose-evidence.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""compose-evidence.py — deterministic visual-evidence compositor.
+
+Usage:
+    python3 lib/compose-evidence.py <baseline-dir> <postchange-dir> <composites-dir>
+
+Pairs PNG captures with identical file stems from the baseline and
+post-change evidence directories and emits two composites per pair into
+the composites directory:
+
+    <stem>-sidebyside.png   baseline | postchange, side by side with a divider
+    <stem>-overlay.png      amplified absolute-difference image
+
+Stdout is machine-readable: one `PAIR <stem> -> ...` line per composite
+pair, one `SKIP <stem> (<reason>)` line per stem that has no counterpart.
+
+Determinism contract: no timestamps, no randomness, no network. Same
+inputs always produce byte-identical outputs. Exit code is nonzero on
+errors (bad arguments, missing directories, unreadable images).
+
+Requires Pillow (PIL).
+"""
+
+import os
+import sys
+
+try:
+    from PIL import Image, ImageChops
+except ImportError:
+    Image = None
+    ImageChops = None
+
+DIVIDER_PX = 2
+BACKGROUND = (240, 240, 240)
+DIVIDER_COLOR = (32, 32, 32)
+# Difference amplification factor: |a-b| * k, clipped to 255. Fixed at 4 —
+# enough to make sub-perceptual pixel shifts visible, deterministic.
+DIFF_AMPLIFY = 4
+
+
+def fail(msg):
+    print("ERROR: " + msg, file=sys.stderr)
+    sys.exit(1)
+
+
+def main():
+    if len(sys.argv) != 4:
+        fail("usage: compose-evidence.py <baseline-dir> <postchange-dir> <composites-dir>")
+    baseline_dir, postchange_dir, composites_dir = sys.argv[1:4]
+    for label, d in (("baseline", baseline_dir), ("postchange", postchange_dir)):
+        if not os.path.isdir(d):
+            fail(label + " dir is not a directory: " + d)
+    try:
+        os.makedirs(composites_dir, exist_ok=True)
+    except OSError as e:
+        fail("cannot create composites dir " + composites_dir + ": " + e)
+
+    if Image is None or ImageChops is None:
+        fail("Pillow (PIL) is required but not installed")
+
+    def stems(d):
+        out = []
+        for name in os.listdir(d):
+            if name.lower().endswith(".png"):
+                full = os.path.join(d, name)
+                if os.path.isfile(full):
+                    out.append(name[:-4])
+        return sorted(out)
+
+    base_stems = stems(baseline_dir)
+    post_stems = stems(postchange_dir)
+    post_set = set(post_stems)
+
+    exit_code = 0
+
+    def load(d, stem):
+        return Image.open(os.path.join(d, stem + ".png")).convert("RGB")
+
+    for stem in base_stems:
+        if stem not in post_set:
+            print("SKIP " + stem + " (only in baseline)")
+            continue
+        try:
+            base = load(baseline_dir, stem)
+            post = load(postchange_dir, stem)
+        except Exception as e:
+            print("ERROR: cannot read pair " + stem + ": " + str(e), file=sys.stderr)
+            exit_code = 1
+            continue
+        try:
+            sidebyside = make_sidebyside(base, post)
+            side_name = stem + "-sidebyside.png"
+            sidebyside.save(os.path.join(composites_dir, side_name), format="PNG")
+
+            overlay = make_overlay(base, post)
+            over_name = stem + "-overlay.png"
+            overlay.save(os.path.join(composites_dir, over_name), format="PNG")
+        except Exception as e:
+            print("ERROR: cannot compose pair " + stem + ": " + str(e), file=sys.stderr)
+            exit_code = 1
+            continue
+        print("PAIR " + stem + " -> " + side_name + " " + over_name)
+
+    for stem in post_stems:
+        if stem not in set(base_stems):
+            print("SKIP " + stem + " (only in postchange)")
+
+    return exit_code
+
+
+def pad_to(image, width, height):
+    """Return image pasted top-left on a BACKGROUND canvas of (width, height)."""
+    canvas = Image.new("RGB", (width, height), BACKGROUND)
+    canvas.paste(image, (0, 0))
+    return canvas
+
+
+def make_sidebyside(base, post):
+    """Baseline left, post-change right, separated by a divider column."""
+    height = max(base.height, post.height)
+    base_p = pad_to(base, base.width, height)
+    post_p = pad_to(post, post.width, height)
+    total = base_p.width + DIVIDER_PX + post_p.width
+    canvas = Image.new("RGB", (total, height), BACKGROUND)
+    canvas.paste(base_p, (0, 0))
+    divider = Image.new("RGB", (DIVIDER_PX, height), DIVIDER_COLOR)
+    canvas.paste(divider, (base_p.width, 0))
+    canvas.paste(post_p, (base_p.width + DIVIDER_PX, 0))
+    return canvas
+
+
+def make_overlay(base, post):
+    """Amplified absolute per-channel difference; identical pixels stay black."""
+    width = max(base.width, post.width)
+    height = max(base.height, post.height)
+    base_p = pad_to(base, width, height)
+    post_p = pad_to(post, width, height)
+    diff = ImageChops.difference(base_p, post_p)
+    # Fixed amplification, clipped — deterministic and byte-stable.
+    return diff.point(lambda v: v * DIFF_AMPLIFY if v * DIFF_AMPLIFY < 255 else 255)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/lib/crew-release.sh

@@ -15,7 +15,8 @@
 #                                    # release on every deploy/rollback
 #
 # The Muse workflow runtime snapshots .js scripts at launch.
-# /tmp/crew-lib-* pins lifecycle scripts per run.
+# $CREW_HOME/.pins/<task> pins lifecycle scripts per run (persistent disk —
+# /tmp is tmpfs and cell reboots wipe it mid-run).
 # The merge lock serializes deploys at the integration step.
 # This script handles only: atomic activation, version identity, rollback.
 #
@@ -171,6 +172,13 @@ cmd_deploy() {
         cp -r seed/workflows "$staging_dir/seed/"
       fi
     fi
+    # Build the static workflow registry from the workflow files' meta blocks.
+    # The workflow files remain the single source of truth; registry.json is a
+    # generated build artifact and must never be hand-edited.
+    if ! node "$staging_dir/lib/build-registry.js" "$staging_dir/workflows" "$staging_dir/workflows/registry.json"; then
+      rm -rf "$staging_dir"
+      die "release $hash rejected: registry build failed"
+    fi
     # Gate: refuse to install a release whose workflow scripts don't parse.
     if ! _validate_workflows "$staging_dir"; then
       rm -rf "$staging_dir"

package/lib/merge-lock.sh

@@ -27,6 +27,24 @@ case "$cmd" in
       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
       echo "HELD by $holder since $acquired_at (pid $lock_pid)"
       exit 1
     fi

package/lib/orphan-sweep.sh

@@ -1,19 +1,33 @@
 #!/usr/bin/env bash
-# orphan-sweep.sh — find and clean orphaned worktrees + stale merge locks
+# orphan-sweep.sh — find and clean orphaned worktrees, stale merge locks,
+# and stale lifecycle pins
 #
 # Usage:
 #   orphan-sweep.sh report  — list orphans (read-only for worktrees);
 #                              stale locks with dead PIDs are released
-#   orphan-sweep.sh clean   — remove safe-to-clean orphans (merged branches only)
-#                              and release stale merge locks
+#   orphan-sweep.sh clean   — remove safe-to-clean orphans (merged branches only),
+#                              release stale merge locks, and remove pins whose
+#                              task has no running session
 #
 # Active-run knowledge is injected by the caller, never fetched here:
 #   CREW_ACTIVE_TASKS      — space-separated task IDs with a running session
 #   CREW_ACTIVE_TASKS_FILE — path to a file with one task ID per line
 #                            (blank lines and '#' comments are ignored)
-# Both inputs feed one active set, matched exactly against worktree dir names.
-# A task in the active set is never touched: its worktree and any merge lock
-# it holds are skipped regardless of merge status, lock age, or PID liveness.
+# Both inputs feed one active set, matched exactly against worktree dir names
+# and pin dir names. Both inputs must contain full task UUIDs (lowercase
+# 8-4-4-4-12 hex, e.g. 7dbe861d-cddd-479f-87e9-9423539c08a3): clean mode
+# validates every entry against that format and exits 2 with a BLOCKED line
+# on any malformed entry, because a truncated or reformatted ID would never
+# match exactly and would silently defeat the never-touch-active-runs
+# promise.
+# A task in the active set is never touched: its worktree, any merge lock
+# it holds, and its lifecycle pin are skipped regardless of merge status,
+# lock age, or PID liveness.
+#
+# Lifecycle pins live on persistent disk ($CREW_HOME/.pins/<task>) so a VM
+# reboot (which wipes tmpfs /tmp) can't strand a run mid-flight. A pin whose
+# task has no running session is safe to remove: any new run re-pins
+# idempotently (mkdir -p + cp) before use.
 #
 # Fail closed: clean mode without either input refuses to remove anything
 # and exits 2. Report mode without either input still runs read-only but
@@ -61,6 +75,22 @@ task_is_active() {
   esac
 }
 
+# Fail closed on malformed active-run IDs: the guard below matches entries
+# exactly against full-UUID directory names, branch names, and merge-lock
+# holders. A short/truncated/reformatted ID would never match and would
+# silently defeat the never-touch-active-runs promise. No prefix or fuzzy
+# matching — ambiguous prefixes could match multiple runs; refusing is
+# the correct behavior.
+UUID_RE='^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+if [ "$cmd" = "clean" ] && [ "$have_active_data" -eq 1 ]; then
+  for entry in $ACTIVE_TASKS; do
+    if [[ ! "$entry" =~ $UUID_RE ]]; then
+      echo "BLOCKED: CREW_ACTIVE_TASKS entry '$entry' is not a full task UUID (expected lowercase 8-4-4-4-12 hex) — refusing to clean"
+      exit 2
+    fi
+  done
+fi
+
 if [ "$cmd" = "clean" ] && [ "$have_active_data" -eq 0 ]; then
   echo "BLOCKED: clean mode requires the active-run list (set CREW_ACTIVE_TASKS or CREW_ACTIVE_TASKS_FILE) — refusing to remove anything"
   exit 2
@@ -157,8 +187,41 @@ if [ -d "$WORKTREE_DIR" ]; then
   done
 fi
 
+# --- Reap stale lifecycle pins ---
+# Pins live on persistent disk ($CREW_HOME/.pins/<task>) so a reboot can't
+# strand a run; pins for tasks with no running session are garbage.
+PINS_DIR="${CREW_HOME:-$HOME/workspace/.jarvis}/.pins"
+if [ -d "$PINS_DIR" ]; then
+  for pin in "$PINS_DIR"/*/; do
+    [ -d "$pin" ] || continue
+    task_id=$(basename "$pin")
+
+    # Skip hidden dirs
+    [[ "$task_id" == .* ]] && continue
+
+    found=1
+
+    # Active runs are never touched.
+    if task_is_active "$task_id"; then
+      echo "ACTIVE_PIN: $task_id — dashboard shows a running session, kept"
+      continue
+    fi
+
+    echo "STALE_PIN: $task_id — no running session, safe to remove"
+    if [ "$cmd" = "clean" ]; then
+      rm -rf "$pin"
+      if [ ! -d "$pin" ]; then
+        echo "  → removed"
+      else
+        echo "  → FAILED: pin still present after rm, left in place"
+        any_failed=1
+      fi
+    fi
+  done
+fi
+
 if [ "$found" -eq 0 ]; then
-  echo "CLEAN: no orphans, no stale locks"
+  echo "CLEAN: no orphans, no stale locks, no stale pins"
 fi
 
 if [ "$any_failed" -eq 1 ]; then

package/lib/publish-npm.sh

@@ -0,0 +1,174 @@
+#!/usr/bin/env bash
+# publish-npm.sh — deterministic npm publish for Muse Crew.
+#
+# Takes the entire publish decision as input; the Publish agent makes none.
+# TARGET_VERSION is authoritative — computed by the workflow, never here.
+# Idempotent on retry/resume: if this task already published the target
+# version (version-bump commit + registry both present), the mutation steps
+# are skipped and the run goes straight to push (idempotent) + finalize.
+#
+# Env:
+#   TASK_ID          task id (idempotent commit message + merge-lock ops)
+#   REPO_PATH        repo checkout (Publish runs here, not in a worktree)
+#   PKG              npm package name (default: muse-crew)
+#   TARGET_VERSION   version to publish (workflow-computed, authoritative)
+#   CREW_HOME        crew instance home (accepted for uniformity; unused here)
+#   LIFECYCLE        pinned worktree-lifecycle.sh
+#   RELEASE_SCRIPT   crew-release.sh (stable path)
+#   NPM_PUBLISH_PY   publish helper (default: ~/workspace/skills/npm/bin/npm-publish.py)
+#   DRY_RUN=1        print markers and exit before any mutation
+#
+# Output markers (PUBLISH_* lines). On any failure: print
+# PUBLISH_FAILED=<short-reason> plus one detail line, exit 1.
+# 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.
+
+set -euo pipefail
+
+PKG="${PKG:-muse-crew}"
+NPM_PUBLISH_PY="${NPM_PUBLISH_PY:-$HOME/workspace/skills/npm/bin/npm-publish.py}"
+
+fail() { # fail <reason> [detail]
+  echo "PUBLISH_FAILED=$1"
+  if [ $# -ge 2 ]; then
+    echo "$2"
+  fi
+  exit 1
+}
+
+# 1-2. Validate env, then print the target.
+[ -n "${TASK_ID:-}" ] || fail "env" "TASK_ID is required"
+[ -n "${REPO_PATH:-}" ] || fail "env" "REPO_PATH is required"
+[ -n "${TARGET_VERSION:-}" ] || fail "env" "TARGET_VERSION is required"
+echo "PUBLISH_TARGET=$TARGET_VERSION"
+git -C "$REPO_PATH" rev-parse --git-dir >/dev/null 2>&1 \
+  || fail "env" "REPO_PATH is not a git checkout: $REPO_PATH"
+
+# 3. Dry run: markers only, no lock, no deploy, no mutation.
+if [ "${DRY_RUN:-0}" = "1" ]; then
+  echo "PUBLISH_DRY_RUN=1"
+  exit 0
+fi
+
+# 4. Idempotency: this task's version-bump commit is HEAD and the registry
+# already serves the target version — a prior Publish finished. Skip the
+# mutation steps; push (idempotent) and finalize still run.
+ALREADY_PUBLISHED=0
+HEAD_MSG="$(git -C "$REPO_PATH" log -1 --format=%s)"
+REG="$(npm view "$PKG" version 2>/dev/null || true)"
+if { [ "$HEAD_MSG" = "release: $PKG@$TARGET_VERSION ($TASK_ID)" ] \
+   || [ "$HEAD_MSG" = "release: $PKG@$TARGET_VERSION" ]; } \
+   && [ "$REG" = "$TARGET_VERSION" ]; then
+  ALREADY_PUBLISHED=1
+  echo "PUBLISHED_ALREADY=$TARGET_VERSION"
+  echo "PUBLISH_VERIFIED=$TARGET_VERSION"
+fi
+
+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"
+  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.
+  REG="$(npm view "$PKG" version 2>/dev/null)" \
+    || fail "verify" "npm view $PKG failed"
+  [ "$REG" = "$TARGET_VERSION" ] \
+    || fail "verify" "registry=$REG"
+  echo "PUBLISH_VERIFIED=$TARGET_VERSION"
+fi
+
+# 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"
+echo "PUBLISH_PUSHED=1"
+
+# 14. Finalize: releases the merge lock and cleans up the worktree.
+FIN_OUT="$(CREW_REPO="$REPO_PATH" bash "$LIFECYCLE" post-deploy "$TASK_ID" 2>&1)" \
+  || fail "post-deploy" "$FIN_OUT"
+case "$FIN_OUT" in
+  *DEPLOYED*) echo "PUBLISH_FINALIZED=1" ;;
+  *) fail "post-deploy" "missing DEPLOYED marker: $FIN_OUT" ;;
+esac
+
+# Final marker: the full publish path completed.
+echo "PUBLISH_COMPLETE=$TARGET_VERSION"

package/lib/test-merge-lock.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# 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.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LOCK="$SCRIPT_DIR/merge-lock.sh"
+
+pass=0
+fail=0
+ok() { echo "PASS: $1"; pass=$((pass + 1)); }
+no() { echo "FAIL: $1"; fail=$((fail + 1)); }
+
+TMPBASE="$(mktemp -d)"
+trap 'rm -rf "$TMPBASE"' EXIT
+
+export CREW_REPO="$TMPBASE/repo"
+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 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 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 ---
+out=$("$LOCK" status 2>&1); code=$?
+[ "$code" -eq 0 ] && [[ "$out" == "UNLOCKED" ]] && ok "4: status UNLOCKED after release" || no "4: 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: after reclaim, the new holder owns the lock ---
+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"
+
+# --- 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 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 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"
+"$LOCK" release task-4 >/dev/null 2>&1
+
+echo ""
+echo "merge-lock: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]

package/lib/test-orphan-sweep.sh

@@ -4,6 +4,10 @@
 # Self-contained: builds throwaway git fixtures in a temp dir and drives
 # lib/orphan-sweep.sh through the CREW_ACTIVE_TASKS / CREW_ACTIVE_TASKS_FILE
 # seam (no network, no dashboard). Exits 0 only if every case passes.
+#
+# Format contract: clean mode validates every active-set entry is a full
+# lowercase task UUID and exits 2 with a BLOCKED line otherwise (cases 9, 10).
+# Report mode has no format expectation and keeps current behavior.
 
 set -uo pipefail
 
@@ -43,14 +47,20 @@ merged_worktree() {
 }
 
 # --- Case 1: live run protected (the incident's exact case) ---
-# T1's branch tip equals main (no commits — "merged" by equality), clean tree.
+# Active-set fixtures must be full lowercase UUIDs: clean mode fails closed
+# (exit 2) on any active-set entry that is not one, and exact matching means
+# the worktree dir / lock holder / pin dir names use the same UUIDs.
+UUID_ACTIVE="8e951fb5-cddd-479f-87e9-9423539c08a3"   # live-run guard + incident case
+UUID_LOCK="bc5a1654-cddd-479f-87e9-9423539c08a3"     # merge-lock holder
+UUID_PIN="1c4b0e7b-cddd-479f-87e9-9423539c08a3"      # lifecycle pin owner
+SHORT_ACTIVE="8e951fb5"                              # 8-char prefix of UUID_ACTIVE
 new_fixture case1
-git worktree add -q .worktrees/T1 -b task/T1 >/dev/null
-out=$(CREW_ACTIVE_TASKS="T1" "$SWEEP" clean 2>&1); code=$?
+git worktree add -q ".worktrees/$UUID_ACTIVE" -b "task/$UUID_ACTIVE" >/dev/null
+out=$(CREW_ACTIVE_TASKS="$UUID_ACTIVE" "$SWEEP" clean 2>&1); code=$?
 [ "$code" -eq 0 ] && ok "1: clean exits 0 with only an active run present" || no "1: exit $code, want 0"
-[ -d .worktrees/T1 ] && ok "1: active worktree dir preserved" || no "1: active worktree dir removed"
-git show-ref --verify --quiet refs/heads/task/T1 && ok "1: active branch preserved" || no "1: active branch deleted"
-echo "$out" | grep -q "ACTIVE: T1" && ok "1: ACTIVE line printed" || no "1: no ACTIVE line in output"
+[ -d ".worktrees/$UUID_ACTIVE" ] && ok "1: active worktree dir preserved" || no "1: active worktree dir removed"
+git show-ref --verify --quiet "refs/heads/task/$UUID_ACTIVE" && ok "1: active branch preserved" || no "1: active branch deleted"
+echo "$out" | grep -q "ACTIVE: $UUID_ACTIVE" && ok "1: ACTIVE line printed" || no "1: no ACTIVE line in output"
 
 # --- Case 2: dead run cleaned ---
 new_fixture case2
@@ -89,8 +99,8 @@ out=$(CREW_ACTIVE_TASKS="" "$SWEEP" clean 2>&1); code=$?
 echo "$out" | grep -q "released (dead PID)" && 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 'T6 2020-01-01T00:00:00Z 999999\n' > .worktrees/.merge-lock
-out=$(CREW_ACTIVE_TASKS="T6" "$SWEEP" clean 2>&1); code=$?
+printf '%s 2020-01-01T00:00:00Z 999999\n' "$UUID_LOCK" > .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"
@@ -104,6 +114,62 @@ echo "$out" | grep -q "NOTE: no active-run data provided; ACTIVE checks skipped"
 [ -d .worktrees/T7 ] && ok "6: report mode removes nothing" || no "6: report mode removed a worktree"
 echo "$out" | grep -q "MERGED: T7" && ok "6: MERGED line still listed" || no "6: MERGED line missing from report"
 
+# --- Case 7: lifecycle pins — active kept, stale reaped ---
+new_fixture case7
+export CREW_HOME="$TMPBASE/case7home"
+mkdir -p "$CREW_HOME/.pins/$UUID_PIN" "$CREW_HOME/.pins/STALEPIN"
+echo x > "$CREW_HOME/.pins/$UUID_PIN/worktree-lifecycle.sh"
+echo x > "$CREW_HOME/.pins/STALEPIN/worktree-lifecycle.sh"
+out=$(CREW_ACTIVE_TASKS="$UUID_PIN" "$SWEEP" clean 2>&1); code=$?
+[ "$code" -eq 0 ] && ok "7: clean exits 0 with pins present" || no "7: exit $code, want 0"
+[ -d "$CREW_HOME/.pins/$UUID_PIN" ] && ok "7: active task's pin kept" || no "7: active task's pin removed"
+[ ! -d "$CREW_HOME/.pins/STALEPIN" ] && ok "7: stale pin removed" || no "7: stale pin still present"
+echo "$out" | grep -q "ACTIVE_PIN: $UUID_PIN" && ok "7: ACTIVE_PIN line printed" || no "7: no ACTIVE_PIN line in output"
+echo "$out" | grep -q "STALE_PIN: STALEPIN" && ok "7: STALE_PIN line printed" || no "7: no STALE_PIN line in output"
+
+# --- Case 8: pins — report mode removes nothing; clean without active data fails closed ---
+new_fixture case8
+export CREW_HOME="$TMPBASE/case8home"
+mkdir -p "$CREW_HOME/.pins/R1"
+out=$(CREW_ACTIVE_TASKS="" "$SWEEP" report 2>&1); code=$?
+[ "$code" -eq 0 ] && ok "8a: report exits 0" || no "8a: exit $code, want 0"
+[ -d "$CREW_HOME/.pins/R1" ] && ok "8a: report mode removes no pins" || no "8a: report mode removed a pin"
+echo "$out" | grep -q "STALE_PIN: R1" && ok "8a: STALE_PIN listed in report" || no "8a: STALE_PIN missing from report"
+
+out=$(env -u CREW_ACTIVE_TASKS -u CREW_ACTIVE_TASKS_FILE "$SWEEP" clean 2>&1); code=$?
+[ "$code" -eq 2 ] && ok "8b: clean without active data exits 2" || no "8b: exit $code, want 2"
+[ -d "$CREW_HOME/.pins/R1" ] && ok "8b: pin left alone when BLOCKED" || no "8b: pin removed despite BLOCKED"
+
+# --- Case 9: fail closed on a short ID in CREW_ACTIVE_TASKS (the incident) ---
+# The sweep worker once passed 8-char prefixes; the guard would never match
+# them exactly, so clean must refuse instead of silently defeating the
+# active-run guard.
+new_fixture case9
+export CREW_HOME="$TMPBASE/case9home"
+merged_worktree "$UUID_ACTIVE"
+mkdir -p "$CREW_HOME/.pins/$UUID_ACTIVE"
+out=$(CREW_ACTIVE_TASKS="$SHORT_ACTIVE" "$SWEEP" clean 2>&1); code=$?
+[ "$code" -eq 2 ] && ok "9: short ID in CREW_ACTIVE_TASKS exits 2" || no "9: exit $code, want 2"
+echo "$out" | grep -q "BLOCKED" && ok "9: BLOCKED line printed" || no "9: no BLOCKED line in output"
+echo "$out" | grep -q "$SHORT_ACTIVE" && ok "9: BLOCKED line names the bad entry" || no "9: BLOCKED line does not name the entry"
+[ -d ".worktrees/$UUID_ACTIVE" ] && ok "9: worktree preserved" || no "9: worktree removed despite BLOCKED"
+git show-ref --verify --quiet "refs/heads/task/$UUID_ACTIVE" && ok "9: branch preserved" || no "9: branch deleted despite BLOCKED"
+[ -d "$CREW_HOME/.pins/$UUID_ACTIVE" ] && ok "9: pin preserved" || no "9: pin removed despite BLOCKED"
+
+# --- Case 10: fail closed on a short ID in CREW_ACTIVE_TASKS_FILE ---
+new_fixture case10
+export CREW_HOME="$TMPBASE/case10home"
+merged_worktree "$UUID_ACTIVE"
+mkdir -p "$CREW_HOME/.pins/$UUID_ACTIVE"
+printf '%s\n' "$SHORT_ACTIVE" > "$TMPBASE/case10-active.txt"
+out=$(env -u CREW_ACTIVE_TASKS CREW_ACTIVE_TASKS_FILE="$TMPBASE/case10-active.txt" "$SWEEP" clean 2>&1); code=$?
+[ "$code" -eq 2 ] && ok "10: short ID in CREW_ACTIVE_TASKS_FILE exits 2" || no "10: exit $code, want 2"
+echo "$out" | grep -q "BLOCKED" && ok "10: BLOCKED line printed" || no "10: no BLOCKED line in output"
+echo "$out" | grep -q "$SHORT_ACTIVE" && ok "10: BLOCKED line names the bad entry" || no "10: no BLOCKED line naming the entry"
+[ -d ".worktrees/$UUID_ACTIVE" ] && ok "10: worktree preserved" || no "10: worktree removed despite BLOCKED"
+git show-ref --verify --quiet "refs/heads/task/$UUID_ACTIVE" && ok "10: branch preserved" || no "10: branch deleted despite BLOCKED"
+[ -d "$CREW_HOME/.pins/$UUID_ACTIVE" ] && ok "10: pin preserved" || no "10: pin removed despite BLOCKED"
+
 echo ""
 echo "== $pass passed, $fail failed =="
 [ "$fail" -eq 0 ]