feat(repo-hygiene): fleet batch mode for the caches/build/git/all tiers

[kyle-sexton]

Summary

Adds fleet (batch) mode for the clean skill's selective tiers — caches / build / git / all — so a multi-repo sweep no longer has to be hand-rolled (which the auto-mode classifier blocks). This is the selective-tier sibling of the existing tree-batch.

A new clean-batch.sh --tier <caches|build|git|all> orchestrator runs the single-repo tiers across a repo set behind ONE confirmation gate. It runs no removal itself — every per-repo action delegates to the unchanged single-repo child (clean-caches.sh, clean-build.sh, git-prune.sh), so every child gate (protection classes, submodule/reparse guards, the dry-run manifest + re-stat staleness guard) is reused verbatim.

New action spellings: caches-batch / build-batch / git-batch / all-batch (plus *-fleet aliases), resolved by resolve-clean-action.sh.

Design

• One --tier orchestrator, not four scripts. The batch-plan format, the single batch-wide gate, and the apply-from-plan logic are one cohesive contract; the tier is a data difference (which child + manifest-mode vs gitdir-mode), not a structural one. The resolver maps the four spellings to clean-batch.sh --tier X.
• The batch plan IS the gated set. --dry-run writes a plan (REPO lines → per-repo child manifest; GITDIR lines → unique shared object stores) and prints BatchPlan: <path> + aggregate Summary: repos=N planned=P bytes=K. --apply --batch-plan <path> acts on that plan ONLY and errors without it. This is the fleet-level analogue of the child's per-repo manifest staleness guard: a repo that vanished after the dry-run applies idempotently (paths already gone); a repo that appeared is not in the plan, so it is never touched.
• Central path normalization (lib/batch-common.sh): ghq list -p backslash paths → the git-friendly D:/repos/... forward-slash form once (backslashes break xargs and [[ -d ]]; git check-ignore rejects MSYS /d/… forms).
• Shared-object-store dedup: the git tier groups repos by unique git rev-parse --git-common-dir and prunes each store once (from a representative worktree cwd), not once per linked worktree.
• Shared plumbing in lib/batch-common.sh. tree-batch predates this module and keeps its own inline copy of read-lines / resolve-dedup / emit; migrating it onto batch-common.sh is a deliberate fast-follow (kept out of scope to keep this diff off feat(repo-hygiene): single pruned walk + dry-run manifest + apply summary #1023's churn and tree-batch's large test suite). Recorded as a decision (noted in the lib header), not silence.

Spec deviations (recorded)

• Batch git = prune / gc / remote-prune only. Branch audit/deletion is excluded because interactive per-branch deletion can't sit behind one fleet-wide gate. Therefore all-batch = build + git-prune, no branch audit — matching the single-repo all (build + git, no tree).
• tree is not batched here — the destructive tier has its own batch form (tree-batch) with a dirty guard.

Independent review

An independent reviewer (fresh context) audited the apply path; fixes landed here:

• Fail-closed aggregate counter — a per-repo child that exits non-zero without a parseable Summary (e.g. a repo that lost its .git mid-sweep) now counts as a failure, so the batch exits 1 instead of silently reporting failed=0 / exit 0.
• Fleet-alias safety routing — a selective tier token co-occurring with a fleet indicator (clean caches across all repos, caches fleet, prune git across the fleet) routes to the non-destructive <tier>-batch, never the destructive tree-batch; the ambiguous bare "fleet" trigger was dropped from the skill description.
• Batch-plan write guard — the dry-run creates the plan directory and verifies the plan is writable, failing loudly instead of printing BatchPlan / Summary and exiting 0 with no plan.
• Apply summary gates the gitdirs= field to the git/all tiers; the gitdir first-seen-representative limitation is documented.

Testing

• New clean-batch.test.sh and lib/batch-common.test.sh, TDD-first; resolver gains routing cases including the fleet-safety ones. All repo-hygiene *.test.sh green; shellcheck --rcfile .shellcheckrc, shfmt -i 2, and markdownlint clean. Re-run against this PR's rebased (hardened) single-repo children.
• Verified with real multi-repo dry-runs (never --apply) over a local ghq fleet: caches-batch over 3 repos; git-batch over a main clone + its linked worktree correctly reports gitdirs=1 (shared object store deduped); node_modules present in a repo is correctly preserved (0 planned).

Related

• repo-hygiene: fleet-sweep field report umbrella — guard, perf, batch, verification (session fee18cc2) #1003 — umbrella (repo-hygiene fleet/batch capabilities)
• repo: per-change version bump + top-insert CHANGELOG serialize concurrent same-plugin PRs (conflict by construction) #464 — serialization
• PR feat(repo-hygiene): single pruned walk + dry-run manifest + apply summary #1023 — Stacked on feat(repo-hygiene): single pruned walk + dry-run manifest + apply summary #1023, now merged (its single-repo manifest work is in main; this branch merged main forward, so the diff is just the fleet-batch changes)

Closes #994

[claude]

Claude finished @kyle-sexton's task in 5m 42s —— View job

---

PR Review: feat(repo-hygiene) fleet batch mode

• Gather context and understand the request
• Read key changed files (clean-batch.sh, batch-common.sh, clean-common.sh, resolve-clean-action.sh)
• Review for correctness, error handling, and security
• Check test coverage
• Review documentation and skill changes
• Post review findings

---

Overall this is a well-designed, thoughtful piece of work. The one-gate/plan-is-the-set contract is sound, the fail-closed aggregate counter is correct, and the gitdir dedup is the right call. The documentation is thorough. I found a few issues ranging from a latent bug to a missing test case.

P1 — Child dry-run failure is not detected; broken REPO line is written to the plan

clean-batch.sh:326–338

out="$(cd "$top" && bash "$child" --dry-run --manifest "$manifest" "${extra[@]}" 2>&1)"
r="$(printf '%s\n' "$out" | sed -n 's/^Summary: //p' | head -1)"
planned="${planned:-0}"   # ← silent default if child failed
...
printf 'REPO\t%s\t%s\t%s\n' "$top" "$tok" "$manifest" >>"$PLAN"  # ← always written

If the manifest child exits non-zero (say, a permission error mid-walk), the script silently defaults planned=0, writes the REPO plan line, and exits dry-run with exit 0. On --apply, the child is then invoked with --apply --manifest <empty-or-missing-file> and fails — but now the user has confirmed what they thought was a clean dry-run. The dry-run should surface per-repo child failures (analogous to the fail-closed logic in the apply path at line 211).

Suggested fix: capture rc=$? after the child dry-run, and if rc != 0, emit batch_emit "$top" failed "child dry-run failed (rc=$rc)", increment a FAILED counter, and skip writing the REPO plan line. The dry-run would then exit non-zero, and the apply would never see a broken plan entry for that repo.

Fix this →

---

P2 — batch_add_gitdir rc=1 (unresolvable --git-common-dir) silently misreports as "deduped"

clean-batch.sh:346–351, batch-common.sh:109–124

batch_add_gitdir has three return codes: 0 (new), 2 (duplicate), 1 (could not resolve --git-common-dir). The caller only checks for 0:

if batch_add_gitdir "$top"; then       # ← rc=0 only
  # ... write GITDIR line
else
  reason_parts+=("git: shared object store (deduped with a sibling worktree)")
  # ← rc=1 AND rc=2 both land here — wrong message for rc=1
fi

When rc=1, no GITDIR line is written, git prune for that repo is silently skipped, and the reason reported to the user is "deduped with a sibling worktree" — factually wrong. In practice, rc=1 requires git rev-parse --git-common-dir to silently fail on a repo that already passed batch_resolve_repos, which is unlikely but possible (e.g., a corrupted .git). A third branch would make the failure explicit:

rc=0; batch_add_gitdir "$top" || rc=$?
if   [[ "$rc" -eq 0 ]]; then
  ...
elif [[ "$rc" -eq 2 ]]; then
  reason_parts+=("git: shared object store (deduped with a sibling worktree)")
else
  reason_parts+=("git: could not resolve shared object store — prune skipped")
  batch_emit "$top" blocked "could not resolve --git-common-dir"
fi

Fix this →

---

P3 — batch_add_gitdir fallback produces non-canonical keys on git < 2.26, defeating worktree dedup

batch-common.sh:112–115

common="$(git -C "$top" rev-parse --path-format=absolute --git-common-dir 2>/dev/null | tr -d '\r')"
if [[ -z "$common" ]]; then
  common="$(git -C "$top" rev-parse --git-common-dir 2>/dev/null | tr -d '\r')"
  [[ -n "$common" && "$common" != /* && "$common" != ?:/* ]] && common="$top/$common"
fi

When --path-format=absolute is unavailable (git < 2.26, released April 2020), the fallback joins $top with a potentially relative path (e.g., ../../.git). For a linked worktree, two paths like /repos/a/.git/worktrees/wt1/../../.. and /repos/a/.git/worktrees/wt2/../../.. would produce different string keys after clean_path_key, even though they name the same directory. Git gc would then run once per worktree instead of once per store — the exact problem this dedup is designed to prevent.

realpath (GNU coreutils, also available in MSYS2) or cd "$common" && pwd would canonicalize the path before keying:

common="$(cd "$common" 2>/dev/null && pwd || printf '%s' "$common")"

Fix this →

---

P4 — all-batch apply path is not integration-tested

clean-batch.test.sh:155–163

Test 8 (the all tier) verifies the dry-run plan contains both REPO and GITDIR lines, but never calls --apply --batch-plan. The combined REPO+GITDIR apply path — the only code path that exercises both BUILD_CHILD and GIT_CHILD in a single apply loop — is untested. A follow-up apply call (analogous to test 3 for caches or test in §6 for build) would cover it:

out="$(bash "$BATCH" --tier all --apply --batch-plan "$APLAN")"
assert_contains "all apply cleaned build artifacts" "$out" "Outcome: cleaned"
assert_contains "all apply pruned git store" "$out" "Outcome: pruned"
assert_file_absent "build dir removed by all apply" "$AR/bin/b"

Fix this →

---

P5 — resolve_one called twice per token in the fleet-routing loop

resolve-clean-action.sh:108–110

for token in "$@"; do
  case "$(resolve_one "$(printf '%s' "$token" | tr '[:upper:]' '[:lower:]')")" in
  caches | build | git)
    t="$(resolve_one "$(printf '%s' "$token" | tr '[:upper:]' '[:lower:]')")"  # ← redundant

resolve_one is a pure function; the second call with identical input is wasteful. One assignment before the case eliminates both forks and a needless subshell:

for token in "$@"; do
  lower="$(printf '%s' "$token" | tr '[:upper:]' '[:lower:]')"
  t="$(resolve_one "$lower")"
  case "$t" in
  caches | build | git)
    ...
  esac
done

This is minor, but given the resolver runs on every skill invocation it's a clean win.

Fix this →

---

Minor nit: predictable temp dir fallback

clean-batch.sh:266

PLAN_DIR="$(mktemp -d 2>/dev/null)" || PLAN_DIR="${TMPDIR:-/tmp}/clean-batch.$$"

The $$-based fallback is predictable. mktemp -d should never fail on a POSIX system, so this is not a real risk, but the existing siblings (clean-manifest.sh, git-tree-reset-batch.sh) use the same pattern, so keeping it consistent is fine. Just noting it for awareness.

---

Architecture — what looks good

• One gate, plan-is-the-set contract is well-designed and correctly enforced: --apply errors without --batch-plan, and the plan write is guarded before BatchPlan:/Summary: are printed.
• Fail-closed aggregate counter (line 211): correctly handles a child that exits non-zero without a parseable Summary line (the scenario described in the PR body).
• Gitdir dedup is sound in structure; the key collision issue (P3) only surfaces on very old git.
• Fleet-alias safety routing in resolve-clean-action.sh (has_fleet_indicator + selective-tier priority) is correct, clean, and well-tested.
• clean-common.sh fd-3 manifest reader and the unencodable-path rejection are solid defensive patterns.
• CLEAN_GUARD_ACK=1 prefixing is correctly delegated to the hook layer, not replicated in clean-batch.sh itself.
• The deferred tree-batch → batch-common.sh migration is properly noted in the lib header rather than left as silent debt.

[claude]

Claude finished @kyle-sexton's task in 5m 49s —— View job

---

Security Review — PR #1064

• Gather PR diff and changed files
• Audit shell scripts for command injection / path traversal
• Audit batch orchestration logic for access-control gaps
• Audit plan-file handling and path normalization
• Review GitHub Actions patterns (if any)
• Compile and post findings

---

Scope: New files clean-batch.sh, lib/batch-common.sh, additions to lib/clean-common.sh (the manifest engine), changes to resolve-clean-action.sh, and refactored clean-caches.sh / clean-build.sh.

Overall assessment

The PR's security posture is strong. The manifest engine in lib/clean-common.sh implements thorough defense-in-depth: every apply entry is checked for ..-traversal, absolute paths, pruned-tree membership, symlinked ancestors, and type-validity before rm -rf fires. The batch orchestrator is a thin pass-through that adds no new removal capability — all destructive work stays in the existing children. No critical or high-severity findings.

Two lower-severity items follow.

---

SUGGESTION — Predictable temp-dir fallback opens plan-file race

Confidence: PLAUSIBLE

clean-batch.sh line 266

PLAN_DIR="$(mktemp -d 2>/dev/null)" || PLAN_DIR="${TMPDIR:-/tmp}/clean-batch.$$"

When mktemp -d fails (rare but possible on full /tmp or a race), the fallback uses $$ — the current PID — which is predictable. A local attacker who knows the PID (e.g., by monitoring /proc) could pre-create /tmp/clean-batch.<pid>/ before the script runs. mkdir -p on the pre-existing directory succeeds silently, then : >"$PLAN" creates (or truncates) the plan file inside the attacker-controlled directory. On a subsequent --apply, the script would consume the attacker's crafted plan.

Impact is limited by the robust apply-side validation — every REPO and GITDIR entry in the plan is only acted on with fully-quoted arguments and the child scripts re-validate all paths before any rm. But a crafted plan can direct cd to attacker-chosen directories and invoke git-prune.sh, which runs git gc, git worktree prune, and git remote prune in that directory. Those ops are non-destructive to file content but will pack/prune loose objects in an unintended repo.

Mitigation options:

• Fail hard if mktemp -d returns empty (remove the || fallback entirely), or emit a clear error and exit 2.
• If a human-readable fallback path must remain, use mkdir -m 0700 to create it atomically and fail if it already exists.

---

SUGGESTION — No reparse-point guard on repo toplevel in apply path

Confidence: PLAUSIBLE

clean-batch.sh line 187 and line 225

# REPO branch
if [[ ! -d "$a" ]]; then
  ...continue...
fi
out="$(cd "$a" && bash "$child" --apply --manifest "$c" "${extra[@]}" 2>&1)"

# GITDIR branch
if [[ ! -d "$a" ]]; then
  ...continue...
fi
out="$(cd "$a" && bash "$GIT_CHILD" --apply 2>&1)"

The only pre-flight check before cd "$a" is [[ -d "$a" ]], which follows symlinks. If $a (a repo toplevel recorded at dry-run time) is swapped for a symlink pointing to a different directory between dry-run and apply — a local TOCTOU — the script would cd into the wrong location and run child scripts there.

For REPO lines the impact is bounded: the caches/build children immediately re-run git rev-parse --show-toplevel and re-root themselves, and the manifest entries are fully re-validated with clean_manifest_target_valid + clean_path_has_reparse_ancestor before any removal. So file deletion in an unintended repo via this vector would require that repo to also contain eligible cache/build targets matching the manifest — unlikely.

For GITDIR lines the impact is wider: git-prune.sh --apply runs git worktree prune, git remote prune origin, and git gc --auto in whatever directory $a resolves to, without the manifest-engine's re-validation layer. A symlink swap here causes those ops to run in an unintended repository (packfile changes, worktree stale-ref pruning).

Mitigation: Apply the same clean_path_is_reparse_point guard that already exists for manifest entries to $a before cd:

if clean_path_is_reparse_point "$a"; then
  batch_emit "$a" skipped "toplevel became a reparse point (symlink swap?)"
  continue
fi

---

Non-findings noted (for completeness)

• eval "$op" in git-prune.sh line 67: Pre-existing code, not introduced by this PR. GIT_PRUNE_OPS is a static array defined in cleanup-paths.sh with no user-input dataflow.
• --batch-plan FILE truncates existing files without format check: Intentional documented behavior (the flag means "write plan here"). Contrast with the child manifest's clean_manifest_writable_target guard — that guard exists because --manifest is also the apply flag; the batch plan is write-only at dry-run time.
• Manifest class allowed-check with empty $class: An empty class field passes the " $allowed " != *" $class "* glob check but is correctly rejected downstream by clean_manifest_target_valid's *) return 1 fallthrough. Defense-in-depth works.
• clean_plan sort pipe with paths: Tabs and newlines in paths are filtered before elig_abs is populated; no path injection into the sort.
• resolve-clean-action.sh fleet routing: Pattern matching only, no command execution on user input.
• No GitHub Actions changes in this PR.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 35e4075280

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kyle-sexton]

🔒 babysit-prs lane claiming this PR for on-branch fix work this cycle (amendment-round: 16, safe tier). Will fix clear branch-owned findings and push; will not resolve threads or merge (safe tier).

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[github-actions]

Warning

Automated review did not complete — this is an infrastructure failure, not a review verdict.

Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."

• Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/29958834574
• Last SDK result: {"subtype":"success","is_error":true,"num_turns":1,"duration_ms":470,"total_cost_usd":0}

Re-running the job, or pushing a new commit, will retry the review.

[github-actions]

Warning

Automated security review did not complete — this is an infrastructure failure, not a review verdict.

Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."

• Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/29958834568
• Last SDK result: {"subtype":"success","is_error":true,"num_turns":1,"duration_ms":926,"total_cost_usd":0}

Re-running the job, or pushing a new commit, will retry the review.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6d0c564d18

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 29047f0e29

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error after 1s —— View job

---

I'll analyze this and get back to you.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c0c7f8f7b4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".