---
title: internal/workspace
description: Go API reference for the workspace package.
---

<!-- Code generated by gomarkdoc. DO NOT EDIT -->

# workspace

```go
import "github.com/jbcom/radioactive-ralph/internal/workspace"
```

Package workspace manages the on\-disk git workspace a variant runs in.

Four orthogonal knobs, resolved from variant profile \+ config.toml overrides with safety\-floor precedence:

```
isolation     — shared | shallow | mirror-single | mirror-pool
object_store  — reference | full  (mirror-* only)
sync_source   — local | origin | both
lfs_mode      — full | on-demand | pointers-only | excluded
```

Dispatch:

- shared → no mirror, no worktree; variant runs against the operator's repo
- shallow → git clone \-\-depth=1 into StateRoot/\<hash\>/shallow
- mirror\-single → git clone \-\-mirror into MirrorGit, one worktree
- mirror\-pool → mirror \+ up to MaxParallelWorktrees worktrees

Zero git work happens in the package outside of clone, fetch, repack, and worktree add/remove. Commits, PRs, merges, and history rewrites are operator\-skill work that lives inside the worktree Claude session.

## Index

- [func CopyHooks\(repoPath, mirrorGit string\) error](<#CopyHooks>)
- [func HasLFS\(repoPath string\) \(bool, error\)](<#HasLFS>)
- [type Manager](<#Manager>)
  - [func New\(repoPath string, p variant.Profile, isolation variant.IsolationMode, objectStore variant.ObjectStoreMode, syncSource variant.SyncSource, lfs variant.LFSMode\) \(\*Manager, error\)](<#New>)
  - [func \(m \*Manager\) AcquireWorktree\(ctx context.Context\) \(\*Worktree, error\)](<#Manager.AcquireWorktree>)
  - [func \(m \*Manager\) Fetch\(ctx context.Context\) error](<#Manager.Fetch>)
  - [func \(m \*Manager\) Init\(ctx context.Context\) error](<#Manager.Init>)
  - [func \(m \*Manager\) Pool\(\) \[\]\*Worktree](<#Manager.Pool>)
  - [func \(m \*Manager\) Reconcile\(ctx context.Context\) error](<#Manager.Reconcile>)
  - [func \(m \*Manager\) ReleaseWorktree\(ctx context.Context, wt \*Worktree\) error](<#Manager.ReleaseWorktree>)
- [type Worktree](<#Worktree>)


<a name="CopyHooks"></a>
## func [CopyHooks](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/workspace/hooks.go#L19>)

```go
func CopyHooks(repoPath, mirrorGit string) error
```

CopyHooks copies the operator's .git/hooks/\* into the mirror's hooks/ directory. Preserves the executable bit so a repo's pre\-commit / pre\-push still runs inside a worktree.

The mirror is a bare clone so its hooks live under MirrorGit/hooks, not MirrorGit/.git/hooks.

If the operator's hooks dir is missing, this is a no\-op.

<a name="HasLFS"></a>
## func [HasLFS](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/workspace/lfs.go#L17>)

```go
func HasLFS(repoPath string) (bool, error)
```

HasLFS reports whether repoPath has \`.gitattributes\` entries that reference git\-lfs filters. Used by pre\-flight to decide whether LFS knob choices matter at all.

<a name="Manager"></a>
## type [Manager](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/workspace/workspace.go#L37-L62>)

Manager coordinates the per\-variant on\-disk workspace.

```go
type Manager struct {
    // RepoPath is the absolute path to the operator's repo.
    RepoPath string

    // Paths is the resolved XDG layout for this repo.
    Paths xdg.Paths

    // Variant is the active profile driving the workspace.
    Variant variant.Profile

    // Isolation, ObjectStore, SyncSource, LFS are the resolved values
    // (variant default, possibly overridden by config.toml, with safety
    // floors pinned at config.Resolve time).
    Isolation   variant.IsolationMode
    ObjectStore variant.ObjectStoreMode
    SyncSource  variant.SyncSource
    LFS         variant.LFSMode

    // CopyHooksEnabled controls whether operator's .git/hooks are copied
    // to mirror.git on Init. Default true.
    CopyHooksEnabled bool
    // contains filtered or unexported fields
}
```

<a name="New"></a>
### func [New](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/workspace/workspace.go#L67-L70>)

```go
func New(repoPath string, p variant.Profile, isolation variant.IsolationMode, objectStore variant.ObjectStoreMode, syncSource variant.SyncSource, lfs variant.LFSMode) (*Manager, error)
```

New constructs a Manager for repoPath with the given profile and resolved knob values. The repoPath MUST be an existing git repo; callers verify this in pre\-flight.

<a name="Manager.AcquireWorktree"></a>
### func \(\*Manager\) [AcquireWorktree](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/workspace/worktree.go#L55>)

```go
func (m *Manager) AcquireWorktree(ctx context.Context) (*Worktree, error)
```

AcquireWorktree creates a new worktree for an available slot and returns it. Returns errPoolFull if all slots are in use.

Branch is named \`ralph/\<variant\>/\<slot\>\-\<gen\>\` where gen is a monotonic counter so recycled slots never collide with stale worktree admin data in git.

<a name="Manager.Fetch"></a>
### func \(\*Manager\) [Fetch](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/workspace/workspace.go#L223>)

```go
func (m *Manager) Fetch(ctx context.Context) error
```

Fetch refreshes the mirror from its configured remotes. Two\-remote variants \(sync\_source=both\) fetch from local first \(fast, shared objects\), then from origin to pick up anything merged remotely.

<a name="Manager.Init"></a>
### func \(\*Manager\) [Init](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/workspace/workspace.go#L104>)

```go
func (m *Manager) Init(ctx context.Context) error
```

Init performs first\-run setup for this variant's workspace. Safe to call multiple times — each step checks whether the target already exists and is correctly formed.

Idempotent actions:

- IsolationShared: ensures RepoPath exists, returns.
- IsolationShallow: ensures shallow clone exists; fetches if stale.
- IsolationMirrorSingle / IsolationMirrorPool: ensures mirror.git exists, fetches from configured remotes, copies hooks, sets LFS config, repacks if corruption detected.

<a name="Manager.Pool"></a>
### func \(\*Manager\) [Pool](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/workspace/worktree.go#L38>)

```go
func (m *Manager) Pool() []*Worktree
```

Pool returns the current list of live worktrees. Callers should not mutate the slice.

<a name="Manager.Reconcile"></a>
### func \(\*Manager\) [Reconcile](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/workspace/worktree.go#L141>)

```go
func (m *Manager) Reconcile(ctx context.Context) error
```

Reconcile walks \`git worktree list\` and removes any registered worktrees whose disk paths have disappeared \(likely from an ungraceful prior shutdown\). Called at supervisor boot after replaying the event log.

<a name="Manager.ReleaseWorktree"></a>
### func \(\*Manager\) [ReleaseWorktree](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/workspace/worktree.go#L118>)

```go
func (m *Manager) ReleaseWorktree(ctx context.Context, wt *Worktree) error
```

ReleaseWorktree removes a worktree and frees its slot. Safe to call on a crashed worktree — uses \`worktree remove \-\-force\`.

<a name="Worktree"></a>
## type [Worktree](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/workspace/worktree.go#L16-L25>)

Worktree describes a live git worktree created by the manager.

```go
type Worktree struct {
    // Slot is the worktree index inside the pool (0..MaxParallelWorktrees-1).
    Slot int

    // Path is the absolute path on disk where the worktree is checked out.
    Path string

    // Branch is the ref HEAD points to inside the worktree.
    Branch string
}
```

Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)