feat(ledger): coverage self-seeds — enter_project background refresh + refresh_pattern_coverage tool + shape-accounting skill (#2802, milestone 294)

The UI Refresh button must not be the only seed path (operator directive,
hit live: the P7 backfill stalled waiting for a click). Three parts:

- enter_project fire-and-forgets refresh_if_stale on the project OWNER —
  absent or day-old readouts recompute in the background (same spawn the
  webhook path uses), the enter stays fast, forge-less owners exit quietly
  (rule #115 baseline), and an in-flight guard keeps concurrent enters from
  fetching the same tarball N times.
- refresh_pattern_coverage(project_id): the synchronous agent-facing form —
  write-gated, owner-keyring resolution, and ValueError messages that name
  the fix (add a connection / bind_repo) instead of measuring nothing
  silently.
- plugin 0.1.33 ships the shape-accounting skill: the five statuses, the
  seed/todo/judge loop, and the derive-first rule, triggered by the
  coverage line or any proved code-to-canon relationship.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/scribe/services/coverage.py

@@ -31,7 +31,7 @@ import logging
 import posixpath
 import re
 import tarfile
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 
 from scribe.services.forge import ForgeSelector, get_forges
 from scribe.services.repo_bindings import keys_for_project
@@ -323,6 +323,90 @@ async def refresh_coverage(
     return coverage
 
 
+# The arrival-moment self-seed (#2802). A ledger that has never been computed
+# used to wait for someone to find the UI Refresh button; entering the project
+# is the moment the number is wanted, so entering is the moment it seeds.
+_SEED_MAX_AGE = timedelta(hours=24)
+
+# Projects with a refresh already running — concurrent enters must not fetch
+# the same tarball N times. In-process on purpose: the cost being bounded is
+# per-process forge traffic, and a rare double-fetch across workers is
+# harmless (the upsert is idempotent).
+_inflight_seed: set[int] = set()
+
+
+async def refresh_if_stale(
+    user_id: int, project_id: int, cached: dict | None = None
+) -> None:
+    """Background-refresh a project's ledger when its readout is absent or
+    older than a day. Fire-and-forget material (background.spawn): every exit
+    is quiet, every failure a WARNING — a seed must never surface as an
+    enter_project error. ``user_id`` is the project OWNER (whose keyring and
+    cache this is); pass ``cached`` when the caller already read it.
+    """
+    try:
+        if cached is None:
+            cached = await cached_coverage(user_id, project_id)
+        if cached:
+            try:
+                computed = datetime.fromisoformat(cached.get("computed_at") or "")
+                if datetime.now(timezone.utc) - computed < _SEED_MAX_AGE:
+                    return
+            except ValueError:
+                pass  # an unreadable stamp reads as stale
+        if project_id in _inflight_seed:
+            return
+        selector = await get_forges(user_id, project_id)
+        if not selector.configured:
+            return  # rule #115: forge-less stays exactly as it was
+        _inflight_seed.add(project_id)
+        try:
+            await refresh_coverage(user_id, project_id, selector=selector)
+        finally:
+            _inflight_seed.discard(project_id)
+    except Exception:
+        logger.warning(
+            "background coverage seed failed for project %s", project_id,
+            exc_info=True,
+        )
+
+
+async def refresh_for_caller(caller_id: int, project_id: int) -> dict:
+    """The explicit agent-facing refresh (#2802) — synchronous, named errors.
+
+    Write-gated: recomputing spends the owner's forge API budget and rewrites
+    ledger rows' seen-markers, so a read share doesn't grant it. Resolution
+    runs on the OWNER's keyring like every other forge read. Raises
+    ValueError with a fixable message instead of silently measuring nothing —
+    the caller is an agent mid-task, and "None" would strand it exactly the
+    way the button-only path did.
+    """
+    from scribe.models import async_session
+    from scribe.models.project import Project
+    from scribe.services import access
+
+    if not await access.can_write_project(caller_id, project_id):
+        raise ValueError(f"project {project_id} not found or no write access")
+    async with async_session() as session:
+        project = await session.get(Project, project_id)
+    if project is None:
+        raise ValueError(f"project {project_id} not found")
+    owner_id = project.user_id or caller_id
+    selector = await get_forges(owner_id, project_id)
+    if not selector.configured:
+        raise ValueError(
+            "No forge connection serves this project — the owner adds one "
+            "under Settings → Integrations → Git Forges"
+        )
+    coverage = await refresh_coverage(owner_id, project_id, selector=selector)
+    if coverage is None:
+        raise ValueError(
+            "No bound repo is served by the owner's forge connections — "
+            "bind_repo the project's repo on a host a connection serves"
+        )
+    return coverage
+
+
 async def cached_coverage(user_id: int, project_id: int) -> dict | None:
     """The last computed summary, or None — never computes."""
     raw = await get_setting(user_id, f"{_CACHE_KEY_PREFIX}{project_id}", "")