running-tend

Worktrunk Tend CI

Project-specific guidance for tend workflows running on worktrunk (a Rust CLI for managing git worktrees). The generic skills (tend-running-in-ci, tend-review, tend-triage, etc.) provide the workflow framework; this skill adds worktrunk conventions.

Filing issues in other repos

Standing exception granted: file directly in agent-equipped targets (per Filing Issues in Other Repos in the bundled running-in-ci skill) without asking permission here first. The default rule (open an issue here asking permission first) still applies when the target shows no agent signals.

Codecov Monitoring

After required CI checks pass, poll codecov/patch — it is mandatory despite being marked non-required:

for i in $(seq 1 5); do
  CODECOV=$(gh pr checks <number> 2>&1 | grep 'codecov/patch' || true)
  if echo "$CODECOV" | grep -q 'pass'; then
    echo "codecov/patch passed"; exit 0
  elif echo "$CODECOV" | grep -q 'fail'; then
    echo "codecov/patch FAILED"; exit 1
  fi
  sleep 60
done

If codecov fails locally, investigate with task coverage and cargo llvm-cov report --show-missing-lines | grep <file>.

Investigating codecov failures in CI

task and cargo-llvm-cov are not installed in the claude-setup action. Don't try to cargo install them in the sandbox — past attempts at source-compiling installs cascaded into bash-tool interrupts that blocked even pwd and echo. (Pre-built single-script installers like Determinate Nix's are fine — see Weekly Maintenance: MSRV & Toolchain for the one we use. The block is specifically about long-running cargo compiles.) Instead, query Codecov directly, following tests/CLAUDE.md → Coverage Investigation for the endpoints and their traps.

If the Codecov API markers aren't enough, download the code-coverage-report artifact from the PR head's coverage workflow run — it contains a cobertura.xml with per-line hit counts:

REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
# Find the coverage run on the PR head SHA:
CI_RUN=$(gh api "repos/$REPO/commits/<sha>/check-runs" --jq '.check_runs[] | select(.name == "code-coverage") | .details_url | capture("runs/(?<id>[0-9]+)") | .id')
# List artifacts, then download the coverage one:
gh api "repos/$REPO/actions/runs/$CI_RUN/artifacts" --jq '.artifacts[] | {name, id}'
gh api "repos/$REPO/actions/artifacts/<id>/zip" > /tmp/coverage.zip
unzip -q /tmp/coverage.zip -d /tmp/coverage

Test Commands

cargo run -- hook pre-merge --yes   # full suite + lints
cargo test --lib --bins             # unit tests only
cargo test --test integration       # integration tests only

CI runs on Linux, Windows, and macOS.

Session Log Paths

Artifact paths: -home-runner-work-worktrunk-worktrunk/<session-id>.jsonl

Labels

• automated-fix — fix PRs from triage and ci-fix workflows
• nightly-cleanup — nightly sweep issues and PRs

CI Fix: Prefer Rerun for Transient Infrastructure Failures

Before opening a fix/ci-* PR, classify the failure:

• Transient infrastructure (link-check timeouts, apt-get flakes, GitHub outages, runner disk issues, codecov upload blips) — do not create a PR. The maintainer will rerun CI. Comment on the run or exit silently; a permanent config change for a one-off timeout is churn the maintainer will close.
• Flaky test (known-flaky or first-seen PTY/shell test) — try to fix it.
• Real regression — proceed with a fix PR.

Non-required ≠ transient. A non-required job (e.g. collect affected coverage, affected tests (linux, advisory)) can fail from a real regression. The required/non-required distinction is about merge-blocking, not about how the failure is classified. If a deterministic build error (error[E...], "binary not found", "ambiguous candidates", missing target) repeats across consecutive runs of the same shape, it's a real regression even when the job is advisory. Reserve "transient" for non-deterministic causes: BrokenPipe, connection reset, runner disk full, GitHub API timeouts, host-availability blips.

Lychee link-check timeouts are always transient unless the same URL has failed on at least two separate runs within the last few days. The check runs as the link-check job in the nightly workflow. .config/lychee.toml already sets max_retries = 6 and lists known-unreliable hosts; one timeout is not enough evidence to extend that list. Signals you have a transient failure, not a broken link:

• The previous run on the same or a nearby commit passed.
• Only [TIMEOUT] is reported (not 404/403/410).
• The URL is reachable from a local curl.

