devsandbox

package
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 12, 2026 License: AGPL-3.0 Imports: 18 Imported by: 0

README

internal/devsandbox

Dev sandboxes for developing loom inside loom. A sandbox is a named, persistent dir under BaseDir() (${XDG_STATE_HOME:-~/.local/state}/loom-dev/<name>) holding a dev build, a toy workspace, seeded config, its own global dir and a private tmux server (loomdev-<name>), so a dev loom runs from inside a loom pane without touching the host's sessions or state. Design: docs/superpowers/specs/2026-09-16-dev-sandbox-design.md. CLI: tools/loomdev; deterministic agent stand-in: tools/fakeagent. tools/ is excluded from the Nix package.

Layout and setup (sandbox.go, up.go, toyrepo.go)

  • Open validates the name and computes the paths: bin/ (LoomBin, FakeAgentBin, PersonaDir), global/ (GlobalDir, the sandbox's LOOM_GLOBAL_DIR), home/ (HomeDir, its LOOM_HOME), repo/ (the toy workspace, WorkspaceName) and origin.git; sandbox.json is its Meta (source worktree, build SHA, the sticky real-Claude flag).
  • Up creates the sandbox or tops up a partial one: the toy repo with a bare origin, the sandbox config and state seeded into both global/ and repo/.loom/, and the registry entry. Each step checks for its own artifact, so re-running is safe; it warns when the sandbox was last used from another source worktree and refuses a path holding whitespace (loom splits program strings on spaces).
  • SeedWorkspace gives another workspace repository (one a test registers with loom workspace add) the toy workspace's config and state; without it that workspace runs the default program, the real claude. The profiles are fake, fake-claude, fake-aider, fake-claude-trust (the Claude persona, which stops at its trust prompt on every launch until something answers it) and shell.
  • Build compiles loom and fakeagent from the source worktree; BuildLoom compiles another build beside it, with ldflags (a newer release for the replace-the-daemon tests, say).
  • Env is the overlay every sandboxed process runs with (LOOM_TMUX_SOCKET, LOOM_GLOBAL_DIR, LOOM_HOME); Environ appends it to the process environment, and Cmd runs a command in it from the toy repo.

The daemon

A sandboxed loom spawns the sandbox's own daemon (its own global dir), which outlives the driver. Daemon reads its lock record, StopDaemon stops it gracefully (its TUIs wait for a daemon), KillDaemon sends it SIGKILL as a crash does (its TUIs reconnect; ErrNoDaemon when none runs), Stop quits the driver and stops the daemon while StopDriver leaves it running, Start with Restart does both first, and Down stops it before removing the sandbox and the socket files a killed daemon or tmux left outside it. A lock holder that won't stop (a daemon past its stop timeout, a loom from before the daemon) makes Down fail with nothing removed, its error naming loomdev down --force; ForceDown (--force) kills it with SIGKILL instead, and KillDaemon (loomdev daemon --kill) does the same without removing anything, both only once its executable is proved a build in the sandbox's bin dir (killSandboxLoom, runsSandboxLoom), since a stale record's pid may have been reused. List reports every sandbox with its daemon, and TailLogs the end of each log (LogFiles: the TUI's loom.log files, the daemon's serve.log and serve-crash.log).

The driver (driver.go)

A headless loom in a tmux session (DriverSession, no loom prefix) on the sandbox's private socket: Start (StartOptions: pane size, command, restart), SendKeys/SendText, Screen, WaitFor (whose timeout error carries the screen) and Stop.

Start keeps a running driver and replaces a dead one, which remain-on-exit keeps for diagnosis. The private server exits with its last session, so the new-session after killing the old driver (or after Stop, for Restart) can reach that server while it exits; tmux then answers "server exited unexpectedly" having run nothing, and Start tries once more, which starts a fresh server.

For the e2e suite: WithDriver (a second driver session on the same daemon), BuildLoom, Cmd and Text (the pane with wrapped lines joined).

What it does not isolate

CLAUDE_CONFIG_DIR, PATH and the clipboard stay the host's. An account flow needs a throwaway CLAUDE_CONFIG_DIR and fakeagent first on PATH as claude; a drag-select in a sandboxed loom writes the host's clipboard.

Documentation

Overview

Package devsandbox creates and drives isolated loom dev environments: a named directory holding a dev build, a toy workspace repo, seeded config, and a private tmux server, so a dev loom can run from inside a loom pane without touching the host's sessions or state. See docs/superpowers/specs/2026-09-16-dev-sandbox-design.md.

Index

Constants

View Source
const DriverSession = "dev-driver"

DriverSession is the tmux session the headless dev loom runs in. It has no loom_ prefix, so loom's orphan sweep never touches it.

View Source
const WorkspaceName = "toy"

WorkspaceName is the name the toy repo is registered under.

Variables

View Source
var ErrNoDaemon = errors.New("no loom daemon runs in the sandbox")

ErrNoDaemon: nothing holds the sandbox's lock, so there is no daemon to kill.

Functions

func BaseDir

func BaseDir() (string, error)

BaseDir returns the directory holding every sandbox: ${XDG_STATE_HOME:-~/.local/state}/loom-dev.

func DefaultName

func DefaultName(branch string) string

DefaultName derives a sandbox name from a git branch: the leaf after the last "/", lowercased, with runs of other characters collapsed to "-".

func ShellQuote

func ShellQuote(s string) string

ShellQuote single-quotes s for a POSIX shell.

Types

type Info

type Info struct {
	Name        string
	Dir         string
	ServerAlive bool
	Meta        *Meta // nil when sandbox.json is missing or unreadable
	// Daemon is the lock record of the process holding the sandbox's global
	// dir (its daemon, or one still booting: no socket yet); nil when none
	// holds it.
	Daemon *daemon.Record
}

Info summarizes one sandbox for List.

func List

func List() ([]Info, error)

List returns every sandbox under BaseDir, sorted by name.

type Meta

type Meta struct {
	Name           string    `json:"name"`
	Socket         string    `json:"socket"`
	SourceWorktree string    `json:"source_worktree"`
	BuildSHA       string    `json:"build_sha,omitempty"`
	RealClaude     bool      `json:"real_claude"`
	CreatedAt      time.Time `json:"created_at"`
}

Meta is the sandbox's sandbox.json.

type Sandbox

type Sandbox struct {
	Name string
	Dir  string
	// contains filtered or unexported fields
}

Sandbox is one named, persistent dev environment.

func Open

func Open(name string) (*Sandbox, error)

Open resolves the sandbox called name without touching disk.

func (*Sandbox) BinDir

func (s *Sandbox) BinDir() string

BinDir holds the sandbox's built binaries.

func (*Sandbox) Build

func (s *Sandbox) Build(srcDir string) error

Build compiles loom and fakeagent from the module rooted at srcDir into the sandbox and records the source revision. The sandbox must be Up. A sandbox daemon still running the previous build is replaced by the next sandboxed loom to start when this build is newer (rpc.CompareBuilds: a later commit, or an edited tree rebuilt at the same one, which takes a srcDir that is a git checkout, so the build names its commit); an older one is refused, and one naming no commit joins the running daemon, so the daemon must be stopped first.

func (*Sandbox) BuildLoom added in v0.14.0

func (s *Sandbox) BuildLoom(srcDir, out, ldflags string) error

BuildLoom compiles loom from the module rooted at srcDir to out, with ldflags when not empty: another build beside the sandbox's own, such as `-X main.version=99.0.0` for a newer release. Run it with Cmd, or in a driver (StartOptions.Command), to use the sandbox.

func (*Sandbox) Cmd added in v0.14.0

func (s *Sandbox) Cmd(argv ...string) *exec.Cmd

Cmd runs argv in the sandbox's environment from the toy repo, as a sandboxed loom would run: Cmd(sb.LoomBin(), "serve", "stop"), say.

func (*Sandbox) Daemon added in v0.14.0

func (s *Sandbox) Daemon() (rec daemon.Record, held bool)

Daemon reads the lock record of the sandbox's daemon, the `loom serve` a sandboxed loom started (with the sandbox's global dir). held reports whether a process holds the lock now: a daemon, or one still booting (no socket yet).

