code-context-control 2.154.0__py3-none-any.whl → 2.156.0__py3-none-any.whl

cli/c3.py

@@ -91,7 +91,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.154.0"
+__version__ = "2.156.0"
 
 # The PreToolUse matcher for native subagent calls (installer and hub migration).
 AGENT_MATCHER = "Agent|Task"
@@ -264,6 +264,7 @@ _C3_MCP_ALLOW = [
     "mcp__c3__c3_jira", "mcp__c3__c3_credentials",
     "mcp__c3__c3_project", "mcp__c3__c3_task", "mcp__c3__c3_artifacts",
     "mcp__c3__c3_override", "mcp__c3__c3_ci", "mcp__c3__c3_shell_job",
+    "mcp__c3__c3_schedule",
 ]
 
 # Obsolete MCP tool names from earlier C3 versions. `c3 permissions clean`
@@ -7235,6 +7236,95 @@ def _enforce_audit(result: dict, project_path: str) -> None:
 _OVERRIDE_DEFAULT_TOOL = {"read": "Read", "write": "Edit"}
 
 
+def cmd_schedule(args):
+    """`c3 schedule` — scheduled tasks: list, add, run, approve or deny (docs/scheduled-tasks.md)."""
+    import json as _json
+
+    from cli.tools.schedule import build_target, build_when
+    from services.schedule_approvals import ApprovalError, ApprovalStore
+    from services.schedule_store import ScheduleError, ScheduleStore
+
+    sub = getattr(args, "schedule_cmd", None)
+    if not sub:
+        print("Usage: c3 schedule <list|add|show|rm|enable|disable|run|runs|approvals|approve|deny> ...")
+        return
+    store = ScheduleStore()
+    approvals = ApprovalStore()
+    try:
+        if sub == "list":
+            rows = store.list()
+            if not rows:
+                print("No schedules. Add one with `c3 schedule add`.")
+            for row in rows:
+                when = row.get("when") or {}
+                cadence = when.get("expr") or (f"every {when.get('seconds')}s" if when.get("type") == "every"
+                                                else when.get("when", ""))
+                flag = "on " if row.get("enabled") else "off"
+                print(f"  {row['id']} [{flag}] {row['name']!r} {row['kind']} @ {cadence} {row['autonomy']} "
+                      f"next={row.get('next_run_at') or '-'} last={row.get('last_status') or '-'}  "
+                      f"{row['project_path']}")
+        elif sub == "show":
+            row = store.get(args.schedule_id)
+            if row is None:
+                raise ScheduleError(f"no schedule {args.schedule_id}")
+            print(_json.dumps(row, indent=2, ensure_ascii=False))
+        elif sub == "add":
+            from oracle.config import load_config
+            from oracle.services.scheduler import defaults_from_config
+            when = build_when(cron=args.cron, every=args.every, at=args.at, preset=args.preset, tz=args.tz,
+                              preset_at=args.preset_at, days=args.days)
+            if when is None:
+                raise ScheduleError("give one of --cron, --every, --at or --preset")
+            fields = {
+                "name": args.name, "kind": args.kind, "target": build_target(args.kind, args.target),
+                "provider": args.provider, "model": args.model, "effort": args.effort,
+                "autonomy": args.autonomy, "project_path": str(Path(args.project_path).resolve()),
+                "when": when, "overlap": args.overlap, "check_command": args.check_command,
+            }
+            if args.timeout_s:
+                fields["timeout_s"] = args.timeout_s
+            if args.max_budget_usd:
+                fields["max_budget_usd"] = args.max_budget_usd
+            if args.permission_mode:
+                fields["permission_mode"] = args.permission_mode
+            row = store.create(fields, defaults=defaults_from_config(load_config()), created_by="cli")
+            print(f"Created {row['id']} {row['name']!r}; next run {row['next_run_at']}")
+        elif sub in ("enable", "disable"):
+            row = store.set_enabled(args.schedule_id, sub == "enable", by="cli")
+            print(f"{row['id']} {sub}d; next run {row.get('next_run_at') or '-'}")
+        elif sub == "rm":
+            if not store.delete(args.schedule_id, by="cli"):
+                raise ScheduleError(f"no schedule {args.schedule_id}")
+            print(f"Deleted {args.schedule_id}")
+        elif sub == "run":
+            if store.get(args.schedule_id) is None:
+                raise ScheduleError(f"no schedule {args.schedule_id}")
+            run = store.request_run(args.schedule_id, trigger="manual", by="cli", approved=args.bypass_approval)
+            print(f"Queued run {run['run_id']} ({run['status']}); the Oracle dispatches it on its next tick")
+        elif sub == "runs":
+            rows = store.runs(schedule_id=args.schedule_id or None, status=args.status or None, limit=args.limit)
+            if not rows:
+                print("No runs.")
+            for run in rows:
+                cost = f" ${run['cost_usd']:.3f}" if run.get("cost_usd") is not None else ""
+                err = f" — {str(run['error'])[:80]}" if run.get("error") else ""
+                print(f"  {run['run_id']} {run['status']:<17} {run['trigger']:<8} {run['schedule_name']!r} "
+                      f"{(run.get('claimed_at') or '')[:19]}{cost}{err}")
+        elif sub == "approvals":
+            rows = approvals.list(status=args.status or "pending")
+            if not rows:
+                print(f"No {args.status or 'pending'} approvals.")
+            for row in rows:
+                print(f"  {row['id']} {row['status']:<8} {row['schedule_name']!r} {row['summary']} "
+                      f"expires={row['expires_at']}")
+        elif sub in ("approve", "deny"):
+            row = approvals.decide(args.approval_id, sub, decided_by="cli", note=args.note or "")
+            print(f"{row['id']} {row['status']}; the Oracle acts on it on its next tick")
+    except (ScheduleError, ApprovalError) as exc:
+        print(f"Error: {exc}")
+        sys.exit(1)
+
+
 def cmd_override(args):
     """`c3 override` — Override Requests: allow one blocked call, once.
 
@@ -9663,6 +9753,7 @@ def main():
         "access": cmd_access,
         "enforce": cmd_enforce,
         "override": cmd_override,
+        "schedule": cmd_schedule,
         "locks": cmd_locks,
         "prune-quarantine": cmd_prune_quarantine,
         "ci": cmd_ci,

cli/commands/parser.py

@@ -840,6 +840,56 @@ def build_parser(version: str, parse_cli_ide_arg):
     ov_costs.add_argument("--path", dest="project_path", default=".",
                           help="Project directory (default: current)")
 
+    # ── Scheduled tasks (docs/scheduled-tasks.md) ─────────────────────────
+    # The human CLI over the same stores the Oracle fires from. approve/deny
+    # live here and on the Hub/Desk/phone, never on the c3_schedule agent tool.
+    p_schedule = subparsers.add_parser(
+        "schedule", help="Scheduled tasks — skills, prompts or commands the Oracle fires on a cadence")
+    sched_subs = p_schedule.add_subparsers(dest="schedule_cmd")
+    sched_subs.add_parser("list", help="Every schedule on this machine")
+    sc_show = sched_subs.add_parser("show", help="One schedule as JSON")
+    sc_show.add_argument("schedule_id")
+    sc_add = sched_subs.add_parser("add", help="Create a schedule")
+    sc_add.add_argument("name")
+    sc_add.add_argument("target", help="'/skill args', a prompt, or a command (see --kind)")
+    sc_add.add_argument("--kind", choices=["skill", "prompt", "command"], default="skill")
+    sc_add.add_argument("--cron", default="", help="5-field cron, e.g. '0 9 * * 1-5'")
+    sc_add.add_argument("--every", type=int, default=0, help="Seconds between runs")
+    sc_add.add_argument("--at", default="", help="One-shot ISO datetime")
+    sc_add.add_argument("--preset", choices=["hourly", "daily", "weekdays", "weekly", "monthly"], default="")
+    sc_add.add_argument("--preset-at", dest="preset_at", default="09:00", help="HH:MM for --preset")
+    sc_add.add_argument("--days", default="", help="Weekly preset days, e.g. mon,fri")
+    sc_add.add_argument("--tz", default="local", help="IANA zone or 'local'")
+    sc_add.add_argument("--provider", choices=["claude", "codex", "gemini", "grok"], default="claude")
+    sc_add.add_argument("--model", default="")
+    sc_add.add_argument("--effort", choices=["", "low", "medium", "high", "xhigh", "max"], default="")
+    sc_add.add_argument("--autonomy", choices=["autonomous", "approval"], default="approval")
+    sc_add.add_argument("--permission-mode", dest="permission_mode", default="")
+    sc_add.add_argument("--timeout", dest="timeout_s", type=int, default=0)
+    sc_add.add_argument("--budget", dest="max_budget_usd", type=float, default=0.0, help="--max-budget-usd cap")
+    sc_add.add_argument("--overlap", choices=["skip", "allow"], default="skip")
+    sc_add.add_argument("--check", dest="check_command", default="",
+                        help="Command whose exit 1 arms the run; exit 0 skips it")
+    sc_add.add_argument("--path", dest="project_path", default=".", help="Project directory (default: current)")
+    for verb, help_text in (("enable", "Resume a schedule"), ("disable", "Pause a schedule"),
+                            ("rm", "Delete a schedule")):
+        sp = sched_subs.add_parser(verb, help=help_text)
+        sp.add_argument("schedule_id")
+    sc_run = sched_subs.add_parser("run", help="Queue a run now")
+    sc_run.add_argument("schedule_id")
+    sc_run.add_argument("--bypass-approval", dest="bypass_approval", action="store_true",
+                        help="Skip the approval gate for this one run")
+    sc_runs = sched_subs.add_parser("runs", help="Recent runs")
+    sc_runs.add_argument("--schedule", dest="schedule_id", default="")
+    sc_runs.add_argument("--status", default="")
+    sc_runs.add_argument("--limit", type=int, default=30)
+    sc_appr = sched_subs.add_parser("approvals", help="Pending (or --status) approvals")
+    sc_appr.add_argument("--status", default="")
+    for verb in ("approve", "deny"):
+        sp = sched_subs.add_parser(verb, help=f"{verb.capitalize()} one pending scheduled run")
+        sp.add_argument("approval_id")
+        sp.add_argument("--note", default="")
+
     # ── Tool discipline / enforcement mode (v2.66.0) ────────────────────
     # LAYER C: how hard C3 pushes the agent toward c3_* tools. Distinct from
     # `c3 access` (path policy — a security boundary) and from

cli/guide/tools.html

@@ -107,6 +107,7 @@
       <a href="#c3_impact"    class="sidebar-link"><span class="icon">💥</span> c3_impact</a>
       <a href="#c3_shell"     class="sidebar-link"><span class="icon">⚡</span> c3_shell</a>
       <a href="#c3_shell_job" class="sidebar-link"><span class="icon">🕐</span> c3_shell_job</a>
+      <a href="#c3_schedule" class="sidebar-link"><span class="icon">📅</span> c3_schedule</a>
       <a href="#c3_ci"        class="sidebar-link"><span class="icon">🧪</span> c3_ci</a>
     </div>
     <div class="sidebar-section">
@@ -166,6 +167,7 @@
         <a href="#c3_impact"   class="toc-item">c3_impact   <span class="cat">Analysis</span></a>
         <a href="#c3_shell"    class="toc-item">c3_shell    <span class="cat">Execute</span></a>
         <a href="#c3_shell_job" class="toc-item">c3_shell_job <span class="cat">Execute</span></a>
+        <a href="#c3_schedule" class="toc-item">c3_schedule <span class="cat">Execute</span></a>
         <a href="#c3_ci"       class="toc-item">c3_ci       <span class="cat">Execute</span></a>
         <a href="#c3_edit"     class="toc-item">c3_edit     <span class="cat">Write</span></a>
         <a href="#c3_validate" class="toc-item">c3_validate <span class="cat">Write</span></a>
@@ -1602,6 +1604,49 @@ c3_task(action=<span class="str">'note_add'</span>, note=<span class="str">'Kanb
         </div>
       </div>
 
+      <!-- c3_schedule -->
+      <div class="tool-card" id="c3_schedule">
+        <div class="tool-card-header">
+          <span class="tool-name">c3_schedule</span>
+          <div class="tag-row">
+            <span class="badge badge-purple">execute</span>
+            <span class="badge">v2.156.0</span>
+          </div>
+          <span class="tool-tagline">Scheduled tasks — a skill, prompt or command the Oracle fires on a cadence, autonomously or after a human approves each run</span>
+        </div>
+        <div class="tool-card-body">
+          <p class="tool-desc">A schedule names what to run (<code>kind='skill'</code> with <code>target='/daily_report weekly'</code>, a free <code>prompt</code>, or a plain <code>command</code> with no LLM), where (a registered project), how (<code>provider</code> claude / codex / gemini / grok, <code>model</code>, <code>effort</code>, <code>permission_mode</code>, <code>max_budget_usd</code>) and when (<code>cron</code>, <code>preset</code>, <code>every</code> seconds, or a one-shot <code>at</code>). The Oracle's scheduler claims each due slot once, runs it as a detached shell job in the project, records exit, duration, cost and tokens, and writes a <code>kind=schedule</code> notification the Hub, Desk and phone show. <code>autonomy='approval'</code> (the default from an agent) creates a pending approval instead of firing; nobody approving before the TTL means the slot is logged <code>expired</code> and skipped. Deciding is human-only — the Hub Schedules tab, the Desk, the phone or <code>c3 schedule approve</code>. See <code>docs/scheduled-tasks.md</code>.</p>
+
+          <h4>Actions</h4>
+          <table class="params-table">
+            <thead><tr><th>Action</th><th>Group</th><th>Description</th></tr></thead>
+            <tbody>
+              <tr><td class="param-name">create</td><td>Write</td><td class="param-desc"><code>name</code>, <code>kind</code>, <code>target</code>, one cadence (<code>cron</code> + <code>tz</code> | <code>preset</code> + <code>preset_at</code> [+ <code>days</code>] | <code>every</code> | <code>at</code>), then <code>provider</code>, <code>model</code>, <code>effort</code>, <code>autonomy</code>, <code>project</code>, <code>cwd</code>, <code>timeout</code>, <code>max_budget_usd</code>, <code>permission_mode</code>, <code>allowed_tools</code>, <code>check_command</code> (exit 1 arms the run, exit 0 skips it for free), <code>overlap</code>, <code>misfire_grace_s</code></td></tr>
+              <tr><td class="param-name param-list">update, enable, disable, delete</td><td>Write</td><td class="param-desc"><code>schedule_id</code> + changed fields; a disabled schedule keeps its history</td></tr>
+              <tr><td class="param-name">run_now</td><td>Write</td><td class="param-desc">Queue one run outside the cadence; approval-mode schedules still ask</td></tr>
+              <tr><td class="param-name param-list">list, get, runs, approvals, status</td><td>Read</td><td class="param-desc">Schedules, one row, recent runs ([<code>schedule_id</code>] [<code>status</code>] [<code>limit</code>]), pending approvals, the loop's state</td></tr>
+              <tr><td class="param-name">preview</td><td>Read</td><td class="param-desc">A cadence → its next fire times, before you commit to it</td></tr>
+            </tbody>
+          </table>
+
+          <h4>Examples</h4>
+          <pre><code><span class="com"># A weekday report, sonnet at medium effort, asking first</span>
+c3_schedule(action=<span class="str">'create'</span>, name=<span class="str">'daily report'</span>, kind=<span class="str">'skill'</span>,
+            target=<span class="str">'/daily_report'</span>, preset=<span class="str">'weekdays'</span>, preset_at=<span class="str">'09:00'</span>,
+            model=<span class="str">'sonnet'</span>, effort=<span class="str">'medium'</span>, max_budget_usd=<span class="num">1.0</span>)
+
+<span class="com"># A free command every hour, no LLM, fires on its own</span>
+c3_schedule(action=<span class="str">'create'</span>, name=<span class="str">'fetch'</span>, kind=<span class="str">'command'</span>,
+            target=<span class="str">'git fetch --all --prune'</span>, every=<span class="num">3600</span>, autonomy=<span class="str">'autonomous'</span>)
+
+<span class="com"># See what a cron would do, then what ran</span>
+c3_schedule(action=<span class="str">'preview'</span>, cron=<span class="str">'0 18 * * 1-5'</span>, tz=<span class="str">'Europe/Berlin'</span>)
+c3_schedule(action=<span class="str">'runs'</span>, limit=<span class="num">10</span>)</code></pre>
+
+          <p class="tool-desc"><strong>Surfaces:</strong> the Hub's Schedules tab (create, edit, pause, run now, approve or deny), <code>/api/mobile/schedules</code> for the Desk and the phone, and <code>c3 schedule</code> on the command line.</p>
+        </div>
+      </div>
+
       <!-- c3_artifacts -->
       <div class="tool-card" id="c3_artifacts">
         <div class="tool-card-header">

cli/hook_session_open.py

@@ -30,6 +30,12 @@ the hub, and it skips a project that already has a live UI port, so a
 ``C3_NO_UI_AUTOSTART=1`` or
 ``.c3/config.json → {"ui": {"autostart_on_session": false}}``.
 
+A ``clear`` (or an in-session ``resume``) keeps the MCP server it already
+has, under a host session id that just ended. This hook finds that server
+by the host pid both of them share and hands it the new id
+(``services.host_handoff``, v2.155.0); the server then writes the
+``C3 connected <new id>`` row the desktop sentinel is waiting for.
+
 ``source: "compact"`` writes NOTHING: a compaction is the same session and
 the same MCP process, and a "Session started" toast on every compaction
 would teach the user to ignore the real ones.
@@ -48,6 +54,8 @@ from __future__ import annotations
 import json
 import os
 import sys
+import time
+import uuid
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent.parent))
@@ -56,6 +64,11 @@ from cli._hook_utils import detect_host, find_project, log_hook_error  # noqa: E
 from cli.hook_session_end import short_id  # noqa: E402
 
 _SILENT_SOURCES = {"compact"}
+# How long one session's UI launch holds the project against the next. A
+# server lands in the registry only after it binds its port, a few seconds
+# after Popen; this covers that gap with room to spare. After it, the live
+# registry entry (``_ui_running``) is the guard again.
+_LAUNCH_GRACE_S = 90.0
 
 
 def _ui_autostart_enabled(project: Path) -> bool:
@@ -96,7 +109,10 @@ def _ui_running(pm, project: Path) -> bool:
     """True when a live UI server is already registered for this project.
 
     This is what keeps `resume` / `clear` — both real SessionStart events —
