muse-crew 0.6.5 → 0.6.7

package/lib/crew-release.sh

@@ -3,6 +3,8 @@
 #
 # Lives at a STABLE path (~/.jarvis/crew-release.sh) outside the release
 # layout so it survives rollback. Init copies it here from the repo.
+# Deploy self-updates it from the repo (syntax-checked) before running,
+# so the stable copy can never go stale behind the repo's logic.
 #
 # Layout:
 #   ~/.jarvis/
@@ -134,6 +136,23 @@ cmd_deploy() {
   local home="${2:-$CREW_HOME}"
   CREW_HOME="$home"
 
+  # Self-update: the stable script is installed once by cmd_init and would
+  # otherwise go stale (2026-09-12: the stable copies predated the
+  # registry-build block, so deploys silently skipped registry.json).
+  # If the repo's lib/crew-release.sh differs from the running script,
+  # syntax-check it, install it to the stable path, and re-exec through it
+  # so the deploy always runs current logic.
+  local repo_script="$repo/lib/crew-release.sh"
+  local self_path
+  self_path="$(realpath "$0")"
+  if [ -f "$repo_script" ] && ! cmp -s "$repo_script" "$self_path"; then
+    bash -n "$repo_script" || die "repo's crew-release.sh fails syntax check; refusing to self-update"
+    cp -f "$repo_script" "$CREW_HOME/crew-release.sh"
+    chmod +x "$CREW_HOME/crew-release.sh"
+    echo "SELF-UPDATE: stable crew-release.sh refreshed from repo"
+    exec bash "$repo_script" deploy "$repo" "$home"
+  fi
+
   cd "$repo"
   local hash
 

package/lib/merge-lock.sh

@@ -6,9 +6,8 @@
 # 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.
+# owned version assignment. PID is the wrong liveness signal — 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>
@@ -29,9 +28,23 @@
 
 set -euo pipefail
 
-LOCK_DIR="${CREW_REPO:-$HOME/workspace/ts-spaces/orchestra-dashboard}/.worktrees"
+# Fail closed: no stale dev-path defaults. An unset CREW_REPO would
+# operate on another checkout's lock file; an unset CREW_HOME would log
+# to another instance's audit log. Every caller (workflows thread both
+# through LIFECYCLE_ENV; the orphan sweep sets CREW_REPO per repo)
+# provides them.
+if [ -z "${CREW_REPO:-}" ]; then
+  echo "BLOCKED: CREW_REPO is not set — refusing to touch a merge lock (a default path would hit the wrong repo)"
+  exit 2
+fi
+if [ -z "${CREW_HOME:-}" ]; then
+  echo "BLOCKED: CREW_HOME is not set — refusing to touch a merge lock (a default path would log to the wrong instance)"
+  exit 2
+fi
+
+LOCK_DIR="$CREW_REPO/.worktrees"
 LOCK_FILE="$LOCK_DIR/.merge-lock"
-LOG_FILE="${CREW_HOME:-$HOME/workspace/.jarvis}/.merge-lock.log"
+LOG_FILE="$CREW_HOME/.merge-lock.log"
 LEASE_SECONDS="${MERGE_LOCK_LEASE_SECONDS:-600}"
 
 log_op() { # log_op <op> <detail> — audit trail; logging never breaks a lock op

package/lib/publish-npm.sh

@@ -12,7 +12,8 @@
 #   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)
+#   CREW_HOME        crew instance home (passed through to the lifecycle
+#                    seam — the lifecycle and merge-lock fail closed without it)
 #   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)
@@ -79,14 +80,14 @@ if [ "$ALREADY_PUBLISHED" = "0" ]; then
   # 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)" \
+  LOCK_STATE="$(CREW_HOME="${CREW_HOME:-}" 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
     # 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)" \
+    LOCK_OUT="$(CREW_HOME="${CREW_HOME:-}" CREW_REPO="$REPO_PATH" bash "${LIFECYCLE:?LIFECYCLE is required}" refresh-lock "$TASK_ID" 2>&1)" \
       || fail "lock-refresh" "$LOCK_OUT"
   fi
   # STEP-5-END
@@ -115,6 +116,28 @@ if [ "$ALREADY_PUBLISHED" = "0" ]; then
     # empty diff and fails closed at the numstat check.
     # STEP-8-ANCHOR: version write (escape-preserving)
     PKG_JSON="$REPO_PATH/package.json"
+    # STRANDED-ANCHOR: resume after a killed publish (release commit made,
+    # registry never updated). If the working tree's package.json already
+    # carries TARGET_VERSION and HEAD is the script's own release commit for
+    # it, the version write is a no-op by design — skip it and let step 9
+    # confirm the commit. If HEAD is NOT the release commit, fail closed:
+    # a foreign version bump must never be papered over by a publish.
+    PRE_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 before write"
+    STRANDED=0
+    if [ "$PRE_VER" = "$TARGET_VERSION" ]; then
+      case "$HEAD_MSG" in
+        "release: $PKG@$TARGET_VERSION"*)
+          STRANDED=1
+          echo "PUBLISH_STRANDED_RESUME=1"
+          ;;
+        *)
+          fail "version-diff" "package.json already at $TARGET_VERSION but HEAD is not its release commit: $HEAD_MSG"
+          ;;
+      esac
+    fi
+    # STRANDED-END
+    if [ "$STRANDED" = "0" ]; then
     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"
