Per-channel sync state + Sync-now + next-run (live channels, plan steps 6-7)

Closes the gap between what shipped in v0.2.2 and the full new_goals.md plan
(whose post-pseudocode sections were never seen until now): per-channel
last-synced visibility, a per-channel re-run trigger, and a Dashboard "next run".

Backend:
  - data/recipe_state.json: cosmetic per-channel sync metadata
    { "<num>": { checked_at, changed_at?, change_summary? } }. Written by the
    scheduler (atomic temp-swap) at the end of APPLY cycles only — checked_at for
    every live channel in the cycle, changed_at/change_summary only when that
    channel was actually patched; full cycles prune entries no longer live. This
    is NOT correctness state (the diff still reads live Tunarr) — it lives in its
    own file specifically so it never races with channels.json edits/deploys. This
    is the principled version of the plan's "write back to channels.json" step,
    without making the scheduler a channels.json writer.
  - run_cycle/_run_cycle_blocking gain an `only=<number>` filter to scope a cycle
    to a single live channel; POST /api/recipes/run?only=N exposes it.
  - get_status() adds next_run_seconds (seconds to next auto cycle, null if
    disabled/paused) and a channels map (recipe_state). last_auto_run switched
    from event-loop time to wall-clock so the sync status handler can compute
    next_run without touching the loop.

Frontend:
  - Channels page: each live row shows "synced Xago" (from recipe_state); the
    edit modal gains a "Save & Sync now" button (live channels only) that saves
    then runs only=N&apply=true, applying the recipe in place without leaving the
    editor. Save logic refactored into a shared persist().
  - Dashboard Auto-Updates card shows "next ~in Xh" from next_run_seconds.

Verified locally in Docker against live Tunarr (all no-ops, no mutations):
  - status returns next_run_seconds (~12h) + channels map for all 4 live channels.
  - scoped run only=7 processes just #7; full apply writes recipe_state for all 4.
  - recipe_state.json written atomically; channels.json untouched.
  - frontend builds clean (tsc + vite).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: AlpineArchitecture

backend/routers/recipes_router.py

@@ -78,13 +78,14 @@ def recipes_status():
 
 
 @router.post("/recipes/run")
-async def recipes_run(apply: bool = Query(True)):
+async def recipes_run(apply: bool = Query(True), only: Optional[int] = Query(None)):
     """Run one cycle on demand. apply=false is a dry run (detect + log, no patch).
+    `only=N` limits the run to a single live channel (the per-channel "Sync now").
 
     This is the manual-refresh / test trigger — it runs the exact same code path
     the background loop does, so you don't have to wait for the interval.
     """
-    return await scheduler.run_cycle(apply=apply)
+    return await scheduler.run_cycle(apply=apply, only=only)
 
 
 @router.post("/recipes/pause")

backend/scheduler.py

@@ -25,6 +25,7 @@
 import json
 import os
 import sys
+import time
 from collections import Counter
 from datetime import datetime, timezone
 from pathlib import Path
@@ -48,9 +49,11 @@
     "paused": False,
     "running": False,
     "last_cycle": None,      # summary dict of the most recent cycle
-    "last_auto_run": None,   # event-loop time of last automatic cycle (None = never)
+    "last_auto_run": None,   # wall-clock time.time() of last automatic cycle (None = never)
 }
 
+STATE_FILE = "recipe_state.json"  # cosmetic per-channel sync metadata (NOT correctness state)
+
 DEFAULT_INTERVAL_HOURS = 12
 
 
@@ -80,6 +83,29 @@ def _live_channels(channels: list) -> list:
     return [ch for ch in channels if ch.get("live")]
 
 
+# ── Cosmetic per-channel sync state (recipe_state.json) ────────────────────────
+# Purely for the UI: last-synced timestamps + last change. NOT used by the diff —
+# correctness still reads live Tunarr. Kept in a separate file so it never races
+# with channels.json edits or deploys.
+
+def _load_state() -> dict:
+    try:
+        with open(DATA_DIR / STATE_FILE) as f:
+            return json.load(f)
+    except Exception:
+        return {}
+
+
+def _save_state(state: dict) -> None:
+    try:
+        tmp = DATA_DIR / (STATE_FILE + ".tmp")
+        with open(tmp, "w") as f:
+            json.dump(state, f, indent=2)
+        tmp.replace(DATA_DIR / STATE_FILE)  # atomic swap — no torn reads
+    except Exception:
+        pass  # cosmetic state must never break a cycle
+
+
 # ── Diff helpers ───────────────────────────────────────────────────────────────
 
 def _program_ids(resolved: list) -> set:
