bootstrap.py: a leg detached off the pin is left where it is and said, so a commit made there is no longer stranded when its branch is already at the pin, the not moving an existing branch line names where the checkout is, and bump-leg.py and AGENTS-shape.md say "or says why not" (#533)

scripts/bump-leg.py

@@ -1667,7 +1667,8 @@ def cmd_bump(args) -> int:
         + body, args.trailer)
     print(f"\n  committed {head[:12]}: " + ", ".join(staged))
     print(f"  {path}/ is left DETACHED at {commit[:12]}; `make bootstrap` in "
-          "the root re-places it on its tracking branch AT the new pin")
+          "the root puts it on its tracking branch AT the new pin, or says "
+          "why not")
     print(f"\nNEXT  git -C {root} push -u origin {branch}")
     print(f"      then open a pull request against {project.tracking}; never "
           "push the bump to the default branch directly")

templates/assembly-root/AGENTS-shape.md

@@ -83,18 +83,18 @@ script guessing at `../`.
 ## The five commands
 
 ```
-make bootstrap   the legs onto their tracking branch AT the pinned commit,
-                 then the validators, then the review-authority readout
+make bootstrap   puts the legs on their tracking branch AT the pin, or says why
+                 not; then the validators, then the review-authority readout
 make validate    naming + manifest + lockstep pins (what CI runs)
 make pins        the lockstep pin validator alone
 make park        commit, push and RECORD every open feature, so another
                  workstation can take the work up
 make resume      recreate the parked features here, from that record
 ```
 
