feat: per-agent Gitea identity resolution (#873)

Closes #873

Mos (id-11) Gate-16 merge: independent APPROVE @4b472a22 (author-blocker dissolved via (a) re-author, identical tree hash to tech-approved head), author id2 != approver id11, clean mosaic-coder commit-author, CI green wp1985. Framework train COMPLETE 6/6.

Co-authored-by: jason.woltje <jason@diversecanvas.com>
Co-committed-by: jason.woltje <jason@diversecanvas.com>

packages/mosaic/framework/tools/git/README.md

@@ -33,3 +33,64 @@ The Gitea API token is **never passed on a curl command line.** An `Authorizatio
 Both `pr-review.sh` and `issue-comment.sh` accept an optional `--login <name>` flag that overrides the automatically detected Gitea login for that single invocation. The override selects **which credential the REST write, the `/user` identity lookup, and the read-back all use** — its token is resolved from the tea config for that login name (`get_gitea_token_for_login`), falling back to the repo host's credential when no login is named. The resolved login is **host- and port-bound**: the login's configured URL host **and effective port** (the scheme's default port — 80 for `http`, 443 for `https` — applies when a port is omitted, symmetrically on both sides) must match the repo remote's, so a login name shared across hosts (or an override configured for a different Gitea, including one on a different port of the same host) can never send one host's credential to another — a host or port mismatch fails closed rather than leaking a cross-host token. Resolving the acting identity and the read-back from the _same_ login that performs the write is essential: a write performed under an overridden login must be verified against that login's identity, not the host default's. Callers who need a different login than the host default should pass `--login <reviewer-login>`.
 
 As a durable successor to this mechanism, consider giving each reviewer/approver slot its own dedicated Gitea login credential, so that author≠reviewer holds at the credential level rather than relying on wrapper-level `--login` bookkeeping. This is a recommendation for future hardening, not something implemented by this flag.
+
+## Per-agent Gitea identity (Gate-16 author≠reviewer)
+
+By default, git push/fetch (via `git-credential-mosaic`) and the API wrappers above (via
+`detect-platform.sh`'s `get_gitea_token`) all authenticate as the single shared Gitea
+account/token configured through `tools/_lib/credentials.sh`. That means every agent in a
+fleet commits, pushes, and opens PRs under one identity — with no cryptographic
+separation between an author and a reviewer.
+
+Both `git-credential-mosaic` and `get_gitea_token()` resolve an optional **per-agent
+identity** before falling back to the shared account:
+
+1. `MOSAIC_GIT_IDENTITY` environment variable, or
+2. `git config --get mosaic.gitIdentity` (set per-worktree; persists on disk across
+   non-persistent shells — `git config mosaic.gitIdentity <agent-id>`), or
+3. (git-credential-mosaic only) the username git itself supplies for the credential
+   request.
+
+If the resolved identity has a token file at
+`~/.config/mosaic/secrets/gitea-tokens/gitea-{usc,mosaicstack}-<agent-id>.token`, that
+identity + token is used. **Nothing configured → nothing changes**: with no per-slot
+token file present, both tools fall through to the existing shared-account path
+unchanged, so this feature is a no-op on any host that hasn't provisioned per-slot
+tokens.
+
+### Enabling it for a clone
+
+The framework installer syncs `git-credential-mosaic` to
+`~/.config/mosaic/tools/git/git-credential-mosaic` (executable) on every install/update,
+but does **not** register it as git's credential helper automatically. Registration is a
+one-time, explicit step:
+
+```bash
+# Per-repo (recommended — scopes the helper to this clone only):
+git config credential.helper "$HOME/.config/mosaic/tools/git/git-credential-mosaic"
+
+# Per-worktree identity pin (Gate-16 separation):
+git config mosaic.gitIdentity <agent-id>
+```
+
+This is deliberately **not** auto-registered on install/update: `credential.helper` is
+global, order-sensitive git config (`~/.gitconfig`) that can already hold an
+operator-chosen credential manager (keychain, `store`, `manager-core`, …) for
+repositories unrelated to Mosaic. Silently inserting an entry on every framework
+install/upgrade risks reordering or shadowing that operator-owned surface across the
+whole host — the same operator-owned config the installer's manifest system is
+otherwise careful never to touch. Because identity is already resolved per-worktree
+(`mosaic.gitIdentity`), the correct granularity for registering the helper is per-clone
+too, so a documented manual step is the right shape here, not a global auto-write.
+
+### PowerShell parity
+
+`detect-platform.ps1`'s Gitea wrappers authenticate through `tea` CLI logins
+(`Get-GiteaLoginForHost`), not a raw-token `get_gitea_token`-equivalent function — there
+is nothing to prepend the identity-resolution block to on the PowerShell side. A native
+PowerShell git-credential helper is also unnecessary: `git-credential-mosaic` is invoked
+by git's credential-helper protocol (stdin/stdout), which works identically under Git for
+Windows' bundled `bash`/`sh` when configured via `credential.helper`, without a `.ps1`
+counterpart. A `tea`-login-based per-agent identity for the PowerShell wrappers is a
+separate, larger design (mapping identities to `tea login` profiles) and is out of scope
+here.