devops-bot-sdk 1.4.159__tar.gz → 1.6.2__tar.gz

{devops_bot_sdk-1.4.159 → devops_bot_sdk-1.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.4.159
+Version: 1.6.2
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.4.159 → devops_bot_sdk-1.6.2}/devops_bot_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.4.159
+Version: 1.6.2
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.4.159 → devops_bot_sdk-1.6.2}/devops_bot_sdk.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ sdk/config.py
 sdk/crucial.py
 sdk/exceptions.py
 sdk/git_ops.py
+sdk/github_ingest.py
 sdk/graphify.py
 sdk/local_exec.py
 sdk/platform_compat.py
@@ -97,6 +98,7 @@ tests/test_agent_prompt_models.py
 tests/test_agent_run_ticket.py
 tests/test_agents_connectors_builder.py
 tests/test_git_action.py
+tests/test_github_ingest.py
 tests/test_health.py
 tests/test_otp_login.py
 tests/test_updater_extras.py

{devops_bot_sdk-1.4.159 → devops_bot_sdk-1.6.2}/sdk/__init__.py

@@ -1,6 +1,6 @@
 """AgentOS Desktop SDK — thin HTTPS/SSE client for the Electron app.
 
-Version: 1.4.154
+Version: 1.6.2
 
 Public surface:
   BackendClient.from_config()        — create client from ~/.agentos/config.toml
@@ -30,7 +30,7 @@ Rules:
   - All data egress through submit_webhook only
 """
 
-__version__ = "1.4.159"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
+__version__ = "1.6.2"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
 __author__  = "AgentOS"   # sdk.client.SDK_VERSION and the UI server version all read this.
 
 from sdk.client import BackendClient

{devops_bot_sdk-1.4.159 → devops_bot_sdk-1.6.2}/sdk/cli.py

@@ -96,12 +96,16 @@ def main() -> None:
         _default_agents_command(rest)
         return
 
+    if noun == "github":
+        _github_command(rest)
+        return
+
     _print_usage()
     sys.exit(1)
 
 
 def _print_usage() -> None:
-    print("usage: agentos <configure|agent|integration|default-agents|agentd> ...")
+    print("usage: agentos <configure|agent|integration|default-agents|agentd|github> ...")
     print()
     print("  agentos configure [--rotate]")
     print("  agentos agent <list|run NAME|chat NAME MSG|logs NAME|enable NAME|disable NAME|rm NAME>")
@@ -109,6 +113,7 @@ def _print_usage() -> None:
     print("  agentos integration <add PATH|test NAME|list|rm NAME>")
     print("  agentos default-agents list [--department-id UUID]   # read-only; agents are created in the web app")
     print("  agentos agentd <start [--foreground]|status>")
+    print("  agentos github <ingest [--days N]|status>            # PR ingestion; --days N backfills N days")
 
 
 # ── agent ────────────────────────────────────────────────────────────────
@@ -590,5 +595,60 @@ def _agentd_command(args: list[str]) -> None:
     sys.exit(1)
 
 
