Documentation
¶
Index ¶
- Constants
- func MarshalToolData(claudeSessionID string, claudeDetectedAt time.Time, geminiSessionID string, ...) json.RawMessage
- func MigrateFromJSON(jsonPath string, db *StateDB) (int, int, error)
- func SetGlobal(db *StateDB)
- type GroupRow
- type InstanceRow
- type MultiRepoWorktreeData
- type RecentSessionRow
- type StateDB
- func (s *StateDB) AliveInstanceCount() (int, error)
- func (s *StateDB) CleanDeadInstances(timeout time.Duration) error
- func (s *StateDB) Close() error
- func (s *StateDB) DB() *sql.DB
- func (s *StateDB) DeleteGroup(path string) error
- func (s *StateDB) DeleteInstance(id string) error
- func (s *StateDB) ElectPrimary(timeout time.Duration) (bool, error)
- func (s *StateDB) GetMeta(key string) (string, error)
- func (s *StateDB) Heartbeat() error
- func (s *StateDB) IsEmpty() (bool, error)
- func (s *StateDB) LastModified() (int64, error)
- func (s *StateDB) LoadGroups() ([]*GroupRow, error)
- func (s *StateDB) LoadInstances() ([]*InstanceRow, error)
- func (s *StateDB) LoadRecentSessions() ([]*RecentSessionRow, error)
- func (s *StateDB) LoadWatcherByName(name string) (*WatcherRow, error)
- func (s *StateDB) LoadWatcherEvents(watcherID string, limit int) ([]WatcherEventRow, error)
- func (s *StateDB) LoadWatchers() ([]*WatcherRow, error)
- func (s *StateDB) LookupWatcherEventSessionByDedupKey(watcherID, dedupKey string) (string, error)
- func (s *StateDB) LookupWatcherIDByDedupKey(dedupKey string) (string, error)
- func (s *StateDB) Migrate() error
- func (s *StateDB) ReadAllStatuses() (map[string]StatusRow, error)
- func (s *StateDB) RegisterInstance(isPrimary bool) error
- func (s *StateDB) ResignPrimary() error
- func (s *StateDB) SaveGroups(groups []*GroupRow) error
- func (s *StateDB) SaveInstance(inst *InstanceRow) error
- func (s *StateDB) SaveInstances(insts []*InstanceRow) error
- func (s *StateDB) SaveRecentSession(row *RecentSessionRow) error
- func (s *StateDB) SaveWatcher(w *WatcherRow) error
- func (s *StateDB) SaveWatcherEvent(watcherID, dedupKey, sender, subject, routedTo, sessionID string, ...) (bool, error)
- func (s *StateDB) SetAcknowledged(id string, ack bool) error
- func (s *StateDB) SetMeta(key, value string) error
- func (s *StateDB) Touch() error
- func (s *StateDB) UnregisterInstance() error
- func (s *StateDB) UpdateInstanceField(id, field string, value any) error
- func (s *StateDB) UpdateWatcherEventRoutedTo(watcherID, dedupKey, routedTo, triageSessionID string) error
- func (s *StateDB) UpdateWatcherEventSessionID(watcherID, dedupKey, sessionID string) error
- func (s *StateDB) UpdateWatcherStatus(watcherID string, status string) error
- func (s *StateDB) WriteStatus(id, status, tool string) error
- type StatusRow
- type WatcherEventRow
- type WatcherRow
Constants ¶
const SchemaVersion = 7
SchemaVersion tracks the current database schema version. Bump this when adding migrations.
Variables ¶
This section is empty.
Functions ¶
func MarshalToolData ¶
func MarshalToolData( claudeSessionID string, claudeDetectedAt time.Time, geminiSessionID string, geminiDetectedAt time.Time, geminiYoloMode *bool, geminiModel string, openCodeSessionID string, openCodeDetectedAt time.Time, codexSessionID string, codexDetectedAt time.Time, latestPrompt string, notes string, loadedMCPNames []string, toolOptionsJSON json.RawMessage, sandboxJSON json.RawMessage, sandboxContainer string, sshHost string, sshRemotePath string, multiRepoEnabled bool, additionalPaths []string, multiRepoTempDir string, multiRepoWorktrees []MultiRepoWorktreeData, channels []string, extraArgs []string, color string, ) json.RawMessage
func MigrateFromJSON ¶
MigrateFromJSON reads a sessions.json file and inserts all data into the StateDB. Returns the number of instances and groups migrated.
Types ¶
type InstanceRow ¶
type InstanceRow struct {
ID string
Title string
ProjectPath string
GroupPath string
Order int
Command string
Wrapper string
Tool string
Status string
TmuxSession string
CreatedAt time.Time
LastAccessed time.Time
ParentSessionID string
IsConductor bool
NoTransitionNotify bool
// TmuxSocketName mirrors Instance.TmuxSocketName (v1.7.50+, issue #687).
// Empty for pre-v1.7.50 rows — those keep targeting the default server
// after upgrade.
TmuxSocketName string
// TitleLocked blocks Claude session-name sync into Title (v1.7.52+, issue #697).
TitleLocked bool
WorktreePath string
WorktreeRepo string
WorktreeBranch string
ToolData json.RawMessage // JSON blob for tool-specific data
}
InstanceRow represents a session row in the database.
type MultiRepoWorktreeData ¶ added in v0.26.2
type MultiRepoWorktreeData struct {
OriginalPath string
WorktreePath string
RepoRoot string
Branch string
}
MarshalToolData creates a tool_data JSON blob from individual fields. This is the forward path: Instance fields -> JSON blob for SQLite storage. MultiRepoWorktreeData holds multi-repo worktree info for serialization.
func UnmarshalToolData ¶
func UnmarshalToolData(data json.RawMessage) ( claudeSessionID string, claudeDetectedAt time.Time, geminiSessionID string, geminiDetectedAt time.Time, geminiYoloMode *bool, geminiModel string, openCodeSessionID string, openCodeDetectedAt time.Time, codexSessionID string, codexDetectedAt time.Time, latestPrompt string, notes string, loadedMCPNames []string, toolOptionsJSON json.RawMessage, sandboxJSON json.RawMessage, sandboxContainer string, sshHost string, sshRemotePath string, multiRepoEnabled bool, additionalPaths []string, multiRepoTempDir string, multiRepoWorktrees []MultiRepoWorktreeData, channels []string, extraArgs []string, color string, )
UnmarshalToolData extracts individual fields from the tool_data JSON blob. This is the reverse path: JSON blob from SQLite -> individual Instance fields.
type RecentSessionRow ¶ added in v0.20.0
type RecentSessionRow struct {
ID string // SHA-256 dedup key (title+path+tool+group)
Title string
ProjectPath string
GroupPath string
Command string
Wrapper string
Tool string
ToolOptions json.RawMessage // serialized ToolOptionsWrapper
SandboxEnabled bool
GeminiYoloMode *bool
DeletedAt time.Time
}
RecentSessionRow captures the config of a deleted session for quick re-creation.
type StateDB ¶
type StateDB struct {
// contains filtered or unexported fields
}
StateDB wraps a SQLite database for session/group persistence. Thread-safe for concurrent use from multiple goroutines within one process. Multiple OS processes can safely read/write via WAL mode + busy timeout.
func GetGlobal ¶
func GetGlobal() *StateDB
GetGlobal returns the global StateDB instance (may be nil).
func (*StateDB) AliveInstanceCount ¶
AliveInstanceCount returns how many TUI instances have fresh heartbeats.
func (*StateDB) CleanDeadInstances ¶
CleanDeadInstances removes heartbeat entries that haven't been updated within timeout.
func (*StateDB) DeleteGroup ¶
DeleteGroup removes a group by path.
func (*StateDB) DeleteInstance ¶
DeleteInstance removes an instance by ID.
func (*StateDB) ElectPrimary ¶ added in v0.11.1
ElectPrimary attempts to make this instance the primary. Returns true if this instance is now (or already was) the primary. Uses a transaction to atomically clear stale primaries and claim if available.
func (*StateDB) LastModified ¶
LastModified returns the last_modified timestamp from metadata.
func (*StateDB) LoadGroups ¶
LoadGroups returns all groups ordered by sort_order.
func (*StateDB) LoadInstances ¶
func (s *StateDB) LoadInstances() ([]*InstanceRow, error)
LoadInstances returns all instances ordered by sort_order.
func (*StateDB) LoadRecentSessions ¶ added in v0.20.0
func (s *StateDB) LoadRecentSessions() ([]*RecentSessionRow, error)
LoadRecentSessions returns all recent sessions ordered by most recently deleted.
func (*StateDB) LoadWatcherByName ¶ added in v1.5.1
func (s *StateDB) LoadWatcherByName(name string) (*WatcherRow, error)
LoadWatcherByName returns the watcher with the given name, or nil if not found. A missing watcher is not an error; (nil, nil) is returned.
func (*StateDB) LoadWatcherEvents ¶ added in v1.5.1
func (s *StateDB) LoadWatcherEvents(watcherID string, limit int) ([]WatcherEventRow, error)
LoadWatcherEvents returns up to limit events for the given watcher, ordered most recent first.
func (*StateDB) LoadWatchers ¶ added in v1.5.1
func (s *StateDB) LoadWatchers() ([]*WatcherRow, error)
LoadWatchers returns all watchers ordered by name.
func (*StateDB) LookupWatcherEventSessionByDedupKey ¶ added in v1.5.1
LookupWatcherEventSessionByDedupKey queries the session_id for a specific event. Returns ("", nil) if no matching event exists or session_id is empty.
func (*StateDB) LookupWatcherIDByDedupKey ¶ added in v1.5.1
LookupWatcherIDByDedupKey returns the watcher_id for the first watcher_events row with the given dedup_key. Returns an error if no row is found. Used by the triageReaper to correlate a result.json back to its originating event (D-08).
func (*StateDB) Migrate ¶
Migrate creates tables if they don't exist and runs any pending migrations.
func (*StateDB) ReadAllStatuses ¶
ReadAllStatuses returns status + acknowledged flag for every instance.
func (*StateDB) RegisterInstance ¶
RegisterInstance records this process as an active TUI instance.
func (*StateDB) ResignPrimary ¶ added in v0.11.1
ResignPrimary clears the is_primary flag for this process.
func (*StateDB) SaveGroups ¶
SaveGroups replaces all groups in a single transaction.
func (*StateDB) SaveInstance ¶
func (s *StateDB) SaveInstance(inst *InstanceRow) error
SaveInstance inserts or replaces a single instance.
func (*StateDB) SaveInstances ¶
func (s *StateDB) SaveInstances(insts []*InstanceRow) error
SaveInstances inserts or replaces multiple instances in a single transaction. It also removes any rows from the database that are not in the provided list, ensuring deleted sessions don't reappear on reload.
func (*StateDB) SaveRecentSession ¶ added in v0.20.0
func (s *StateDB) SaveRecentSession(row *RecentSessionRow) error
SaveRecentSession inserts or replaces a recent session entry, then prunes to 20.
func (*StateDB) SaveWatcher ¶ added in v1.5.1
func (s *StateDB) SaveWatcher(w *WatcherRow) error
SaveWatcher inserts or replaces a watcher row.
func (*StateDB) SaveWatcherEvent ¶ added in v1.5.1
func (s *StateDB) SaveWatcherEvent(watcherID, dedupKey, sender, subject, routedTo, sessionID string, maxEvents int) (bool, error)
SaveWatcherEvent inserts an event with dedup via INSERT OR IGNORE. Returns true if the row was inserted (new event), false if it was a duplicate. Prunes to maxEvents after successful insert.
func (*StateDB) SetAcknowledged ¶
SetAcknowledged sets or clears the acknowledged flag for an instance.
func (*StateDB) Touch ¶
Touch updates a metadata timestamp that other instances can poll to detect changes.
func (*StateDB) UnregisterInstance ¶
UnregisterInstance removes this process from the heartbeat table.
func (*StateDB) UpdateInstanceField ¶
UpdateInstanceField updates a single column for a given instance. field must be a valid column name (caller is responsible for safety).
func (*StateDB) UpdateWatcherEventRoutedTo ¶ added in v1.5.1
func (s *StateDB) UpdateWatcherEventRoutedTo(watcherID, dedupKey, routedTo, triageSessionID string) error
UpdateWatcherEventRoutedTo updates the routed_to and triage_session_id columns for the row matching (watcher_id, dedup_key). Returns a wrapped error if no row matches (0 rows affected), allowing the caller to distinguish "update OK" from "event not found".
func (*StateDB) UpdateWatcherEventSessionID ¶ added in v1.5.1
UpdateWatcherEventSessionID sets the session_id on an existing watcher event. Returns an error if no matching row exists (0 rows affected).
func (*StateDB) UpdateWatcherStatus ¶ added in v1.5.1
UpdateWatcherStatus sets the status field on a watcher row. Returns an error if no watcher with the given ID exists.
func (*StateDB) WriteStatus ¶
WriteStatus updates the status and tool for an instance.