feat(sync): seed remote Git metadata from local objects

[coygeek]

Summary

Add an explicit, opt-in synchronization path that creates a remote Git workspace from sanitized local Git objects when the runner cannot read the repository origin. This should support valid private, SSH, authenticated, host-local, or otherwise runner-unreachable origins without forwarding origin credentials or copying raw local .git state.

Ordinary manifest sync should remain the default and the authoritative source for working-tree content.

Problem to solve

Crabbox normally seeds a runner by cloning or fetching the local HEAD from origin, then overlays the Git-managed working set. If the origin is not readable from the runner, seeding fails and Crabbox falls back to ordinary file sync. The files arrive, but the remote workspace has no .git metadata.

That fallback is correct for file-only workloads and protects credentials, but it leaves no supported route for private or host-local repositories whose remote commands need repository identity or history. Builds and tests commonly call git rev-parse, git describe, git merge-base, version generators, change selectors, or tools that locate the repository root. Copying the working tree cannot satisfy those contracts.

The current opt-in Git-overlay feature does not fill this gap. Merged pull request #1453 deliberately requires an anonymous HTTP(S) or remotely readable filesystem origin and falls back for private, SSH, embedded-credential, and runner-unreachable origins.

Proposed behavior

Provide an explicit local-object seed mode for valid Git worktrees whose current commit cannot be fetched safely by the runner.

The mode should:

• construct a bounded, inspectable seed from local Git objects sufficient for the advertised HEAD and the documented history operations;
• transfer it through the existing provider-neutral SSH synchronization path;
• create a normal remote Git workspace at the exact local commit before applying the ordinary working-set manifest;
• keep the existing manifest, exclusions, executable bits, symlink identities, staged/unstaged/untracked changes, and deletion list authoritative for the resulting worktree;
• exclude origin URLs, credentials, credential helpers, prompts, hooks, global or repository configuration, filters, reflogs, linked-worktree metadata, alternates, and unrelated unreachable objects;
• apply existing transfer size limits, path validation, reserved-path rules, sparse-checkout and incomplete-worktree checks, workspace ownership, and cleanup guarantees; and
• fail with an actionable local preflight or seed diagnostic when a safe bounded seed cannot be constructed.

The exact command or configuration name is a product decision. The authority change should remain explicit rather than becoming an automatic fallback for every failed remote clone.

Acceptance criteria

• A valid local repository with an origin unavailable from the runner can opt in and produce a remote workspace where git rev-parse HEAD equals the exact local commit.
• The documented bounded history operations, such as HEAD^ or a merge-base against a caller-selected base when supported by the mode, work without making the origin reachable from the runner.
• Dirty tracked files, untracked files, deletions, renames, executable bits, symlinks, excludes, and the complete ordinary sync manifest retain their existing behavior.
• The seed contains no remote credential, credential helper, prompt configuration, hook, filter, reflog, alternate object path, worktree-private metadata, or unrelated unreachable object.
• A credential-bearing, SSH, private HTTP, or host-local origin is never forwarded to the lease as a side effect of enabling the mode.
• The mode reports its selected/fallback state and transferred seed size in sync diagnostics and timing JSON.
• An oversized, incomplete, conflicted, sparse-hidden, submodule-dependent, corrupt, or otherwise unsupported repository state fails before remote mutation or uses a documented safe fallback.
• Existing ordinary Git seeding, default-off Git overlay, fresh-PR checkout, Actions-owned workspaces, and no-sync behavior remain unchanged when the new mode is not selected.
• Regression coverage includes a runner-unreachable local origin, a private-origin credential canary, a dirty working tree, deletion and executable/symlink changes, bounded ancestry, size rejection, and cleanup after an interrupted seed.

Affected area

• Local Git eligibility and seed planning in internal/cli/repo.go.
• SSH-backed seed transfer, workspace preparation, and finalization in internal/cli/run.go and internal/cli/ssh.go.
• Sync configuration, diagnostics, timing evidence, and sync-plan inspection.
• POSIX, WSL2, and native-Windows behavior to the extent supported by the existing Git seed transport.
• Sync, security, and troubleshooting documentation.

