repos

Local repository registry

This package owns the repository tables in the shared private (0600) app.sqlite application database. It stores what the user chose to review. It reads local git metadata only and contacts nothing; the daemon supplies the one GitHub lookup its HTTP handler uses.

Stored data

• repositories(identity, settings): settings shared by every clone of a repository. identity is the lowercase owner/name on github.com and host/owner/name elsewhere. settings is JSON (automatic, decisions); a daily_cap, backend or model an older baum stored is ignored and dropped on the next write, and dropped from a request an older app sends: the harnesses and models are global preferences.

• clones(id, path, common_dir, repository): registered working trees. A list reprobes each path and reports a changed or missing one unavailable without rewriting it.

• picked(identity): repositories picked by name, possibly without a clone.

• aliases(alias, repository): earlier github.com names GitHub forwards to a repository after a rename or transfer, recorded when a folder whose remote uses one is registered (AddForwarded). Open and OpenReadOnly load them into gitlocal (every baum command opens the registry read-only first), so in that process every remote URL using an earlier name reads as the current one (gitlocal.RemoteRepository, github.RepositoryFromRemote) and the clone is a clone of the repository everywhere. Clones registered under the earlier name move to the current one, which is picked once and takes the earlier name's settings while its own are still the default. Renames chain, and renaming back undoes them. The daemon asks GitHub again at startup, and a fix before it pushes for its repository (RecheckAliases): an alias GitHub now answers with another repository than the recorded one (a new one took the name) is dropped, so its remotes name that repository again; one it could not check or does not show the token is kept, but a fix does not push while one is: a repository the token cannot see may have taken the name. The remote is never rewritten. Repositories lists as earlier_names only those a registered clone's remote still uses, read from the clones' git configuration on each listing, so updating the remote clears it; the alias itself stays.

• preferences(key, value): the global preferences as one JSON row. Its appearance object (theme, key_hints, page_modifier) stores the device’s General settings independently of the daemon’s loopback port. Its plan_usage.show object maps claude and codex to the person's choice of showing that plan's usage; a missing plan follows the backends in use (see planusage). Its decisions object (enabled, model) configures local decision capture; Settings.DecisionsEnabled combines it with the automatic master switch and the repository's decisions (nil is on). See decisionlog. Its review_time_limit_minutes and run_time_limit_minutes, when set (1 to MaxTimeLimit, 240), replace the config file's review_timeout and run_timeout in Preferences.Resolve; a value out of range keeps the file's and does not block saving other preferences.

• prompt_overrides(repository, prompt_id, text, based_on, updated_at): custom review, fix and extraction prompts (ids from agent/prompt). They are stored only here and never read from repository content.

  • repository is '' (GlobalPrompts) for the global scope, else the repository's current lowercase identity. Callers pass that name; earlier alias names are not followed, as with RepositorySettings.
  • SetPromptOverride runs prompt.Validate; a rejection wraps ErrInvalidPrompt. It stores the prompt's built-in version in based_on.
  • SetPromptOverride and DeletePromptOverride require a picked repository (ErrNotPicked, checked in the transaction); the global scope needs none. DeletePromptOverride fails with ErrInvalidPrompt for an unknown id; deleting a missing row is no error.
  • ResolvePrompts picks per prompt id the repository's text, else the global one, else the built-in (absent from the returned prompt.Overrides), and reports a PromptSource for every id. A repository that is not picked gets only the global texts. A stored text that no longer passes prompt.Validate is skipped.
  • Unpick keeps the rows, so a re-pick sees them.
  • AddForwarded copies the earlier name's rows to the current name when the earlier name is still picked and the current name has no overrides (deliberately unlike settings, which copy only while they are the default). It then deletes the earlier name's rows in any case, because it is unpicked and another repository may later take the name.
  • A read-only registry reads no overrides while the table is missing, and sees them once a writer has created it.

A repository is picked exactly when it has a picked row. Adding a clone also picks its repository, and removing the clone keeps it picked with zero clones. A repository with no clone is still registered: RepositorySettings and automatic admission treat it as such, and only unpick revokes that. Work that needs a clone waits for one: discovery lists the repository's pull requests, but the job API answers needs_clone and automatic generation submits nothing until a clone is registered. Unpick deletes the repository's clones and its picked row but keeps the repositories row, so its settings survive a re-pick. Pick accepts only github.com owner/name; it reads no local git and checks nothing on GitHub.