When in doubt, post a comment on the failed run summarizing the diagnosis and wait — don't open a PR.

Applying GitHub Suggestions

Apply the literal suggestion only — change the lines it covers, nothing more. If surrounding lines also need updating, note that in your reply.

PR Review: Don't Self-Dismiss Over Unrelated Test Flakes

If a clearly-unrelated test fails after you've already approved a PR, leave the approval in place and post a comment noting the flake. Do not dismiss your own approval to "gate" on a rerun.

GitHub blocks both gh run rerun --failed and per-job rerun (POST /repos/{owner}/{repo}/actions/jobs/{id}/rerun) with HTTP 403 while any job in the same workflow run is still in_progress. The non-required benchmarks job routinely runs 80+ minutes after test (linux|macos|windows) finish, so dismiss-then-wait-then-rerun cascades into a long session for no benefit — the maintainer can rerun the failed job directly once benchmarks clears, or merge regardless if the failure is clearly a flake.

The codecov-failure dismissal pattern is different and remains correct: CLAUDE.md requires explicit user approval before merging with failing codecov/patch, so dismissing the approval until the coverage gap is addressed is intentional.

Issue Triage

When you need more information to diagnose a reported bug, the primary ask is wt -vv <command>. Re-running the failing command with -vv writes a diagnostic bundle — a single report containing wt/git/OS versions, shell integration, wt config show, git worktree list --porcelain, and a trace.log of every git invocation with its output. The -vv output prints the bundle's exact absolute path (Diagnostics and performance profile saved @ …) followed by a ready-to-run gh gist create --web <path> line — point the user at those printed lines; don't hand them a hardcoded path. In particular, never tell them to cat .git/wt/logs/diagnostic.md: inside a linked worktree .git is a gitdir file, not a directory, so that path fails with Not a directory (os error 20) (ENOTDIR). The bundle actually lives under the git common dir — "$(git rev-parse --git-common-dir)/wt/logs/diagnostic.md" resolves from any worktree, and the printed absolute path already points there. One gist URL pasted into the issue gives us most of what we'd otherwise ask for piecemeal, so lead with this for unexplained failures rather than chaining version/config/repro questions across multiple round-trips.

When the report is about a slow wt command, read its Performance profile section first. It renders the same breakdown as wt config state logs profile (subprocess time by command type, slowest calls, repeated (command, context) pairs) directly from the bundled trace.log, so you can spot redundant git calls and slow commands without parsing the raw trace by hand. The same report run against a statusline capture is the weekly per-render cache check — see Weekly Maintenance: Statusline Cache-Check.

Reach for narrower asks only when the diagnostic is overkill:

• wt --version — when the only question is whether a fix has landed.
• wt config show — when the suspicion is purely config/shell-integration and you already have the command + repro.

Don't ship fixes you can't verify

When the bug or proposed fix turns on runtime state the bot can't observe from CI — plugin hooks firing inside an agent CLI (Claude Code, Codex, Gemini), shell-integration side effects, interactive prompt rendering, signal forwarding into a TTY — do not open a PR premised on the hypothesis. Signals to stop:

• The proposed transition fires inside a running agent session the bot can't drive from a test (PostToolUse, Stop, Notification, statusline redraws).
• The "analysis" in the issue is an LLM-written trace pasted by the reporter, not a verified observation. Treat that as a starting hypothesis, not ground truth — a Claude-written explanation of why X is broken is no more trustworthy than the bot's own first guess.
• The repro requires an interactive shell or claude running in a tmux that the bot can't spin up.

Comment on the issue with what's known, ask the reporter for the concrete symptom they observe ("which marker shows where, when") rather than for a fix to validate, and exit without a PR. The bar for opening a fix PR is the failure mode is reproducible and the fix is testable, not the hypothesis seems plausible. If you post a fix despite limited testability (rare — usually only when the reporter has confirmed the exact symptom and the code change is obviously correct from inspection), explicitly flag what wasn't verified in the PR body.

Closing Duplicates

When an issue is clearly a duplicate, close it after commenting. Use gh issue close <number> and tell the reporter: if they believe this was closed in error, they can let us know and we'll reopen it.

Check --config-set before calling a setting unpinnable

wt --config-set '<toml>' overrides any user config key for one invocation, above both config files and WORKTRUNK_SECTION__KEY env vars (inline config overrides). The resolver just reads repo.config().<key> and shows no sign of that

Content truncated.