feat: automatic git-config self-heal in helpers4-common, opt-in SSH keys in dotfiles-sync

[baxyz]

Summary

Fixes a real production incident (missing SSH-format commit signing key + a stale credential.helper pointing at a since-moved gh binary) and generalizes the fix into permanent infrastructure, per discussion.

The root cause

A client's own automatic behavior — VS Code copying ~/.gitconfig, SSH agent forwarding — happens outside any devcontainer Feature's control, verbatim, with no awareness that a host-specific path might not resolve inside this particular container:

signingkey = ~/.ssh/id_baxyz_craft_ed25519.pub   # never existed in the container
[credential "https://gist.github.com"]
    helper = !/snap/gh/751/gh auth git-credential  # gh lives at /usr/local/bin/gh here

Neither is caused by (or fixable in) a single feature — this is a client-copy problem, so the fix has to run after the client's own copy has happened, for every consumer, not just one project that remembered to configure something.

helpers4-common (feat, 1.0.1 → 1.1.0)

New postAttachCommand: git-config-self-heal.sh — automatic for every consumer, since every feature already depends on helpers4-common:

• credential.helper (incl. per-URL scopes), gpg.program, gpg.ssh.program, core.editor: a shell-out to an absolute path that doesn't resolve here gets rewritten to the bare command name once a same-named binary is found on $PATH — bare, not a fresh absolute path, so it never goes stale again even if the tool moves on a future rebuild.
• user.signingkey (gpg.format=ssh only): tries a same-basename file under ~/.ssh/~/.gnupg first, then recovers the public key live from a forwarded ssh-agent matched against user.email (ssh-add -L only, never touches private key material). On GitHub Codespaces, which doesn't forward a local ssh-agent at all — confirmed via GitHub's own community discussion, an official response states this explicitly — warns with a pointer to Codespaces secrets instead of silently doing nothing.

Also adds h4_detect_cloud_env to common.sh (Codespaces/Gitpod/DevPod/WSL detection), shared with dotfiles-sync.

A real bug found and fixed while testing: a multi-valued credential.helper (a blank "reset" entry followed by a real one — legitimate, common) makes plain git config <key> <value> refuse outright (exit 5). The first implementation swallowed that failure via 2>/dev/null || true while still reporting success. Fixed by targeting the one broken value via --replace-all <key> <new> <old-as-anchored-regex> and actually checking the exit status.

dotfiles-sync (refactor, 1.0.8 → 1.1.0)

• SSH private/public key file copying is now opt-in (syncSshKeys, default false). ~/.ssh/config and known_hosts still sync unconditionally (agent forwarding doesn't provide either). Normal SSH auth already works through the client's forwarded agent with no local key file needed — copying them by default put private key material on the container's disk against what agent-forwarding-only setups deliberately avoid.
• Removed this feature's own .gitconfig path-rewriting/verification (path-keys.sh) — helpers4-common's self-heal now does the same job, better (actively fixes credential.helper/gpg.program, not just warns), for every consumer regardless of whether dotfiles-sync is in use.
• Now dependsOn: helpers4-common.

Docs

• Both READMEs updated (options, version history, a note recommending disabling VS Code's dev.containers.copyGitConfig when using dotfiles-sync, since it currently wins silently over that feature's smarter merge).
• AGENTS.md: version bumps + a new "Design constraints" entry on why this lives in helpers4-common and the git config multi-value gotcha for future feature authors.

Test plan

• bash -n / jq empty on all changed scripts and manifests
• Real Docker end-to-end: reproduced the exact reported .gitconfig (stale gh path + missing SSH signing key), ran the self-heal, confirmed both fixed; confirmed idempotence (clean second run); confirmed both warning paths (nothing resolvable locally, and the GitHub Codespaces-specific message)
• Real Docker end-to-end: dotfiles-sync default config skips key files while still merging config/known_hosts; syncSshKeys=true places them; helpers4-common's self-heal correctly finds a locally-synced .pub by basename to repair a still-host-shaped signingkey path
• devcontainer features test build phase for both features, confirming dependsOn: helpers4-common resolves correctly (launch itself hits the same docker-outside-of-docker sandbox limitation as prior PRs, unrelated to this change)
• test/helpers4-common/test.sh and test/dotfiles-sync/test.sh updated and passing, including new functional assertions for the self-heal and the syncSshKeys gating
• Verified the Codespaces-secrets doc URL referenced in the warning message resolves to a real, current GitHub docs page

🤖 Generated with Claude Code

[github-actions]

✅ PR Validation Passed

All checks passed!

---

📋 Pipeline Status

	Job	Status
✅	🧾 Conventional Commits	passing
✅	🔖 Version Bump	passing
✅	🧪 Feature Tests	passing
✅	🐚 ShellCheck	passing

---

_{🤖 Generated by @helpers4 CI • 2026-09-06}

[baxyz]

Splitting this into two PRs, per discussion — see #75 for the reasoning (the helpers4-common half needs to actually merge and publish to GHCR before dotfiles-sync's own CI test can correctly pick up the new h4_detect_cloud_env function via dependsOn, since that resolves from the published registry, not this repo's local src/ tree).

• helpers4-common: feat(helpers4-common): automatic git-config self-heal on every attach #75
• dotfiles-sync: follow-up PR once feat(helpers4-common): automatic git-config self-heal on every attach #75 merges and releases

Closing this one in favor of those.