The mode table listed four writes but omitted submodule sync after a
fast-forward and first-party selector moves, which leave unstaged Gitlink
changes even without a fast-forward.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@@ -16,3 +16,3 @@
 | Request | Flags | What changes |
 | --- | --- | --- |
-| Audit, clean up, "which are behind" | none | Fetch and prune `origin`; fast-forward eligible default checkouts; prune stale worktree registrations; remove proven-merged linked worktrees inside the root. |
+| Audit, clean up, "which are behind" | none | Fetch and prune `origin`; fast-forward eligible default checkouts and sync their submodules; in first-party default checkouts, move submodules to their configured branch or tag, leaving the Gitlink change unstaged; prune stale worktree registrations; remove proven-merged linked worktrees inside the root. |

@@ -23,3 +23,4 @@
 
 - A repository whose work integrates somewhere other than `origin/<default>`, such as a fork with an `upstream`: `--no-remove`. Removal proves containment against `origin/<default>` only.
 - A repository with a custom `origin` fetch refspec: `--no-fetch --no-remove`. The fetch prunes every `refs/remotes/origin/*` ref that no server branch supplies (see [references/checkout-updates.md](references/checkout-updates.md)).
+- A first-party checkout whose submodules must stay where they are: `--no-fetch --no-remove`. Selector moves happen even without a fast-forward, and `update = none` does not stop the post-fast-forward sync.

@@ -23,3 +23,4 @@
 
 - A repository whose work integrates somewhere other than `origin/<default>`, such as a fork with an `upstream`: `--no-remove`. Removal proves containment against `origin/<default>` only.
 - A repository with a custom `origin` fetch refspec: `--no-fetch --no-remove`. The fetch prunes every `refs/remotes/origin/*` ref that no server branch supplies (see [references/checkout-updates.md](references/checkout-updates.md)).
+- A first-party checkout whose submodules must stay where they are: `--no-fetch --no-remove`. The driver moves branch- or tag-tracked submodules even when nothing fast-forwards, and `update = none` stops only that move, not the checkout at recorded commits after a fast-forward.

@@ -5,3 +5,3 @@
 ## What the driver already updates
 
-The driver fast-forwards a default-branch checkout only when its comparison is fresh, it has no local commits, and it is strictly behind `origin/<default>`. A dirty checkout qualifies only when every changed path is deferred guidance (`AGENTS.md`, `.agents/**`, at any depth) or first-party `.gitmodules`/Gitlink maintenance, and upstream did not touch those paths. The merge runs `--ff-only` with `merge.autostash=false`, because autostash would round-trip the tree through a stash and silently unstage staged guidance. After a fast-forward it synchronizes committed submodules to the recorded Gitlinks.
+The driver fast-forwards a default-branch checkout only when its comparison is fresh, it has no local commits, and it is strictly behind `origin/<default>`. A dirty checkout qualifies only when every changed path is deferred guidance (`AGENTS.md`, `.agents/**`, at any depth) or first-party `.gitmodules`/Gitlink maintenance whose submodule commit some ref holds, and upstream did not touch those paths. The merge runs `--ff-only` with `merge.autostash=false`, because autostash would round-trip the tree through a stash and silently unstage staged guidance. After a fast-forward it initializes committed submodules and checks them out at the recorded Gitlinks.

@@ -18,3 +18,3 @@
 
 - **Under a `third-party/` path component:** `.gitmodules` and Gitlinks belong to upstream. Never add or change selectors, URLs, paths, update policies, or Gitlinks; only synchronize what upstream committed.
-- **Everywhere else (first-party):** each submodule needs exactly one selector, `branch = <name>` for a moving line or `tag = <name>` for an exact release. On fresh eligible default checkouts the driver fetches that branch or tag, checks the submodule out detached, and leaves the Gitlink change unstaged for the owner's next commit.
+- **Everywhere else (first-party):** each submodule needs exactly one selector, `branch = <name>` for a moving line or `tag = <name>` for an exact release. On fresh eligible default checkouts the driver fetches that branch or tag, checks the submodule out detached, and leaves the Gitlink change unstaged for the owner's next commit. A submodule checked out at a commit that is neither the recorded Gitlink nor held by any ref stays where it is, and its checkout is reported for a decision. A local tag whose commit no other ref holds is never replaced; the selector update fails and says so.