func (*Sandbox) Down

func (s *Sandbox) Down() error

Down stops the sandbox's loom daemon (a sandboxed loom started it, with the sandbox's global dir), kills its private tmux server and deletes its directory, and the socket files both leave outside it. It refuses any Dir that is not <BaseDir>/<Name>. A daemon that won't stop, or a loom from before the daemon holding the sandbox's lock, stops it with nothing removed; ForceDown kills that process instead.

func (*Sandbox) Driver added in v0.14.0

func (s *Sandbox) Driver() string

Driver is the tmux session the driver methods act on.

func (*Sandbox) DriverRunning

func (s *Sandbox) DriverRunning() bool

DriverRunning reports whether the driver session exists and its program is still alive (a dead pane is kept by remain-on-exit). false also covers a session that has been fully removed (e.g. after Stop), even when paneDead's underlying query returns the empty-output false-success some tmux builds give for a missing target — see paneDead.

func (*Sandbox) Env

func (s *Sandbox) Env() []string

Env is the environment overlay every sandboxed loom process runs with.

func (*Sandbox) Environ

func (s *Sandbox) Environ() []string

Environ is os.Environ() with Env() appended; os/exec uses the last value of a duplicated key, so the overlay wins.

func (*Sandbox) FakeAgentBin

func (s *Sandbox) FakeAgentBin() string