@@ -129,6 +152,7 @@ if [ "$ALREADY_PUBLISHED" = "0" ]; then
     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"
+    fi
     # STEP-8-END
 
     # 9. Commit only if changed (retried run leaves the commit in place).
@@ -202,7 +226,7 @@ fi
 # 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)" \
+LOCK_OUT2="$(CREW_HOME="${CREW_HOME:-}" 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).
@@ -211,7 +235,7 @@ PUSH_OUT="$(git -C "$REPO_PATH" push origin main 2>&1)" \
 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)" \
+FIN_OUT="$(CREW_HOME="${CREW_HOME:-}" 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" ;;

package/lib/schema.sql

@@ -0,0 +1,101 @@
+-- Muse Crew state schema.
+--
+-- The crew owns this schema. It is the contract between the crew and any
+-- client (workflows, dashboard, CLIs): every invariant the crew depends on
+-- lives here as a CHECK constraint or index, never in client prose.
+--
+-- Column names are snake_case and match the historical dashboard tables
+-- exactly, so a one-time migration is a straight row copy.
+--
+-- Vocabulary notes:
+-- - Event types include 'rejected': workflows record a Review/QA rejection
+--   as both a session status AND an event type with the same word. A schema
+--   that accepts 'rejected' for sessions but not for events crashes the
+--   workflow mid-run (canary 2026-09-11). One vocabulary, one constraint.
+-- - Task states never include 'blocked': it is derived from unmet
+--   dependencies, never stored.
+
+CREATE TABLE IF NOT EXISTS projects (
+  id            TEXT PRIMARY KEY,
+  display_name  TEXT NOT NULL,
+  repo_path     TEXT NOT NULL,
+  deploy_type   TEXT NOT NULL CHECK (deploy_type IN ('npm', 'artifact', 'vercel', '')),
+  deploy_slug   TEXT,
+  description   TEXT NOT NULL DEFAULT '',
+  simultaneity  INTEGER NOT NULL DEFAULT 2 CHECK (simultaneity >= 0 AND simultaneity <= 100),
+  quiesced      INTEGER NOT NULL DEFAULT 0 CHECK (quiesced IN (0, 1)),
+  visual_protocol INTEGER CHECK (visual_protocol IN (0, 1)),
+  created_at    TEXT NOT NULL,
+  updated_at    TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS tasks (
+  id             TEXT PRIMARY KEY,
+  title          TEXT NOT NULL CHECK (length(title) >= 1 AND length(title) <= 200),
+  description    TEXT NOT NULL DEFAULT '',
+  state          TEXT NOT NULL DEFAULT 'todo'
+                 CHECK (state IN ('todo', 'in_progress', 'parked', 'done')),
+  priority       TEXT NOT NULL DEFAULT 'normal'
+                 CHECK (priority IN ('high', 'normal', 'low')),
+  project        TEXT NOT NULL DEFAULT 'orchestra-dashboard',
+  workflow       TEXT,
+  next_phase     TEXT,
+  deps           TEXT NOT NULL DEFAULT '[]',
+  filed_by       TEXT,
+  retry_reset_at TEXT,
+  created_at     TEXT NOT NULL,
+  updated_at     TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS poll_state (
+  id                       INTEGER PRIMARY KEY,
+  last_poll_at             TEXT,
+  poll_requested           INTEGER NOT NULL DEFAULT 0 CHECK (poll_requested IN (0, 1)),
+  min_poll_interval_seconds INTEGER NOT NULL DEFAULT 300
+);
+
+CREATE TABLE IF NOT EXISTS config (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS agent_sessions (
+  id             TEXT PRIMARY KEY,
+  task_id        TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+  identity       TEXT NOT NULL,
+  step           TEXT,
+  status         TEXT NOT NULL CHECK (status IN
+                   ('running', 'completed', 'failed', 'rejected',
+                    'timed_out', 'stalled', 'passed', 'superseded')),
+  started_at     TEXT NOT NULL,
+  ended_at       TEXT,
+  notes          TEXT NOT NULL DEFAULT '',
+  caveats        TEXT NOT NULL DEFAULT '[]',
+  failure_reason TEXT,
+  last_heartbeat TEXT
+);
+
+CREATE TABLE IF NOT EXISTS events (
+  id        TEXT PRIMARY KEY,
+  type      TEXT NOT NULL CHECK (type IN
+              ('dispatched', 'completed', 'failed', 'blocked', 'created',
+               'note', 'release_activated', 'deployed', 'rejected')),
+  task_id   TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+  identity  TEXT,
+  message   TEXT NOT NULL CHECK (length(message) >= 1 AND length(message) <= 1000),
+  timestamp TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS projects_display_name_idx ON projects(display_name);
+CREATE INDEX IF NOT EXISTS tasks_state_idx ON tasks(state);
+CREATE INDEX IF NOT EXISTS tasks_updated_at_idx ON tasks(updated_at);
+CREATE INDEX IF NOT EXISTS agent_sessions_status_idx ON agent_sessions(status);
+CREATE INDEX IF NOT EXISTS agent_sessions_task_id_idx ON agent_sessions(task_id);
+CREATE INDEX IF NOT EXISTS events_timestamp_idx ON events(timestamp);
+CREATE INDEX IF NOT EXISTS events_task_id_idx ON events(task_id);
+
+-- Atomic claim: at most one running session per task. claim-task inserts a
+-- 'running' session with ON CONFLICT DO NOTHING; zero inserted rows means
+-- another session holds the claim.
+CREATE UNIQUE INDEX IF NOT EXISTS agent_sessions_one_running_per_task_idx
+  ON agent_sessions(task_id) WHERE status = 'running';

package/lib/test-merge-lock.sh

@@ -107,6 +107,19 @@ 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"
 
+# --- Case 13: fail closed on unset CREW_REPO / CREW_HOME ---
+# No stale dev-path defaults: any op without both vars prints BLOCKED
+# and exits 2 instead of touching the wrong repo's lock file.
+out=$(env -u CREW_REPO "$LOCK" status 2>&1); code=$?
+[ "$code" -eq 2 ] && [[ "$out" == *"BLOCKED"* ]] && [[ "$out" == *"CREW_REPO"* ]] \
+  && ok "13a: unset CREW_REPO exits 2 with BLOCKED" || no "13a: exit $code, out: $out"
+out=$(env -u CREW_HOME "$LOCK" status 2>&1); code=$?
+[ "$code" -eq 2 ] && [[ "$out" == *"BLOCKED"* ]] && [[ "$out" == *"CREW_HOME"* ]] \
+  && ok "13b: unset CREW_HOME exits 2 with BLOCKED" || no "13b: exit $code, out: $out"
+out=$(env -u CREW_REPO -u CREW_HOME "$LOCK" acquire task-x "task-x/run" 2>&1); code=$?
+[ "$code" -eq 2 ] && [[ "$out" == *"BLOCKED"* ]] \
+  && ok "13c: unset both on acquire exits 2 with BLOCKED" || no "13c: exit $code, out: $out"
+
 echo ""
 echo "merge-lock: $pass passed, $fail failed"
 [ "$fail" -eq 0 ]

package/lib/test-publish-skip.sh

@@ -43,6 +43,7 @@ echo x > "$SCRATCH/f.txt"
 git -C "$SCRATCH" add -A && git -C "$SCRATCH" commit -qm init
 
 export CREW_REPO="$SCRATCH" CREW_LIB="$SCRIPT_DIR"
+export CREW_HOME="$TMPBASE/home"  # lifecycle + merge-lock fail closed without both vars
 
 TASK="skiptest-task-1"
 
@@ -59,8 +60,9 @@ fi
 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)"
+if [ $CODE -eq 0 ] && printf '%s' "$OUT" | grep -Eq "^locked=true$" \
+  && printf '%s' "$OUT" | grep -Eq "^task_id=$TASK$"; then
+  ok "lock-status reports key=value (locked=true, task_id=$TASK) (exit 0)"
 else
   no "lock-status LOCKED: code=$CODE out='$OUT'"
 fi
@@ -105,7 +107,7 @@ run_block() { # run_block <lock_setup: none|held|broken>
   esac
   (
     set -euo pipefail
-    export CREW_REPO="$SCRATCH" TASK_ID="$TASK" REPO_PATH="$SCRATCH"
+    export CREW_REPO="$SCRATCH" TASK_ID="$TASK" REPO_PATH="$SCRATCH" CREW_HOME="$TMPBASE/home"
     if [ "$mode" = "broken" ]; then
       export LIFECYCLE="/nonexistent/lifecycle.sh"
     else

package/lib/test-publish-stranded.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# test-publish-stranded.sh — regression test for the stranded-release resume
+# in lib/publish-npm.sh (park 2026-09-11).
+#
+# A service restart can kill a Publish run between the release commit and the
+# registry PUT. The release commit is pushed, but npm never got the tarball.
+# Replaying the script must not fail the version-diff guard (the write is a
+# no-op because package.json already carries the target): the script detects
+# the stranded state and resumes at pack/publish. A package.json already at
+# the target whose HEAD is NOT the script's own release commit is a foreign
+# version bump and must fail closed.
+#
+# Self-contained: extracts the shipped STRANDED block from lib/publish-npm.sh
+# by anchor and runs it against scratch checkouts.
+#
+# Anchors: `# STRANDED-ANCHOR` ... `# STRANDED-END` in lib/publish-npm.sh.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PUBLISH="$SCRIPT_DIR/publish-npm.sh"
+
+PKG="muse-crew"
+TARGET_VERSION="9.9.9"
+STRANDED_MSG="release: muse-crew@9.9.9 (task-aaa)"
+STRANDED_MSG_BARE="release: muse-crew@9.9.9"
+
+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
+
+# --- Extract the shipped STRANDED block by anchor ---
+BLOCK="$TMPBASE/stranded.sh"
+sed -n '/# STRANDED-ANCHOR/,/# STRANDED-END/p' "$PUBLISH" > "$BLOCK"
+if grep -q 'PUBLISH_STRANDED_RESUME=1' "$BLOCK" && grep -q 'fail "version-diff"' "$BLOCK"; then
+  ok "extracted STRANDED block from publish-npm.sh"
+else
+  no "STRANDED extraction failed (anchors missing)"
+fi
+
+# make_checkout <version> <head-msg>: a scratch git checkout whose
+# package.json carries <version> and whose HEAD message is <head-msg>.
+make_checkout() {
+  local ver="$1" msg="$2" dir="$TMPBASE/checkout-$RANDOM"
+  mkdir -p "$dir"
+  git -C "$dir" init -q
+  git -C "$dir" config user.email "test@test"
+  git -C "$dir" config user.name "test"
+  printf '{\n  "name": "muse-crew",\n  "version": "%s"\n}\n' "$ver" > "$dir/package.json"
+  git -C "$dir" add package.json
+  git -C "$dir" commit -q -m "$msg"
+  printf '%s' "$dir"
+}
+
+# run_stranded <checkout-dir> <head-msg>: runs the shipped block with
+# PKG_JSON/PKG/TARGET_VERSION/HEAD_MSG set; captures stdout in $OUT.
+run_stranded() {
+  local dir="$1" msg="$2" runner="$TMPBASE/runner-$RANDOM.sh"
+  {
+    echo 'fail() { echo "PUBLISH_FAILED=$1"; shift; echo "$1"; exit 1; }'
+    cat "$BLOCK"
+    echo 'echo "STRANDED_RESULT=$STRANDED"'
+  } > "$runner"
+  chmod +x "$runner"
+  OUT="$(PKG_JSON="$dir/package.json" PKG="$PKG" \
+    TARGET_VERSION="$TARGET_VERSION" HEAD_MSG="$msg" \
+    bash "$runner" 2>&1)"
+  local code=$?
+  echo "$OUT"
+  return "$code"
+}
+
+# --- Case 1: stranded release commit (with task id) — resume, no write ---
+DIR1="$(make_checkout "$TARGET_VERSION" "$STRANDED_MSG")"
+BEFORE1="$(cat "$DIR1/package.json")"
+OUT="$(run_stranded "$DIR1" "$STRANDED_MSG")"
+CODE=$?
+if [ "$CODE" -eq 0 ]; then
+  ok "stranded resume: block exits 0"
+else
+  no "stranded resume: block exited $CODE (output: $OUT)"
+fi
+case "$OUT" in
+  *"PUBLISH_STRANDED_RESUME=1"*)
+    ok "stranded resume: prints PUBLISH_STRANDED_RESUME=1" ;;
+  *) no "stranded resume: missing PUBLISH_STRANDED_RESUME=1 (output: $OUT)" ;;
+esac
+case "$OUT" in
+  *"STRANDED_RESULT=1"*)
+    ok "stranded resume: STRANDED=1 (skips the version write)" ;;
+  *) no "stranded resume: expected STRANDED=1 (output: $OUT)" ;;
+esac
+if [ "$(cat "$DIR1/package.json")" = "$BEFORE1" ]; then
+  ok "stranded resume: package.json untouched (write skipped)"
+else
+  no "stranded resume: package.json was modified"
+fi
+
+# --- Case 2: bare release message form (no task id) — also resumes ---
+DIR2="$(make_checkout "$TARGET_VERSION" "$STRANDED_MSG_BARE")"
+OUT="$(run_stranded "$DIR2" "$STRANDED_MSG_BARE")"
+CODE=$?
+if [ "$CODE" -eq 0 ] && grep -q 'PUBLISH_STRANDED_RESUME=1' <<< "$OUT"; then
+  ok "bare release message form also resumes"
+else
+  no "bare release message form failed to resume (code $CODE, output: $OUT)"
+fi
+
+# --- Case 3: foreign version bump — fail closed ---
+DIR3="$(make_checkout "$TARGET_VERSION" "merge: some other fix")"
+OUT="$(run_stranded "$DIR3" "merge: some other fix")"
+CODE=$?
+if [ "$CODE" -ne 0 ]; then
+  ok "foreign version: block fails closed (non-zero exit)"
+else
+  no "foreign version: block exited 0 despite foreign HEAD"
+fi
+case "$OUT" in
+  *"PUBLISH_FAILED=version-diff"*)
+    ok "foreign version: keeps the PUBLISH_FAILED=version-diff marker" ;;
+  *) no "foreign version: missing PUBLISH_FAILED=version-diff (output: $OUT)" ;;
+esac
+case "$OUT" in
+  *"not its release commit"*)
+    ok "foreign version: detail names the mismatch" ;;
+  *) no "foreign version: missing mismatch detail (output: $OUT)" ;;
+esac
+
+# --- Case 4: normal path (package.json behind) — no resume, write proceeds ---
+DIR4="$(make_checkout "9.9.8" "merge: some other fix")"
+OUT="$(run_stranded "$DIR4" "merge: some other fix")"
+CODE=$?
+if [ "$CODE" -eq 0 ]; then
+  ok "normal path: block exits 0"
+else
+  no "normal path: block exited $CODE (output: $OUT)"
+fi
+case "$OUT" in
+  *"STRANDED_RESULT=0"*)
+    ok "normal path: STRANDED=0 (version write proceeds)" ;;
+  *) no "normal path: expected STRANDED=0 (output: $OUT)" ;;
+esac
+case "$OUT" in
+  *"PUBLISH_STRANDED_RESUME=1"*) no "normal path: must not print PUBLISH_STRANDED_RESUME=1" ;;
+  *) ok "normal path: no stranded-resume marker" ;;
+esac
+
+echo ""
+echo "$pass passed, $fail_count failed."
+[ "$fail_count" -eq 0 ]

