S4: docs — scheduler as the one schedule surface; verb-compat, deprecations, scoped break

- CHANGELOG: Added (lifecycle on SchedulerClient, reason=), Changed (scoped
  breaking get/save/list_for_agent removal with one-line migrations; typed
  get_schedule), Deprecated (AgentScheduleClient/ScheduleClient/
  get_agent_schedule_client), Fixed (PUT-first with 405->GET fallback across
  server families).
- docs/SCHEDULE.md: verb-compatibility note (OSS=PUT, Orkes=GET, transparent
  fallback), pause reason= example (OSS-only storage), new Schedule Lifecycle
  Helpers section (the six typed-error operations; reads/writes/lists stay on
  the native methods).
- docs/agents/{advanced,api-reference,writing-agents}.md: schedule surface
  documented on SchedulerClient; samples migrated off the removed wrappers;
  deprecation guidance for the shim symbols.
- AGENTS.md §1.2: HAND-FIX policy — never regenerate scheduler_resource_api.py
  without re-applying the marked fixes; the contract guard tests fail loudly.

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

Author: Kowser

AGENTS.md

@@ -122,6 +122,15 @@ conductor-{language}/
 
 #### 1.2 HTTP/API Layer
 
+> **HAND-FIX policy:** the bundled scheduler API spec is out of date, so
+> `scheduler_resource_api.py` carries hand-applied fixes marked with `HAND-FIX`
+> comments (per-schedule pause/resume verbs are `PUT` — the OSS Conductor dialect,
+> with a 405→`GET` fallback for Orkes servers living in `OrkesSchedulerClient` —
+> plus an optional `reason` query param and `get_schedule`
+> `response_type='WorkflowSchedule'`). Never regenerate that file without
+> re-applying them; `tests/unit/orkes/test_scheduler_resource_contract.py` fails
+> loudly if a regeneration reverts them.
+
 - [ ] Generate models from OpenAPI specification
 - [ ] Generate resource API classes
 - [ ] Implement ApiClient with:

CHANGELOG.md

