// Package fallbacksync manages the scheduled job that runs // `glab minder audit sync --all` when agent hooks fail to sync a session. package fallbacksync import ( "bytes" "context" "encoding/json" "encoding/xml" "errors" "fmt" "io" "io/fs" "os" "os/exec" "path/filepath" "strconv" "strings" "time" "gitlab.com/gitlab-org/cli/internal/api" "gitlab.com/gitlab-org/cli/internal/cmdutils" "gitlab.com/gitlab-org/cli/internal/commands/govern/internal/claudehooks" "gitlab.com/gitlab-org/cli/internal/commands/govern/internal/gaig" "gitlab.com/gitlab-org/cli/internal/commands/govern/internal/opencodeplugin" "gitlab.com/gitlab-org/cli/internal/commands/version" ) const ( launchdLabel = "com.gitlab.glab-govern-audit-sync" systemdServiceName = "glab-govern-audit-sync.service" systemdTimerName = "glab-govern-audit-sync.timer" // Interval is how often the scheduled job runs. Interval = 30 * time.Minute ) // ErrUnsupportedOS is returned on platforms without launchd or systemd. var ErrUnsupportedOS = errors.New("fallback periodic sync is supported only on macOS and Linux") // Unit is a file that makes up the scheduled job. type Unit struct { Path string Content string } // Job is what the scheduled job runs. type Job struct { GlabPath string // ConfigDir is passed to the job as GLAB_CONFIG_DIR. launchd and systemd // start jobs without the user's shell environment, so without it a // custom GLAB_CONFIG_DIR or XDG_CONFIG_HOME would point the job at a // different directory from the hooks. ConfigDir string } // Supported reports whether the scheduled job can be installed on goos. func Supported(goos string) bool { return goos == "darwin" || goos == "linux" } // Units returns the files that define the scheduled job on goos. func Units(goos, home string, job Job) ([]Unit, error) { switch goos { case "darwin": return []Unit{{Path: launchdPlistPath(home), Content: launchdPlist(job)}}, nil case "linux": dir := systemdDir(home) return []Unit{ {Path: filepath.Join(dir, systemdServiceName), Content: systemdService(job)}, {Path: filepath.Join(dir, systemdTimerName), Content: systemdTimer()}, }, nil default: return nil, ErrUnsupportedOS } } // Description names the scheduled job for prompts and help text. func Description(goos string) string { switch goos { case "darwin": return fmt.Sprintf("a launchd agent (%s)", launchdPlistPath("~")) case "linux": return fmt.Sprintf("a systemd user timer (%s)", filepath.Join(systemdDir("~"), systemdTimerName)) default: return "a scheduled job" } } func launchdPlistPath(home string) string { return filepath.Join(home, "Library", "LaunchAgents", launchdLabel+".plist") } func systemdDir(home string) string { return filepath.Join(home, ".config", "systemd", "user") } func xmlEscape(s string) string { var b strings.Builder _ = xml.EscapeText(&b, []byte(s)) return b.String() } func launchdPlist(job Job) string { return fmt.Sprintf(` Label %s ProgramArguments %s minder audit sync --all --silent EnvironmentVariables GLAB_CONFIG_DIR %s StartInterval %d RunAtLoad `, launchdLabel, xmlEscape(job.GlabPath), xmlEscape(job.ConfigDir), int(Interval.Seconds())) } // systemdQuoter escapes a value for a double-quoted systemd unit setting. // systemd expands % specifiers even within quotes. var systemdQuoter = strings.NewReplacer(`\`, `\\`, `"`, `\"`, "%", "%%") var systemdUnquoter = strings.NewReplacer(`\\`, `\`, `\"`, `"`, "%%", "%") func systemdService(job Job) string { return fmt.Sprintf(`[Unit] Description=GitLab AI agent governance fallback sync [Service] Type=oneshot Environment="GLAB_CONFIG_DIR=%s" ExecStart="%s" minder audit sync --all --silent `, systemdQuoter.Replace(job.ConfigDir), systemdQuoter.Replace(job.GlabPath)) } func systemdTimer() string { return fmt.Sprintf(`[Unit] Description=GitLab AI agent governance fallback sync timer [Timer] OnBootSec=5min OnUnitActiveSec=%dmin [Install] WantedBy=timers.target `, int(Interval.Minutes())) } // Install writes the job's files and loads the job, replacing any existing one. func Install(ctx context.Context, executor cmdutils.Executor, goos, home string, job Job, uid int) error { units, err := Units(goos, home, job) if err != nil { return err } for _, u := range units { if err := os.MkdirAll(filepath.Dir(u.Path), 0o755); err != nil { return fmt.Errorf("could not create %s: %w", filepath.Dir(u.Path), err) } if err := os.WriteFile(u.Path, []byte(u.Content), 0o644); err != nil { return fmt.Errorf("could not write %s: %w", u.Path, err) } } if err := load(ctx, executor, goos, units, uid); err != nil { // Leaving the files would make doctor report a half-installed job, // for example where there is no user launchd domain or systemd bus. for _, u := range units { if rmErr := os.Remove(u.Path); rmErr != nil && !errors.Is(rmErr, fs.ErrNotExist) { err = errors.Join(err, rmErr) } } return err } return nil } func load(ctx context.Context, executor cmdutils.Executor, goos string, units []Unit, uid int) error { switch goos { case "darwin": // bootstrap fails if the label is already loaded, and bootout fails if it is not. _, _ = executor.ExecWithCombinedOutput(ctx, "launchctl", []string{"bootout", launchdTarget(uid)}, nil) return run(ctx, executor, "launchctl", "bootstrap", fmt.Sprintf("gui/%d", uid), units[0].Path) default: if err := run(ctx, executor, "systemctl", "--user", "daemon-reload"); err != nil { return err } return run(ctx, executor, "systemctl", "--user", "enable", "--now", systemdTimerName) } } // Uninstall unloads the job and removes its files. It reports whether any // files were removed. func Uninstall(ctx context.Context, executor cmdutils.Executor, goos, home string, uid int) (bool, error) { units, err := Units(goos, home, Job{}) if err != nil { return false, err } // Unloading fails when the job is not loaded, which is the state we want. switch goos { case "darwin": _, _ = executor.ExecWithCombinedOutput(ctx, "launchctl", []string{"bootout", launchdTarget(uid)}, nil) default: _, _ = executor.ExecWithCombinedOutput(ctx, "systemctl", []string{"--user", "disable", "--now", systemdTimerName}, nil) } removed := false for _, u := range units { err := os.Remove(u.Path) switch { case err == nil: removed = true case errors.Is(err, fs.ErrNotExist): default: return removed, fmt.Errorf("could not remove %s: %w", u.Path, err) } } if removed && goos == "linux" { if err := run(ctx, executor, "systemctl", "--user", "daemon-reload"); err != nil { return removed, err } } return removed, nil } func launchdTarget(uid int) string { return fmt.Sprintf("gui/%d/%s", uid, launchdLabel) } func run(ctx context.Context, executor cmdutils.Executor, name string, args ...string) error { if out, err := executor.ExecWithCombinedOutput(ctx, name, args, nil); err != nil { return fmt.Errorf("%s %s: %w\n%s", name, strings.Join(args, " "), err, out) } return nil } // ErrNotInstalled is returned by ReadInstalled and InstalledBinary when the // job's files are absent. var ErrNotInstalled = errors.New("fallback periodic sync is not installed") // InstalledBinary returns the glab path that the installed job runs. func InstalledBinary(goos, home string) (string, error) { job, err := ReadInstalled(goos, home) return job.GlabPath, err } // Installed describes the installed job. type Installed struct { // GlabPath is the glab that the job runs. GlabPath string // Legacy reports whether the job runs glab govern, as jobs that glab // versions before the rename to glab minder installed do. Legacy bool } // ReadInstalled reads the installed job. func ReadInstalled(goos, home string) (Installed, error) { units, err := Units(goos, home, Job{}) if err != nil { return Installed{}, err } data, err := os.ReadFile(units[0].Path) if errors.Is(err, fs.ErrNotExist) { return Installed{}, ErrNotInstalled } if err != nil { return Installed{}, err } if goos == "darwin" { path, err := plistProgram(data) return Installed{GlabPath: path, Legacy: strings.Contains(string(data), "govern")}, err } for line := range strings.Lines(string(data)) { rest, ok := strings.CutPrefix(line, `ExecStart="`) if !ok { continue } if path, ok := cutQuoted(rest); ok { legacy := strings.HasPrefix(rest[len(path)+1:], " govern audit sync ") return Installed{GlabPath: systemdUnquoter.Replace(path), Legacy: legacy}, nil } break } return Installed{}, fmt.Errorf("could not find ExecStart in %s", units[0].Path) } // cutQuoted returns s up to its first unescaped double quote. func cutQuoted(s string) (string, bool) { for i := 0; i < len(s); i++ { switch s[i] { case '\\': i++ case '"': return s[:i], true } } return "", false } func plistProgram(data []byte) (string, error) { var doc struct { Dict struct { Keys []string `xml:"key"` Arrays []struct { Strings []string `xml:"string"` } `xml:"array"` } `xml:"dict"` } if err := xml.Unmarshal(data, &doc); err != nil { return "", fmt.Errorf("could not parse plist: %w", err) } if len(doc.Dict.Arrays) == 0 || len(doc.Dict.Arrays[0].Strings) == 0 { return "", errors.New("plist has no ProgramArguments") } return doc.Dict.Arrays[0].Strings[0], nil } // JobState is what the system reports about the installed job. type JobState struct { Loaded bool // Ran reports whether the job has finished at least once since it was loaded. Ran bool ExitCode int } // State asks launchd or systemd whether the job is loaded and how its last // run exited. It catches runs that fail before they can write a Status, such // as a glab binary that does not support --all. func State(ctx context.Context, executor cmdutils.Executor, goos string, uid int) (JobState, error) { switch goos { case "darwin": out, err := executor.ExecWithCombinedOutput(ctx, "launchctl", []string{"print", launchdTarget(uid)}, nil) if exited(err) { // launchctl print exits non-zero when the label is not loaded. return JobState{}, nil } if err != nil { return JobState{}, fmt.Errorf("launchctl print: %w", err) } return launchdState(string(out)), nil case "linux": _, err := executor.ExecWithCombinedOutput(ctx, "systemctl", []string{"--user", "is-active", "--quiet", systemdTimerName}, nil) if exited(err) { return JobState{}, nil } if err != nil { return JobState{}, fmt.Errorf("systemctl --user is-active: %w", err) } out, err := executor.ExecWithCombinedOutput(ctx, "systemctl", []string{"--user", "show", systemdServiceName, "--property=ExecMainStartTimestampMonotonic,ExecMainStatus"}, nil) if err != nil { return JobState{}, fmt.Errorf("systemctl --user show %s: %w\n%s", systemdServiceName, err, out) } return systemdState(string(out)), nil default: return JobState{}, ErrUnsupportedOS } } // exited reports whether err is a command exiting with a non-zero status, as // opposed to the command failing to start. func exited(err error) bool { var exitErr *exec.ExitError return errors.As(err, &exitErr) } func launchdState(out string) JobState { state := JobState{Loaded: true} for line := range strings.Lines(out) { value, ok := strings.CutPrefix(strings.TrimSpace(line), "last exit code = ") if !ok { continue } // The value is "(never exited)" before the first run. first, _, _ := strings.Cut(value, " ") if code, err := strconv.Atoi(first); err == nil { state.Ran = true state.ExitCode = code } break } return state } func systemdState(out string) JobState { state := JobState{Loaded: true} for line := range strings.Lines(out) { key, value, _ := strings.Cut(strings.TrimSpace(line), "=") switch key { case "ExecMainStartTimestampMonotonic": state.Ran = value != "" && value != "0" case "ExecMainStatus": state.ExitCode, _ = strconv.Atoi(value) } } return state } // Status records the outcome of the most recent `glab minder audit sync --all` run. type Status struct { StartedAt time.Time `json:"started_at"` FinishedAt time.Time `json:"finished_at"` Paused []string `json:"paused,omitempty"` // GovernanceNotEnabled lists the projects, as host/path, whose sessions // were not synced because GitLab has AI agent governance turned off for // them. These are expected for a user who works in many projects, so they // are not errors. GovernanceNotEnabled []string `json:"governance_not_enabled,omitempty"` // ProjectNotFound lists the projects, as host/path, that GitLab answered // 404 for: deleted, renamed, or not visible to the user. Like // GovernanceNotEnabled, these are expected and are not errors. ProjectNotFound []string `json:"project_not_found,omitempty"` // NoToken lists the GitLab hosts the run found no token for and could not // sync a session on. It looked up their projects anonymously, so their // private projects are in ProjectNotFound too. NoToken []string `json:"no_token,omitempty"` // AgentTypeNotSupported lists agent types a GitLab host does not accept // yet, as " on ". Their sessions are not uploaded, then or // after an upgrade. AgentTypeNotSupported []string `json:"agent_type_not_supported,omitempty"` // Skipped explains why discovered sessions were not synced, for example // a Cursor workspace that matches several directories. Skipped []string `json:"skipped,omitempty"` SessionsSynced int `json:"sessions_synced"` SessionsCompleted int `json:"sessions_completed"` EventsPosted int `json:"events_posted"` // EventsTooLarge counts events skipped because GitLab cannot accept them. EventsTooLarge int `json:"events_too_large,omitempty"` Errors []string `json:"errors,omitempty"` } // ErrNoStatus is returned by ReadStatus when no run has been recorded. var ErrNoStatus = errors.New("no fallback sync run recorded") func statusPath() string { return filepath.Join(gaig.StateDir(), "fallback-sync-status.json") } // WriteStatus replaces the recorded status of the last run. func WriteStatus(s Status) error { path := statusPath() if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { return err } data, err := json.Marshal(s) //nolint:forbidigo // writing to disk, not stdout if err != nil { return err } return os.WriteFile(path, data, 0o600) } // ReadStatus returns the recorded status of the last run. func ReadStatus() (*Status, error) { data, err := os.ReadFile(statusPath()) if errors.Is(err, fs.ErrNotExist) { return nil, ErrNoStatus } if err != nil { return nil, err } var s Status if err := json.Unmarshal(data, &s); err != nil { return nil, fmt.Errorf("could not parse fallback sync status: %w", err) } return &s, nil } // DiscoverableAgents are the agents whose sessions the scheduled job can find // by scanning their transcripts, without hooks. var DiscoverableAgents = []string{"codex", "cursor"} // HookAgents are the agents that glab installs a hook or plugin for, which // syncs their sessions as they run. var HookAgents = []string{"claude-code", "opencode"} func discoveredAgentsPath() string { return filepath.Join(gaig.StateDir(), "discovered-agents.json") } func hookAgentsPath() string { return filepath.Join(gaig.StateDir(), "hook-agents.json") } // SetDiscoveredAgents replaces the agents whose sessions the scheduled job // discovers. func SetDiscoveredAgents(agents []string) error { return writeJSON(discoveredAgentsPath(), agents) } // agentsListError is an error reading a file in which setup lists the agents // it set up. Uninstalling removes those files. type agentsListError struct{ err error } func (e *agentsListError) Error() string { return e.err.Error() } func (e *agentsListError) Unwrap() error { return e.err } // AgentsReadFix says how to fix err, an error working out which agents are set // up. Uninstalling only helps when setup's own lists are unreadable, because // it doesn't change the Claude Code settings or the OpenCode plugin. func AgentsReadFix(err error) string { if errors.As(err, new(*agentsListError)) { return "fix it, or run 'glab minder setup --uninstall' to start again" } return "fix it, then run 'glab minder setup' again" } // DiscoveredAgents returns the agents whose sessions the scheduled job // discovers. None are discovered until setup enables them. func DiscoveredAgents() ([]string, error) { agents, _, err := readAgents(discoveredAgentsPath()) return agents, err } // SetHookAgents records the agents setup installed a hook or plugin for. func SetHookAgents(agents []string) error { return writeJSON(hookAgentsPath(), agents) } // ForgetHookAgents forgets the agents recorded by SetHookAgents. func ForgetHookAgents() error { return ignoreNotExist(os.Remove(hookAgentsPath())) } // RecordedHookAgents returns the agents setup recorded with SetHookAgents, and // false if setup has recorded nothing. ResolvedHookAgents also covers glab // versions that did not record them. func RecordedHookAgents() ([]string, bool, error) { return readAgents(hookAgentsPath()) } // ResolvedHookAgents returns the agents that setup has set up a hook or plugin // for. glab versions that did not record them are judged by what is installed: // the Claude Code hooks in the settings file at claudeSettings, and the // OpenCode plugin. func ResolvedHookAgents(claudeSettings string) ([]string, error) { agents, recorded, err := RecordedHookAgents() if err != nil || recorded { return agents, err } agents = []string{} claude, err := claudehooks.SyncHookInstalled(claudeSettings) if err != nil { return nil, err } if claude { agents = append(agents, "claude-code") } plugin, err := opencodeplugin.Path() if err != nil { return nil, err } switch state, err := opencodeplugin.Check(plugin); { case err != nil: return nil, err case state == opencodeplugin.Current, state == opencodeplugin.Outdated: agents = append(agents, "opencode") } return agents, nil } // DefaultHookAgents returns the agents a setup without --agents sets up: those // set up earlier, or Claude Code when no agent is set up at all. func DefaultHookAgents(setUp, discovered []string) []string { if len(setUp) == 0 && len(discovered) == 0 { return []string{"claude-code"} } return setUp } // AgentSetup records when setup first set up an agent. type AgentSetup struct { SetUpAt time.Time `json:"set_up_at"` // History reports that the user agreed to upload the agent's activity // from before SetUpAt too. History bool `json:"history,omitempty"` } // AgentSetups are the recorded setups, by agent. Agents set up by glab // versions that did not record them are missing. type AgentSetups map[string]AgentSetup // UploadsFrom returns the time from which agent's activity is uploaded, or the // zero time when there is no such limit: the user opted in to its history, or // setup did not record it. Uploading history for an agent set up before glab // recorded setups keeps what that user agreed to, until they run setup again. func (s AgentSetups) UploadsFrom(agent string) time.Time { setup, ok := s[agent] if !ok || setup.History { return time.Time{} } return setup.SetUpAt } func agentSetupsPath() string { return filepath.Join(gaig.StateDir(), "agent-setups.json") } // ReadAgentSetups returns the recorded agent setups. func ReadAgentSetups() (AgentSetups, error) { setups := AgentSetups{} if _, err := readJSON(agentSetupsPath(), &setups); err != nil { return nil, err } return setups, nil } // SetAgentSetups replaces the recorded agent setups. func SetAgentSetups(setups AgentSetups) error { return writeJSON(agentSetupsPath(), setups) } func readAgents(path string) ([]string, bool, error) { var agents []string recorded, err := readJSON(path, &agents) if err != nil { return nil, false, err } return agents, recorded, nil } func writeJSON(path string, v any) error { if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { return err } data, err := json.Marshal(v) //nolint:forbidigo // writing to disk, not stdout if err != nil { return err } return gaig.WriteFileAtomic(path, data) } func ignoreNotExist(err error) error { if errors.Is(err, fs.ErrNotExist) { return nil } return err } // readJSON decodes the file at path into v, and reports false if there is no // such file. func readJSON(path string, v any) (bool, error) { data, err := os.ReadFile(path) if errors.Is(err, fs.ErrNotExist) { return false, nil } if err != nil { return false, &agentsListError{err} } if err := json.Unmarshal(data, v); err != nil { return false, &agentsListError{fmt.Errorf("could not parse %s: %w", path, err)} } return true, nil } // BuildVersion returns what `glab version` prints for the build described by // info. func BuildVersion(info api.BuildInfo) string { return strings.TrimSpace(version.Scheme(info.Version, info.Commit)) } // BinaryVersion runs `glab version` with the glab binary at path. func BinaryVersion(ctx context.Context, executor cmdutils.Executor, path string) (string, error) { var stdout bytes.Buffer if err := executor.ExecWithIO(ctx, path, []string{"version"}, nil, nil, &stdout, io.Discard); err != nil { return "", err } return strings.TrimSpace(stdout.String()), nil }