+# ── github ───────────────────────────────────────────────────────────────
+
+def _github_command(args: list[str]) -> None:
+    """`agentos github ingest [--days N]` / `agentos github status`.
+
+    The daily ingestion normally runs by itself inside `agentos-ui` (see
+    sdk.github_ingest). This is the manual handle: `ingest` runs one now,
+    `--days N` forces an N-day window — that is the backfill.
+    """
+    from sdk import github_ingest as gi
+
+    verb = args[0] if args else None
+
+    if verb == "status":
+        st = gi.status()
+        state = st.get("state") or {}
+        print(f"enabled        : {st['enabled']}")
+        print(f"daily slot     : {st['slot_utc']} UTC")
+        print(f"catch-up cap   : {st['lookback_days']} days")
+        print(f"first-run seed : {st['backfill_days']} days"
+              f"{'' if st['backfilled'] else '  ← not run yet; the next run backfills'}")
+        print(f"last success   : {state.get('last_success_at') or '(never)'}")
+        print(f"last status    : {state.get('last_status') or '(none)'}")
+        if state.get("last_job_id"):
+            print(f"last job       : {state['last_job_id']}  {state.get('last_status_url', '')}")
+        if state.get("last_error"):
+            print(f"last error     : {state['last_error']}")
+        return
+
+    if verb == "ingest":
+        days = None
+        if "--days" in args:
+            try:
+                days = int(args[args.index("--days") + 1])
+            except (IndexError, ValueError):
+                print("error: --days needs a whole number of days, e.g. --days 50")
+                sys.exit(1)
+        result = asyncio.run(gi.run_once(days=days))
+        status = result.get("status")
+        if status == "queued":
+            print(f"queued: PRs since {result['since']}  job_id={result.get('job_id') or '(none)'}")
+            if result.get("status_url"):
+                print(f"poll  : {result['status_url']}  (on the AI backend)")
+            return
+        if status == "no_github_link":
+            print("nothing to do: this account has no GitHub connected.")
+            return
+        print(f"failed: {result.get('reason') or 'unknown error'}")
+        sys.exit(1)
+
+    print("usage: agentos github ingest [--days N]   # N-day backfill; omit for the normal window")
+    print("       agentos github status")
+    sys.exit(1)
+
+
 if __name__ == "__main__":
     main()

{devops_bot_sdk-1.4.159 → devops_bot_sdk-1.6.2}/sdk/client.py

@@ -763,13 +763,18 @@ class BackendClient:
         except Exception:
             return "pending"
 