@@ -11,15 +11,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Canonical metrics mode: opt-in harmonized metric surface via `WORKER_CANONICAL_METRICS=true` -- [details](METRICS.md#detailed-technical-notes--unreleased)
 - `MetricsSettings` gains `clean_directory` and `clean_dead_pids` for opt-in stale `.db` file cleanup (both default to `False`)
+- `SchedulerClient` now carries the schedule lifecycle operations itself: `pause(reason=)`, `resume`, `delete`, `run_now`, `preview_next`, `reconcile` (declarative tri-state sync) — with typed errors (`ScheduleNotFound`, `InvalidCronExpression`, ...). `pause_schedule` gains an optional `reason=` (stored by OSS Conductor servers; ignored by Orkes servers)
 
 ### Changed
 
 - **Multiprocessing start method now defaults to `spawn` on all platforms** (was `fork` everywhere except Windows). `fork` caused silently-restarting `SIGSEGV` worker subprocesses on macOS (exitcode `-11`) and fork-with-held-lock deadlocks on POSIX. 
 - Legacy metrics emit unchanged by default; no env var required
 - `metrics_collector.py` is now a compatibility shim; `from conductor.client.telemetry.metrics_collector import MetricsCollector` continues to work
+- **Breaking (scoped):** schedule client objects no longer expose the mapped `get`/`save`/`list_for_agent` wrappers — `SchedulerClient`'s native methods are the source of truth: `get(wire)` → `get_schedule(wire)`, `save(schedule, agent)` → `save_schedule(SaveScheduleRequest)`, `list_for_agent(agent)` → `get_all_schedules(workflow_name=agent)`. The module-level `schedules.list/get/save` functions (and their `ScheduleInfo` returns) are unchanged
+- `get_schedule` returns a typed `WorkflowSchedule` (or `None` for missing schedules) instead of a raw camelCase dict, matching its declared annotation and [docs/SCHEDULE.md](docs/SCHEDULE.md); dict-consumers should switch to attribute access or `to_dict()`
+
+### Deprecated
+
+- `AgentScheduleClient`/`ScheduleClient` and `OrkesClients.get_agent_schedule_client()` — fully functional delegation shims over `SchedulerClient`; use `get_scheduler_client()`. Removal planned for the next major release
 
 ### Fixed
 
 - `@worker_task` workers are now picklable, making the decorator path work with the `spawn`/`forkserver` start methods (fixes `TypeError: cannot pickle '_thread.lock' object` and `PicklingError: it's not the same object as ...`; issues #264, #271): `Worker.api_client` is created lazily in the worker process, runtime state (locks, pending async tasks, background loop) is excluded from pickling and rebuilt in the child, and decorated functions are pickled as importable references resolved in the child
 - `TaskHandler.start_processes()` no longer hangs the interpreter when a worker fails to start (e.g., unpicklable state under `spawn`); it now cleans up already-started subprocesses and raises with actionable guidance
 - Worker processes killed by a signal now log a diagnostic hint (signal number, `PYTHONFAULTHANDLER=1` guidance) instead of restarting silently
+- Per-schedule pause/resume now work on both Conductor server families: the client sends `PUT` (the OSS Conductor dialect — the spec-generated `GET` failed there) and transparently falls back to `GET` on a 405 for Orkes servers, caching the working dialect per client instance

docs/SCHEDULE.md

@@ -35,6 +35,31 @@ Operations for controlling schedule execution state.
 | `resume_schedule()` | `PUT /api/scheduler/schedules/{name}/resume` | Resume a specific schedule | [Example](#resume-schedule) |
 | `resume_all_schedules()` | `PUT /api/scheduler/schedules/resume` | Resume all schedules | [Example](#resume-all-schedules) |
 
+> **Verb compatibility:** OSS Conductor maps per-schedule pause/resume as `PUT`;
+> Orkes Conductor servers map them as `GET`. The client sends `PUT` first and
+> transparently falls back to `GET` on a 405, remembering the working dialect for
+> the rest of the client's lifetime — both server families work without configuration.
+> The optional `reason` parameter on `pause_schedule` is stored by OSS servers only.
+
+## Schedule Lifecycle Helpers
+
+Beyond the endpoint methods above, `SchedulerClient` carries higher-level lifecycle
+operations (shared with the agents layer). They raise typed errors
+(`ScheduleNotFound`, `InvalidCronExpression`, `ScheduleNameConflict` from
+`conductor.client.ai.schedule_errors`) instead of raw `ApiException`.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `pause()` | `(wire_name, reason=None)` | Pause with typed errors |
+| `resume()` | `(wire_name)` | Resume with typed errors |
+| `delete()` | `(wire_name)` | Delete with typed errors |
+| `preview_next()` | `(cron, n=5, start_at=None, end_at=None) -> list[int]` | Next `n` epoch-ms fire times |
+| `run_now()` | `(info: ScheduleInfo) -> str` | Fire the schedule's workflow once, returns execution id |
+| `reconcile()` | `(workflow_name, desired: list[Schedule] \| None)` | Declarative sync: `None` no-op, `[]` purge, `[...]` upsert+prune |
+
+Reads, writes, and lists have no duplicated helper forms — `get_schedule()`,
+`save_schedule()`, and `get_all_schedules()` are the source of truth.
+
 ## Schedule Execution APIs
 
 APIs for managing and querying schedule executions.
@@ -169,6 +194,9 @@ Pause a specific schedule to stop executions.
 ```python
 scheduler_client.pause_schedule("daily_order_processing")
 print("Schedule paused")
+
+# Optionally record why (stored by OSS Conductor servers; ignored by Orkes servers):
+scheduler_client.pause_schedule("daily_order_processing", reason="maintenance window")
 ```
 
 #### Pause All Schedules

docs/agents/advanced.md

@@ -126,14 +126,16 @@ with AgentRuntime() as runtime:
 
 Key methods: `run`/`run_async`, `start`/`start_async`, `deploy`/`deploy_async`,
 `schedule(agent, schedules)`, `get_status`, `respond`, `stop`, `signal`,
-`stream_sse`, and `.schedules` (the `AgentScheduleClient`). Both sync and async forms
-exist. Most users call `runtime.run/start/deploy` instead, which add local-worker
-management on top of this client.
+`stream_sse`, and `.schedules` (the schedule lifecycle — `pause`/`resume`/`delete`/
+`run_now`/`preview_next`/`reconcile`, now carried by `SchedulerClient` itself). Both
+sync and async forms exist. Most users call `runtime.run/start/deploy` instead,
+which add local-worker management on top of this client.
 
 The raw `/agent/*` HTTP transport behind this client is
 `conductor.client.ai.AgentApiClient` — also reachable without the agents layer via
-`OrkesClients.get_agent_client()` (and `get_agent_schedule_client()` for the cron
-lifecycle). `AgentClient` composes that transport and adds the agent-level surface.
+`OrkesClients.get_agent_client()` (and `get_scheduler_client()` for the cron
+lifecycle; `get_agent_schedule_client()` is deprecated). `AgentClient` composes that
+transport and adds the agent-level surface.
 
 ## Structured output
 
@@ -284,10 +286,12 @@ nightly = Schedule(name="nightly", cron="0 0 * * *", timezone="UTC",
 runtime.deploy(agent, schedules=[nightly])     # upsert; [] purges; omit leaves as-is
 
 sc = runtime.schedules_client()                # or runtime.client.schedules
-sc.list_for_agent(agent.name)
-sc.pause("greeter-nightly")
-sc.run_now(sc.get("greeter-nightly"))
+sc.get_all_schedules(workflow_name=agent.name) # list — source-of-truth read
+sc.pause("greeter-nightly", reason="ship freeze")
 print(sc.preview_next("0 0 * * *", n=5))       # next 5 fire times (epoch ms)
+
+from conductor.ai.agents.schedule import schedules
+schedules.run_now("greeter-nightly", runtime=runtime)  # fire once -> execution id
 ```
 
 ## Skills

docs/agents/api-reference.md

@@ -46,7 +46,7 @@ Context manager (sync and async: `with` / `async with`).
 | `signal` | `(execution_id, message) -> None` | Inject persistent context |
 | `shutdown` | `() -> None` | Stop all workers |
 | `client` (property) | `-> AgentClient` | Control-plane client |
-| `schedules_client` | `() -> AgentScheduleClient` | Shared schedule client |
+| `schedules_client` | `() -> SchedulerClient` | Shared schedule client (a deprecated `AgentScheduleClient` shim) |
 
 Async variants exist for status/respond/approve/reject/send/stop/shutdown
 (`*_async`). Module-level wrappers using a singleton runtime: `run`, `run_async`,
@@ -190,21 +190,27 @@ start_at=None, end_at=None, description=None)` — `cron` is a 5- or 6-field exp
 `ScheduleInfo` (read model) fields include `name`, `short_name`, `agent`, `cron`,
 `timezone`, `input`, `paused`, `catchup`, `next_run`, `create_time`, `update_time`, ...
 
-`AgentScheduleClient` (alias `ScheduleClient`; canonical home
-`conductor.client.ai` — via `runtime.schedules_client()`, `runtime.client.schedules`,
-or `OrkesClients.get_agent_schedule_client()`):
+The schedule lifecycle lives on `SchedulerClient` itself (via
+`runtime.schedules_client()`, `runtime.client.schedules`, or
+`OrkesClients.get_scheduler_client()`):
 
 | Method | Signature |
 |---|---|
-| `save` | `(schedule: Schedule, agent_name) -> None` |
-| `get` | `(wire_name, agent_name=None) -> ScheduleInfo` |
-| `list_for_agent` | `(agent_name) -> list[ScheduleInfo]` |
 | `pause` / `resume` | `(wire_name[, reason])` / `(wire_name)` |
 | `delete` | `(wire_name) -> None` |
 | `run_now` | `(info: ScheduleInfo) -> str` (execution_id) |
 | `preview_next` | `(cron, n=5, start_at=None, end_at=None) -> list[int]` |
 | `reconcile` | `(agent_name, desired: list[Schedule] | None) -> None` |
 
+Reads/writes/lists use the native source-of-truth methods: `get_schedule(wire) ->
+WorkflowSchedule | None`, `save_schedule(SaveScheduleRequest)`,
+`get_all_schedules(workflow_name=...) -> list[WorkflowSchedule]`. The mapped
+`ScheduleInfo` view is returned by the module-level `schedules.list/get`.
+
+`AgentScheduleClient` (alias `ScheduleClient`; `conductor.client.ai`) and
+`OrkesClients.get_agent_schedule_client()` are **deprecated** delegation shims,
+kept for backward compatibility and planned for removal in the next major release.
+
 Errors: `ScheduleError`, `ScheduleNameConflict`, `ScheduleNotFound`,
 `InvalidCronExpression`.
 

docs/agents/writing-agents.md

@@ -422,8 +422,9 @@ with AgentRuntime() as runtime:
 
 `schedules=[]` purges all schedules for the agent; omitting `schedules` leaves them
 untouched. The schedule lifecycle client (`runtime.schedules_client()` or
-`runtime.client.schedules`) exposes `save`, `get`, `list_for_agent`, `pause`,
-`resume`, `delete`, `run_now`, `preview_next`, `reconcile`. See
+`runtime.client.schedules`) exposes `pause`, `resume`, `delete`, `run_now`,
+`preview_next`, `reconcile`, plus the native `get_schedule`/`save_schedule`/
+`get_all_schedules` for reads, writes, and lists. See
 [Advanced](advanced.md) and the [API reference](api-reference.md#schedule).
 
 ## Agents from a class