Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs(network): codify local-first network access policy (#2536)

Maximilian Roosffc8abe82aa4
diff --git a/CLAUDE.md b/CLAUDE.md
index aebe746da..e28305471 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -242,6 +242,14 @@ if msg.contains("no merge base") { return Ok(true); }
When no structured alternative exists, document the fragility inline.
+### Network Access
+
+**Policy:** worktrunk is local-first. The network is touched only when the user asked for it. The single exception is the *first* call to `Repository::default_branch()` per repo, which may fall through to `git ls-remote` to discover the default branch name; the result caches in `worktrunk.default-branch` and every subsequent call is local. No other detection helper may add a similar fallback.
+
+**Why:** "lookup" paths that silently walk to the wire (alias dispatch, hook context build, `wt statusline`, recovery) stall commands the user wouldn't expect to do network work — most painfully on a fresh clone. Allowing the `default_branch()` bootstrap keeps worktrunk usable on a fresh clone while bounding the exception to one helper that fires at most once per repo.
+
+**Implementation:** before adding a new accessor that could fall through to the wire (`gh`, `glab`, `git fetch`, `git ls-remote`, HTTP), confirm the call site is one the user explicitly invoked. Background polling driven by a TTL cache counts — a CI-status check on every shell prompt is invisible to the user but still hits the wire, and is therefore not allowed.
+
### Signal Handling: Ctrl-C Cancels the Current Command
**Policy:** when a child process exits from a signal (SIGINT, SIGTERM), every loop in the foreground execution path MUST abort rather than continue to the next iteration. This applies to worktree loops (`wt step for-each`), hook pipelines, alias steps, concurrent groups, and any future code that runs multiple child processes in sequence.
diff --git a/benches/CLAUDE.md b/benches/CLAUDE.md
index 9b816a505..1c560a0c1 100644
--- a/benches/CLAUDE.md
+++ b/benches/CLAUDE.md
@@ -85,6 +85,15 @@ Default-branch cache contribution is ~17ms per iteration on a typical-8 syntheti
(measured: 166ms with default-branch cached → 183ms fully cold). Small enough that
always clearing it is simpler than introducing a "warm default-branch" bench mode.
+**Bench fixtures don't exercise the wire path.** `setup_fake_remote` writes
+`refs/remotes/origin/HEAD` directly into every repo, so a cold-cache iteration
+falls through to the local `<r>/HEAD` lookup (~17 ms above), never to
+`git ls-remote` (100 ms–2 s in the wild). The cold cost we benchmark is the
+*configured-remote* cold cost, not the *fresh-clone* cold cost. A
+`cold_no_remote` mode (extending `invalidate_caches_auto` to also wipe
+`refs/remotes/origin/HEAD`) would close the gap if the wire-path cost is
+worth measuring at CI cadence.
+
## Expected Performance
**Modest repos** (500 commits, 100 files):
diff --git a/src/git/repository/config.rs b/src/git/repository/config.rs
index 01a097eae..e55850f84 100644
--- a/src/git/repository/config.rs
+++ b/src/git/repository/config.rs
@@ -270,21 +270,27 @@ impl Repository {
/// Get the default branch name for the repository.
///
- /// **Performance note:** This method may trigger a network call on first invocation
- /// if the remote HEAD is not cached locally. The result is then cached in git's
- /// config for subsequent calls. To minimize latency:
- /// - Defer calling this until after fast, local checks (see e497f0f for example)
- /// - Consider passing the result as a parameter if needed multiple times
- /// - For optional operations, provide a fallback (e.g., `.unwrap_or("main")`)
+ /// **Network contract — this is the sole "look it up if missing" helper
+ /// in worktrunk that is allowed to fall through to the wire.** The first
+ /// call per repo may run `git ls-remote` (100 ms–2 s); the result is
+ /// then persisted to `worktrunk.default-branch` and every subsequent
+ /// call is a local cache hit. No other detection helper may add a
+ /// similar fallback. See `CLAUDE.md` → "Network Access" for the policy.
///
/// Detection strategy:
/// 1. Check worktrunk cache (`git config worktrunk.default-branch`)
/// 2. Try primary remote's local cache (e.g., `origin/HEAD`)
- /// 3. Query remote (`git ls-remote`) — may take 100ms-2s
+ /// 3. Query remote (`git ls-remote`) — may take 100 ms–2 s (sole wire fallback)
/// 4. Infer from local branches if no remote
///
- /// Detection results are cached to `worktrunk.default-branch` for future calls.
- /// Result is also cached in the shared repo cache (shared across all worktrees).
+ /// Detection results are cached to `worktrunk.default-branch` for future
+ /// calls. Result is also cached in the shared repo cache (shared across
+ /// all worktrees).
+ ///
+ /// To minimize latency on the rare cold-clone case:
+ /// - Defer calling this until after fast, local checks (see e497f0f for an example).
+ /// - Consider passing the result as a parameter if needed multiple times.
+ /// - For optional operations, provide a fallback (e.g., `.unwrap_or("main")`).
///
/// Returns `None` if the default branch cannot be determined.
pub fn default_branch(&self) -> Option<String> {