@@ -478,0 +504,5 @@
+  fetched_object=$(git -C "$submodule_path" rev-parse --verify --quiet FETCH_HEAD 2>>"$error_path") || return 1
+  fetched_commit=$(git -C "$submodule_path" rev-parse --verify --quiet "FETCH_HEAD^{commit}" 2>>"$error_path") || return 1
+  local_commit=$(git -C "$submodule_path" rev-parse --verify --quiet "refs/tags/$tag^{commit}" 2>/dev/null || true)
+  if [ -n "$local_commit" ] && [ "$local_commit" != "$fetched_commit" ] \
+    && [ -z "$(git -C "$submodule_path" for-each-ref --format='%(refname)' --contains "$local_commit" 2>/dev/null | grep -v -x -F "refs/tags/$tag")" ]; then

@@ -1123,0 +1212,7 @@
+  git(upstreamSuperprojectPath, "commit", "--quiet", "-m", "non-overlapping upstream change");
+  git(superprojectPath, "fetch", "--quiet", upstreamSuperprojectPath, "HEAD:refs/remotes/origin/main");
+
+  const result = audit();
+  assert.equal(result.fastForward.attempted, false);
+  assert.equal(result.trackingUpdate.attempted, false);
+  assert.equal(git(dependencyPath, "rev-parse", "HEAD").trim(), localCommit);

@@ -16,3 +16,3 @@
 | Request | Flags | What changes |
 | --- | --- | --- |
-| Audit, clean up, "which are behind" | none | Fetch and prune `origin`; fast-forward eligible default checkouts; prune stale worktree registrations; remove proven-merged linked worktrees inside the root. |
+| Audit, clean up, "which are behind" | none | Fetch and prune `origin`; fast-forward eligible default checkouts, then initialize their submodules and check them out at the recorded commits; in first-party default checkouts, check submodules out at their configured branch or tag, leaving the Gitlink change unstaged; prune stale worktree registrations; remove proven-merged linked worktrees inside the root. |

@@ -23,3 +23,4 @@
 
 - A repository whose work integrates somewhere other than `origin/<default>`, such as a fork with an `upstream`: `--no-remove`. Removal proves containment against `origin/<default>` only.
 - A repository with a custom `origin` fetch refspec: `--no-fetch --no-remove`. The fetch prunes every `refs/remotes/origin/*` ref that no server branch supplies (see [references/checkout-updates.md](references/checkout-updates.md)).
+- A first-party checkout whose submodules must stay where they are: `--no-fetch --no-remove`. The driver moves branch- or tag-tracked submodules even when nothing fast-forwards, and `update = none` stops only that move; after a fast-forward the driver still checks each submodule out at its recorded commit.

