muse-crew 0.14.1 → 0.14.3

package/lib/worktree-lifecycle.sh

@@ -18,9 +18,11 @@
 #   validate  <task_id>                  — check task ID is safe for branches/paths
 #   prepare   <task_id>                  — create worktree + branch, register ownership
 #   resolve-branch <task_id>             — print the resolved task branch name
-#   inspect   <task_id>                  — diff against main for review
-#   integrate <task_id> <commit_msg>     — merge lock → merge into main → report commit
-#   verify-merge <task_id>              — confirm the task branch tip is an ancestor of main (post-step merge check)
+#   inspect   <task_id>                  — diff against the integration target for review
+#   integrate <task_id> <commit_msg>     — merge lock → merge into the integration target → report commit
+#   integration-target                   — print the integration target (branch name, or HEAD when detached)
+#   push-target <task_id>                — refresh lock, push the integration target (skipped loudly on detached HEAD)
+#   verify-merge <task_id>              — confirm the task branch tip is an ancestor of the integration target (post-step merge check)
 #   post-deploy <task_id>                — commit builder artifacts, cleanup, release lock
 #   terminal-cleanup <task_id>         — park/fail boundary: release lock (always), reclaim worktree+branch only when fully merged
 #   cleanup   <task_id>                  — remove worktree + branch (no lock)
@@ -35,7 +37,7 @@
 #   2 — merge lock held by another task; also BLOCKED on unset
 #       CREW_HOME/CREW_REPO (prints a BLOCKED line, never proceeds silently)
 #   3 — merge conflict
-#   4 — dirty main (cannot merge)
+#   4 — dirty integration target (cannot merge)
 
 set -euo pipefail
 
@@ -62,7 +64,7 @@ MERGE_LOCK="$LIB_DIR/merge-lock.sh"
 # on persistent disk — same durability class as $CREW_HOME/.pins/<task>).
 # Written by cmd_integrate (post-reconcile HEAD). Read by cmd_verify_merge
 # (branch-reclamation fallback) and the workflow. Consumers trust a record
-# only after verifying `git merge-base --is-ancestor <merge_commit> main` —
+# only after verifying `git merge-base --is-ancestor <merge_commit> <target-tip>` —
 # a stale record is inert. Removed by cmd_post_deploy (consumed).
 MERGE_RECORDS_DIR="$CREW_HOME/.merge-records"
 
@@ -135,9 +137,48 @@ validate_task_id() {
   return 0
 }
 