Non-goals

• Forwarding a user's Git credentials, SSH agent, credential helper, or authenticated origin URL to a lease.
• Copying the local .git directory wholesale.
• Making an implicit local-object transfer after any ordinary clone or fetch failure.
• Replacing --fresh-pr, Actions hydration, or the existing anonymous-origin Git-overlay optimization.
• Synchronizing an intentionally non-Git local directory; that separate request is tracked in #1334.
• Adding native Jujutsu revision mapping; that remains tracked in #1081.
• Guaranteeing the complete repository history when the selected bounded history contract does not request it.

Alternatives considered

Make the private origin readable from the runner

Installing standing credentials or forwarding an SSH agent can make the existing clone path work, but it expands the credential boundary and is unavailable for host-local origins. The feature should preserve the protections established after #928 and #1029.

Copy the entire .git directory

Raw Git metadata can contain credentials, hooks, filters, alternates, reflogs, worktree paths, and unrelated objects. It also transfers more state than the runner needs. A sanitized bounded object seed has a narrower contract.

Use ordinary file sync

This is the current safe fallback and should remain the default. It cannot satisfy Git-dependent build and test commands because the remote workspace is not a repository.

Use current Git overlay

Git overlay minimizes working-tree transfer after the runner fetches filtered history from an eligible origin. It explicitly excludes the private and runner-unreachable cases this request addresses, so extending that origin requirement is the missing user-visible outcome rather than a duplicate of the merged feature.

Supporting context

• Release baseline: v0.47.0 at 0a55378990265271f5830a465aa643605d7d41f3.
• Exact current main: bcd756252f16b8e35d0cce6d66706d3c82065aa4.
• Current-main binary SHA-256: 54059e84bdf5b57a1cdd43025076a61bed99776916c977d57e3acf88f0c1724e.
• Build toolchain: go1.26.5 darwin/arm64.
• Current-main reproduction run: run_2a7db4e49845 using local-container and a host-local bare origin unavailable at the same path inside the runner.

The reproduction successfully transferred the tracked file, printed git_dir=absent, exited 0, and cleaned up the lease. It proves the current safe file-sync fallback and the absence of a remote Git workspace for an origin the runner cannot read.

The full 16-commit range from v0.47.0 through the exact current-main SHA was inspected. The complete live corpus of 23 open issues, 15 open pull requests, all 15 open issues authored by coygeek, and relevant closed issues and merged pull requests was screened. No current item requests a credential-free local-object seed for private, SSH, authenticated, host-local, or otherwise runner-unreachable origins.

The feature has one independent closure signal: an opted-in run creates a sanitized remote Git workspace at the exact local commit without exposing origin credentials or weakening ordinary manifest authority.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 28, 2026, 8:43 PM ET / August 29, 2026, 00:43 UTC.

Summary
Keep open for maintainer triage: current main deliberately seeds Git only by having the runner clone a remotely readable origin, so it does not provide the requested credential-free local-object path. This is a new, security-sensitive sync mode whose history scope and opt-in contract require product direction.

Reproducibility: yes. source-reproducible: the current plan requires an origin remote-tracking branch and the runner implementation performs a remote clone, so a runner-unreachable origin has no supported local-object alternative.

Maintainer decision needed

Question	Recommendation
Should Crabbox add a default-off credential-free local-object Git seed for valid worktrees whose origin is unavailable to the runner, and what bounded-history contract should it guarantee?	Adopt a narrow opt-in mode: Specify a bounded object-transfer contract and supported platforms while retaining manifest-only sync as the default and fallback.

Why: Current main intentionally limits Git metadata creation to runner-readable origins; choosing a new local transfer mode and its history guarantees changes the public synchronization contract and security boundary.

Next step
A maintainer must first choose whether this new credential-sensitive sync mode and its public history contract should exist; it is not safe for automated repair routing.

Security
Needs attention: No patch is proposed, but a local-object transfer would materially extend the credential and Git-metadata boundary and requires security review before implementation.