-    from stacking a second server on every reconnect.
+    from stacking a second server on every reconnect. A registered server
+    whose port is quiet but whose pid is running is still "running": it is
+    starting up, or busy, and a second one would only be the leak this
+    check exists to prevent (2.155.0).
     """
     target = os.path.normcase(str(project))
     for entry in pm._read_registry():
@@ -107,8 +123,72 @@ def _ui_running(pm, project: Path) -> bool:
             same = os.path.normcase(str(Path(raw).resolve())) == target
         except Exception:
             same = os.path.normcase(raw) == target
-        if same and entry.get("port") and pm._port_alive(entry["port"]):
+        if not same or not entry.get("port"):
+            continue
+        if pm._port_alive(entry["port"]):
+            return True
+        if entry.get("pid") and pm._pid_alive(entry.get("pid")):
+            return True
+    return False
+
+
+def _launch_lock(project: Path) -> Path:
+    return project / ".c3" / "ui_launch.lock"
+
+
+def _claim_launch(project: Path) -> bool:
+    """Atomically claim the right to launch this project's UI server.
+
+    ``_ui_running`` only sees a server once it has registered its port, a
+    few seconds after launch. Sessions that open inside that window (an
+    agent spawning several at once, or a resume racing a startup) each saw
+    no live UI and each launched one, which is how a project ended up with
+    two servers. The first claimant creates ``.c3/ui_launch.lock`` with
+    O_EXCL; anyone else inside ``_LAUNCH_GRACE_S`` stands down.
+
+    A lock older than the grace window is stale (the launch died, or the
+    server since exited). It is taken over by renaming it to a unique name,
+    which only one contender can do, then the create is retried. If the
+    lock cannot be handled at all the answer is True, which is the
+    behaviour from before this lock existed: a missing UI is worse than a
+    rare duplicate.
+    """
+    lock = _launch_lock(project)
+    try:
+        lock.parent.mkdir(parents=True, exist_ok=True)
+    except Exception:
+        return True
+    for _ in range(3):
+        try:
+            fd = os.open(str(lock), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError:
+            try:
+                age = time.time() - lock.stat().st_mtime
+            except FileNotFoundError:
+                continue  # released between our create and stat; retry
+            except Exception:
+                return True
+            if age < _LAUNCH_GRACE_S:
+                return False
+            stale = lock.with_name(f"ui_launch.stale-{uuid.uuid4().hex}")
+            try:
+                os.rename(str(lock), str(stale))
+            except FileNotFoundError:
+                continue  # another contender took it over first
+            except Exception:
+                return False
+            try:
+                stale.unlink()
+            except Exception:
+                pass
+            continue
+        except Exception:
             return True
+        try:
+            os.write(fd, f"{os.getpid()} {time.time():.0f}\n".encode("ascii"))
+        finally:
+            os.close(fd)
+        return True
     return False
 
 
@@ -136,6 +216,8 @@ def ensure_ui(project: Path, host_session_id: str = "") -> str:
             return "unregistered"
         if _ui_running(pm, project):
             return "already-running"
+        if not _claim_launch(project):
+            return "launch-pending"
         # launch_session copies os.environ into the detached child, which is
         # where cli/server._register_session reads the ownership from.
         os.environ["C3_UI_OWNER"] = "session"
@@ -150,6 +232,22 @@ def ensure_ui(project: Path, host_session_id: str = "") -> str:
         return "error"
 
 
+def hand_off_runtime(project: Path, host: str, host_sid: str, start_source: str) -> list:
+    """Point the MCP server this host already runs at its new session id.
+
+    Returns the C3 session ids handed off (usually one, often none: a
+    ``startup`` has no server yet). Never raises.
+    """
+    if not host_sid:
+        return []
+    try:
+        from services.host_handoff import hand_off
+        return hand_off(project, host, host_sid, start_source)
+    except Exception as exc:
+        log_hook_error("hook_session_open", exc)
+        return []
+
+
 def run(payload: dict, project_path: Path | None = None):
     """Core logic — importable by the dispatcher and tests. Returns None."""
     start_source = str(payload.get("source") or "").strip().lower()
@@ -178,6 +276,7 @@ def run(payload: dict, project_path: Path | None = None):
                kind="session", ref_id=host_sid)
     except Exception:
         pass
+    hand_off_runtime(project, host, host_sid, start_source)
     ensure_ui(project, host_sid)
     return None
 

cli/hub_server.py

@@ -83,7 +83,7 @@ _HUB_CONFIG_DEFAULTS = {
 
 # Top-bar tabs a persisted ``main_view`` may name (cli/hub_ui/components/topbar.js).
 _MAIN_VIEWS = {"projects", "board", "ci", "creds", "tokens", "locks", "access",
-               "enforce", "sessions"}
+               "enforce", "sessions", "schedules"}
 
 # Stock command per IDE id, and whether it takes the project path as an
 # argument (GUI) instead of being run inside a terminal at that path.
@@ -400,6 +400,7 @@ _HUB_JS_FILES = [
     "hub_ui/components/hub_enforcement.js",
     "hub_ui/components/hub_sessions.js",
     "hub_ui/components/hub_ci.js",
+    "hub_ui/components/hub_schedules.js",
     "hub_ui/components/drill_subprojects.js",
     "hub_ui/components/drill_health.js",
     "hub_ui/components/drill_tasks.js",
@@ -3249,6 +3250,180 @@ def _hub_override_audit(action: str, row: dict, *, confirmed: bool = False,
         pass
 
 
+# ── Scheduled tasks (docs/scheduled-tasks.md) ────────────────────────────
+# The Oracle owns the loop; the hub reads and writes the same stores on this
+# machine, so a Hub edit or decision is picked up on the Oracle's next tick.
+
+def _schedule_api():
+    from oracle.config import load_config as _oracle_config
+    from oracle.services import schedule_api
+    from services.schedule_approvals import ApprovalStore
+    from services.schedule_store import ScheduleStore
+    if schedule_api._get_store() is None:
+        store, approvals = ScheduleStore(), ApprovalStore()
+        schedule_api.configure(get_scheduler=lambda: None, get_store=lambda: store,
+                               get_approvals=lambda: approvals, get_scanner=lambda: None,
+                               get_cfg=_oracle_config)
+    return schedule_api
+
+
+def _sched_call(fn, *args, **kwargs):
+    api = _schedule_api()
+    try:
+        return fn(*args, **kwargs), None
+    except api.ApiError as exc:
+        return None, (jsonify({"error": str(exc)}), exc.status)
+    except ValueError as exc:
+        return None, (jsonify({"error": str(exc)}), 400)
+
+
+def _sched_project_arg(key: str = "path") -> tuple[str, object]:
+    raw = (request.args.get(key) or "").strip()
+    if not raw:
+        return "", None
+    try:
+        return str(_resolve_project_path(raw)), None
+    except ValueError as exc:
+        return "", (jsonify({"error": str(exc)}), 404)
+
+
+def _sched_body_with_project(body: dict) -> tuple[dict, object]:
+    body = dict(body or {})
+    raw = str(body.pop("project", "") or body.get("project_path") or "").strip()
+    if raw:
+        try:
+            body["project_path"] = str(_resolve_project_path(raw))
+        except ValueError as exc:
+            return body, (jsonify({"error": str(exc)}), 404)
+    return body, None
+
+
+def _sched_with_names(rows: list) -> list:
+    return [dict(r, project_name=Path(str(r.get("project_path") or "")).name) for r in rows]
+
+
+@app.route("/api/hub/schedules", methods=["GET"])
+def api_hub_schedules():
+    project_path, err = _sched_project_arg()
+    if err:
+        return err
+    store = _schedule_api()._get_store()
+    rows = _sched_with_names(store.list(project_path=project_path or None))
+    return jsonify({"schedules": rows, "count": len(rows), "rev": store.rev(), "project": project_path})
+
+
+@app.route("/api/hub/schedules", methods=["POST"])
+def api_hub_schedules_create():
+    body, err = _sched_body_with_project(request.get_json(silent=True) or {})
+    if err:
+        return err
+    row, err = _sched_call(_schedule_api().create_schedule, body, scanner=None, by="desktop")
+    return err or (jsonify(row), 201)
+
+
+@app.route("/api/hub/schedules/status", methods=["GET"])
+def api_hub_schedules_status():
+    """The Oracle's scheduler status, or ``reachable: false`` when it is down."""
+    base = (_read_hub_config().get("oracle_url") or "").strip() or _oracle_service().url()
+    try:
+        with urllib.request.urlopen(f"{base.rstrip('/')}/api/schedules/status", timeout=2) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except (OSError, ValueError) as exc:
+        return jsonify({"running": False, "reachable": False, "error": str(exc), "oracle_url": base})
+    data["reachable"] = True
+    data["oracle_url"] = base
+    return jsonify(data)
+
+
+@app.route("/api/hub/schedules/preview", methods=["POST"])
+def api_hub_schedules_preview():
+    data, err = _sched_call(_schedule_api().preview_when, request.get_json(silent=True) or {})
+    return err or jsonify(data)
+
+
+@app.route("/api/hub/schedules/runs", methods=["GET"])
+def api_hub_schedule_runs():
+    project_path, err = _sched_project_arg()
+    if err:
+        return err
+    try:
+        limit = max(1, min(int(request.args.get("limit") or 50), 500))
+    except (TypeError, ValueError):
+        limit = 50
+    rows = _schedule_api()._get_store().runs(
+        schedule_id=(request.args.get("schedule_id") or None),
+        status=((request.args.get("status") or "").strip() or None),
+        project_path=project_path or None, limit=limit)
+    return jsonify({"runs": _sched_with_names(rows), "count": len(rows), "project": project_path})
+
+
+@app.route("/api/hub/schedules/approvals", methods=["GET"])
+def api_hub_schedule_approvals():
+    project_path, err = _sched_project_arg()
+    if err:
+        return err
+    rows = _schedule_api()._get_approvals().list(
+        status=((request.args.get("status") or "").strip() or None), project_path=project_path or None)
+    return jsonify({"approvals": _sched_with_names(rows), "count": len(rows)})
+
+
+@app.route("/api/hub/schedules/approvals/<approval_id>", methods=["POST"])
+def api_hub_schedule_decide(approval_id):
+    row, err = _sched_call(_schedule_api().decide_approval, str(approval_id),
+                           request.get_json(silent=True) or {}, by="desktop")
+    return err or jsonify(row)
+
+
+@app.route("/api/hub/schedules/<schedule_id>", methods=["GET"])
+def api_hub_schedule_one(schedule_id):
+    store = _schedule_api()._get_store()
+    row = store.get(schedule_id)
+    if row is None:
+        return jsonify({"error": f"no schedule {schedule_id}"}), 404
+    return jsonify(dict(row, rev=store.rev(), project_name=Path(str(row.get("project_path") or "")).name))
+
+
+@app.route("/api/hub/schedules/<schedule_id>", methods=["PATCH"])
+def api_hub_schedule_update(schedule_id):
+    body, err = _sched_body_with_project(request.get_json(silent=True) or {})
+    if err:
+        return err
+    row, err = _sched_call(_schedule_api().update_schedule, schedule_id, body, scanner=None, by="desktop")
+    return err or jsonify(row)
+
+
+@app.route("/api/hub/schedules/<schedule_id>", methods=["DELETE"])
+def api_hub_schedule_delete(schedule_id):
+    if not _schedule_api()._get_store().delete(schedule_id, by="desktop"):
+        return jsonify({"error": f"no schedule {schedule_id}"}), 404
+    return jsonify({"deleted": schedule_id})
+
+
+@app.route("/api/hub/schedules/<schedule_id>/run", methods=["POST"])
+def api_hub_schedule_run(schedule_id):
+    run, err = _sched_call(_schedule_api().run_schedule, schedule_id, request.get_json(silent=True) or {},
+                           by="desktop")
+    return err or (jsonify(run), 202)
+
+
+@app.route("/api/hub/schedules/<schedule_id>/<action>", methods=["POST"])
+def api_hub_schedule_toggle(schedule_id, action):
+    if action not in ("enable", "disable"):
+        return jsonify({"error": "unknown action"}), 404
+    row, err = _sched_call(_schedule_api().update_schedule, schedule_id, {"enabled": action == "enable"},
+                           scanner=None, by="desktop")
+    return err or jsonify(row)
+
+
+@app.route("/api/hub/schedules/<schedule_id>/runs", methods=["GET"])
+def api_hub_schedule_runs_one(schedule_id):
+    store = _schedule_api()._get_store()
+    if store.get(schedule_id) is None:
+        return jsonify({"error": f"no schedule {schedule_id}"}), 404
+    rows = store.runs(schedule_id=schedule_id, status=((request.args.get("status") or "").strip() or None))
+    return jsonify({"runs": rows, "count": len(rows)})
+
+
 @app.route("/api/hub/overrides", methods=["GET"])
 def api_hub_overrides():
     """Pending + recently-decided requests across every project, newest first.

cli/hub_ui/app.js

@@ -44,7 +44,7 @@ function App() {
       if (cfg.projects_view === 'grid') setView('grid');
       if (cfg.sidebar_collapsed != null) setSidebarCollapsed(!!cfg.sidebar_collapsed);
       if (cfg.sidebar_group) setFilter(cfg.sidebar_group);
-      if (['board', 'ci', 'creds', 'tokens', 'locks', 'access', 'enforce', 'sessions'].includes(cfg.main_view)) setMainView(cfg.main_view);
+      if (['board', 'ci', 'creds', 'tokens', 'locks', 'access', 'enforce', 'sessions', 'schedules'].includes(cfg.main_view)) setMainView(cfg.main_view);
     } catch { }
     try { const v = await api.get('/api/version'); setVersion(v.c3_version || ''); } catch { }
   }, []);
@@ -129,6 +129,8 @@ function App() {
             <HubEnforcement projects={projects} onOpenDrill={openDrill} />
           ) : mainView === 'sessions' ? (
             <HubSessions projects={projects} />
+          ) : mainView === 'schedules' ? (
+            <HubSchedules projects={projects} onOpenDrill={openDrill} />
           ) : (
             <React.Fragment>
               <SummaryBar projects={projects} search={search} setSearch={setSearch}