Workspaces and git

When a task is bound to a repository, the runner keeps a real checkout of that repository on your machine and works in it. Nothing is cloned fresh per task, and nothing is thrown away between runs.

A task gets bound to a repository by the project it belongs to, so nothing here happens until you have connected a repository.

One workspace per repository

Workspaces are long lived, one per repository, not one per task:

~/.commandchain/workspaces/
  github-com-alpenglow-summitline/
    .git/
    ... the working tree, on the current task branch

The directory name is derived from the repository URL, so the same repository always lands in the same place no matter how it is addressed:

Repository URL	Directory
https://github.com/alpenglow/summitline.git	github-com-alpenglow-summitline
git@github.com:alpenglow/summitline.git	github-com-alpenglow-summitline
ssh://git@bitbucket.org/alpenglow/summitline	bitbucket-org-alpenglow-summitline

Reusing the checkout is what keeps a run on a large repository quick: the second task on a repository fetches rather than clones.

The branch a task works on

Each task gets its own branch, named task/<task id>. A run can override the name, and it can say which branch to start from.

The runner prepares the branch before the agent starts:

1. Clone, if the repository is not in the workspace root yet.
2. Fetch all remotes and prune deleted ones.
3. Stash anything left uncommitted by a previous failed attempt, under a name that says where it came from, and log a warning. Work is never silently discarded.
4. Check out the task branch: existing locally, it is checked out and updated; existing only on the remote, it is checked out to track that remote; new, it is created from the base branch.

Then the coding agent runs, inside the sandbox, in that working tree.

The runner pushes, not the agent

When the agent finishes successfully, the runner commits the changes and pushes the branch, and reports the resulting commit back to your workspace. The commit is authored as CommandChain Runner <runner@commandchain.local>, so an automated change is never disguised as a person’s.

This split is a security property, not a convenience:

• The agent is sandboxed and has no access to your git credentials. It cannot push, and it cannot read the keys that would let it.
• The runner is not sandboxed, and it is the only thing that talks to your remote. It uses the SSH agent or git credential helper already configured for your user, so private repositories work with the access you already have.
• Git executes code it finds in a repository, in hook scripts and in command-valued configuration keys. Those paths are kept outside what the agent can write, and the runner re-establishes the layout after the agent process is gone and before it runs git itself. It also runs its own git with hooks disabled outright.

Set up git access before starting the runner

The runner uses whatever git access the machine already has:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519          # SSH, recommended

git config --global credential.helper store   # or an HTTPS credential helper

If git push works for you in a terminal on that machine, it works for the runner.

Where the workspaces live

The installer points the runner at ~/.commandchain/workspaces, created with mode 0700. The directory survives upgrades and ordinary uninstalls, and is deleted only by --uninstall --purge.

That matters more than it sounds: a task branch that has not been pushed yet lives there. See upgrades and uninstall.

Reviewing what came back

A finished coding run leaves you three things to look at: the branch on your remote, the commit reported on the run, and the run’s own timeline of what the agent did. Nothing is merged for you.

Next steps

• The security model: why the agent cannot reach git’s executable configuration.
• Knowledge in runs: what an agent can look up while it works.
• Troubleshooting: pushes that fail, and stashes you did not expect.