feat(server): gitenv keys accept ~ home paths; document setup + lazy load (t3o-34)

[brentkelly]

Summary

Follow-up to #71 (per-project GitHub token overrides via gitenv), which merged to t3o.

• ~ home paths in keys. A gitenv key may now be written ~/projects/foo (or bare ~), expanded against the server user's home. Before this, a ~-prefixed key failed the isAbsolute check and was silently dropped — a real footgun, since "absolute path" invites ~. ~otheruser is deliberately left unexpanded (it needs a passwd lookup) and, staying non-absolute, is skipped as before. Kept the module dependency-free (adds only node:os).
• User-facing docs. New section in docs/user/source-control.md — "Using a different GitHub identity for specific projects" — in shipped-product voice (no source paths/internals), plus a troubleshooting entry; cross-linked from the contributor doc.
• On-demand load made explicit. Both docs now state that nothing reads the file at boot; it's read on each GitHub-touching action and re-read on mtime/size change, so you can create or edit it with the server running — no restart.

Test plan

• vp test run apps/server/src/sourceControl/gitenv.test.ts — 11 pass, incl. the new "expands a leading ~ in a key to the home directory" (drives os.homedir via \$HOME)
• docs/user/source-control.md reads in product voice with no repo internals leaked
• Manual: a ~/project=... entry authenticates that project as the configured identity; creating the file with the server already running takes effect on the next action

Model: Claude Opus 4.8 via Claude Code.

[brentkelly]

High-Level Summary

Follow-up to #71: gitenv keys may now be written with a leading ~/~/ (expanded against the server user's home via os.homedir()), plus user + contributor doc updates and an explicit "loaded lazily" note. GitHub-only, server-side. Reviewed on GitHub; same-repo trusted author.

The core change is small, correct, and well-targeted: expansion happens in parseGitenv before the isAbsolute gate, ~otheruser is left non-absolute and skipped as documented, and the new test drives real os.homedir() via $HOME. No correctness, security, or regression concerns found. Two nitpicks only.

[brentkelly]

Re-review adjudication — round 1

Both prior findings (🟢 Nitpicks) verified against current head ec133e3.

#	severity	file:line	finding	claim	verdict
1	🟢	docs/user/source-control.md:196	Troubleshooting entry contradicted ~ support / overstated subfolder+symlink strictness	fixed	✅ fix-upheld
2	🟢	apps/server/src/sourceControl/gitenv.test.ts:163	Only 1 of expandTilde's 3 branches tested	fixed	✅ fix-upheld

#1 — Line 196 now reads "Confirm the key points at the project's main folder — an absolute path, or a ~-rooted path", and the inaccurate "(not a subfolder or a symlink)" clause is gone. Matches the setup section and the parser.

#2 — Two new tests added: "expands a bare ~ key to the home directory" (path === "~" → homedir()) and "does not expand ~otheruser and skips the entry" (stays non-absolute, dropped at the isAbsolute guard). All three expandTilde branches are now exercised; suite is 13 tests.

No disagreements. RESPOND is a no-op this round.

[brentkelly]

High-Level Summary (round 2)

De-novo re-review of the current head (ec133e3). This PR adds ~/~/ home-path expansion to gitenv keys (expandTilde, applied in parseGitenv before the isAbsolute gate), plus user/contributor doc updates and an explicit "loaded lazily" note. GitHub-only, server-side. Reviewed on GitHub; same-repo trusted author.

The core change is small and correct: expansion runs before the isAbsolute gate, ~otheruser stays non-absolute and is skipped exactly as documented, and the parsed key still flows through resolveMainRepositoryRoot/realpathOrSelf so worktree and subfolder resolution are unaffected. No correctness, security, or regression concerns.

Status of round-1 findings (both were 🟢 Nitpicks)

• ✅ Troubleshooting wording contradicted ~ support (docs/user/source-control.md) — reworded to "an absolute path, or a ~-rooted path"; no longer overstates strictness.
• ✅ Only one of expandTilde's three branches was tested — commit 2 adds a bare-~ test and a ~otheruser skip test; all three branches (~, ~/, non-expanded) are now covered with non-vacuous assertions.

Nothing new or outstanding. 🟢 Looks good to me, no changes required.

[brentkelly]

🤖 Automated review loop summary (default 5-round cap)

Termination

✅ Converged at round 2 — the round-2 fresh review of head ec133e39 found no findings at all (0 🔴 / 0 🟡 / 0 🟢). Round 1 surfaced two 🟢 nitpicks (no blocking findings); both were fixed and rereview-upheld, and the round-2 fresh pass confirmed a clean head. PR is ready to merge.

✅ What was fixed

• 🟢 docs/user/source-control.md:196 — the troubleshooting entry said the key must be an absolute path "not a subfolder or a symlink", which contradicted the ~ support this PR adds and overstated strictness (subfolder keys resolve to the repo root; symlinks are realpath'd). Reworded to "an absolute path, or a ~-rooted path" (round 1, ec133e39)
• 🟢 apps/server/src/sourceControl/gitenv.test.ts — only the ~/ branch of expandTilde was tested; added coverage for the bare-~ branch and the deliberate ~otheruser non-expansion+skip. Suite is 13/13 (round 1, ec133e39)

⏭️ What was rejected

None.

⚠️ Standing disagreements for human review

None.

Note for the merger

Small follow-up to #71 (which merged to t3o as a squash). Branch is based on the current t3o tip, so it applies cleanly. Docs + test-heavy; the only runtime change is expandTilde in gitenv.ts.