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.mdindex 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.mdindex 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 thatalways 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.rsindex 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> {