-`make bootstrap` places each leg on the tracking branch AT its pinned commit —
-not a detached HEAD, and not somebody's newer tip. The line `authority is not
-wallet-carried in this org` is a report, not a fault.
+`make bootstrap` places each leg on its tracking branch AT the pin where that
+loses nothing, and leaves one detached at any other commit, saying why. The
+line `authority is not wallet-carried in this org` is a report, not a fault.
 
 **`make park` BEFORE the human leaves a workstation; on the next one, clone,
 `make bootstrap`, then `make resume`** — that order, because `resume`

templates/assembly-root/scripts/bootstrap.py

@@ -23,11 +23,16 @@
       what git's own recursive clone leaves when the leg's remote has moved
       past the pin, and the remote-tracking ref still holds every commit.
       Any other branch holding a commit the pin does not contain is never
-      moved; bootstrap prints both and leaves them alone. Advancing a pin
-      remains an explicit commit in this repository — see `README.md`, "The
-      lockstep invariant". This is why `.gitmodules` carries no `branch=`:
-      that would buy the same ergonomics by weakening the pin, and then "what
-      commit is this project" would have two answers.
+      moved; bootstrap prints both and leaves them alone. A leg DETACHED at a
+      commit that is not the pin is never moved off it either, whether its
+      branch is at the pin, behind it, ahead of it or not there at all, and
+      whatever the branch or `origin` holds: a commit made there is on no
+      branch, and a checkout would leave it only in the reflog, so bootstrap
+      says where the leg is instead. Advancing a pin remains an explicit commit
+      in this repository — see `README.md`, "The lockstep invariant". This is
+      why `.gitmodules` carries no `branch=`: that would buy the same
+      ergonomics by weakening the pin, and then "what commit is this project"
+      would have two answers.
 
   (b) RUNS THE NEUTRAL VALIDATORS — naming, manifest, lockstep pins. These are
       the only ones a fork with no review lane and no wallet register has, and
@@ -243,15 +248,54 @@
     print(NOTHING_ELSE)
 
 
-def _say_after(why: list[str] | None) -> None:
+def _say_after(why: list[str] | None, moved: bool = True) -> None:
     """What git said when it exited non-zero AFTER HEAD reached the branch
     (a failing post-checkout hook): the move happened and its line has been
-    printed, so git's words follow it as they are, not as a refusal."""
+    printed, so git's words follow it as they are, not as a refusal.
+
+    `moved` is whether the checkout changed where HEAD is. HEAD already on
+    the branch at the pin, there was nothing to check out, so `checked out,
+    and then git said:` over a stale `.git/index.lock` was false (#533). What
+    is true of that state whatever git exited over (a stale lock, a failing
+    post-checkout hook, an unmerged index) is that there was nothing to check
+    out, so that is what it says, and never `refused`: a hook failing is not
+    a refusal. Git's lines follow either way: the same lock blocks the
+    person's next commit.
+    """
     if why:
-        print("          checked out, and then git said:")
+        print("          checked out, and then git said:" if moved else
+              "          nothing to check out, and then git said:")
         _say_lines(why)
 
 
+def _place_of(current: str | None) -> str:
+    """Where HEAD is, for a line that names it: `detached`, or `on <branch>`
+    with the branch spelled (#391)."""
+    if current is None:
+        return "detached"
+    return "on " + spelled(current.split("refs/heads/", 1)[-1])
+
+
+def _say_keep(options: str = "the pin or the branch") -> None:
+    """What to do about a checkout step (a) will not move, in the words
+    both refusals of it share. Nothing moves."""
+    print("          not moving the checkout off it. Keep any commit made "
+          f"there on a branch, check out {options} in the leg, and run "
+          "bootstrap again.")
+
+
+def _say_neither(label: str, state: str, head: str | None,
+                 current: str | None) -> None:
+    """The checkout is not one a move starts from: `state` says what the
+    branch is to the pin, and the line names where the leg stands instead.
+    Nothing moves. A commit made on a leg detached off the pin is on no
+    branch, so checking the branch out would leave it only in the reflog,
+    and a leg on another branch is somebody's work."""
+    print(f"  {label}: {state}, and the checkout is at {_short(head)} "
+          f"({_place_of(current)}), which is neither")
+    _say_keep()
+
+
 def place_at_pin(sub: Path, label: str, branch: str, pin: str) -> None:
     """Step (a) for a leg whose tracking branch IS the pin: check it out,
     and say `on <branch>` only when HEAD is on it afterwards.
@@ -261,15 +305,29 @@
     leg left detached (a stale `index.lock`) or on another branch (a local
     edit in the way): the next commit made there was on no branch, or on
     the wrong one, under a line saying otherwise.
+
+    HEAD is read first (#533). Detached at a commit that is NOT the pin, the
+    leg is left there, as `fast_forward_to_pin` leaves it. `bump-leg.py` to
+    a branch's own tip, then a commit made on the detached leg, then
+    bootstrap, checked the branch out and printed `on <branch> at <pin>`
+    over a commit that was then on no branch, held by HEAD's reflog alone.
+    Detached AT the pin, or already on the branch, the checkout is as it was.
+    On ANOTHER branch it is as it was too: that branch holds its commits.
     """
     named = spelled(branch)
+    head, current = _head_of(sub)
+    if current is None and head != pin:
+        _say_neither(label, f"branch {named} is at the pin {_short(pin)}",
+                     head, current)
+        return
+    already = (head, current) == (pin, f"refs/heads/{branch}")
     placed, why = _check_out(sub, branch, pin)
     if not placed:
         _say_refused(f"  {label}: branch {named} is at the pin "
                      f"{_short(pin)}, and git refused to check it out:", why)
         return
     print(f"  {label}: on {named} at {_short(pin)} (branch tip == pin)")
-    _say_after(why)
+    _say_after(why, moved=not already)
 
 
 def fast_forward_to_pin(sub: Path, label: str, branch: str, local: str,
@@ -310,15 +368,8 @@
     elif current is None and head == pin:
         moved, placed, why = _move_and_check_out(sub, branch, pin)
     else:
-        place = "detached"
-        if current is not None:
-            place = "on " + spelled(current.split("refs/heads/", 1)[-1])
-        print(f"  {label}: branch {named} tip {_short(local)} is behind the "
-              f"PIN {_short(pin)}, and the checkout is at {_short(head)} "
-              f"({place}), which is neither")
-        print("          not moving the checkout off it. Keep any commit made "
-              "there on a branch, check out the pin or the branch in the "
-              "leg, and run bootstrap again.")
+        _say_neither(label, f"branch {named} tip {_short(local)} is behind "
+                     f"the PIN {_short(pin)}", head, current)
         return
     if not placed:
         if moved:
@@ -390,7 +441,22 @@
     _say_after(why)
 
 
+def _stays(sub: Path, branch: str, pin: str) -> str:
+    """Where the checkout stays, for the `not moving an existing branch`
+    line (#533): `on <branch> at its tip` when HEAD is on the branch that
+    holds the commits the pin lacks, `at the pin` when it is detached there,
+    and else `at <sha> (detached)` or `at <sha> (on <other branch>)`, as
+    `_say_neither` names the place. The line said `at the pin` whatever the
+    checkout was, which was false for a HEAD on the branch itself."""
+    head, current = _head_of(sub)
+    if current == f"refs/heads/{branch}":
+        return f"on {spelled(branch)} at its tip"
+    if current is None and head == pin:
+        return "at the pin"
+    return f"at {_short(head)} ({_place_of(current)})"
+
+
 def checkout_tracking_branch(root: Path, leg: dict, branch: str) -> None:
     """Step (a) for one leg. Prints; never raises; never moves the pin."""
     path = str(leg.get("path") or "")
     sub = root / path
@@ -413,6 +479,19 @@
         if pin is None:
             print(f"  {where}: no gitlink recorded; leaving as is")
             return
+        head, current = _head_of(sub)
+        if head is not None and current is None and head != pin:
+            # `checkout -b <branch> <pin>` from a leg detached anywhere else
+            # leaves the commit made there on no branch (#533), as placing a
+            # branch that exists would. The branch is not there to check
+            # out, so the way out names the pin alone. A HEAD git cannot
+            # read (the leg's gitdir is gone) is no commit to keep: the
+            # checkout below fails, and says it could not.
+            print(f"  {where}: branch {named} does not exist, and the "
+                  f"checkout is at {_short(head)} (detached), which is not "
+                  f"the pin {_short(pin)}")
+            _say_keep("the pin")
+            return
         if _try_git(["checkout", "-q", "-b", branch, pin], sub) is None:
             print(f"  {where}: could not create branch {branch!r} at "
                   f"the pin {_short(pin)}; leaving detached")
@@ -443,9 +522,9 @@
 
     print(f"  {where}: PIN {_short(pin)} != branch {named} tip "
           f"{_short(local)}")
-    print("          not moving an existing branch. The checkout stays at "
-          "the pin; the recorded pin is authoritative and advancing it is an "
-          "explicit commit in this repository.")
+    print("          not moving an existing branch. The checkout stays "
+          f"{_stays(sub, branch, pin)}; the recorded pin is authoritative "
+          "and advancing it is an explicit commit in this repository.")
 
 
 def shape_upstream_notice(root: Path) -> None: