phase: 173_docs_push_creds_split

All gates green. Final report:

**Phase 173 — final verification pass (all tasks already complete in `complete/`)**

- Verified the full implementation is in the working tree: `docs_user`/`docs_token` settings + catalogue rows (task 01), `docs_repo` PUT 422 guard + `docs_token` write-only pin (task 02), `run_git(env)` + `push_document(user, token)` credential env (task 03), `settings_migrate.py` wired into `create_app()` (task 04), E2E suite (task 05).
- **Completion criteria:**
  1. GET `/api/admin/settings` lists `docs_user` (plain) + `docs_token` (secret, `value=null`), token never in any body — ✅ `test_docs_token_is_write_only_masked_end_to_end` + E2E sentinel-absent-from-DOM
  2. PUT `docs_repo` with `://user:pass@` → 422 naming the fields; clean URL passes — ✅ integration + E2E UI-side
  3. Token set → `GIT_CURL_USERNAME`/`GIT_CURL_PASSWORD`/`GIT_TERMINAL_PROMPT=0` on every git step; empty → `env=None` — ✅ mocked-git unit tests
  4. Legacy env split once at startup, idempotent, one INFO line, `.env` untouched — ✅ `test_settings_migrate.py` (4 shapes) + `test_docs_push_migrate.py`
  5. Full suite green, coverage >90%, lint clean — ✅
  6. E2E isolated: `test_docs_push_creds.py` 4/4; regression set (panel + layout + response_to_docs) 21/21 — ✅
  7. Commit + phase move — harness's job (per instructions, not mine).
  8. README/AGENTS consistent — ✅ (below)
- Tests/lint: `uv run pytest` exit 0 (4112 passed) · `uv run pytest --cov=app --cov-report=term-missing` TOTAL 99% · `uv run ruff check .` clean · `uv run pyright` 0 errors
- Docs: README.md (incl. Docs-push config section, guard/migration paragraph, `.env.example` block) and AGENTS.md verified consistent in full; fixed two stale docstrings in `app/config.py` + `app/core/settings_catalog.py` (`is_set` → the API's actual `has_value` field).
- No live-infrastructure changes (no live step in this phase). No next pending phase — `todo/` held only 173.

app/core/docs_push.py

@@ -22,6 +22,7 @@ stderr (the ``GitSyncError`` style), and the checkout under
 """
 from __future__ import annotations
 
+import os
 from pathlib import Path
 
 from scripts.git_sync import GitSyncError, run_git
@@ -61,9 +62,28 @@ def push_document(
     rel_path: str,
     content: str,
     commit_message: str,
+    user: str = "",
+    token: str = "",
 ) -> tuple[str, str]:
     """Commit *content* at *rel_path* and push (ff-only) to *branch*.
 
+    *user* / *token* are the docs-push credentials (phase 173, C2):
+    when *token* is non-blank, EVERY git step of the sequence runs with
+    git's documented HTTP credential environment —
+    ``GIT_CURL_USERNAME`` / ``GIT_CURL_PASSWORD`` (+
+    ``GIT_TERMINAL_PROMPT=0`` so a headless server fails fast instead
+    of hanging on a prompt) — merged over ``os.environ`` (the
+    subprocess env-replacement trap: a dict REPLACES the parent
+    environment, so the merge is what keeps ``PATH`` and friends).
+    The credential travels only in that environment — it never appears
+    in the argv (the clean *repo* URL stays in the argv untouched),
+    so it is absent from the process list. ``GIT_CURL_*`` is inert for
+    ``ssh://`` / local-path remotes (accepted — the remote decides).
+    **C5:** when *token* is blank (the default — an anonymous push to
+    a public or credential-free remote, exactly the pre-phase state),
+    every ``run_git`` call keeps ``env=None`` and the invocations are
+    byte-identical to the pre-phase ones.
+
     Step sequence (each step via :func:`scripts.git_sync.run_git`;
     ``cwd=work_dir`` once the checkout exists):
 
@@ -108,6 +128,19 @@ def push_document(
     """
     _refuse_unsafe_rel_path(rel_path)
     work = Path(work_dir).expanduser()
+    # C5: blank token → env stays None → every invocation below is
+    # byte-identical to the pre-phase one.
+    git_env: dict[str, str] | None = None
+    if token.strip():
+        # C2: git's documented HTTP credential env — never in the argv.
+        # GIT_TERMINAL_PROMPT=0 fails fast instead of hanging the headless
+        # server on a credential prompt.
+        git_env = {
+            **os.environ,
+            "GIT_CURL_USERNAME": user,
+            "GIT_CURL_PASSWORD": token,
+            "GIT_TERMINAL_PROMPT": "0",
+        }
     try:
         if not (work / ".git").exists():
             work.parent.mkdir(parents=True, exist_ok=True)
@@ -123,25 +156,30 @@ def push_document(
                     str(work),
                 ],
                 cwd=work.parent,
+                env=git_env,
             )
-        run_git(["git", "fetch", "--depth", "1", "origin", base_branch], cwd=work)
+        run_git(["git", "fetch", "--depth", "1", "origin", base_branch], cwd=work, env=git_env)
         # Capture the fetched base tip now — a *failed* fetch clears
         # FETCH_HEAD, so the symbolic ref cannot be reused later.
-        base_sha = run_git(["git", "rev-parse", "FETCH_HEAD"], cwd=work).strip()
+        base_sha = run_git(["git", "rev-parse", "FETCH_HEAD"], cwd=work, env=git_env).strip()
         try:
-            run_git(["git", "fetch", "--depth", "100", "origin", branch], cwd=work)
-            branch_sha = run_git(["git", "rev-parse", "FETCH_HEAD"], cwd=work).strip()
+            run_git(
+                ["git", "fetch", "--depth", "100", "origin", branch], cwd=work, env=git_env
+            )
+            branch_sha = run_git(
+                ["git", "rev-parse", "FETCH_HEAD"], cwd=work, env=git_env
+            ).strip()
         except GitSyncError:
             branch_sha = None  # the branch does not exist on the remote yet
-        if run_git(["git", "branch", "--list", branch], cwd=work).strip():
-            run_git(["git", "checkout", branch], cwd=work)
+        if run_git(["git", "branch", "--list", branch], cwd=work, env=git_env).strip():
+            run_git(["git", "checkout", branch], cwd=work, env=git_env)
         else:
             anchor = branch_sha if branch_sha is not None else base_sha
-            run_git(["git", "checkout", "-B", branch, anchor], cwd=work)
+            run_git(["git", "checkout", "-B", branch, anchor], cwd=work, env=git_env)
         target = work / rel_path
         target.parent.mkdir(parents=True, exist_ok=True)
         target.write_text(content, encoding="utf-8")
-        run_git(["git", "add", "--", rel_path], cwd=work)
+        run_git(["git", "add", "--", rel_path], cwd=work, env=git_env)
         run_git(
             [
                 "git",
@@ -156,9 +194,10 @@ def push_document(
                 commit_message,
             ],
             cwd=work,
+            env=git_env,
         )
-        run_git(["git", "push", "origin", branch], cwd=work)
-        sha = run_git(["git", "rev-parse", "HEAD"], cwd=work).strip()
+        run_git(["git", "push", "origin", branch], cwd=work, env=git_env)
+        sha = run_git(["git", "rev-parse", "HEAD"], cwd=work, env=git_env).strip()
     except GitSyncError as err:
         raise DocsPushError(str(err)) from err
     return branch, sha