Review details

Best possible solution:

Define a default-off local-object seed contract with bounded ancestry selection, provider-neutral SSH transfer, strict metadata exclusion, and end-to-end proof that the ordinary manifest remains authoritative.

Do we have a high-confidence way to reproduce the issue?

Yes, source-reproducible: the current plan requires an origin remote-tracking branch and the runner implementation performs a remote clone, so a runner-unreachable origin has no supported local-object alternative.

Is this the best way to solve the issue?

Unclear: the proposed local-object path addresses the demonstrated gap, but maintainers must first choose its opt-in surface, supported history operations, and cross-platform security contract.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A local-object seed must define exactly which commits, trees, and blobs are transferable without carrying local Git configuration, hooks, alternates, credentials, or unrelated reachable history.
• The requested POSIX, WSL2, and native-Windows coverage expands the change beyond the existing Linux-only overlay path and needs a deliberate supported-platform contract.

Codex review notes: model internal, reasoning high; reviewed against bcd756252f16.

Label changes

Label changes:

• add impact:other: Runner-unreachable origins leave Git-dependent remote commands without repository metadata while ordinary file synchronization remains available.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.
• add clawsweeper:needs-security-review: Current issue advisory state selects this label.
• remove issue-rating: 🌊 off-meta tidepool: Current issue advisory state no longer selects this label.

Label justifications:

• P3: This is a proposed opt-in synchronization capability, not a regression in the default file-sync workflow.
• impact:other: Runner-unreachable origins leave Git-dependent remote commands without repository metadata while ordinary file synchronization remains available.

Evidence reviewed

Security concerns:

• [medium] Define a safe Git-object transfer boundary
  The proposed seed must exclude credentials and executable/configuration metadata while ensuring imported objects and history cannot bypass current workspace, path, or cleanup protections.
  Confidence: 0.94

What I checked:

• Current seed eligibility: The current coherence plan requires a remote URL, an exact local commit, and an origin remote-tracking branch containing that commit; it has no local-object transfer branch. (internal/cli/repo.go:615, bcd756252f16)
• Runner-side implementation: The normal seed implementation constructs a runner-side git clone from the origin URL and checks out the planned commit, confirming that metadata comes from the remote rather than local objects. (internal/cli/ssh.go:2002, bcd756252f16)
• Documented supported boundary: Current documentation says Git seeding requires a remotely reachable ref, while Git overlay is opt-in and falls back for SSH, private, credential-bearing, and unsupported origins. (docs/features/sync.md:204, bcd756252f16)
• Existing security controls: Credential-bearing HTTP(S), SSH, and git+https origins are rejected from the current seed plan, so a local-object mode must preserve this no-forwarding boundary rather than relaxing origin eligibility. (internal/cli/repo.go:806, bcd756252f16)
• Related merged feature provenance: Merged pull request feat: add opt-in Git overlay sync #1453 introduced the opt-in Git overlay, which current docs limit to runner-readable anonymous HTTP(S) or filesystem origins; it does not implement this issue’s runner-unreachable case. (docs/features/sync.md:212, 24d76cb35dc4)
• Vision fit: VISION.md explicitly places workspace synchronization in Crabbox scope and supports bounded capabilities that preserve ownership, isolation, cleanup, and evidence guarantees. (VISION.md:24, bcd756252f16)

Likely related people:

• Peter Steinberger: Current coherence-plan lines blame to the v0.47.0 release preparation commit, and the feature-history shortlog shows the largest contribution volume across the central sync files. (role: recent current-main contributor; confidence: high; commits: 0a5537899026, bcd756252f16; files: internal/cli/repo.go, internal/cli/run.go, internal/cli/ssh.go)
• vincentkoc: Merged pull request feat: add opt-in Git overlay sync #1453 introduced the adjacent opt-in Git-overlay feature and its remote-origin safety constraints. (role: Git-overlay feature introducer; confidence: high; commits: 24d76cb35dc4; files: internal/cli/sync_git_overlay.go, internal/cli/sync_git_overlay_test.go, docs/features/sync.md)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.