The application database owns schema versioning. Pre-release registry files are not imported; a new registration follows the global automatic preference.

HTTP

Registry.Handler has no authentication; the daemon mounts it behind its authenticated host and origin checks. JSON is decoded strictly.

Only POST validates the name. DELETE and PUT only lowercase it and look it up, so a malformed owner/name answers 404, and an Enterprise identity added through add can be unpicked from the CLI.

Add files a clone under its first GitHub remote, origin first. AddFor(path, repository, settings) files it under repository when any of its GitHub remotes names it (a fork clone whose upstream is the picked repository), and fails with ErrNoMatchingRemote when none does. The fork's own repository is neither registered nor picked. A list reprobes a clone by its stored repository the same way, so such a clone stays available while some remote names that repository. Pull request commits a clone lacks are fetched by generation from the remote whose URL matches the registered repository, not origin, into refs/baum/pull/<N>/.

Cloning a picked repository is served beside these routes by internal/githubrepos (the registry package contacts nothing): GET /api/repositories/{owner}/{name}/clone-target (the default folder), POST /api/repositories/{owner}/{name}/clone {"dir"?} (picks the repository if needed, clones in the background and registers the clone with AddFor; 202, 400, 409) and GET .../clone (the current or last state).

The explicit Choose folder action supplies repository to POST /api/repos, which calls AddFor. When no remote names the repository, HandlerWith's CurrentName (the daemon asks GitHub) checks each GitHub remote, origin first; the first GitHub answers with the repository's current name is registered through AddForwarded. Otherwise the request fails with 400 and a JSON message naming the repositories the remotes use, or saying GitHub could not be asked. Handler has no CurrentName and refuses such folders. Omitting it preserves the standalone path registration behavior.

AddFor moves a path already registered to another repository to the new one. The daemon's clone finder uses AttachFound instead, which never changes what is stored: it fails with ErrClonedElsewhere when the path or its repository directory belongs to another repository, and with ErrNotPicked unless the repository is picked, checked in the same transaction, so an unpick in between is not undone. PickedWithoutClones (picked repositories with no clone row), CloneRows (clones as stored, available false) and RepositoryRows (Repositories with clones as stored) read the registry only and run no git, unlike List and Repositories, which probe every clone.

A probe runs git in the clone only when something its answer is read from changed. The process keeps each clone's last availability with a stamp of:

• that its directory exists;
• its .git entry's kind, and for a linked worktree's file its contents;
• its common directory's config size and modification time, where the remotes live.

The modification times of the directory and its .git directory are not part of the stamp: they move on every index write and new file without changing the answer. Concurrent misses for one clone share a single probe.

While the stamp is unchanged the answer is reused, for at most ProbeMaxAge (5 minutes). A rewrite that only global git configuration makes, such as url.insteadOf, therefore shows within that time. A clone whose directory or .git is gone is unavailable without running git.

Settings PUTs replace the whole object and require automatic, null for the default. A daily_cap an older app still sends, in a settings PUT or in the settings of a POST, is dropped rather than refused: baum sets no spending limits.

CLI

baum internal repos add <path> registers an existing clone for desktop onboarding. Repository selection, removal and settings are managed through the desktop app and the authenticated HTTP routes above. The command changes no Git configuration or hooks and starts no daemon.

A registration the daemon stores (POST /api/repos, AddFor, AttachFound, a cloned repository) calls Registry.Registered, which the daemon sets to ensure baum's Git hook dispatchers in the clone in the background (githooks). It never fails or waits for the registration. A registry opened elsewhere, such as the CLI's, has no such hook. git config baum.hooks false in a clone opts it out: the daemon takes the dispatchers out and restores the hooks they replaced. Remove and Unpick call Registry.Removed for each clone they delete, and the daemon then does the same, unless a registered clone, the same one registered again included, shares the clone's path or common Git directory; the daemon reads the registry again before it installs or restores, so a sweep cannot reinstall hooks of a clone removed meanwhile. A removal before the service starts is restored when it does.