@@ -105,8 +131,13 @@ def _summarize(ids: set, id_label: dict) -> list:
 
 # ── The cycle ──────────────────────────────────────────────────────────────────
 
-def _run_cycle_blocking(apply: bool) -> dict:
-    """Synchronous body of one cycle. Runs in a worker thread."""
+def _run_cycle_blocking(apply: bool, only: int = None) -> dict:
+    """Synchronous body of one cycle. Runs in a worker thread.
+
+    `only` (a channel number) limits the cycle to a single live channel — used by
+    the per-channel "Sync now" button. The full library index is still built once
+    regardless, so this is about scope, not speed.
+    """
     started = datetime.now(timezone.utc)
     cfg = _load_config()
     tunarr_url = cfg.get("tunarr_url", "").rstrip("/")
@@ -128,6 +159,8 @@ def _run_cycle_blocking(apply: bool) -> dict:
         return summary
 
     live = _live_channels(_load_channels())
+    if only is not None:
+        live = [ch for ch in live if ch.get("number") == only]
     summary["live"] = len(live)
     if not live:
         return summary
@@ -194,6 +227,29 @@ def _run_cycle_blocking(apply: bool) -> dict:
 
     summary["changed"] = len(summary["changes"])
     _write_log(summary)
+
+    # Record cosmetic per-channel sync metadata (apply cycles only — a dry run
+    # isn't a real "sync"). Carries forward prior change info for unchanged channels.
+    if apply:
+        state = _load_state()
+        changed_by_num = {c["number"]: c for c in summary["changes"] if c.get("applied")}
+        for ch in live:
+            num = str(ch.get("number"))
+            entry = state.get(num, {})
+            entry["checked_at"] = summary["time"]
+            c = changed_by_num.get(ch.get("number"))
+            if c:
+                entry["changed_at"] = summary["time"]
+                entry["change_summary"] = (
+                    f"+{c['added_count']}" + (f" −{c['removed_count']}" if c["removed_count"] else "")
+                )
+            state[num] = entry
+        if only is None:
+            # Full cycle: drop entries for channels that are no longer live
+            live_nums = {str(ch.get("number")) for ch in live}
+            state = {k: v for k, v in state.items() if k in live_nums}
+        _save_state(state)
+
     return summary
 
 
@@ -216,12 +272,12 @@ def _write_log(summary: dict) -> None:
         pass  # logging must never break a cycle
 
 
-async def run_cycle(apply: bool = True) -> dict:
+async def run_cycle(apply: bool = True, only: int = None) -> dict:
     """Run one cycle under the deploy lock. Blocking work offloaded to a thread."""
     async with deploy_lock:
         _state["running"] = True
         try:
-            summary = await asyncio.to_thread(_run_cycle_blocking, apply)
+            summary = await asyncio.to_thread(_run_cycle_blocking, apply, only)
         finally:
             _state["running"] = False
     _state["last_cycle"] = summary
@@ -243,7 +299,7 @@ async def scheduler_loop() -> None:
             enabled = bool(cfg.get("recipes_enabled", False))
             interval_h = float(cfg.get("recipe_interval_hours", DEFAULT_INTERVAL_HOURS) or DEFAULT_INTERVAL_HOURS)
             interval_s = max(60.0, interval_h * 3600.0)
-            now = asyncio.get_event_loop().time()
+            now = time.time()  # wall clock — comparable from the status handler too
             last = _state["last_auto_run"]
             due = last is None or (now - last) >= interval_s
             if enabled and not _state["paused"] and due:
@@ -260,13 +316,25 @@ async def scheduler_loop() -> None:
 
 def get_status() -> dict:
     cfg = _load_config()
+    enabled = bool(cfg.get("recipes_enabled", False))
+    interval_h = float(cfg.get("recipe_interval_hours", DEFAULT_INTERVAL_HOURS) or DEFAULT_INTERVAL_HOURS)
+
+    # Seconds until the next automatic cycle (null if disabled/paused). last_auto_run
+    # is wall-clock, so this is safe to compute from the sync status handler.
+    next_run_seconds = None
+    if enabled and not _state["paused"]:
+        last = _state["last_auto_run"]
+        next_run_seconds = 0 if last is None else max(0.0, last + interval_h * 3600.0 - time.time())
+
     return {
-        "enabled": bool(cfg.get("recipes_enabled", False)),
+        "enabled": enabled,
         "paused": _state["paused"],
         "running": _state["running"],
-        "interval_hours": float(cfg.get("recipe_interval_hours", DEFAULT_INTERVAL_HOURS) or DEFAULT_INTERVAL_HOURS),
+        "interval_hours": interval_h,
+        "next_run_seconds": next_run_seconds,
         "live_count": len(_live_channels(_load_channels())),
         "last_cycle": _state["last_cycle"],
+        "channels": _load_state(),
     }
 
 