-    async def github_token(self) -> str | None:
-        """GET /ml-api/github/token → the user's GitHub access token (gho_…).
-
-        Used by the LOCAL agent to authenticate git/gh for clone/push/PR. The
-        endpoint lives on the ML backend (devopsbot-be), authorised by the same
-        co_ token. Best-effort: returns None on any failure so a run without a
-        connected GitHub account still proceeds (clone/PR steps just won't auth).
+    async def github_token_record(self) -> dict | None:
+        """GET /ml-api/github/token → the caller's WHOLE GitHub link record.
+
+        Returns the ``data`` object — ``{id, userId, githubId, username,
+        accessToken, scope, …}`` — or None when this user has no GitHub link, the
+        token is rejected, or the backend is unreachable. Inherently per-user: the
+        ML backend resolves WHICH link to return from the ``co_`` token, so there
+        is no list-all form.
+
+        ``github_token()`` below is the accessToken-only view of this. The daily
+        PR-ingest cron (``sdk.github_ingest``) needs ``username`` too, which is why
+        the full record is exposed. Best-effort — never raises.
         """
         from sdk.config import BE_DEFAULT_URL
 
@@ -785,9 +790,72 @@ class BackendClient:
                 resp = await client.get(url, headers=headers)
             if resp.status_code >= 400:
                 return None
-            data = (resp.json() or {}).get("data") or {}
-            return data.get("accessToken") or None
-        except Exception:
+            return (resp.json() or {}).get("data") or None
+        except Exception:  # noqa: BLE001
+            return None
+
+    async def github_token(self) -> str | None:
+        """GET /ml-api/github/token → the user's GitHub access token (gho_…).
+
+        Used by the LOCAL agent to authenticate git/gh for clone/push/PR. The
+        endpoint lives on the ML backend (devopsbot-be), authorised by the same
+        co_ token. Best-effort: returns None on any failure so a run without a
+        connected GitHub account still proceeds (clone/PR steps just won't auth).
+        """
+        record = await self.github_token_record()
+        return (record or {}).get("accessToken") or None
+
+    async def ingest_github_prs(
+        self,
+        *,
+        github_username: str,
+        github_access_token: str,
+        since: str | None = None,
+        user_id: str = "",
+    ) -> dict | None:
+        """POST /api/v1/github/prs — queue PR ingestion for THIS user on the backend.
+
+        This is the daily GitHub ingestion trigger. It runs on the AI backend
+        (``devopsbot-ai.apiswagger.co.uk`` — ``self._url``, the same base every other
+        ``/api/v1`` call uses), NOT the ML gateway: the backend owns the LLM
+        summarise, the downstream daily-summary forward, and the Qdrant upsert.
+        The SDK only decides WHEN, because only this machine knows this user's
+        schedule and its own last-success watermark.
+
+        ``since`` is an ISO date (``YYYY-MM-DD``) → the backend's
+        ``GetUserPRsRequest.date_from``. Omitted means "today", which is what a
+        never-missed daily run wants; ``sdk.github_ingest`` sends the catch-up
+        watermark instead so a machine that was off does not silently lose days.
+
+        The credentials are sent in the body because that is what the endpoint
+        accepts today. The ``Authorization: co_`` header goes with every request
+        regardless, so once the backend resolves the GitHub link server-side from
+        that token (see docs/GITHUB_SCHEDULING_SDK_MIGRATION.md §3 step 1) it can
+        ignore the body fields without breaking this client.
+
+        Returns the response JSON (``{job_id, …}``) or None on any failure —
+        never raises into the cron.
+        """
+        payload = [{
+            "userId": user_id or self._user_id_from_token(),
+            "githubUsername": github_username,
+            "githubAccessToken": github_access_token,
+            "apiTokenHash": self._token,   # downstream daily-summary Authorization
+        }]
+        if since:
+            payload[0]["date_from"] = since
+        try:
+            async with httpx.AsyncClient(timeout=60.0) as client:
+                resp = await client.post(
+                    self._url("/api/v1/github/prs"), json=payload, headers=self._headers,
+                )
+            if resp.status_code >= 400:
+                logger.warning("client.ingest_github_prs failed status=%s body=%s",
+                               resp.status_code, resp.text[:200])
+                return None
+            return resp.json()
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("client.ingest_github_prs error err=%s", exc)
             return None
 
     async def move_to_backlog(self, task_id: str) -> bool:

devops_bot_sdk-1.6.2/sdk/github_ingest.py

@@ -0,0 +1,408 @@
+"""Daily GitHub PR ingestion — the SDK-side scheduler.
+
+Replaces the AI backend's Celery-beat entry ``github-prs-daily``, which fired
+once for the whole org and iterated a Postgres roster of every user holding a
+``co_`` token. Here there is no roster: one machine is one user, and this machine
+already holds that user's token — so it schedules only itself. See
+``docs/GITHUB_SCHEDULING_SDK_MIGRATION.md`` in the devops-bot-ai repo (Option A).
+
+What moves and what does NOT:
+  * MOVED here — the trigger, and only the trigger.
+  * STAYS on the backend — fetching the PRs, the LLM summarise, the per-repo
+    daily-summary forward, and the Qdrant upsert. This machine never talks to
+    Postgres, Qdrant, or Azure, and holds no credential beyond the ``co_`` token
+    it was configured with. One VPS cannot write another user's vectors.
+
+**Two things run, both on by default, no configuration needed:**
+  1. a ONE-TIME 50-day history backfill, fired from ``agentos-auto update`` via
+     :func:`run_backfill_once` and guarded by ``BACKFILL_ID`` so it happens at
+     most once per machine;
+  2. the DAILY loop below, started by the ``agentos-ui`` lifespan alongside the
+     2-hourly ``sdk.vps_health`` ping.
+
+The daily loop also covers the backfill: if a box never runs ``agentos-auto
+update``, the first tick sees ``backfill_pending`` and seeds the history itself.
+
+Schedule semantics — a real daily slot, not a naive interval:
+  * the loop ticks every ``_TICK_S`` (cheap: no network unless a run is due),
+  * a run is DUE when the UTC clock has passed ``AGENTOS_GITHUB_INGEST_AT``
+    (default ``13:30`` UTC = 18:30 Asia/Karachi, the slot the beat entry used) and
+    no successful run has been recorded for today's UTC date,
+  * so a machine that was asleep at 13:30 catches up the moment it comes back —
+    the failure mode that made this the riskiest part of the migration.
+
+Catch-up window: the request carries ``since`` = the date of the last SUCCESSFUL
+run (capped at ``_MAX_LOOKBACK_DAYS``), not "today". A box that was off for three
+days asks for three days of PRs on its next run instead of silently losing them.
+The backend's ingestion is expected to be idempotent per (user, repo, date) —
+overlapping windows WILL re-send PRs.
+
+State lives in ``~/.agentos/github_ingest.json``: ``last_success_at`` (the
+watermark), plus the last attempt's outcome for ``GET /api/ui/github-ingest``.
+
+Config — process env OR ``~/.agentos/.env`` (process env wins), all optional:
+  ``AGENTOS_GITHUB_INGEST``      ``0``/``false``/``no``/``off`` disables everything.
+  ``AGENTOS_GITHUB_INGEST_DAILY``  ``0`` turns the recurring daily loop OFF (default ON).
+  ``AGENTOS_GITHUB_INGEST_BACKFILL_DAYS``  one-time seed size (default 50, max 365).
+  ``AGENTOS_GITHUB_INGEST_AT``   daily UTC slot, ``HH:MM`` (default ``13:30``).
+  ``AGENTOS_GITHUB_INGEST_LOOKBACK_DAYS``  catch-up cap (default 7, max 90).
+
+Best-effort throughout: a failed run is recorded and retried on the next day's
+slot; nothing here raises into the host process.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from datetime import date, datetime, timedelta, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover — typing only
+    from sdk.client import BackendClient
+
+logger = logging.getLogger("sdk.github_ingest")
+
+STATE_FILE = Path.home() / ".agentos" / "github_ingest.json"
+
+DEFAULT_AT = "13:30"          # UTC — 18:30 Asia/Karachi (PKT = UTC+5, no DST)
+DEFAULT_LOOKBACK_DAYS = 7
+MAX_LOOKBACK_DAYS = 90
+# First run on a machine (no watermark yet) pulls HISTORY, not just today — so a
+# box that upgrades into this version seeds the platform with real PR history
+# instead of starting empty. This is the auto-trigger: the state file does not
+# exist on any machine yet, so the first tick after the upgrade backfills.
+DEFAULT_BACKFILL_DAYS = 50
+MAX_BACKFILL_DAYS = 365
+# Identifies THIS rollout's one-time history seed. The backfill runs once per
+# machine per id: a box that already has a watermark (it was ingesting before this
+# release) still gets the 50-day seed exactly once, and no future upgrade repeats
+# it. Bump this string ONLY to deliberately re-seed the whole fleet.
+BACKFILL_ID = "2026-08-pr50"
+_TICK_S = 900.0               # 15 min — resolution of the daily slot check
+_FALSEY = {"0", "false", "no", "off"}
+
+
+# ── Config ──────────────────────────────────────────────────────────────────
+
+def _setting(name: str) -> str:
+    """Read a toggle from the process env OR ``~/.agentos/.env`` (process env wins)."""
+    val = (os.environ.get(name) or "").strip()
+    if val:
+        return val
+    try:
+        from sdk.config import _dotenv_value
+        return (_dotenv_value(name) or "").strip()
+    except Exception:  # noqa: BLE001 — a config hiccup must never break the cron
+        return ""
+
+
+def enabled() -> bool:
+    """Master switch — False only when ``AGENTOS_GITHUB_INGEST`` is explicitly falsey.
+
+    Gates BOTH the one-time backfill and the daily loop.
+    """
+    return _setting("AGENTOS_GITHUB_INGEST").lower() not in _FALSEY
+
+
+def daily_enabled() -> bool:
+    """Is the RECURRING daily loop switched on? **Default: yes.**
+
+    The steady state is two schedules running side by side on every box, with no
+    configuration required: ``sdk.vps_health`` every 2 hours, and this one daily
+    at :func:`slot`. Opt OUT with ``AGENTOS_GITHUB_INGEST_DAILY=0`` (or turn off
+    GitHub ingestion entirely with ``AGENTOS_GITHUB_INGEST=0``).
+    """
+    return _setting("AGENTOS_GITHUB_INGEST_DAILY").lower() not in _FALSEY
+
+
+def slot() -> tuple[int, int]:
+    """The daily UTC slot as ``(hour, minute)``. Bad values fall back to the default."""
+    raw = _setting("AGENTOS_GITHUB_INGEST_AT") or DEFAULT_AT
+    try:
+        hh, _, mm = raw.partition(":")
+        hour, minute = int(hh), int(mm or 0)
+        if 0 <= hour <= 23 and 0 <= minute <= 59:
+            return hour, minute
+    except ValueError:
+        pass
+    logger.warning("github_ingest.bad_slot value=%r — using %s", raw, DEFAULT_AT)
+    hh, _, mm = DEFAULT_AT.partition(":")
+    return int(hh), int(mm)
+
+
+def lookback_days() -> int:
+    """Catch-up cap in days — how far back a long-offline machine may ask for."""
+    raw = _setting("AGENTOS_GITHUB_INGEST_LOOKBACK_DAYS")
+    if not raw:
+        return DEFAULT_LOOKBACK_DAYS
+    try:
+        return max(1, min(MAX_LOOKBACK_DAYS, int(raw)))
+    except ValueError:
+        logger.warning("github_ingest.bad_lookback value=%r — using %s",
+                       raw, DEFAULT_LOOKBACK_DAYS)
+        return DEFAULT_LOOKBACK_DAYS
+
+
+def backfill_days() -> int:
+    """How much history the FIRST run on this machine pulls (default 50 days).
+
+    Distinct from ``lookback_days()``: that bounds a routine catch-up after
+    downtime, this is the one-time seed. Set ``AGENTOS_GITHUB_INGEST_BACKFILL_DAYS=0``
+    to skip the backfill and start from today.
+    """
+    raw = _setting("AGENTOS_GITHUB_INGEST_BACKFILL_DAYS")
+    if not raw:
+        return DEFAULT_BACKFILL_DAYS
+    try:
+        return max(0, min(MAX_BACKFILL_DAYS, int(raw)))
+    except ValueError:
+        logger.warning("github_ingest.bad_backfill value=%r — using %s",
+                       raw, DEFAULT_BACKFILL_DAYS)
+        return DEFAULT_BACKFILL_DAYS
+
+
+# ── State ───────────────────────────────────────────────────────────────────
+
+def load_state() -> dict:
+    """Read the watermark file. Missing / corrupt → empty state (a first run)."""
+    try:
+        if STATE_FILE.exists():
+            data = json.loads(STATE_FILE.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                return data
+    except Exception as exc:  # noqa: BLE001 — a bad state file must not wedge the cron
+        logger.warning("github_ingest.state_unreadable err=%s", exc)
+    return {}
+
+
+def save_state(state: dict) -> None:
+    """Persist the watermark. Never raises — a lost write just re-runs tomorrow."""
+    try:
+        STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        STATE_FILE.write_text(json.dumps(state, indent=2), encoding="utf-8")
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("github_ingest.state_write_failed err=%s", exc)
+
+
+# ── Scheduling decisions (pure — the interesting logic, kept testable) ──────
+
+def backfill_pending(state: dict) -> bool:
+    """True when THIS rollout's one-time history seed has not run on this machine.
+
+    Keyed on ``BACKFILL_ID``, not on "is the state file empty" — so a machine that
+    was already ingesting daily before this release still seeds its history once,
+    and a machine that has seeded never does it again.
+    """
+    return backfill_days() > 0 and str(state.get("backfill_id") or "") != BACKFILL_ID
+
+
+def is_due(now: datetime, state: dict) -> bool:
+    """Should a run happen right now?
+
+    Two reasons: the one-time backfill for this rollout is still pending (fires
+    immediately, without waiting for the daily slot — the history should land as
+    part of the update, not up to 24h later), or today's slot has passed with no
+    successful run recorded for today (UTC).
+    """
+    if backfill_pending(state):
+        return True
+    hour, minute = slot()
+    if (now.hour, now.minute) < (hour, minute):
+        return False
+    last = str(state.get("last_success_at") or "")
+    return last[:10] != now.date().isoformat()
+
+
+def since_for(now: datetime, state: dict, days: int | None = None) -> str:
+    """The ``date_from`` to request.
+
+    Three cases, in order:
+      * ``days`` given — an explicit backfill (CLI / API): ``now - days``;
+      * this rollout's one-time seed still pending (``backfill_pending``) —
+        ``now - backfill_days()``, 50 days by default, so upgrading into this
+        version seeds history instead of starting blank;
+      * otherwise — the last success's date, floored at ``lookback_days()``.
+        Re-sending the last successful day is deliberate: a run that succeeded at
+        13:30 did not see that day's later PRs. With no watermark and the seed
+        disabled (``…BACKFILL_DAYS=0``) it falls back to today.
+    """
+    if days is not None:
+        return (now - timedelta(days=max(0, days))).date().isoformat()
+
+    if backfill_pending(state):
+        return (now - timedelta(days=backfill_days())).date().isoformat()
+
+    last = str(state.get("last_success_at") or "")[:10]
+    if not last:
+        return now.date().isoformat()
+    try:
+        parsed = date.fromisoformat(last)
+    except ValueError:
+        return now.date().isoformat()
+    floor = (now - timedelta(days=lookback_days())).date()
+    return max(parsed, floor).isoformat()
+
+
+# ── One run ─────────────────────────────────────────────────────────────────
+
+async def run_once(client: "BackendClient | None" = None, *, now: datetime | None = None,
+                   days: int | None = None) -> dict:
+    """Resolve this user's GitHub link, POST the ingest request, record the outcome.
+
+    ``days`` forces an explicit window (``now - days`` → today) instead of the
+    watermark — that is what ``agentos github backfill --days 50`` and
+    ``POST /api/ui/github-ingest/run?days=50`` use. It still advances the watermark
+    on success, so a manual backfill also satisfies that day's scheduled run.
+
+    Returns ``{ok, status, since, job_id, reason}``. ``status`` is ``queued``,
+    ``no_github_link`` (this user never connected GitHub — not a failure), or
+    ``failed``. Never raises.
+    """
+    stamp = (now or datetime.now(timezone.utc))
+    state = load_state()
+    since = since_for(stamp, state, days)
+    out: dict[str, Any] = {"ok": False, "status": "failed", "since": since,
+                           "job_id": "", "reason": ""}
+    try:
+        if client is None:
+            from sdk.client import BackendClient
+            client = BackendClient.from_config()
+
+        record = await client.github_token_record()
+        username = str((record or {}).get("username") or "").strip()
+        access_token = str((record or {}).get("accessToken") or "").strip()
+        if not username or not access_token:
+            # The common case for a user who never connected GitHub. Record it and
+            # move on — retrying every tick would spam the gateway for no reason.
+            out.update({"ok": True, "status": "no_github_link"})
+            logger.info("github_ingest.no_github_link")
+            state.update({"last_run_at": stamp.isoformat(), "last_status": "no_github_link",
+                          "backfill_id": BACKFILL_ID})
+            save_state(state)
+            return out
+
+        resp = await client.ingest_github_prs(
+            github_username=username, github_access_token=access_token, since=since,
+        )
+        if resp is None:
+            out["reason"] = "backend_rejected_or_unreachable"
+            state.update({"last_run_at": stamp.isoformat(), "last_status": "failed",
+                          "last_error": out["reason"]})
+            save_state(state)
+            logger.warning("github_ingest.failed since=%s", since)
+            return out
+
+        job_id = str(resp.get("job_id") or resp.get("jobId") or "")
+        # The backend returns its own poll path (`/api/v1/github/prs/status/{id}`) —
+        # keep it verbatim so an operator can follow a queued job without
+        # reconstructing the URL.
+        status_url = str(resp.get("status_url") or "")
+        out.update({"ok": True, "status": "queued", "job_id": job_id,
+                    "status_url": status_url})
+        # Watermark advances on ACCEPTANCE (202 + job_id), not on completion — the
+        # endpoint is fire-and-forget. A job that then fails backend-side is visible
+        # in its own job status; re-running the whole window daily would be worse.
+        state.update({
+            "last_success_at": stamp.isoformat(),
+            "last_run_at": stamp.isoformat(),
+            "last_status": "queued",
+            "last_job_id": job_id,
+            "last_status_url": status_url,
+            "last_since": since,
+            "last_error": "",
+            # Marks this rollout's one-time seed as done. Stamped on ANY accepted
+            # run — the first accepted run IS the seed (its window was the 50 days),
+            # so there is nothing left to catch up.
+            "backfill_id": BACKFILL_ID,
+        })
+        save_state(state)
+        logger.info("github_ingest.queued job_id=%s since=%s", job_id, since)
+        return out
+    except Exception as exc:  # noqa: BLE001 — the cron must never take the panel down
+        out["reason"] = str(exc)[:200]
+        logger.warning("github_ingest.error err=%s", exc)
+        return out
+
+
+def status() -> dict:
+    """Config + watermark + last outcome — surfaced by ``GET /api/ui/github-ingest``."""
+    hour, minute = slot()
+    state = load_state()
+    return {
+        "enabled": enabled(),
+        "daily_loop": daily_enabled(),
+        "slot_utc": f"{hour:02d}:{minute:02d}",
+        "lookback_days": lookback_days(),
+        "backfill_days": backfill_days(),
+        "backfill_id": BACKFILL_ID,
+        "backfill_pending": backfill_pending(state),   # True → the next run seeds history
+        "backfilled": not backfill_pending(state),
+        "state": state,
+    }
+
+
+# ── The cron loop ───────────────────────────────────────────────────────────
+
+async def run_forever(tick_s: float = _TICK_S) -> None:
+    """Tick until cancelled; run when today's slot has passed and today has no run."""
+    hour, minute = slot()
+    logger.info("github_ingest.cron_start slot_utc=%02d:%02d tick_s=%s", hour, minute, tick_s)
+    try:
+        while True:
+            try:
+                now = datetime.now(timezone.utc)
+                if is_due(now, load_state()):
+                    await run_once(now=now)
+            except Exception as exc:  # noqa: BLE001 — one bad tick must not end the loop
+                logger.warning("github_ingest.tick_failed err=%s", exc)
+            await asyncio.sleep(tick_s)
+    except asyncio.CancelledError:  # pragma: no cover — shutdown path
+        logger.info("github_ingest.cron_stop")
+        raise
+
+
+def start() -> "asyncio.Task | None":
+    """Start the RECURRING daily loop. On by default; returns the task, or None
+    when GitHub ingestion (or just the daily loop) has been switched off."""
+    if not enabled():
+        logger.info("github_ingest.disabled (AGENTOS_GITHUB_INGEST is off)")
+        return None
+    if not daily_enabled():
+        logger.info("github_ingest.daily_loop_off (AGENTOS_GITHUB_INGEST_DAILY is off)")
+        return None
+    return asyncio.ensure_future(run_forever())
+
+
+# ── The one-time backfill (what `agentos-auto update` fires) ────────────────
+
+def run_backfill_once(client: "BackendClient | None" = None) -> dict:
+    """Run THIS rollout's 50-day history backfill — at most once per machine.
+
+    Called from ``agentos-auto update``. Safe to call on every update: the
+    ``BACKFILL_ID`` marker in ``~/.agentos/github_ingest.json`` means the second
+    and later calls are a no-op, so a user who updates weekly still ingests the
+    history exactly once.
+
+    Synchronous by design — the update command is a plain CLI flow, not an event
+    loop. Returns ``{ran, status, since, job_id, status_url, reason}``;
+    ``ran=False`` with ``status="already_done"`` when the marker is already set,
+    or ``"disabled"`` when the feature is switched off. Never raises: a failed
+    backfill must not fail the update.
+    """
+    if not enabled():
+        return {"ran": False, "status": "disabled", "reason": "AGENTOS_GITHUB_INGEST is off"}
+
+    state = load_state()
+    if not backfill_pending(state):
+        return {"ran": False, "status": "already_done",
+                "since": state.get("last_since", ""), "job_id": state.get("last_job_id", "")}
+
+    try:
+        result = asyncio.run(run_once(client, days=backfill_days()))
+    except Exception as exc:  # noqa: BLE001 — never fail `agentos-auto update`
+        logger.warning("github_ingest.backfill_failed err=%s", exc)
+        return {"ran": True, "status": "failed", "reason": str(exc)[:200]}
+    return {"ran": True, **result}