small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
albedo robot-docs worktrees.md
2.9 kB · 67 lines
Markdown
at main

Worktrees #

The worktrees extension creates and tracks version-control checkouts for sessions and agents. Its extension registers host calls and managed context. worktree.gleam owns the common record and lifecycle.

Layout #

worktree.base_dir places managed checkouts under $ALBEDO_HOME/wt. worktree_path adds a repository slug and a chosen name. The record distinguishes the checkout path from workspace, which preserves the origin's subdirectory within the checkout. origin records the originating workspace. Creation rejects remote SSH locations.

Worktree providers #

A worktree.Provider detects a repository and implements creation, listing, and removal for its version-control system. worktree.detect selects a matching enabled provider. worktree.create creates the checkout and records it. If recording fails, it attempts to remove the checkout. The extension can select a provider by kind. See worktree.gleam and the extension dispatch.

Python #

The Python binding exposes asynchronous worktrees.create, get, query, list, and remove. A Worktree record includes its ID, repository, workspace, kind, revision, branch, session, and existence state. query supports filters. list returns the matching records.

worktree.remove refuses the main checkout and paths outside the managed base. Without force, it refuses a worktree occupied by a running session. Removal deletes the checkout, then runs every declared extension's WorktreeRemoved follower in the transaction that deletes the record. Route callers pass context.followers. The work extension's follower moves work-ledger entries to the origin checkout. Closing an agent does not automatically delete its worktree. See remove and the extension instructions.

Agents #

The extension accepts a worktree for agent creation, or a request to create one for the agent. The agent's workspace then points into that checkout. See the worktrees extension and agents.

Managed context #

For a session associated with a worktree, the extension adds context naming the checkout and origin. Its context identifies the origin as the shared scope for memory and the work ledger. See workspaces for locations and links.