FakeAgentBin is the built fakeagent.

func (*Sandbox) ForceDown added in v0.14.0

func (s *Sandbox) ForceDown() error

ForceDown is Down, except that a process holding the sandbox's lock that won't stop (a daemon past its stop timeout, a loom from before the daemon) is killed with SIGKILL, once it is proved the sandbox's own loom (killSandboxLoom).

func (*Sandbox) GlobalDir

func (s *Sandbox) GlobalDir() string

GlobalDir is LOOM_GLOBAL_DIR: workspaces.json plus the global context's config and state.

func (*Sandbox) HomeDir

func (s *Sandbox) HomeDir() string

HomeDir is LOOM_HOME: startup logs.

func (*Sandbox) KillDaemon added in v0.14.0

func (s *Sandbox) KillDaemon() (daemon.Record, error)

KillDaemon kills the sandbox's daemon with SIGKILL, as a crash does: no bye, no save, and the socket file stays behind. The sessions keep running on the sandbox's tmux server, and a TUI open on the daemon sees a crash, not a stop. It kills only a process proved a build in the sandbox's bin dir (killHolder), and returns the record of the daemon it killed; ErrNoDaemon when none runs, or when it exited before the signal arrived.

func (*Sandbox) LoadMeta

func (s *Sandbox) LoadMeta() (*Meta, error)

LoadMeta reads sandbox.json; the error wraps os.ErrNotExist when the sandbox has never been brought up.

func (*Sandbox) LogFiles

func (s *Sandbox) LogFiles() []string

LogFiles lists the log files a sandboxed loom writes: its TUI's loom.log files, and its daemon's serve.log and the crash file beside it (the runtime's own report of a fatal error, which serve.log can't hold).

func (*Sandbox) LoomBin

func (s *Sandbox) LoomBin() string

LoomBin is the dev build of loom.

func (*Sandbox) OriginDir

func (s *Sandbox) OriginDir() string

OriginDir is the toy repo's bare remote.

func (*Sandbox) PersonaDir

func (s *Sandbox) PersonaDir() string

PersonaDir holds the fakeagent persona symlinks.

func (*Sandbox) RepoDir

func (s *Sandbox) RepoDir() string

RepoDir is the toy workspace repo.

func (*Sandbox) Screen

func (s *Sandbox) Screen(ansi bool) (string, error)

Screen captures the driver pane; ansi keeps colors and attributes. A live pane is captured exactly as shown, nothing more. Once the pane's program has exited, one extra line of scrollback is included: on this tmux, writing the remain-on-exit message unconditionally scrolls a dead pane up by exactly one line before printing "Pane is dead …", which would otherwise drop the program's last line of output from a plain capture.

func (*Sandbox) SeedWorkspace added in v0.14.0

func (s *Sandbox) SeedWorkspace(repoDir string) error

SeedWorkspace gives the workspace repository repoDir, which a test registers with `loom workspace add`, the toy workspace's config and state (as Up does the toy repo): its sessions run the fake agent, and no first-run overlay stops a headless driver. Without it a workspace defaults to the real `claude`. The sandbox must be Up.

func (*Sandbox) SendKeys

func (s *Sandbox) SendKeys(keys ...string) error