frontend/src/api/client.ts

@@ -68,8 +68,11 @@ export const api = {
       body: JSON.stringify({ value, order, exclude }),
     }),
   getRecipesStatus: () => req<RecipesStatus>('/recipes/status'),
-  runRecipes: (apply: boolean) =>
-    req<CycleSummary>(`/recipes/run?apply=${apply}`, { method: 'POST' }),
+  runRecipes: (apply: boolean, only?: number) =>
+    req<CycleSummary>(
+      `/recipes/run?apply=${apply}${only !== undefined ? `&only=${only}` : ''}`,
+      { method: 'POST' },
+    ),
   pauseRecipes: (paused: boolean) =>
     req<RecipesStatus>(`/recipes/pause?paused=${paused}`, { method: 'POST' }),
   saveRecipeConfig: (enabled: boolean, interval_hours: number) =>
@@ -108,9 +111,12 @@ export interface CycleSummary {
   time: string; apply: boolean; live: number; changed: number;
   changes: CycleChange[]; skipped: CycleSkip[]; error: string | null;
 }
+export interface ChannelSyncState { checked_at?: string; changed_at?: string; change_summary?: string }
 export interface RecipesStatus {
   enabled: boolean; paused: boolean; running: boolean;
-  interval_hours: number; live_count: number; last_cycle: CycleSummary | null;
+  interval_hours: number; next_run_seconds: number | null;
+  live_count: number; last_cycle: CycleSummary | null;
+  channels: Record<string, ChannelSyncState>;
 }
 export interface ChannelsFile { channels: Channel[]; orphaned: string[]; suggested_channels: string[] }
 export interface CsvInfo {

frontend/src/pages/Channels.tsx

@@ -6,11 +6,20 @@ import {
 import { useDisclosure } from '@mantine/hooks';
 import { notifications } from '@mantine/notifications';
 import {
-  IconCheck, IconEdit, IconPlus, IconRepeat, IconTag, IconTrash, IconX,
+  IconBolt, IconCheck, IconEdit, IconPlus, IconRepeat, IconTag, IconTrash, IconX,
 } from '@tabler/icons-react';
 import { useEffect, useRef, useState } from 'react';
 import { useNavigate, useParams } from 'react-router-dom';
-import { api, Channel, ContentItem, isMatchRef, RecipeMatch } from '../api/client';
+import { api, Channel, ChannelSyncState, ContentItem, isMatchRef, RecipeMatch } from '../api/client';
+
+function syncedAgo(iso?: string): string {
+  if (!iso) return 'never';
+  const secs = Math.max(0, (Date.now() - new Date(iso).getTime()) / 1000);
+  if (secs < 90) return 'just now';
+  if (secs < 3600) return `${Math.round(secs / 60)}m ago`;
+  if (secs < 86400) return `${Math.round(secs / 3600)}h ago`;
+  return `${Math.round(secs / 86400)}d ago`;
+}
 
 const SHUFFLE_COLOR: Record<string, string> = { ordered: 'blue', block: 'violet', shuffle: 'teal' };
 const SHUFFLE_OPTIONS = [
@@ -170,6 +179,7 @@ function ChannelModal({
   const [matchRef, setMatchRef] = useState<MatchRule | null>(null);
   const [building, setBuilding] = useState(false);
   const [saving, setSaving] = useState(false);
+  const [syncing, setSyncing] = useState(false);
 
   useEffect(() => {
     if (!channel) return;
@@ -198,25 +208,29 @@ function ChannelModal({
     setContent((c) => c.filter((_, idx) => idx !== i));
   }
 
+  async function persist() {
+    const rawContent: ContentItem[] = content.map((c) => {
+      const m = c.match(/^\{collection:\s*(.+)\}$/);
+      return m ? { collection: m[1] } : c;
+    });
+    if (matchRef) {
+      rawContent.push({
+        match: 'title_contains',
+        value: matchRef.value,
+        order: matchRef.order,
+        exclude: matchRef.exclude,
+      });
+    }
+    const payload: any = { number: Number(number), name, shuffle, content: rawContent };
+    if (live) payload.live = true;
+    await api.updateChannel(channel!.number, payload);
+  }
+
   async function save() {
     if (!channel) return;
     setSaving(true);
     try {
-      const rawContent: ContentItem[] = content.map((c) => {
-        const m = c.match(/^\{collection:\s*(.+)\}$/);
-        return m ? { collection: m[1] } : c;
-      });
-      if (matchRef) {
-        rawContent.push({
-          match: 'title_contains',
-          value: matchRef.value,
-          order: matchRef.order,
-          exclude: matchRef.exclude,
-        });
-      }
-      const payload: any = { number: Number(number), name, shuffle, content: rawContent };
-      if (live) payload.live = true;
-      await api.updateChannel(channel.number, payload);
+      await persist();
       notifications.show({ message: 'Channel saved', color: 'green', icon: <IconCheck size={14} /> });
       onSaved();
       onClose();
@@ -227,6 +241,31 @@ function ChannelModal({
     }
   }
 
+  // Save, then immediately run a scheduler cycle scoped to this channel — applies
+  // the recipe to Tunarr in place without leaving the editor.
+  async function saveAndSync() {
+    if (!channel) return;
+    setSyncing(true);
+    try {
+      await persist();
+      const res = await api.runRecipes(true, Number(number));
+      const c = res.changes.find((x) => x.number === Number(number));
+      notifications.show({
+        message: c
+          ? `Synced #${number} — +${c.added_count}${c.removed_count ? ` −${c.removed_count}` : ''}`
+          : `Synced #${number} — already up to date`,
+        color: 'green',
+        icon: <IconCheck size={14} />,
+      });
+      onSaved();
+      onClose();
+    } catch (e: any) {
+      notifications.show({ title: 'Sync failed', message: e.message, color: 'red' });
+    } finally {
+      setSyncing(false);
+    }
+  }
+
   return (
     <Modal
       opened={opened}
@@ -343,6 +382,17 @@ function ChannelModal({
 
         <Group justify="flex-end">
           <Button variant="subtle" color="gray" onClick={onClose}>Cancel</Button>
+          {live && (
+            <Button
+              variant="light"
+              color="orange"
+              leftSection={<IconBolt size={14} />}
+              onClick={saveAndSync}
+              loading={syncing}
+            >
+              Save &amp; Sync now
+            </Button>
+          )}
           <Button color="orange" onClick={save} loading={saving}>Save Channel</Button>
         </Group>
       </Stack>
@@ -354,10 +404,12 @@ function ChannelModal({
 
 function ChannelRow({
   channel,
+  sync,
   onEdit,
   onDelete,
 }: {
   channel: Channel;
+  sync?: ChannelSyncState;
   onEdit: () => void;
   onDelete: () => void;
 }) {
@@ -402,6 +454,9 @@ function ChannelRow({
                 live
               </Badge>
             )}
+            {channel.live && (
+              <Text size="xs" c="dimmed">synced {syncedAgo(sync?.checked_at)}</Text>
+            )}
           </Group>
         </Box>
 
@@ -428,6 +483,7 @@ export default function Channels() {
   const { number } = useParams<{ number?: string }>();
   const nav = useNavigate();
   const [channels, setChannels] = useState<Channel[]>([]);
+  const [sync, setSync] = useState<Record<string, ChannelSyncState>>({});
   const [loading, setLoading] = useState(true);
   const [editing, setEditing] = useState<Channel | null>(null);
   const [opened, { open, close }] = useDisclosure(false);
@@ -436,6 +492,7 @@ export default function Channels() {
     const data = await api.getChannels();
     setChannels([...data.channels].sort((a, b) => a.number - b.number));
     setLoading(false);
+    api.getRecipesStatus().then((s) => setSync(s.channels || {})).catch(() => {});
   }
 
   useEffect(() => { load(); }, []);
@@ -491,6 +548,7 @@ export default function Channels() {
             <ChannelRow
               key={ch.number}
               channel={ch}
+              sync={sync[String(ch.number)]}
               onEdit={() => edit(ch)}
               onDelete={() => load()}
             />

frontend/src/pages/Dashboard.tsx

@@ -68,6 +68,13 @@ function relTime(iso: string): string {
   return `${Math.round(secs / 86400)}d ago`;
 }
 
+function inTime(secs: number): string {
+  if (secs < 90) return 'in <1m';
+  if (secs < 3600) return `in ${Math.round(secs / 60)}m`;
+  if (secs < 86400) return `in ${Math.round(secs / 3600)}h`;
+  return `in ${Math.round(secs / 86400)}d`;
+}
+
 function LiveRecipesCard({ status, onChange }: { status: RecipesStatus; onChange: () => void }) {
   const [busy, setBusy] = useState(false);
   const last = status.last_cycle;
@@ -117,6 +124,7 @@ function LiveRecipesCard({ status, onChange }: { status: RecipesStatus; onChange
             </Group>
             <Text size="xs" c="dimmed">
               {status.live_count} live channel{status.live_count !== 1 ? 's' : ''} · every {status.interval_hours}h
+              {status.next_run_seconds != null && !status.paused ? ` · next ${inTime(status.next_run_seconds)}` : ''}
             </Text>
           </Box>
         </Group>