Documentation
¶
Overview ¶
Package worker manages the full lifecycle of spawned worker sessions.
It handles worker spawning (git worktree setup, tmux session creation, runtime launch command assembly via the gatekeeper deadman-switch wrapper), taskwarrior hook processing (on-add enrichment and on-modify cleanup triggers), worker listing, and session teardown. Workers run in isolated git worktrees within tmux sessions and are tracked via taskwarrior UDAs. The gatekeeper subprocess ensures the AI runtime binary is wrapped for safe lifecycle management.
Plane: manager
Index ¶
- Constants
- Variables
- func CleanupDir() (string, error)
- func ExecuteCleanup(req CleanupRequest, path string, force bool) error
- func Gatekeeper(cfg GatekeeperConfig) int
- func HookOnAdd()
- func HookOnModify()
- func Install() error
- func InstallHooks(hookDir string) error
- func List() error
- func NotifyTelegram(message string)
- func PrintResult(r *CloseResult)
- func RequestCleanup(sessionID, taskUUID string) error
- func RunCleanup(path string, force bool) error
- func RunPendingCleanups(force bool) error
- func Spawn(cfg SpawnConfig) error
- func Uninstall() error
- func WorktreeBranch(taskUUID, projectAlias string) (string, error)
- type CleanupRequest
- type CloseResult
- type GatekeeperConfig
- type SpawnConfig
- type WorkerInfo
- type WorkerStatus
Constants ¶
const CoderAgentName = "coder"
CoderAgentName is the canonical agent name for worker (coder) sessions. Referenced by spawn.go (--agent flag, tmux window, TTAL_AGENT_NAME) and daemon/routing.go (workerWindow). Change here to rename everywhere.
Variables ¶
var ErrNeedsDecision = fmt.Errorf("needs manual decision")
ErrNeedsDecision indicates the worker needs manual intervention (exit code 1).
Functions ¶
func CleanupDir ¶
CleanupDir returns the path to ~/.ttal/cleanup/ (shared across all teams).
func ExecuteCleanup ¶
func ExecuteCleanup(req CleanupRequest, path string, force bool) error
ExecuteCleanup processes a parsed cleanup request: closes the worker, and removes the request file. Returns error for callers that need it (CLI). The force parameter controls whether worker.Close uses force mode.
func Gatekeeper ¶
func Gatekeeper(cfg GatekeeperConfig) int
Gatekeeper runs a child command with deadman's switch behavior: - Starts child in its own process group - Monitors for parent death (orphaning) - Handles signals (SIGTERM, SIGINT, SIGHUP) by killing child
func HookOnAdd ¶
func HookOnAdd()
HookOnAdd handles the taskwarrior on-add event. Reads one JSON line from stdin, enriches inline if project is set, outputs to stdout.
func HookOnModify ¶
func HookOnModify()
HookOnModify is the main taskwarrior on-modify hook entry point.
func InstallHooks ¶ added in v1.2.0
InstallHooks writes taskwarrior hook scripts to the given directory.
func NotifyTelegram ¶
func NotifyTelegram(message string)
NotifyTelegram sends a notification to the team's Telegram chat using the dedicated notification bot token. Sends directly via Telegram API without going through the daemon socket. Fire-and-forget: errors are logged but not propagated.
func PrintResult ¶
func PrintResult(r *CloseResult)
PrintResult outputs the close result in a machine-parseable format matching the Python script's output format.
func RequestCleanup ¶
RequestCleanup writes a cleanup request file for the daemon to process. This is fire-and-forget — the file persists even if the daemon is down. All teams share a single cleanup dir (~/.ttal/cleanup/) — requests are globally unique.
func RunCleanup ¶
RunCleanup processes a single cleanup request file. Designed for manual invocation via `ttal worker cleanup`.
func RunPendingCleanups ¶
RunPendingCleanups processes all .json files in the cleanup directory.
func Spawn ¶
func Spawn(cfg SpawnConfig) error
Spawn creates a new worker: validates task, sets up worktree, launches tmux session, and tracks the worker in taskwarrior.
func WorktreeBranch ¶ added in v1.7.0
WorktreeBranch returns the current git branch for a task's worktree. Derives worktree path from task UUID + project alias (no branch UDA needed). Returns error if worktree doesn't exist or has no branch.
Types ¶
type CleanupRequest ¶
type CleanupRequest struct {
SessionID string `json:"session_id"`
TaskUUID string `json:"task_uuid"`
CreatedAt time.Time `json:"created_at"`
}
CleanupRequest is written to ~/.ttal/cleanup/<session>.json by workers after merge.
type CloseResult ¶
type CloseResult struct {
Cleaned bool
Forced bool
Merged string // "true", "false", "no_pr"
Clean bool
Status string
StateDump string
Error bool
}
CloseResult holds the outcome of a close operation.
func Close ¶
func Close(sessionID string, force bool) (*CloseResult, error)
Close handles worker cleanup with smart or force mode.
Exit semantics (reflected in the returned error and CloseResult):
nil error + Cleaned=true → cleaned up successfully (exit 0) ErrNeedsDecision → needs manual decision (exit 1) other error → script/worker error (exit 2)
type GatekeeperConfig ¶
type GatekeeperConfig struct {
// TaskFile is used only for Codex workers until #321 (Codex JSONL resume support).
// CC workers deliver prompts via synthetic JSONL sessions (claude --resume).
TaskFile string
Command []string
}
GatekeeperConfig holds configuration for the gatekeeper process.
type SpawnConfig ¶
type SpawnConfig struct {
Name string
Project string
TaskUUID string
Worktree bool
Force bool
Runtime runtime.Runtime
Spawner string // team:agent format, set by ttal go
}
SpawnConfig holds configuration for spawning a worker.
type WorkerInfo ¶
type WorkerInfo struct {
Task taskwarrior.Task
Status WorkerStatus
}
WorkerInfo holds a worker task with its derived status.
type WorkerStatus ¶
type WorkerStatus int
WorkerStatus represents the categorized status of a worker.
const ( StatusRunning WorkerStatus = iota // No PR yet StatusWithPR // PR created )
func (WorkerStatus) String ¶
func (s WorkerStatus) String() string
Source Files