SendKeys sends tmux key names (e.g. "n", "Enter", "Escape", "C-c") to the driver pane. A word tmux does not recognize is typed as characters.

func (*Sandbox) SendText

func (s *Sandbox) SendText(text string) error

SendText types text literally, with no key-name interpretation.

func (*Sandbox) Socket

func (s *Sandbox) Socket() string

Socket is the sandbox's private tmux socket name (tmux -L).

func (*Sandbox) Start

func (s *Sandbox) Start(opts StartOptions) error

Start launches the driver session on the private server. A running driver is kept and a dead one replaced, unless opts.Restart is set: that stops the driver and the sandbox's daemon first (Stop), so the dev loom starts afresh.

func (*Sandbox) Stop

func (s *Sandbox) Stop(grace time.Duration) error

Stop quits the dev loom: its TUI (StopDriver), then the sandbox's daemon (StopDaemon). Loom's own agent sessions stay on the private server, so the next Start boots a fresh daemon that reattaches them: the restore path. A daemon serves every driver, so stopping it ends another driver's TUI too.

func (*Sandbox) StopDaemon added in v0.14.0

func (s *Sandbox) StopDaemon() error

StopDaemon stops the sandbox's daemon gracefully (it saves first) and waits for it to go; no daemon running is fine. The sessions keep running on the sandbox's tmux server, and the next sandboxed loom starts a fresh daemon, which reattaches them.

func (*Sandbox) StopDriver added in v0.14.0

func (s *Sandbox) StopDriver(grace time.Duration) error

StopDriver asks the driver's program to quit with `q`, waits up to grace for it to exit, then removes the driver session. The sandbox's daemon keeps running, as after a real quit, so the next Start connects to it.

func (*Sandbox) TailLogs

func (s *Sandbox) TailLogs(n int) string

TailLogs returns the last n lines of each existing sandbox log, each under a tail(1)-style "==> path <==" header.

func (*Sandbox) Text added in v0.14.0

func (s *Sandbox) Text() (string, error)

Text captures the driver pane's text, its scrollback included, with lines the pane wrapped joined: a message wider than the pane (an exited loom's error, say) reads whole.

func (*Sandbox) Up

func (s *Sandbox) Up(opts UpOptions) error

Up creates the sandbox or tops up a partial one. Each step checks for its own artifact, so re-running is safe; config.json is only rewritten when it is missing or opts asks for a profile change.

func (*Sandbox) WaitFor

func (s *Sandbox) WaitFor(text string, timeout time.Duration) error

WaitFor polls the driver screen until text appears or timeout elapses.

func (*Sandbox) WithDriver added in v0.14.0

func (s *Sandbox) WithDriver(name string) (*Sandbox, error)

WithDriver is the sandbox driven through the tmux session name rather than DriverSession: a second headless loom beside the first, on the same server and the same daemon. Everything else is the sandbox's own.

func (*Sandbox) WorkspaceConfigDir

func (s *Sandbox) WorkspaceConfigDir() string

WorkspaceConfigDir is the toy workspace's .loom directory.

type StartOptions

type StartOptions struct {
	// Width and Height size the driver pane (0 means 160×48).
	Width, Height int
	// Restart replaces an already-running driver instead of keeping it.
	Restart bool
	// Command overrides the program (default: the dev loom on the toy
	// workspace). Tests use it to drive plain shell programs.
	Command []string
}

StartOptions configures Start.

type UpOptions

type UpOptions struct {
	// SourceWorktree is the loom checkout the sandbox builds from.
	SourceWorktree string
	// RealClaude adds a profile running the real claude CLI. Sticky.
	RealClaude bool
	// DefaultProfile selects config.json's default profile ("" keeps the
	// existing file, or "fake" for a new one). Non-empty rewrites config.json.
	DefaultProfile string
	// Warn, when non-nil, receives non-fatal warnings.
	Warn io.Writer
}

UpOptions configures Up.

type WaitTimeoutError

type WaitTimeoutError struct {
	Text    string
	Timeout time.Duration
	// Screen is the last successful capture, for diagnosis.
	Screen string
}

WaitTimeoutError is returned by WaitFor when the text never appears.

func (*WaitTimeoutError) Error

func (e *WaitTimeoutError) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL