feat: relationship model (requires/repos/predicates) + git sync

A derived, mostly-computed model of how programs, deployments, and repos relate,
plus the git-sync surfaces that motivated it. See docs/relationships.md.

Core:
- `requires: [{kind, ref, version?, bind?}]` on programs + deployments — one
  precondition relation; `system_dependencies` is its `{kind: system}` alias.
  kind fixes meaning + check (system=installed, deployment=exists).
- relations.py: derives repos (git toplevel / monorepo), fan-in, and the
  predicates functional?/fresh?/deployed? — nothing stored.
- env is generated FROM a `{kind: deployment, bind}` requirement (target URL →
  consumer env), never scraped back into one; explicit defaults.env still wins.
- git.py: working-copy status/pull, repo toplevel + remote url.

Surfaces:
- `castle graph` + GET /graph — the relationship diagnostic.
- GET /repos, /repos/{key}/git|sync — repo-scoped sync (a repo is the sync unit;
  a monorepo backs several programs). GET /programs/{name}/git|sync + repo context.
- Dashboard: Graph screen, program-page git status + repo-aware Sync, and a
  monorepo banner on Programs.

Governing principle: predicates are derived; encode only the non-derivable, as a
node or edge property. Pull-only sync — converge stays a separate step.

castle-api/src/castle_api/programs.py

@@ -2,10 +2,14 @@
 
 from __future__ import annotations
 
+from dataclasses import asdict
+
 from fastapi import APIRouter, HTTPException, status
 
+from castle_core import git
 from castle_core.stacks import available_actions, available_stacks, run_action
 
+from castle_api import stream
 from castle_api.config import get_config
 
 programs_router = APIRouter(tags=["programs"])
@@ -17,6 +21,88 @@ def list_stacks() -> list[str]:
     and keeps it in sync with the backend (no hardcoded frontend list)."""
     return available_stacks()
 
+
+# ---------------------------------------------------------------------------
+# Git sync — pull a program's source working copy up to date (pull only; no
+# build/apply/restart — converge stays an explicit, separate step). Declared
+# BEFORE the generic /{action} route below so the literal `git`/`sync` segments
+# win over the `{action}` path param (Starlette matches in declaration order).
+# ---------------------------------------------------------------------------
+
+
+def _program_source(name: str):
+    """The (program, config) for a named program, or raise the standard 404/400s."""
+    config = get_config()
+    if name not in config.programs:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail=f"'{name}' not found"
+        )
+    return config.programs[name], config
+
+
+@programs_router.get("/programs/{name}/git")
+def program_git_status(name: str) -> dict:
+    """Git status of a program's working copy (branch, dirty, ahead/behind).
+
+    Fetches from the remote first so ``behind`` is current. A program with no
+    source or a non-git source returns a benign ``{"is_repo": false}`` (not an
+    error) so the dashboard can simply hide the sync control."""
+    comp, config = _program_source(name)
+    if not comp.source:
+        return {"is_repo": False}
+    out = asdict(git.git_status(comp.source, fetch=True))
+    # Repo context: which repo this program's source lives in and who else shares it
+    # (a monorepo). Sync is a repo operation — the UI labels it and lists siblings.
+    from castle_core.relations import derive_repos
+
+    for key, repo in derive_repos(config).items():
+        if name in repo.programs:
+            out["repo"] = {
+                "key": key,
+                "programs": repo.programs,
+                "multi": repo.multi,
+                "deployments": repo.deployments,
+            }
+            break
+    return out
+
+
+@programs_router.post("/programs/{name}/sync")
+async def program_sync(name: str) -> dict:
+    """Fast-forward a program's working copy (``git pull --ff-only``).
+
+    Pull-only: it updates the source on disk and reports which deployments may now
+    need a restart/apply, but does not build, apply, or restart anything itself."""
+    comp, config = _program_source(name)
+    if not comp.source:
+        raise HTTPException(status_code=400, detail=f"'{name}' has no source directory")
+    if not git.is_git_repo(comp.source):
+        raise HTTPException(
+            status_code=400, detail=f"'{name}' source is not a git repository"
+        )
+
+    before = git.head(comp.source)
+    ok, output = git.pull(comp.source)
+    if not ok:
+        raise HTTPException(status_code=500, detail=output or "git pull failed")
+
+    pulled = git.head(comp.source) != before
+    deployments = [dname for dname, _ in config.deployments_of(name)]
+    if pulled:
+        # Nudge other clients to refresh this program's git status.
+        await stream.broadcast(
+            "program-sync", {"program": name, "deployments": deployments}
+        )
+
+    return {
+        "program": name,
+        "status": "ok",
+        "output": output,
+        "pulled": pulled,
+        "deployments": deployments if pulled else [],
+    }
+
+
 # ---------------------------------------------------------------------------
 # Unified program action endpoint
 # ---------------------------------------------------------------------------