package/lib/test-terminal-cleanup.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# test-terminal-cleanup.sh — regression tests for the terminal-cleanup
+# lifecycle command (the run's last act at every park/fail boundary).
+#
+# Self-contained: builds throwaway git fixtures in a temp dir and drives
+# lib/worktree-lifecycle.sh terminal-cleanup directly (no network, no
+# dashboard). Exits 0 only if every case passes.
+#
+# Contract under test:
+#   - the merge lock is released unconditionally (even when there is
+#     nothing else to reclaim);
+#   - a fully-merged task branch is reclaimed: worktree removed, branch
+#     deleted, registry unregistered, CLEANED: true;
+#   - a branch holding unmerged commits is PRESERVED (dir, branch, and
+#     registry all intact), CLEANED: false;
+#   - a missing branch is a no-op (BRANCH: absent), exit 0;
+#   - a dirty worktree is never force-removed: the failure is reported
+#     loudly (WORKTREE: remove-failed), the registry is kept, and
+#     CLEANED: false.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIFECYCLE="$SCRIPT_DIR/worktree-lifecycle.sh"
+
+pass=0
+fail=0
+ok() { echo "PASS: $1"; pass=$((pass + 1)); }
+no() { echo "FAIL: $1"; fail=$((fail + 1)); }
+
+TMPBASE="/home/hatch/workspace/.tmp-terminal-cleanup-test-$$"
+rm -rf "$TMPBASE"
+mkdir -p "$TMPBASE"
+trap 'rm -rf "$TMPBASE"' EXIT
+
+# Keep merge-lock.sh's audit log out of the real $CREW_HOME during tests,
+# and point the lifecycle seam at this repo's lib/.
+export CREW_HOME="$TMPBASE/home"
+export CREW_LIB="$SCRIPT_DIR"
+# The sweep resolves crew-api.js from the instance ($CREW_HOME/current/lib);
+# this fixture home has no release layout, so point it at this repo's copy.
+export CREW_API="$SCRIPT_DIR/crew-api.js"
+mkdir -p "$CREW_HOME"
+
+# new_fixture <name> — fresh git repo, one commit on main; exports CREW_REPO.
+new_fixture() {
+  local dir="$TMPBASE/$1"
+  mkdir -p "$dir"
+  git init -q -b main "$dir" >/dev/null
+  git -C "$dir" config user.email "test@example.com"
+  git -C "$dir" config user.name "test"
+  echo base > "$dir/seed.txt"
+  git -C "$dir" add seed.txt
+  git -C "$dir" commit -qm "initial"
+  export CREW_REPO="$dir"
+  cd "$dir" || exit 1
+}
+
+# register_project <slug> — register the current fixture repo as a crew
+# project (the sweep enumerates repos from the crew DB, never CREW_REPO).
+register_project() {
+  node "$SCRIPT_DIR/crew-api.js" --crew-home "$CREW_HOME" create-project \
+    --json "{\"id\":\"$1\",\"display_name\":\"$1\",\"repo_path\":\"$CREW_REPO\"}" >/dev/null
+}
+# make_worktree <task_id> — worktree on task/<task_id> with one commit,
+# plus a registry entry (the way prepare would leave it).
+make_worktree() {
+  local t="$1"
+  git worktree add -q ".worktrees/$t" -b "task/$t" >/dev/null
+  echo "$t" > ".worktrees/$t/work.txt"
+  git -C ".worktrees/$t" add work.txt
+  git -C ".worktrees/$t" commit -qm "work for $t"
+  mkdir -p ".worktrees/.registry"
+  printf 'branch=task/%s\npath=%s/.worktrees/%s\n' "$t" "$CREW_REPO" "$t" > ".worktrees/.registry/$t"
+}
+
+# --- Case 1: merged branch is reclaimed and the lock is released ---
+new_fixture case1
+make_worktree t1
+git merge -q --no-ff "task/t1" -m "merge t1" >/dev/null
+# Hold the merge lock the way a run would.
+"$SCRIPT_DIR/merge-lock.sh" acquire t1 "t1/holder" >/dev/null
+out=$(CREW_REPO="$CREW_REPO" CREW_HOME="$CREW_HOME" CREW_LIB="$SCRIPT_DIR" bash "$LIFECYCLE" terminal-cleanup t1 2>&1)
+[ ! -d ".worktrees/t1" ] && ! git show-ref --verify --quiet "refs/heads/task/t1" \
+  && [ ! -f ".worktrees/.registry/t1" ] \
+  && [[ "$out" == *"CLEANED: true"* ]] \
+  && [[ "$out" == *"LOCK: released"* ]] \
+  && [ "$("$SCRIPT_DIR/merge-lock.sh" status)" = "UNLOCKED" ] \
+  && ok "case1: merged branch reclaimed, registry unregistered, lock released" \
+  || no "case1: merged branch reclaimed (out: $out)"
+
+# --- Case 2: unmerged branch is preserved ---
+new_fixture case2
+make_worktree t2
+# NOTE: no merge — the branch holds one commit ahead of main.
+"$SCRIPT_DIR/merge-lock.sh" acquire t2 "t2/holder" >/dev/null
+out=$(CREW_REPO="$CREW_REPO" CREW_HOME="$CREW_HOME" CREW_LIB="$SCRIPT_DIR" bash "$LIFECYCLE" terminal-cleanup t2 2>&1)
+[ -d ".worktrees/t2" ] && git show-ref --verify --quiet "refs/heads/task/t2" \
+  && [ -f ".worktrees/.registry/t2" ] \
+  && [[ "$out" == *"PRESERVED"* ]] \
+  && [[ "$out" == *"CLEANED: false"* ]] \
+  && [ "$("$SCRIPT_DIR/merge-lock.sh" status)" = "UNLOCKED" ] \
+  && ok "case2: unmerged branch preserved, lock still released" \
+  || no "case2: unmerged branch preserved (out: $out)"
+
+# --- Case 3: missing branch is a no-op ---
+new_fixture case3
+out=$(CREW_REPO="$CREW_REPO" CREW_HOME="$CREW_HOME" CREW_LIB="$SCRIPT_DIR" bash "$LIFECYCLE" terminal-cleanup t3 2>&1)
+rc=$?
+[[ "$out" == *"BRANCH: absent"* ]] && [ "$rc" -eq 0 ] \
+  && ok "case3: missing branch is a no-op, exit 0" \
+  || no "case3: missing branch no-op (rc=$rc out: $out)"
+
+# --- Case 4: dirty worktree is never force-removed ---
+new_fixture case4
+make_worktree t4
+git merge -q --no-ff "task/t4" -m "merge t4" >/dev/null
+echo "uncommitted" > ".worktrees/t4/dirty.txt"
+out=$(CREW_REPO="$CREW_REPO" CREW_HOME="$CREW_HOME" CREW_LIB="$SCRIPT_DIR" bash "$LIFECYCLE" terminal-cleanup t4 2>&1)
+[ -d ".worktrees/t4" ] && git show-ref --verify --quiet "refs/heads/task/t4" \
+  && [ -f ".worktrees/.registry/t4" ] \
+  && [ -f ".worktrees/t4/dirty.txt" ] \
+  && [[ "$out" == *"WORKTREE: remove-failed"* ]] \
+  && [[ "$out" == *"CLEANED: false"* ]] \
+  && [[ "$out" != *"WORKTREE: removed"* ]] \
+  && ok "case4: dirty worktree reported loudly, never force-removed" \
+  || no "case4: dirty worktree honesty (out: $out)"
+
+echo ""
+echo "terminal-cleanup: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]

package/lib/test-verify-merge.sh

@@ -32,6 +32,7 @@ git add -A
 git commit -qm init
 
 export CREW_REPO="$T"
+export CREW_HOME="$T/home"  # lifecycle + merge-lock fail closed without both vars
 tid="verifytest1"
 
 # 1. missing branch → ERROR, non-zero