# Git Transfer Semantics

Cloud Harness MCP enforces strict isolation between repository execution containers and GitHub credentials.

## The Transfer Problem

Standard coding agent sandboxes either:
1. Embed the user's GitHub Personal Access Token or SSH key directly into the container filesystem or environment (allowing arbitrary scripts or dependencies to steal the credential), or
2. Forbid remote push entirely, requiring manual user intervention.

## The Sibling Helper Solution

Cloud Harness solves this with an **ephemeral sibling Git helper**:

```
[ Workspace Container ] (no network, no token)
       ▲
       │ (local disk mount)
       ▼
[ Host Repo Directory ]
       ▲
       │ (local disk mount)
       ▼
[ Sibling Git Helper ] ──(token over stdin)──► [ github.com:owner/repo.git ]
```

1. The agent invokes `git_push(refspec, forceWithLease?, expectedRemoteOid?, idempotencyKey?)`.
2. The Runner starts an ephemeral Alpine container with network access scoped only to `github.com`.
3. The Runner streams an installation token over `stdin` into the helper's `git-credential` helper.
4. The helper executes the push against the remote origin and immediately exits.
5. The container is destroyed. The token is never written to disk or `.git/config`.

## Compare-and-Swap (CAS) & Concurrency Control

- **`git_commit` HEAD Guard (`expectedHeadOid`):** Prevents commits on top of unexpected intermediate state. If the workspace HEAD has moved, the commit is rejected with `STALE_HEAD`.
- **`git_push` Force-with-Lease (`expectedRemoteOid`):** Pushes with `forceWithLease: true` require `expectedRemoteOid`. If the remote branch has diverged, the push fails with `CONFLICT` to prevent silent overwrites.

## Idempotency & Unknown-Outcome Recovery

Network failures or runner restarts during a push can leave the client unsure whether the commit reached the remote repository.

1. Supply an `idempotencyKey` on the initial `git_push` or `workspace_finalize` call.
2. If a transport timeout or network drop occurs, the runner returns `UNKNOWN_REMOTE_STATE` with `resumeAction: "reconcile_push"`.
3. Retrying the identical request with the same `idempotencyKey` triggers automatic remote-ref reconciliation (`git ls-remote` probe). If the commit already landed on the remote branch, the call returns success with `alreadyFinalized: true` without pushing duplicate commits.

## Owner-Scoped Repository Cache

When `enableRepoCache` is enabled, the runner maintains bare Git repository caches partitioned strictly by the authenticated principal ID. Initial clones use `git clone --reference-if-able <cache> --dissociate` to leverage shared local object storage while ensuring that each workspace has a fully detached, independent, and isolated working tree.