@@ -22,8 +22,11 @@ usage() {
   echo "  git fetch --prune origin; git worktree prune (repository-wide, including outside root);"

@@ -478,0 +503,7 @@
+
+  fetched_object=$(git -C "$submodule_path" rev-parse --verify --quiet FETCH_HEAD 2>>"$error_path") || return 1
+  fetched_commit=$(git -C "$submodule_path" rev-parse --verify --quiet "FETCH_HEAD^{commit}" 2>>"$error_path") || return 1
+  local_commit=$(git -C "$submodule_path" rev-parse --verify --quiet "refs/tags/$tag^{commit}" 2>/dev/null || true)
+  if [ -n "$local_commit" ] && [ "$local_commit" != "$fetched_commit" ] \
+    && ! git -C "$submodule_path" merge-base --is-ancestor "$local_commit" "$fetched_commit" 2>/dev/null \
+    && [ -z "$(git -C "$submodule_path" for-each-ref --format='%(refname)' --contains "$local_commit" 2>/dev/null | grep -v -x -F "refs/tags/$tag")" ]; then

@@ -509,5 +548,7 @@
     [ "$update_mode" != none ] || continue
 
-    if ! git -C "$checkout_path" submodule update --init --checkout -- "$configured_path" >>"$output_path" 2>>"$error_path"; then
+    submodule_path="$checkout_path/$configured_path"
+    if [ ! -e "$submodule_path/.git" ] \
+      && ! git -C "$checkout_path" submodule update --init --checkout -- "$configured_path" >>"$output_path" 2>>"$error_path"; then
       return 1
     fi

@@ -1414,11 +1460,20 @@ audit_worktree() {
   write_submodule_metadata "$worktree_path" "$submodule_metadata_path"
   submodule_metadata_ok=$(jq -r '.ok' "$submodule_metadata_path")
 
+  if [ "$outside_root" = false ] && [ -f "$worktree_path/.gitmodules" ]; then
+    if stranded_output=$(list_stranded_submodule_commits "$worktree_path" 2>/dev/null); then

@@ -310,6 +312,12 @@ export function formatAuditReport(report: AuditReport): string {
 
       const isMain = worktree.registration?.isMain === true;
       const onDefault = worktree.status?.branch.isDetached === false && worktree.status.branch.current === defaultBranch;
+      if ((isMain || onDefault) && worktree.strandedSubmodules?.length !== 0) {
+        const stranded = worktree.strandedSubmodules;
+        const why = stranded === null ? "submodule check failed" : `submodule on a commit no ref holds: ${listPaths(stranded)}`;

@@ -16,3 +16,3 @@
 | Request | Flags | What changes |
 | --- | --- | --- |
-| Audit, clean up, "which are behind" | none | Fetch and prune `origin`; fast-forward eligible default checkouts; prune stale worktree registrations; remove proven-merged linked worktrees inside the root. |
+| Audit, clean up, "which are behind" | none | Fetch and prune `origin`; fast-forward eligible default checkouts, then initialize their submodules and check them out at the recorded commits; in first-party default checkouts, check each submodule listed in the checkout's own `.gitmodules` out at its configured branch or tag, leaving the Gitlink change unstaged; prune stale worktree registrations; remove proven-merged linked worktrees inside the root. |

@@ -23,3 +23,4 @@
 
 - A repository whose work integrates somewhere other than `origin/<default>`, such as a fork with an `upstream`: `--no-remove`. Removal proves containment against `origin/<default>` only.
 - A repository with a custom `origin` fetch refspec: `--no-fetch --no-remove`. The fetch prunes every `refs/remotes/origin/*` ref that no server branch supplies (see [references/checkout-updates.md](references/checkout-updates.md)).
+- A checkout whose submodules must stay where they are: `--no-fetch --no-remove`. After a fast-forward the driver checks every submodule, third-party ones included, out at its recorded commit. In first-party checkouts it also moves branch- or tag-tracked submodules when nothing fast-forwards, and `update = none` stops only that move.

@@ -18,3 +18,3 @@
 
 - **Under a `third-party/` path component:** `.gitmodules` and Gitlinks belong to upstream. Never add or change selectors, URLs, paths, update policies, or Gitlinks; only synchronize what upstream committed.
-- **Everywhere else (first-party):** each submodule needs exactly one selector, `branch = <name>` for a moving line or `tag = <name>` for an exact release. On fresh eligible default checkouts the driver fetches that branch or tag, checks the submodule out detached, and leaves the Gitlink change unstaged for the owner's next commit.
+- **Everywhere else (first-party):** each submodule needs exactly one selector, `branch = <name>` for a moving line or `tag = <name>` for an exact release. On fresh eligible default checkouts the driver fetches that branch or tag, checks the submodule out detached, and leaves the Gitlink change unstaged for the owner's next commit. Only submodules listed in the checkout's own `.gitmodules` that are Gitlinks in HEAD move; nested submodules follow their recorded commits. A local tag of the configured name on the same commit is kept as it is. One on another commit is replaced only when the fetched tag's commit contains that commit or another ref holds it. Otherwise, or when the local tag does not point at a commit, that submodule stays where it is, the local tag is kept, and the selector update fails naming the tag.

@@ -27,0 +26,5 @@
+  echo "  submodule selectors advanced outside third-party/ paths; removal of in-root linked"
+  echo "  worktrees that pass every removal gate. A checkout with a submodule, at any depth, on a"
+  echo "  commit neither recorded nor held by a ref gets no fast-forward or selector move; a local"
+  echo "  selector tag is replaced only when the fetched tag or another ref keeps its commit; a"
+  echo "  worktree whose submodules hold work no remote-tracking ref keeps is not removed."

@@ -478,0 +496,7 @@
+  mode=$2
+  prefix=${3:-}
+
+  gitlink_paths=$({
+    git -C "$superproject_path" ls-files --stage -z
+    git -C "$superproject_path" ls-tree -r -z --full-tree HEAD 2>/dev/null
+  } | tr '\0' '\n' | awk -F '\t' '$1 ~ /^160000 / {print $2}' | sort -u) || return 1

@@ -478,0 +524,9 @@
+    [ "$head" != "$recorded" ] && [ -z "$(git -C "$submodule_path" for-each-ref --count=1 --contains "$head")" ]
+    return
+  fi
+  if [ "$head" != "$recorded" ] && [ -z "$(git -C "$submodule_path" for-each-ref --count=1 --contains "$head" refs/remotes)" ]; then
+    return 0
+  fi
+  [ -n "$(git -C "$submodule_path" status --porcelain --untracked-files=normal --ignore-submodules=all)" ] && return 0
+  git -C "$submodule_path" rev-parse --verify --quiet refs/stash >/dev/null && return 0
+  [ -n "$(git -C "$submodule_path" rev-list -n 1 --branches --not --remotes)" ]

@@ -312,1 +320,4 @@
       const onDefault = worktree.status?.branch.isDetached === false && worktree.status.branch.current === defaultBranch;
+      const stranded = worktree.strandedSubmodules ?? [];
+      if ((isMain || onDefault) && stranded.length > 0) {
+        const why = `submodule on a commit no ref holds: ${listPaths(stranded)}; not updated`;

@@ -16,3 +16,3 @@
 | Request | Flags | What changes |
 | --- | --- | --- |
-| Audit, clean up, "which are behind" | none | Fetch and prune `origin`; fast-forward eligible default checkouts; prune stale worktree registrations; remove proven-merged linked worktrees inside the root. |
+| Audit, clean up, "which are behind" | none | Fetch and prune `origin`; fast-forward eligible default checkouts, then initialize their submodules and check them out at the recorded commits; in first-party default checkouts, check each submodule listed in the checkout's own `.gitmodules` out at its configured branch or tag, leaving the Gitlink change unstaged; prune stale worktree registrations; remove proven-merged linked worktrees inside the root. |

@@ -23,3 +23,4 @@
 
 - A repository whose work integrates somewhere other than `origin/<default>`, such as a fork with an `upstream`: `--no-remove`. Removal proves containment against `origin/<default>` only.
 - A repository with a custom `origin` fetch refspec: `--no-fetch --no-remove`. The fetch prunes every `refs/remotes/origin/*` ref that no server branch supplies (see [references/checkout-updates.md](references/checkout-updates.md)).
+- A checkout whose submodules must stay where they are: `--no-fetch --no-remove`. After a fast-forward the driver checks every submodule, third-party ones included, out at its recorded commit. In first-party checkouts it also moves branch- or tag-tracked submodules when nothing fast-forwards, and `update = none` stops only that move.

@@ -5,3 +5,3 @@
 ## What the driver already updates
 
-The driver fast-forwards a default-branch checkout only when its comparison is fresh, it has no local commits, and it is strictly behind `origin/<default>`. A dirty checkout qualifies only when every changed path is deferred guidance (`AGENTS.md`, `.agents/**`, at any depth) or first-party `.gitmodules`/Gitlink maintenance, and upstream did not touch those paths. The merge runs `--ff-only` with `merge.autostash=false`, because autostash would round-trip the tree through a stash and silently unstage staged guidance. After a fast-forward it synchronizes committed submodules to the recorded Gitlinks.
+The driver fast-forwards a default-branch checkout only when its comparison is fresh, it has no local commits, and it is strictly behind `origin/<default>`. A dirty checkout qualifies only when every changed path is deferred guidance (`AGENTS.md`, `.agents/**`, at any depth), a first-party `.gitmodules` edit, or a first-party Gitlink change on a submodule with a `branch` or `tag` selector, and upstream did not touch those paths. The merge runs `--ff-only` with `merge.autostash=false`, because autostash would round-trip the tree through a stash and silently unstage staged guidance. After a fast-forward it initializes committed submodules and checks them out at the recorded Gitlinks. When any populated submodule, at any depth, found from the Gitlinks rather than `.gitmodules`, is checked out at a commit that its superproject does not record and no ref holds, the driver skips the fast-forward and every selector move for that checkout, and the report lists it under "Needs your decision" with the submodule's path.

@@ -27,0 +26,5 @@
+  echo "  submodule selectors advanced outside third-party/ paths; removal of in-root linked"
+  echo "  worktrees that pass every removal gate. A checkout with a submodule, at any depth, on a"
+  echo "  commit neither recorded nor held by a ref gets no fast-forward or selector move; a local"
+  echo "  selector tag is replaced only when the fetched tag or another ref keeps its commit; a"
+  echo "  worktree whose submodules hold work no remote-tracking ref keeps is not removed."

@@ -478,0 +505,4 @@
+    [ -n "$gitlink_path" ] || continue
+    submodule_path="$superproject_path/$gitlink_path"
+    [ -e "$submodule_path/.git" ] || continue
+    head=$(git -C "$submodule_path" rev-parse --verify --quiet HEAD) || continue

@@ -1123,0 +1281,5 @@
+  assert.equal(refused.trackingUpdate.attempted, true);
+  assert.equal(refused.trackingUpdate.ok, false);
+  assert.match(refused.trackingUpdate.error, /local tag v1 .* no other ref holds/);
+  assert.equal(git(dependencyPath, "rev-parse", "v1^{commit}").trim(), localCommit);
+  assert.equal(git(dependencyPath, "rev-parse", "HEAD").trim(), thirdCommit);

@@ -16,3 +16,3 @@
 | Request | Flags | What changes |
 | --- | --- | --- |
-| Audit, clean up, "which are behind" | none | Fetch and prune `origin`; fast-forward eligible default checkouts; prune stale worktree registrations; remove proven-merged linked worktrees inside the root. |
+| Audit, clean up, "which are behind" | none | Fetch and prune `origin`; fast-forward eligible default checkouts, then initialize their submodules and check them out at the recorded commits; in first-party default checkouts, check each submodule listed in the checkout's own `.gitmodules` out at its configured branch or tag, leaving the Gitlink change unstaged; prune stale worktree registrations; remove proven-merged linked worktrees inside the root. |

@@ -23,3 +23,4 @@
 
 - A repository whose work integrates somewhere other than `origin/<default>`, such as a fork with an `upstream`: `--no-remove`. Removal proves containment against `origin/<default>` only.
 - A repository with a custom `origin` fetch refspec: `--no-fetch --no-remove`. The fetch prunes every `refs/remotes/origin/*` ref that no server branch supplies (see [references/checkout-updates.md](references/checkout-updates.md)).
+- A checkout whose submodules must stay where they are: `--no-fetch --no-remove`. After a fast-forward the driver checks every submodule, third-party ones included, out at its recorded commit. In first-party checkouts it also moves branch- or tag-tracked submodules when nothing fast-forwards, and `update = none` stops only that move.

@@ -5,3 +5,3 @@
 ## What the driver already updates
 
-The driver fast-forwards a default-branch checkout only when its comparison is fresh, it has no local commits, and it is strictly behind `origin/<default>`. A dirty checkout qualifies only when every changed path is deferred guidance (`AGENTS.md`, `.agents/**`, at any depth) or first-party `.gitmodules`/Gitlink maintenance, and upstream did not touch those paths. The merge runs `--ff-only` with `merge.autostash=false`, because autostash would round-trip the tree through a stash and silently unstage staged guidance. After a fast-forward it synchronizes committed submodules to the recorded Gitlinks.
+The driver fast-forwards a default-branch checkout only when its comparison is fresh, it has no local commits, and it is strictly behind `origin/<default>`. A dirty checkout qualifies only when every changed path is deferred guidance (`AGENTS.md`, `.agents/**`, at any depth), a first-party `.gitmodules` edit, or a first-party Gitlink change on a submodule with a `branch` or `tag` selector, and upstream did not touch those paths. The merge runs `--ff-only` with `merge.autostash=false`, because autostash would round-trip the tree through a stash and silently unstage staged guidance. After a fast-forward it initializes committed submodules and checks them out at the recorded Gitlinks. When any populated submodule, at any depth, found from the Gitlinks rather than `.gitmodules`, is checked out at a commit that its superproject does not record and no ref holds, the driver skips the fast-forward and every selector move for that checkout, and the report lists it under "Needs your decision" with the submodule's path.

@@ -18,3 +18,3 @@
 
 - **Under a `third-party/` path component:** `.gitmodules` and Gitlinks belong to upstream. Never add or change selectors, URLs, paths, update policies, or Gitlinks; only synchronize what upstream committed.
-- **Everywhere else (first-party):** each submodule needs exactly one selector, `branch = <name>` for a moving line or `tag = <name>` for an exact release. On fresh eligible default checkouts the driver fetches that branch or tag, checks the submodule out detached, and leaves the Gitlink change unstaged for the owner's next commit.
+- **Everywhere else (first-party):** each submodule needs exactly one selector, `branch = <name>` for a moving line or `tag = <name>` for an exact release. On fresh eligible default checkouts the driver fetches that branch or tag, checks the submodule out detached, and leaves the Gitlink change unstaged for the owner's next commit. Only submodules listed in the checkout's own `.gitmodules` that are Gitlinks in HEAD move; nested submodules follow their recorded commits. A local tag of the configured name on the same commit is kept as it is. One on another commit is replaced only when the fetched tag's commit contains that commit or another ref holds it. Otherwise, or when the local tag does not point at a commit, that submodule stays where it is, the local tag is kept, and the selector update fails naming the tag.

@@ -18,3 +19,3 @@
 A worktree lock is an owner pin that expires seven days after its `locked` file's mtime. `git worktree lock` refuses an already locked worktree, so the mtime dates from the original lock; to renew a pin, unlock and lock again. A future-dated lock counts as young. The driver unlocks an expired lock only after every other gate passes, immediately before removal. It reads the lock once, at the gate: a pin renewed during the containment proof and ignored scan that follow is unlocked anyway. If unlock fails, the outcome is `operational/removal-failed`. If removal then fails, the worktree stays unlocked and the next run evaluates it from scratch. Expiry deliberately overrides pins agents leave behind.
 
-Worktrees containing `.gitmodules` are removed with `--force`, because Git otherwise refuses any worktree with submodules; the repeated status check replaces the check `--force` disables. Submodules get no audit or veto of their own: superproject containment says nothing about a submodule's history or ignored files.
+Worktrees containing `.gitmodules` are removed with `--force`, because Git otherwise refuses any worktree with submodules; the repeated status check replaces the check `--force` disables. Removal also deletes each submodule's Git directory, local branches and stash included, so right before the status check the driver walks every populated submodule at any depth. A submodule keeps the worktree (`judgment/submodule-local-work`, paths in `removal.error`) when it has uncommitted files, a stash, a branch or tag commit no remote-tracking ref holds, or a HEAD no remote-tracking ref holds. A Gitlink names a commit without keeping it, so a recorded HEAD needs a remote-tracking ref too. Ignored files inside submodules are not scanned.

@@ -26,1 +25,6 @@
-  echo "  third-party/ paths; removal of in-root linked worktrees that pass every removal gate."
+  echo "  submodule init and checkout at recorded Gitlinks after a fast-forward; branch/tag"
+  echo "  submodule selectors advanced outside third-party/ paths; removal of in-root linked"
+  echo "  worktrees that pass every removal gate. A checkout with a submodule, at any depth, on a"
+  echo "  commit neither recorded nor held by a ref gets no fast-forward or selector move; a local"
+  echo "  selector tag is replaced only when the fetched tag or another ref keeps its commit; a"
+  echo "  worktree whose submodules hold work no remote-tracking ref keeps is not removed."

@@ -478,0 +500,4 @@
+  gitlink_paths=$({
+    git -C "$superproject_path" ls-files --stage -z
+    git -C "$superproject_path" ls-tree -r -z --full-tree HEAD 2>/dev/null || true
+  } | tr '\0' '\n' | awk -F '\t' '$1 ~ /^160000 / {print $2}' | sort -u) || return 1

@@ -478,0 +530,4 @@
+    return
+  fi
+  [ -z "$(git -C "$submodule_path" for-each-ref --count=1 --contains "$head" refs/remotes)" ] && return 0
+  [ -n "$(git -C "$submodule_path" status --porcelain --untracked-files=normal --ignore-submodules=all)" ] && return 0

@@ -478,0 +532,4 @@
+  [ -z "$(git -C "$submodule_path" for-each-ref --count=1 --contains "$head" refs/remotes)" ] && return 0
+  [ -n "$(git -C "$submodule_path" status --porcelain --untracked-files=normal --ignore-submodules=all)" ] && return 0
+  git -C "$submodule_path" rev-parse --verify --quiet refs/stash >/dev/null && return 0
+  [ -n "$(git -C "$submodule_path" rev-list -n 1 --branches --tags --not --remotes)" ]

@@ -1415,2 +1527,4 @@
   submodule_metadata_ok=$(jq -r '.ok' "$submodule_metadata_path")
 
+  if [ "$outside_root" = false ]; then
+    if stranded_output=$(list_submodules_with_local_work "$worktree_path" update 2>/dev/null); then

@@ -312,1 +320,4 @@
       const onDefault = worktree.status?.branch.isDetached === false && worktree.status.branch.current === defaultBranch;
+      const stranded = worktree.strandedSubmodules ?? [];
+      if ((isMain || onDefault) && stranded.length > 0) {
+        const why = `submodule on a commit no ref holds: ${listPaths(stranded)}; not updated`;

@@ -16,3 +16,3 @@
 | Request | Flags | What changes |
 | --- | --- | --- |
-| Audit, clean up, "which are behind" | none | Fetch and prune `origin`; fast-forward eligible default checkouts; prune stale worktree registrations; remove proven-merged linked worktrees inside the root. |
+| Audit, clean up, "which are behind" | none | Fetch and prune `origin`; fast-forward eligible default checkouts, then initialize their submodules and check them out at the recorded commits; in first-party default checkouts, check each submodule listed in the checkout's own `.gitmodules` out at its configured branch or tag, leaving the Gitlink change unstaged; prune stale worktree registrations; remove proven-merged linked worktrees inside the root. |

@@ -23,3 +23,4 @@
 
 - A repository whose work integrates somewhere other than `origin/<default>`, such as a fork with an `upstream`: `--no-remove`. Removal proves containment against `origin/<default>` only.
 - A repository with a custom `origin` fetch refspec: `--no-fetch --no-remove`. The fetch prunes every `refs/remotes/origin/*` ref that no server branch supplies (see [references/checkout-updates.md](references/checkout-updates.md)).
+- A checkout whose submodules must stay where they are: `--no-fetch --no-remove`. After a fast-forward the driver checks every submodule, third-party ones included, out at its recorded commit. In first-party checkouts it also moves branch- or tag-tracked submodules when nothing fast-forwards, and `update = none` stops only that move.

@@ -5,3 +5,3 @@
 ## What the driver already updates
 
-The driver fast-forwards a default-branch checkout only when its comparison is fresh, it has no local commits, and it is strictly behind `origin/<default>`. A dirty checkout qualifies only when every changed path is deferred guidance (`AGENTS.md`, `.agents/**`, at any depth) or first-party `.gitmodules`/Gitlink maintenance, and upstream did not touch those paths. The merge runs `--ff-only` with `merge.autostash=false`, because autostash would round-trip the tree through a stash and silently unstage staged guidance. After a fast-forward it synchronizes committed submodules to the recorded Gitlinks.
+The driver fast-forwards a default-branch checkout only when its comparison is fresh, it has no local commits, and it is strictly behind `origin/<default>`. A dirty checkout qualifies only when every changed path is deferred guidance (`AGENTS.md`, `.agents/**`, at any depth), a first-party `.gitmodules` edit, or a first-party Gitlink change on a submodule with a `branch` or `tag` selector, and upstream did not touch those paths. The merge runs `--ff-only` with `merge.autostash=false`, because autostash would round-trip the tree through a stash and silently unstage staged guidance. After a fast-forward it initializes committed submodules and checks them out at the recorded Gitlinks. When any populated submodule, at any depth, found from the Gitlinks rather than `.gitmodules`, is checked out at a commit that its superproject does not record and no ref holds, the driver skips the fast-forward and every selector move for that checkout, and the report lists it under "Needs your decision" with the submodule's path.

@@ -7,3 +7,3 @@
-The driver fast-forwards a default-branch checkout only when its comparison is fresh, it has no local commits, and it is strictly behind `origin/<default>`. A dirty checkout qualifies only when every changed path is deferred guidance (`AGENTS.md`, `.agents/**`, at any depth) or first-party `.gitmodules`/Gitlink maintenance, and upstream did not touch those paths. The merge runs `--ff-only` with `merge.autostash=false`, because autostash would round-trip the tree through a stash and silently unstage staged guidance. After a fast-forward it synchronizes committed submodules to the recorded Gitlinks.
+The driver fast-forwards a default-branch checkout only when its comparison is fresh, it has no local commits, and it is strictly behind `origin/<default>`. A dirty checkout qualifies only when every changed path is deferred guidance (`AGENTS.md`, `.agents/**`, at any depth), a first-party `.gitmodules` edit, or a first-party Gitlink change on a submodule with a `branch` or `tag` selector, and upstream did not touch those paths. The merge runs `--ff-only` with `merge.autostash=false`, because autostash would round-trip the tree through a stash and silently unstage staged guidance. After a fast-forward it initializes committed submodules and checks them out at the recorded Gitlinks. When any populated submodule, at any depth, found from the Gitlinks rather than `.gitmodules`, is checked out at a commit that its superproject does not record and no ref holds, the driver skips the fast-forward and every selector move for that checkout, and the report lists it under "Needs your decision" with the submodule's path.
 
 A fast-forward, submodule sync, or selector update can fail after an earlier step succeeded. Inspect the actual HEAD, index, and submodule state before repairing; never describe a failed multi-step update as atomic, and never force a refused merge.

@@ -18,3 +18,3 @@
 
 - **Under a `third-party/` path component:** `.gitmodules` and Gitlinks belong to upstream. Never add or change selectors, URLs, paths, update policies, or Gitlinks; only synchronize what upstream committed.
-- **Everywhere else (first-party):** each submodule needs exactly one selector, `branch = <name>` for a moving line or `tag = <name>` for an exact release. On fresh eligible default checkouts the driver fetches that branch or tag, checks the submodule out detached, and leaves the Gitlink change unstaged for the owner's next commit.
+- **Everywhere else (first-party):** each submodule needs exactly one selector, `branch = <name>` for a moving line or `tag = <name>` for an exact release. On fresh eligible default checkouts the driver fetches that branch or tag, checks the submodule out detached, and leaves the Gitlink change unstaged for the owner's next commit. Only submodules listed in the checkout's own `.gitmodules` that are Gitlinks in HEAD move; nested submodules follow their recorded commits. A local tag of the configured name on the same commit is kept as it is. One on another commit is replaced only when the fetched tag's commit contains that commit or another ref holds it. Otherwise, or when the local tag does not point at a commit, that submodule stays where it is, the local tag is kept, and the selector update fails naming the tag.

@@ -44,6 +45,7 @@ The outcome names the first blocker only; later gates may never have run. After
 | `judgment/hidden-index-flags` | Have the owner clear the flags they set, prove the revealed tree clean, then rerun. In `git ls-files -v`, a lowercase letter is assume-unchanged (clear it with `--no-assume-unchanged`); an uppercase `S` outside a sparse cone is a hand-set skip-worktree bit (clear it with `--no-skip-worktree`). Leave a sparse cone's `S` entries alone. |
 | `judgment/sparse-checkout` | Keep the cone's `skip-worktree` bits: clearing them turns absent files into apparent deletions. Confirm the cone with `git sparse-checkout list`, verify no file outside it is materialized, then remove manually once every other gate holds. |
 | `judgment/precious-ignored-files` | Leave `preciousPaths` in place until the owner disposes of them or authorizes their deletion, then rerun. |
+| `judgment/submodule-local-work` | The listed submodules hold work only this worktree has. Show the owner what each holds; rerun once it is pushed or they authorize discarding it. |

@@ -27,0 +26,5 @@
+  echo "  submodule selectors advanced outside third-party/ paths; removal of in-root linked"
+  echo "  worktrees that pass every removal gate. A checkout with a submodule, at any depth, on a"
+  echo "  commit neither recorded nor held by a ref gets no fast-forward or selector move; a local"
+  echo "  selector tag is replaced only when the fetched tag or another ref keeps its commit; a"
+  echo "  worktree whose submodules hold work no remote-tracking ref keeps is not removed."

@@ -478,0 +497,7 @@
+  mode=$2
+  prefix=${3:-}
+
+  gitlink_paths=$({
+    git -C "$superproject_path" ls-files --stage -z
+    git -C "$superproject_path" ls-tree -r -z --full-tree HEAD 2>/dev/null || true
+  } | tr '\0' '\n' | awk -F '\t' '$1 ~ /^160000 / {print $2}' | sort -u) || return 1

@@ -1415,2 +1541,4 @@
   submodule_metadata_ok=$(jq -r '.ok' "$submodule_metadata_path")
 
+  if [ "$outside_root" = false ]; then
+    if stranded_output=$(list_submodules_with_local_work "$worktree_path" update 2>/dev/null); then

@@ -1123,0 +1277,7 @@
+  git(dependencyPath, "tag", "--no-sign", "--force", "v1");
+  git(dependencyPath, "checkout", "--quiet", "--detach", thirdCommit);
+
+  const refused = audit();
+  assert.equal(refused.trackingUpdate.attempted, true);
+  assert.equal(refused.trackingUpdate.ok, false);
+  assert.match(refused.trackingUpdate.error, /local tag v1 .* no other ref holds/);

@@ -1123,0 +1405,8 @@
+  assert.match(unreadable.removal.error, /cannot read submodule dependency/);
+  execFileSync("git", ["config", "--file", join(dependencyGitDir, "config"), "--unset", "core.worktree"]);
+
+  // Nor must a submodule whose status query fails, even with uncommitted work the superproject cannot see.
+  writeFileSync(join(dependencyPath, "README.md"), "uncommitted\n");
+  const dependencyIndex = join(dependencyGitDir, "index");
+  const healthyIndex = readFileSync(dependencyIndex);
+  writeFileSync(dependencyIndex, "not an index");

@@ -143,6 +146,7 @@ function branchLabel(worktree: Worktree): string {
 
 function stepFailure(worktree: Worktree, fetched: boolean): string | null {
   if (worktree.statusError !== null) return `status query failed: ${firstLine(worktree.statusError)}`;
+  if (worktree.strandedSubmodules === null) return "submodule check failed; checkout not updated";

@@ -311,2 +319,8 @@
       const isMain = worktree.registration?.isMain === true;
       const onDefault = worktree.status?.branch.isDetached === false && worktree.status.branch.current === defaultBranch;
+      const stranded = worktree.strandedSubmodules ?? [];
+      if ((isMain || onDefault) && stranded.length > 0) {
+        const why = `submodule on a commit no ref holds: ${listPaths(stranded)}; not updated`;
+        decisions.push([path, branch, formatAheadBehind(worktree.defaultComparison), why]);
+        continue;
+      }