code-context-control 2.154.0__tar.gz → 2.157.1__tar.gz

{code_context_control-2.154.0 → code_context_control-2.157.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.154.0
+Version: 2.157.1
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0
@@ -45,6 +45,7 @@ Requires-Dist: click>=8.0.0
 Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: keyring>=24.0
 Requires-Dist: cryptography>=41.0
+Requires-Dist: tzdata>=2024.1; sys_platform == "win32"
 Provides-Extra: vector
 Requires-Dist: scikit-learn>=1.3.0; extra == "vector"
 Requires-Dist: numpy>=1.24.0; extra == "vector"
@@ -391,7 +392,7 @@ C3 also records real per-tool usage to `.c3/tool_telemetry.jsonl`, so estimates
 
 - **All web servers bind `127.0.0.1` by default** and are guarded against browser-based attacks even on loopback — a Host-header allowlist (defeats DNS rebinding) plus an Origin/Referer check on every request (defeats cross-origin CSRF), with scoped, non-wildcard CORS. There is still **no user authentication**, so do not expose these servers to an untrusted network without auth/TLS in front. Binding to a non-loopback interface is opt-in and warned at startup. *(Hardening added in v2.33.0.)*
 - **Mobile gateway (`/api/mobile/*`)** — the Oracle exposes a companion-app surface for the C3 mobile app: merged cross-project feed, project overview, PM board read/write, digest, notification ack, plus the security surface (credential vault, Access Guard rules and masks, tool discipline). Unlike the legacy Oracle GETs it requires a **Bearer token on every method, GETs included** — the Discovery token, or (v2.125.0+) a **per-client token**: one credential per paired device, stored hashed in `~/.c3/oracle/clients.json`, revocable one at a time, and carrying a kind (`mobile` or `desk`) that override decisions are audited under. It validates every project path against the registry, and audits every write to the project's activity log and edit ledger. Pair the app from Oracle Settings → *Mobile app* (the QR carries the URL and a freshly minted per-device token; a legacy Discovery-token code is one button away). A same-machine client such as C3 Desk pairs itself with `POST /api/mobile/clients` and the owner-only `~/.c3/oracle/bootstrap.key`. Remote reachability is the same recipe as the Discovery API: set `bind_host` to the Tailscale/LAN interface IP (avoid `0.0.0.0`) and list that address in `allowed_hosts`, both in `~/.c3/oracle/config.json`; with such a bind the Oracle also listens on `127.0.0.1` (`loopback_listener`, default on) so local clients are not refused. Disable the whole surface with `"mobile_api_enabled": false`, or any subsystem with `mobile_credentials_enabled` / `mobile_access_enabled` / their `_write` twins.
-- **The mobile gateway never returns a credential value.** It has no reveal route by design: entries cross the wire through an allowlist serializer, and a value can only be identified by its length and an on-demand fingerprint. Two further levers ship **off** — `mobile_creds_agent_readable_raise` (raising `agent_readable` from the phone) and `mobile_access_global_scope` (machine-wide access rules) — because each exceeds what a leaked Bearer token could otherwise reach. Deliberately absent from the surface: bulk `.env` import, denial-counter clearing, `set_builtin_disabled`, and the raw-content access preview.
+- **The mobile gateway never returns a credential value.** It has no reveal route by design: entries cross the wire through an allowlist serializer, and a value can only be identified by its length and an on-demand fingerprint. Two further levers ship **off** — `mobile_creds_agent_readable_raise` (raising `agent_readable` from the phone) and `mobile_access_global_scope` (machine-wide access rules) — because each exceeds what a leaked Bearer token could otherwise reach. Deliberately absent from the surface: bulk `.env` import, denial-counter clearing, any way to loosen or disable a built-in guard (v2.157.0 adds read, tighten and end-a-lease-early only), lock force-release, and the raw-content access preview. Since v2.157.0 (API version 7) the gateway also serves the cross-project views C3 Desk reads from the Hub (locks, Access Guard rules, tool discipline, override policy, built-in guards, the session catalog without transcript text, and a Now snapshot), so the companion app can show what Desk shows.
 - **No telemetry by default.** The OSS package collects nothing. Opt-in Sentry crash reporting requires the `[telemetry]` extra plus both `SENTRY_DSN` and `C3_TELEMETRY_OPT_IN=1`; even then request bodies, local variables, and prompts are stripped.
 - **LLM memory distillation is local-first.** Cloud distillation (v2.51.0) is off by default and opt-in per project.
 - **API keys** for third-party providers are read from the environment and never persisted by C3.

{code_context_control-2.154.0 → code_context_control-2.157.1}/README.md

@@ -324,7 +324,7 @@ C3 also records real per-tool usage to `.c3/tool_telemetry.jsonl`, so estimates
 
 - **All web servers bind `127.0.0.1` by default** and are guarded against browser-based attacks even on loopback — a Host-header allowlist (defeats DNS rebinding) plus an Origin/Referer check on every request (defeats cross-origin CSRF), with scoped, non-wildcard CORS. There is still **no user authentication**, so do not expose these servers to an untrusted network without auth/TLS in front. Binding to a non-loopback interface is opt-in and warned at startup. *(Hardening added in v2.33.0.)*
 - **Mobile gateway (`/api/mobile/*`)** — the Oracle exposes a companion-app surface for the C3 mobile app: merged cross-project feed, project overview, PM board read/write, digest, notification ack, plus the security surface (credential vault, Access Guard rules and masks, tool discipline). Unlike the legacy Oracle GETs it requires a **Bearer token on every method, GETs included** — the Discovery token, or (v2.125.0+) a **per-client token**: one credential per paired device, stored hashed in `~/.c3/oracle/clients.json`, revocable one at a time, and carrying a kind (`mobile` or `desk`) that override decisions are audited under. It validates every project path against the registry, and audits every write to the project's activity log and edit ledger. Pair the app from Oracle Settings → *Mobile app* (the QR carries the URL and a freshly minted per-device token; a legacy Discovery-token code is one button away). A same-machine client such as C3 Desk pairs itself with `POST /api/mobile/clients` and the owner-only `~/.c3/oracle/bootstrap.key`. Remote reachability is the same recipe as the Discovery API: set `bind_host` to the Tailscale/LAN interface IP (avoid `0.0.0.0`) and list that address in `allowed_hosts`, both in `~/.c3/oracle/config.json`; with such a bind the Oracle also listens on `127.0.0.1` (`loopback_listener`, default on) so local clients are not refused. Disable the whole surface with `"mobile_api_enabled": false`, or any subsystem with `mobile_credentials_enabled` / `mobile_access_enabled` / their `_write` twins.
-- **The mobile gateway never returns a credential value.** It has no reveal route by design: entries cross the wire through an allowlist serializer, and a value can only be identified by its length and an on-demand fingerprint. Two further levers ship **off** — `mobile_creds_agent_readable_raise` (raising `agent_readable` from the phone) and `mobile_access_global_scope` (machine-wide access rules) — because each exceeds what a leaked Bearer token could otherwise reach. Deliberately absent from the surface: bulk `.env` import, denial-counter clearing, `set_builtin_disabled`, and the raw-content access preview.
+- **The mobile gateway never returns a credential value.** It has no reveal route by design: entries cross the wire through an allowlist serializer, and a value can only be identified by its length and an on-demand fingerprint. Two further levers ship **off** — `mobile_creds_agent_readable_raise` (raising `agent_readable` from the phone) and `mobile_access_global_scope` (machine-wide access rules) — because each exceeds what a leaked Bearer token could otherwise reach. Deliberately absent from the surface: bulk `.env` import, denial-counter clearing, any way to loosen or disable a built-in guard (v2.157.0 adds read, tighten and end-a-lease-early only), lock force-release, and the raw-content access preview. Since v2.157.0 (API version 7) the gateway also serves the cross-project views C3 Desk reads from the Hub (locks, Access Guard rules, tool discipline, override policy, built-in guards, the session catalog without transcript text, and a Now snapshot), so the companion app can show what Desk shows.
 - **No telemetry by default.** The OSS package collects nothing. Opt-in Sentry crash reporting requires the `[telemetry]` extra plus both `SENTRY_DSN` and `C3_TELEMETRY_OPT_IN=1`; even then request bodies, local variables, and prompts are stripped.
 - **LLM memory distillation is local-first.** Cloud distillation (v2.51.0) is off by default and opt-in per project.
 - **API keys** for third-party providers are read from the environment and never persisted by C3.

{code_context_control-2.154.0 → code_context_control-2.157.1}/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.157.1"
 
 # 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,

{code_context_control-2.154.0 → code_context_control-2.157.1}/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

{code_context_control-2.154.0 → code_context_control-2.157.1}/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.157.1</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">

{code_context_control-2.154.0 → code_context_control-2.157.1}/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