-require_clean_main() {
+# Prints the integration target: the current branch name, or "HEAD" when
+# the repo sits on a detached HEAD. Clean-room staging pins the reviewed SHA
+# and commits crew-init on top -- there is no branch to check out, and
+# checking one out would abandon the staged line and break the stamped
+# provenance (room #21, J3: require_clean_main's `git checkout main`
+# discarded the detached crew-init commit; Publish then failed closed on
+# ancestry). Every merge/verify/push operation resolves the target through
+# this helper. The workflow NEVER checks out a branch.
+integration_target() {
   cd "$REPO"
-  git checkout main 2>/dev/null
+  git rev-parse --abbrev-ref HEAD 2>/dev/null || { echo "ERROR: cannot resolve HEAD"; return 1; }
+}
+
+# Resolve the remote branch a detached HEAD pushes to: the remote's default
+# branch (origin/HEAD). Prints the bare branch name (no origin/ prefix).
+# Attached checkouts never need this (their target IS the branch name).
+# Fails when the destination is genuinely unknowable -- the caller fails
+# closed (never a silent skip, never a refusal of a knowable push).
+# (2026-09-19 detached-HEAD audit REDO: the old code treated detached+remote
+# as PUSH_SKIPPED->PASS "by policy", hiding merged work that never reached
+# the remote. The contract is explicit HEAD:<destination> semantics.)
+resolve_push_destination() {
+  cd "$REPO"
+  local sym
+  sym=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null) || {
+    echo "ERROR: detached HEAD with an origin remote, but origin/HEAD is not set -- the push destination is genuinely unknowable; set it (git remote set-head origin -a) and retry -- not pushing"
+    return 1
+  }
+  printf '%s\n' "${sym#origin/}"
+}
+
+# (2026-09-19 REVIEW: the old integration_tip() helper is deleted — it had
+# zero call sites and cmd_verify_merge reimplemented tip resolution inline
+# with different semantics, a drift hazard. Tip resolution lives in exactly
+# two places now: cmd_integrate/cmd_push_target resolve the target name via
+# integration_target(); cmd_verify_merge resolves the live tip directly.)
+
+require_clean_target() {
+  cd "$REPO"
+  # NOTE: no `git checkout` here, ever. The integration target is the repo's
+  # current checkout (branch or detached HEAD); moving it would break the
+  # publish-base provenance the workflow stamped at task start.
   # The crew's own worktree dir is crew state, not user changes: exclude it
   # from the cleanliness check. (2026-09-17: 0.9.0 failed closed on every
   # target repo whose .gitignore doesn't cover .worktrees/ — which is every
@@ -147,7 +188,9 @@ require_clean_main() {
   local dirty
   dirty=$(git status --porcelain 2>/dev/null | grep -vE "^.{3}$wt_esc(/|$)" | wc -l)
   if [ "$dirty" -gt 0 ]; then
-    echo "ERROR: main has $dirty uncommitted changes"
+    local target
+    target=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "?")
+    echo "ERROR: integration target $target has $dirty uncommitted changes"
     git status --short
     return 1
   fi
@@ -194,8 +237,8 @@ cmd_prepare() {
     return 0
   fi
 
-  # Preflight: main must be clean — prepare fails closed.
-  require_clean_main || exit 4
+  # Preflight: the integration target must be clean — prepare fails closed.
+  require_clean_target || exit 4
 
   local base_commit
   base_commit=$(git rev-parse HEAD)
@@ -242,52 +285,30 @@ cmd_inspect() {
   tip=$(git rev-parse "$branch")
   echo "TIP: $tip"
   echo ""
-  echo "=== Commits ahead of main ==="
-  git log --oneline "main..$branch"
+  local target
+  target=$(integration_target) || return 1
+  echo "=== Integration target: $target ==="
   echo ""
-  echo "=== Diff: main...$branch ==="
-  git diff --stat "main...$branch"
+  echo "=== Commits ahead of $target ==="
+  git log --oneline "$target..$branch"
   echo ""
-  git diff "main...$branch"
+  echo "=== Diff: $target...$branch ==="
+  git diff --stat "$target...$branch"
+  echo ""
+  git diff "$target...$branch"
 }
 
-cmd_integrate() {
+# Acquire the merge lock with bounded backoff (serializes version assignment
+# across concurrent runs). The holder is the opaque task+run identity from
+# WORKFLOW_RUN_ID — never a PID (bug 2fc8f52f: short-lived agent PIDs made
+# every concurrent acquire take the stale path). Another task mid
+# Integrate/Publish is normal under simultaneity>1: bounded backoff (30s
+# sleeps, 10min cap, overridable via MERGE_LOCK_RETRY_SECS /
+# MERGE_LOCK_RETRY_CAP_SECS), then give up with LOCK_HELD so the workflow
+# records the failure with a reason (dispatcher retries under its cap, parks
+# after the cap). Returns 2 on LOCK_HELD / LOCK_ERROR; the caller exits.
+acquire_merge_lock() {
   local task_id="$1"
-  local commit_msg="${2:-merge: $task_id}"
-  validate_task_id "$task_id"
-
-  local branch
-  branch=$(resolve_branch "$task_id")
-
-  cd "$REPO"
-
-  # Preflight: main must be clean
-  require_clean_main || exit 4
-
-  # Verify task branch exists and has commits ahead of main
-  if ! git rev-parse --verify "$branch" >/dev/null 2>&1; then
-    echo "ERROR: branch $branch does not exist"
-    return 1
-  fi
-
-  local ahead
-  ahead=$(git rev-list --count "main..$branch")
-  if [ "$ahead" -eq 0 ]; then
-    # Approved empty diff: the deliverable was runtime state (cron,
-    # scheduler, dashboard config), not a repo change. Nothing to merge,
-    # nothing to serialize — the merge lock is intentionally not taken.
-    echo "MERGED_EMPTY: $branch has no commits ahead of main — runtime-state deliverable, nothing to merge"
-    return 0
-  fi
-
-  # Acquire the merge lock (serializes version assignment across concurrent
-  # runs). The holder is the opaque task+run identity from WORKFLOW_RUN_ID —
-  # never a PID (bug 2fc8f52f: short-lived agent PIDs made every concurrent
-  # acquire take the stale path). Another task mid Integrate/Publish is
-  # normal under simultaneity>1: bounded backoff (30s sleeps, 10min cap,
-  # overridable via MERGE_LOCK_RETRY_SECS / MERGE_LOCK_RETRY_CAP_SECS), then
-  # give up with LOCK_HELD so the workflow records the failure with a reason
-  # (dispatcher retries under its cap, parks after the cap).
   local holder="${WORKFLOW_RUN_ID:-$task_id}"
   local retry_secs="${MERGE_LOCK_RETRY_SECS:-30}"
   local retry_cap="${MERGE_LOCK_RETRY_CAP_SECS:-600}"
@@ -296,25 +317,176 @@ cmd_integrate() {
   while true; do
     if lock_result=$("$MERGE_LOCK" acquire "$task_id" "$holder"); then
       echo "$lock_result"
-      break
+      return 0
     fi
     case "$lock_result" in
       HELD*)
         if [ "$waited" -ge "$retry_cap" ]; then
           echo "LOCK_HELD: $lock_result (waited ${waited}s of ${retry_cap}s backoff)"
-          exit 2
+          return 2
         fi
         sleep "$retry_secs"
         waited=$((waited + retry_secs))
         ;;
       *)
         echo "LOCK_ERROR: $lock_result"
-        exit 2
+        return 2
         ;;
     esac
   done
+}
+
+# Deterministic push of the integration target. Called inline by
+# cmd_integrate on the main path (the lock was just acquired there — no
+# refresh needed) and by cmd_push_target for the R5 manual-conflict path
+# (which refreshes the lock first). Never force-pushes.
+#
+# The caller must hold the merge lock. Prints one of PUSHED /
+# NO_REMOTE_PUSH and returns 0, or prints PUSH_FAILED / CONFLICT / ERROR
+# and returns 1 as labeled. (PUSH_SKIPPED belongs to cmd_push_target's
+# nothing-merged path only -- F-R3.) The push
+# refspec is always explicit: a branch pushes as <branch>, a detached HEAD
+# pushes as HEAD:<destination> where the destination is the remote's
+# default branch resolved by resolve_push_destination() -- never a silent
+# skip (2026-09-19 detached-HEAD audit REDO: PUSH_SKIPPED->PASS on
+# detached+remote hid merged work that never reached the remote).
+do_push() {
+  local task_id="$1"
+  cd "$REPO"
+
+  local target
+  target=$(integration_target) || return 1
+
+  # No remote configured: fail soft, loudly. (2026-09-19 REVIEW: the old
+  # code ran `git push origin` unconditionally, which exits 128 with no
+  # origin, got mislabeled PUSH_REJECTED, and failed the phase — while
+  # cmd_integrate on the same repo had already reported MERGED with a
+  # fail-soft NO_REMOTE. A branch-based repo without a remote could never
+  # pass Integrate.)
+  if ! git remote get-url origin >/dev/null 2>&1; then
+    echo "NO_REMOTE_PUSH: no origin remote configured -- nothing to push"
+    return 0
+  fi
+
+  # Attached: branch name; detached: remote default branch via resolve_push_destination() (see header).
+  local dest refspec
+  if [ "$target" = "HEAD" ]; then
+    # Surface the resolver's reason: the caller cannot remediate a swallowed
+    # failure, and the retry-promise below must not lie about it (F-R1).
+    dest=$(resolve_push_destination) || { echo "$dest"; return 1; }
+    refspec="HEAD:$dest"
+  else
+    dest="$target"
+    refspec="$target"
+  fi
+
+  if git push origin "$refspec" 2>&1; then
+    echo "PUSHED: origin/$dest (refspec $refspec)"
+    return 0
+  fi
+
+  # Push failed. Do not assert a cause (the old code labeled every failure
+  # "non-fast-forward" — auth errors got the same label). Recover
+  # mechanically while the lock is held: fetch, merge, retry once.
+  echo "PUSH_FAILED: push did not complete -- reconciling once while the lock is held"
+  if ! git fetch origin "$dest" 2>&1; then
+    echo "ERROR: git fetch origin $dest failed -- push not completed"
+    return 1
+  fi
+  if ! git merge --no-edit "origin/$dest" -m "merge: push-time reconcile ($task_id)" 2>&1; then
+    echo "CONFLICT: origin/$dest diverged with conflicting changes -- aborting"
+    git merge --abort 2>/dev/null || true
+    return 1
+  fi
+  if git push origin "$refspec" 2>&1; then
+    echo "PUSHED: origin/$dest (refspec $refspec, after reconcile)"
+    return 0
+  fi
+  echo "ERROR: push failed again after reconcile -- not pushing"
+  return 1
+}
+
+cmd_integrate() {
+  local task_id="$1"
+  local commit_msg="${2:-merge: $task_id}"
+  validate_task_id "$task_id"
+
+  local branch
+  branch=$(resolve_branch "$task_id")
+
+  cd "$REPO"
+
+  # Preflight: the integration target must be clean
+  require_clean_target || exit 4
+
+  # Verify task branch exists and has commits ahead of the integration target
+  if ! git rev-parse --verify "$branch" >/dev/null 2>&1; then
+    echo "ERROR: branch $branch does not exist"
+    return 1
+  fi
+
+  local target
+  target=$(integration_target) || exit 1
+
+  # Staged-base guard (2026-09-19 REVIEW): the integration line must still
+  # descend from the staged publish base. Catches a stray checkout that
+  # redirected the line (room #21 J3: `git checkout main` abandoned the
+  # detached reviewed-SHA ancestry) BEFORE the merge lands on the wrong
+  # line — Publish's ancestry check is the backstop, not the guard.
+  # CREW_STAGED_BASE is ferried by the workflow from get-provenance; empty
+  # means no provenance is stamped and the check is skipped.
+  if [ -n "${CREW_STAGED_BASE:-}" ]; then
+    if ! git merge-base --is-ancestor "$CREW_STAGED_BASE" HEAD 2>/dev/null; then
+      echo "STAGED_BASE_MISMATCH: staged base $CREW_STAGED_BASE is not an ancestor of HEAD $(git rev-parse HEAD 2>/dev/null) -- the integration line was redirected; refusing to merge"
+      return 1
+    fi
+    echo "STAGED_BASE_OK: $CREW_STAGED_BASE is an ancestor of HEAD"
+  fi
+
+  local ahead
+  ahead=$(git rev-list --count "$target..$branch")
+  if [ "$ahead" -eq 0 ]; then
+    # Merged-but-unpushed recovery (2026-09-19 REVIEW): a prior attempt's
+    # merge landed but its push never completed. Take the lock and push now
+    # instead of reporting MERGED_EMPTY — otherwise the retry loop parks
+    # the task with the work stranded and no path ever pushes it.
+    # The check is ancestor-based, not equality-based: if a prior attempt's
+    # push failed, do_push's retry path may have added a reconcile merge
+    # on top of the recorded commit before failing again. Equality would
+    # miss that and fall through to MERGED_EMPTY — reporting PASS while the
+    # push never happened.
+    local record_file="$MERGE_RECORDS_DIR/$task_id"
+    local recorded_commit=""
+    if [ -f "$record_file" ]; then
+      recorded_commit=$(grep "^merge_commit=" "$record_file" | tail -1 | cut -d= -f2-)
+    fi
+    local live_head
+    live_head=$(git rev-parse HEAD)
+    if [ -n "$recorded_commit" ] && git merge-base --is-ancestor "$recorded_commit" "$live_head" 2>/dev/null; then
+      acquire_merge_lock "$task_id" || exit 2
+      if do_push "$task_id"; then
+        echo "MERGED: $recorded_commit (recovered: merge landed in a prior attempt; push completed now)"
+      else
+        echo "ERROR: push recovery failed for previously-merged $recorded_commit"
+        return 1
+      fi
+      echo "LOCK: held by $task_id — release after deploy with post-deploy"
+      return 0
+    fi
+    # Approved empty diff: the deliverable was runtime state (cron,
+    # scheduler, dashboard config) or an already-merged sha the workflow
+    # verified — not a repo change. Nothing to merge, nothing to serialize —
+    # the merge lock is intentionally not taken.
+    echo "MERGED_EMPTY: $branch has no commits ahead of $target — runtime-state deliverable or verified already-merged sha, nothing to merge"
+    return 0
+  fi
+
+  acquire_merge_lock "$task_id" || exit 2
 
-  # Merge
+  # Merge into the integration target: the repo's current checkout. No
+  # `git checkout` anywhere in this flow — on a detached HEAD (clean-room
+  # staging) the merge advances the detached HEAD itself, preserving the
+  # publish-base ancestry Publish verifies.
   if ! git merge --no-ff "$branch" -m "$commit_msg" 2>&1; then
     echo "CONFLICT: merge failed — aborting"
     git merge --abort 2>/dev/null || true
@@ -322,24 +494,30 @@ cmd_integrate() {
   fi
 
   # Reconcile with the remote while the merge lock is still held. Another
-  # writer (a second crew instance, direct pushes) can land commits on
-  # origin/main outside this lock; pushing a stale main then fails
-  # non-fast-forward and the Integrate phase fails closed. Fetch and merge
-  # origin/main now so the agent's subsequent push is a fast-forward.
+  # writer (a second crew instance, direct pushes) can land commits on the
+  # remote branch outside this lock; pushing a stale branch then fails and
+  # the Integrate phase fails closed. Fetch and merge the remote branch now
+  # so the subsequent push is a fast-forward.
   # Fail-soft when there is no remote; fail closed on a real conflict.
-  if git rev-parse --verify "origin/main" >/dev/null 2>&1; then
-    if git fetch origin main 2>&1; then
-      if ! git merge --no-edit "origin/main" -m "merge: reconcile with origin/main before push ($task_id)" 2>&1; then
-        echo "CONFLICT: origin/main diverged with conflicting changes — aborting"
+  # Detached: there is no static branch target to reconcile against inline;
+  # do_push resolves the destination explicitly and reconciles on push
+  # failure, so the inline reconcile is skipped here (F-R2 -- the old
+  # "local by design" rationale is the rejected 0.14.2 policy).
+  if [ "$target" = "HEAD" ]; then
+    echo "NO_REMOTE_RECONCILE: detached HEAD -- destination resolved explicitly by do_push, skipping inline reconcile"
+  elif git rev-parse --verify "origin/$target" >/dev/null 2>&1; then
+    if git fetch origin "$target" 2>&1; then
+      if ! git merge --no-edit "origin/$target" -m "merge: reconcile with origin/$target before push ($task_id)" 2>&1; then
+        echo "CONFLICT: origin/$target diverged with conflicting changes — aborting"
         git merge --abort 2>/dev/null || true
         exit 3
       fi
-      echo "RECONCILED: merged origin/main into main"
+      echo "RECONCILED: merged origin/$target into $target"
     else
       echo "WARNING: git fetch origin failed — pushing without remote reconcile; the push step may report non-fast-forward"
     fi
   else
-    echo "NO_REMOTE: no origin/main — skipping remote reconcile"
+    echo "NO_REMOTE: no origin/$target — skipping remote reconcile"
   fi
 
   local merged_commit
@@ -348,13 +526,23 @@ cmd_integrate() {
 
   # Record the merge commit (merge-lease fix, 2026-09-12): if the branch is
   # later reclaimed (e.g. under an expired lease), verify-merge can still
-  # confirm the merge landed from this record. Append-only, on persistent disk.
+  # confirm the merge landed from this record. Append-only, on persistent
+  # disk. One atomic printf (not three appends — a torn write against a
+  # concurrent reader is benign today but not worth the risk), and cut
+  # -d= -f2- on read so values containing `=` survive.
   mkdir -p "$MERGE_RECORDS_DIR"
-  {
-    echo "merge_commit=$merged_commit"
-    echo "merged_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-  } >> "$MERGE_RECORDS_DIR/$task_id"
-  echo "RECORDED: merge commit $merged_commit in $MERGE_RECORDS_DIR/$task_id"
+  printf 'merge_commit=%s\nintegration_target=%s\nmerged_at=%s\n' \
+    "$merged_commit" "$target" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    >> "$MERGE_RECORDS_DIR/$task_id"
+  echo "RECORDED: merge commit $merged_commit (target $target) in $MERGE_RECORDS_DIR/$task_id"
+
+  # Push inline while the lock is held — no agent round-trip (the old STEP 2
+  # agent run added only a lock refresh). R5's manual-conflict path uses the
+  # push-target command instead.
+  if ! do_push "$task_id"; then
+    echo "ERROR: push failed after merge $merged_commit -- merge is recorded; a re-run of push-target retries transient failures, but an unknowable destination needs 'git remote set-head origin -a' (see the ERROR line above -- F-R1)"
+    return 1
+  fi
 
   echo "LOCK: held by $task_id — release after deploy with post-deploy"
 }
@@ -372,17 +560,38 @@ cmd_verify_merge() {
 
   cd "$REPO"
 
+  # The integration target is always the repo's current checkout,
+  # re-resolved NOW — never the merge record's word for it. (2026-09-19
+  # REVIEW: the old code read the target name from the record and, for
+  # target=HEAD, used the record's merge_commit as the tip — so both sides
+  # of the ancestry check came from the same record and is-ancestor(X, X)
+  # certified merges no longer on the line. The tip below is always live.)
+  local target
+  target=$(integration_target) || return 1
+  local target_tip
+  if [ "$target" = "HEAD" ]; then
+    target_tip=$(git rev-parse HEAD 2>/dev/null || echo "")
+  else
+    target_tip=$(git rev-parse --verify "$target" 2>/dev/null || echo "")
+  fi
+  if [ -z "$target_tip" ]; then
+    echo "ERROR: cannot resolve tip of integration target $target"
+    return 1
+  fi
+
+  local record_file="$MERGE_RECORDS_DIR/$task_id"
+
   # If the branch is gone, fall back to the merge record (merge-lease fix,
   # 2026-09-12): the branch may have been reclaimed under an expired lease
   # after the merge landed. The record is trusted only if the recorded
-  # commit is actually an ancestor of main.
+  # commit is actually an ancestor of the integration target's LIVE tip —
+  # never the record's own word for the tip.
   if ! git rev-parse --verify "$branch" >/dev/null 2>&1; then
-    local record_file="$MERGE_RECORDS_DIR/$task_id"
     if [ -f "$record_file" ]; then
       local recorded_commit
-      recorded_commit=$(grep "^merge_commit=" "$record_file" | tail -1 | cut -d= -f2)
-      if [ -n "$recorded_commit" ] && git merge-base --is-ancestor "$recorded_commit" main 2>/dev/null; then
-        echo "VERIFIED: branch $branch gone but recorded merge commit $recorded_commit is an ancestor of main — merge landed"
+      recorded_commit=$(grep "^merge_commit=" "$record_file" | tail -1 | cut -d= -f2-)
+      if [ -n "$recorded_commit" ] && git merge-base --is-ancestor "$recorded_commit" "$target_tip" 2>/dev/null; then
+        echo "VERIFIED: branch $branch gone but recorded merge commit $recorded_commit is an ancestor of $target ($target_tip) — merge landed"
         return 0
       fi
     fi
@@ -393,17 +602,18 @@ cmd_verify_merge() {
   local tip
   tip=$(git rev-parse "$branch")
 
-  # The merge landed iff the task branch tip is an ancestor of main. A
-  # genuine empty-diff Integrate (MERGED_EMPTY: no commits ahead of main)
-  # verifies vacuously — the tip is then main itself or behind it.
-  if git merge-base --is-ancestor "$branch" main 2>/dev/null; then
-    echo "VERIFIED: $branch tip $tip is an ancestor of main — merge landed"
+  # The merge landed iff the task branch tip is an ancestor of the
+  # integration target's tip. A genuine empty-diff Integrate (MERGED_EMPTY:
+  # no commits ahead of the target) verifies vacuously — the tip is then
+  # the target tip itself or behind it.
+  if git merge-base --is-ancestor "$branch" "$target_tip" 2>/dev/null; then
+    echo "VERIFIED: $branch tip $tip is an ancestor of $target ($target_tip) — merge landed"
     return 0
   fi
 
   local ahead
-  ahead=$(git rev-list --count "main..$branch")
-  echo "NOT_MERGED: $branch tip $tip is not an ancestor of main — $ahead commit(s) still ahead of main"
+  ahead=$(git rev-list --count "$target..$branch" 2>/dev/null || echo "?")
+  echo "NOT_MERGED: $branch tip $tip is not an ancestor of $target — $ahead commit(s) still ahead of $target"
   return 1
 }
 
@@ -412,13 +622,17 @@ cmd_post_deploy() {
   validate_task_id "$task_id"
 
   cd "$REPO"
-  git checkout main 2>/dev/null
+  # NOTE: no `git checkout` here, ever. Builder leftovers are committed onto
+  # the integration target (the current checkout) — checking out main would
+  # abandon a detached-HEAD room line exactly the way room #21's Integrate
+  # did, breaking provenance for the next journey in this repo.
 
   # Commit any changes the artifact builder left behind.
   # The crew's own .worktrees/ dir (merge lock, registry) is crew-owned
   # state, never user content — unstage it after the add so a stray lock
-  # file can never be committed into main (J1 canary: .merge-lock landed
-  # in main via add -A). Never use an all-negative pathspec here: on git
+  # file can never be committed into the integration target (J1 canary:
+  # .merge-lock landed in main via add -A). Never use an all-negative
+  # pathspec here: on git
   # 2.43.0 `git add -A -- ':!.worktrees/'` still exits 1 against the
   # crew's own gitignored .worktrees/ (room #15, J3), and set -e then
   # kills post-deploy before "DEPLOYED:". A plain add never errors on
@@ -466,7 +680,7 @@ cmd_post_deploy() {
 # merge lock is a shared resource, so its release is unconditional and
 # forgiving (only the holder can release; anyone else is a no-op). The
 # worktree and branch are reclaimed ONLY when the task branch is fully
-# merged into main — then they are redundant and safe to drop. Anything
+# merged into the integration target — then they are redundant and safe to drop. Anything
 # else is preserved for the human by design: parked work awaiting
 # judgment must survive its run. Never force-removes a dirty worktree:
 # uncommitted work is reported loudly, never silently destroyed.
@@ -489,9 +703,15 @@ cmd_terminal_cleanup() {
     echo "CLEANED: false"
     return 0
   fi
-  if ! git merge-base --is-ancestor "$branch" main 2>/dev/null; then
+  local target
+  if ! target=$(integration_target); then
+    echo "PRESERVED: cannot resolve the integration target — leaving branch for human"
+    echo "CLEANED: false"
+    return 0
+  fi
+  if ! git merge-base --is-ancestor "$branch" "$target" 2>/dev/null; then
     local ahead
-    ahead=$(git rev-list --count "main..$branch" 2>/dev/null || echo "?")
+    ahead=$(git rev-list --count "$target..$branch" 2>/dev/null || echo "?")
     echo "PRESERVED: $branch holds $ahead unmerged commit(s) — left for human"
     echo "CLEANED: false"
     return 0
@@ -591,12 +811,14 @@ cmd_status() {
 
   # Branch existence and merge status
   if git rev-parse --verify "$branch" >/dev/null 2>&1; then
+    local target
+    target=$(integration_target 2>/dev/null || echo "unresolvable")
     local ahead behind
-    ahead=$(git rev-list --count "main..$branch" 2>/dev/null || echo "?")
-    behind=$(git rev-list --count "$branch..main" 2>/dev/null || echo "?")
-    echo "Branch: $branch (${ahead} ahead, ${behind} behind main)"
+    ahead=$(git rev-list --count "$target..$branch" 2>/dev/null || echo "?")
+    behind=$(git rev-list --count "$branch..$target" 2>/dev/null || echo "?")
+    echo "Branch: $branch (${ahead} ahead, ${behind} behind $target)"
     local merged
-    merged=$(git branch --merged main 2>/dev/null | sed 's/^[* +]*//' | grep -Fx "$branch" || true)
+    merged=$(git branch --merged "$target" 2>/dev/null | sed 's/^[* +]*//' | grep -Fx "$branch" || true)
     [ -n "$merged" ] && echo "Merged: yes" || echo "Merged: no"
   else
     echo "Branch: not found"
@@ -633,6 +855,67 @@ cmd_merge_record() {
   fi
 }
 
+# Agent-side one-liner: prints the integration target (branch name, or
+# "HEAD" when detached). Workflow prompts resolve "main" language through
+# this instead of assuming a branch.
+cmd_integration_target() {
+  integration_target
+}
+
+# Agent-side one-liner: prints the remote branch a push updates. Attached:
+# the branch name. Detached: the resolved destination from
+# resolve_push_destination() (fails when genuinely unknowable).
+cmd_push_destination() {
+  local target
+  target=$(integration_target) || exit 1
+  if [ "$target" = "HEAD" ]; then
+    resolve_push_destination
+  else
+    printf '%s\n' "$target"
+  fi
+}
+
+# Deterministic push of the integration target. Thin wrapper over do_push
+# for the R5 manual-conflict path (re-running `integrate` there misfires on
+# ahead=0 -> MERGED_EMPTY, so the manually-merged line still needs a
+# deterministic push). Refreshes the merge lock first: a slow push must not
+# let the lease expire under us. Do not push without the lock.
+#
+# Distinguishes "nothing merged" from "lock lost" (2026-09-19 REVIEW): after
+# a MERGED_EMPTY integrate there is no merge record and no lock — an agent
+# that runs push-target anyway gets a loud skip, not a false "lock lost".
+cmd_push_target() {
+  local task_id="$1"
+  validate_task_id "$task_id"
+
+  cd "$REPO"
+
+  local record_file="$MERGE_RECORDS_DIR/$task_id"
+  if [ ! -f "$record_file" ]; then
+    # No merge record: either MERGED_EMPTY (nothing to push) or the R5
+    # manual path (the lock is still held from the conflicted integrate).
+    # The lock tells them apart.
+    if cmd_refresh_lock "$task_id" >/dev/null 2>&1; then
+      echo "LOCK: refreshed for push (manual-merge path)"
+      do_push "$task_id"
+      return $?
+    fi
+    echo "PUSH_SKIPPED: no merge record for $task_id and no lock held -- nothing was merged, nothing to push"
+    return 0
+  fi
+
+  # Refresh the merge lock first: a slow push must not let the lease expire
+  # under us. Do not push without the lock.
+  if ! cmd_refresh_lock "$task_id" >/dev/null 2>&1; then
+    echo "ERROR: merge lock lost before push -- not pushing without the lock"
+    return 1
+  fi
+  echo "LOCK: refreshed for push"
+
+  do_push "$task_id"
+  return $?
+}
+
 # --- dispatch ---
 
 cmd="${1:-}"
@@ -645,6 +928,9 @@ case "$cmd" in
   inspect)      cmd_inspect "${1:?task_id required}" ;;
   integrate)    cmd_integrate "${1:?task_id required}" "${2:-}" ;;
   verify-merge) cmd_verify_merge "${1:?task_id required}" ;;
+  integration-target) cmd_integration_target ;;
+  push-destination) cmd_push_destination ;;
+  push-target)   cmd_push_target "${1:?task_id required}" ;;
   post-deploy)  cmd_post_deploy "${1:?task_id required}" ;;
   terminal-cleanup) cmd_terminal_cleanup "${1:?task_id required}" ;;
   cleanup)      cmd_cleanup "${1:?task_id required}" ;;
@@ -654,7 +940,7 @@ case "$cmd" in
   merge-record) cmd_merge_record "${1:?task_id required}" ;;
   *)
     echo "Usage: worktree-lifecycle.sh <command> [args]"
-    echo "Commands: validate, prepare, resolve-branch, inspect, integrate, verify-merge, post-deploy, terminal-cleanup, cleanup, status, refresh-lock, lock-status, merge-record"
+    echo "Commands: validate, prepare, resolve-branch, inspect, integrate, integration-target, push-target, verify-merge, post-deploy, terminal-cleanup, cleanup, status, refresh-lock, lock-status, merge-record"
     exit 1
     ;;
 esac

package/package.json

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