Documentation
¶
Overview ¶
Package workspace manages a bones workspace: the .bones/ directory, its on-disk config, and the associated leaf daemon process. Workspaces created before the rename used .agent-infra/; both Init and Join silently migrate that legacy name to .bones/ on first touch.
Two entry points:
Init creates a fresh workspace and starts a leaf daemon. Join locates an existing workspace (walking up from cwd) and verifies its leaf is reachable.
Index ¶
Constants ¶
const BonesDirEnvVar = "BONES_DIR"
BonesDirEnvVar is the name of the environment variable that, when set, relocates the workspace's bones-state directory away from <root>/.bones/ to an arbitrary path. Mirrors BEADS_DIR.
Variables ¶
var ( ErrAlreadyInitialized = errors.New("workspace already initialized") ErrNoWorkspace = errors.New("no bones workspace found") ErrLeafUnreachable = errors.New("leaf daemon not reachable") ErrLeafStartTimeout = errors.New("leaf daemon failed to start within timeout") ErrLegacyLayout = errors.New("workspace uses pre-ADR-0041 layout") )
Functions ¶
func BonesDir ¶ added in v0.11.0
BonesDir returns the bones storage directory for the workspace at root. Honors the BONES_DIR environment variable: when set, returns the env value (absolutized) verbatim; when unset, returns <root>/.bones/ as the canonical layout.
Operator owns safety. We do not reject ../../etc/passwd or refuse paths outside $HOME — the operator typed it and owns the consequences. (Issue #291.)
Used everywhere bones reasons about workspace-local state: the hub fossil, agent.id, scaffold_version, hub.pid, manifest, swarm slot dirs, etc. The workspace marker (.bones/agent.id) lookup in walkUp also honors this — see FindRoot.
func ExitCode ¶
ExitCode maps errors returned by Init and Join to conventional process exit codes: 0 on success, 2-6 for known sentinels, 1 for anything else. Callers that want a different convention can inspect errors directly.
func FindRoot ¶ added in v0.4.0
FindRoot is the unauthenticated workspace lookup: walks up from start until it finds a directory containing the .bones marker dir, returns that directory, or ErrNoWorkspace if the filesystem root is reached.
Unlike Join, FindRoot does not load config.json or contact the leaf daemon — useful for commands that only need the workspace path (e.g. bones apply, which materializes from the hub fossil and never talks to the leaf).
func HubIsHealthy ¶ added in v0.9.0
HubIsHealthy returns true when hub.pid resolves to a live process and a /healthz GET succeeds within 500ms. False on any failure — caller responds by calling hubStartFunc, or (for read-only verbs) by rendering degraded-mode output.
Exported so read-only verbs (e.g. `bones status`, #207) can probe hub liveness without going through Join, whose auto-start branch would contradict the lazy-hub promise printed by `bones up`.
func MarkerDirName ¶ added in v0.11.0
func MarkerDirName() string
MarkerDirName returns the canonical bones-dir basename relative to a workspace root (".bones"). Exposed so callers outside the workspace package — primarily migration helpers and tests — can reason about the workspace-local layout without reaching into the unexported markerDirName const.
This is NOT the same as BonesDir(root): when BONES_DIR is set, the on-disk state lives elsewhere, but the in-tree marker name is still ".bones" for the purposes of walkUp's check at root.
Types ¶
type Info ¶
Info describes a live workspace. Returned by both Init and Join.
func Init ¶
Init scaffolds a fresh workspace at cwd: ensures .bones/ exists, writes agent.id (idempotent — reused if already present), and transparently migrates a pre-ADR-0041 layout if found. Does NOT start the hub — hub.Start runs lazily on first verb that needs it via workspace.Join.
Returns ErrLegacyLayout if a pre-ADR-0041 hub is still running and must be torn down via `bones down` before migration can proceed.
Init is idempotent: re-invocation against an existing workspace succeeds with the existing agent.id.
func Join ¶
Join locates the nearest .bones/ walking up from cwd, ensures the hub is running (auto-starting via hub.Start when not healthy), and returns a populated Info. A pre-rename .agent-infra/ marker rooted at cwd is silently migrated to .bones/ before walkUp; a pre-ADR-0041 .orchestrator/ layout is migrated transparently when no legacy hub is running, or surfaced as ErrLegacyLayout when one is.
Auto-start is silent on stderr (#249): Claude Code's SessionStart hook treats any stderr output as a "Failed with non-blocking status code" UI error, so an informational "starting hub" line surfaces as a phantom failure on every fresh session. Hub start details are captured in .bones/hub.log instead.
Source Files