feat(templates): materialize a template's declared schedules: at agent creation (trinity-enterprise#89)

[AndriiPasternak31]

Refs trinity-enterprise#89

A template's template.yaml can declare a schedules: block. The abilities
plugin ecosystem treats that block as an agent's design source of truth — but
only /trinity:sync ever reconciled it. Creation via the UI, the API, or MCP
materialized none of it: you created an agent from a template that declared
its own cadence, and it sat there with an empty Schedules tab. This closes that,
for both github: and local: sources, with every declared schedule landing
disabled by default (issue AC — the operator opts in).

Cross-tracker issue — GitHub auto-closes same-repo only, so ent#89 is closed
manually at release (working agreement per #1760). The private issue also
needs status-in-dev set by hand after merge.

The shape

A new tolerant leaf, services/template_schedules.py, is the single reader —
shared by both catalog builders, the creation-time materializer, and the new
compat check, so the report can never drift from what creation actually does.
It is total by contract: a raise would empty the catalog, enter creation's
rollback fence, or fail-open the compat check. Bounds (MAX_DECLARED_SCHEDULES=20,
name/description/message limits), intra-block name dedupe, and strict cron via
schedule_validation.validate_cron_expression — the scheduler's own parser,
not a second regex.

The declared list rides a normalized _TemplateResolution.declared_schedules
carrier, deliberately not folded into template_data. That field is raw YAML
on the local: path and {} on the github: path (which has never populated
it — which is why #383's persistent_state and #1169's data_paths are
effectively local:-only), and its truthiness gates credential-file generation.
Reusing it would have coupled schedules to a field that means two different
things and load-bears a third.

The bit worth reviewing — the github: half needs its own fetch

The catalog's cached metadata is read with the global platform PAT off the
default branch. Materializing from that copy means a creator using a
per-user token against a private repo, or pinning @branch, would have
got zero schedules with no signal — the exact silent-ignore class this
feature exists to close, reintroduced one layer up. So the github: branch does
its own creation-path read: fetch_template_metadata_for_create(repo, pat, ref)
— resolved PAT, parsed @branch ref, cache-bypassed, and loud on any
failure.

Three regressions this change would otherwise have created

• Both GitHub catalog list paths are now fenced per-template. They were bare
  list comprehensions, so one raise in the untrusted GitHub builder 500'd the
  whole GitHub half of GET /api/templates. ent#128 PR-A fenced only the local
  path; adding a second declarative reader to the unfenced one is what made this
  reachable.
• system_service.create_schedules gained a name-match guard. It runs
  after create_agent_internal, so post-ent#89 it is the second schedule
  producer for the same agent — a manifest declaring a name the template already
  materialized would have double-created.
• db.create_schedule's falsy return is now checked. It returns None on
  three paths and never raises, so an unchecked call reports success on failure.

Compat: T-018, and the fail-open class it exposed

T-018 (soft, static) reports the schedules: block's structure only —
cron stays A-002's, because two checks disagreeing on one field is worse than
either. It is the one check that fails closed, and the reason is the bug
class it sits on: run_static converts a raise into skipped and _counts
counts only fail, so a raising soft check drops soft_count 1→0 and — since
overall is a bare > 0 test — flips issues → compatible exactly when its
finding was the only failure. _report_from_persisted then replays that from
checks_json on every stopped-agent read.

Two live instances found and fixed in radius:

• c_p006 (a HARD check) iterated schedules with no isinstance(..., list)
  guard, unlike its four siblings — so schedules: 5 silently vanished from
  hard_count.
• _valid_cron (A-002) was a per-field regex wrong in both directions:
  it rejected 0 9 * * MON and accepted 99 99 * * *. Now delegates to the
  scheduler's own validator.

run_static's swallow now logs (it was silent for all ~100 checks). Converting
it to fail platform-wide is a measured follow-up, not this change.

Validation

• 6,413 unit tests pass (full tests/unit suite, order-independent under
  pytest-randomly). +391 new across three ent#89 files.
• The one deselected failure (test_1069_voip_call_path_param) reproduces
  identically on pristine origin/dev (c4c83f4) — a FastAPI-version drift
  in the local venv, not a regression from this branch.
• Ruff: 4 findings on the touched files, all four byte-identical and
  pre-existing on dev (line numbers shifted only). The new
  template_schedules.py is ruff-clean.
• enterprise-docs-guard pattern run locally against docs/ + the seam files:
  clean.
• No schema change (no dual-track migration owed), no new endpoint, no new
  os.getenv, no compose/Dockerfile change.

Scope

OSS-core — no entitlement gate, consistent with the ent#123 / ent#128 / ent#46→#118
precedent for enterprise-tracker features built in core code.

Docs: requirements §10.16, architecture.md, four feature flows
(template-processing, scheduling, agent-compatibility-validation, system-manifest)

• the index row, docs/agent-validation-spec.md (T-018), learnings.md, and the
  CSO diff audit under docs/security-reports/.

🤖 Generated with Claude Code

[github-actions]

⚠️ Nightly unit-suite check skipped — merge conflict against dev.

Resolve by running git merge dev locally and pushing the result. The next nightly run will re-test once the conflict is gone.

[vybe]

/validate-pr: PASS.

• Base dev ✅ · 23 files ✅ · security scan clean ✅ · no new top-level backend module, no new os.getenv() ✅
• Docs: requirements §10.16 + architecture + 5 feature flows + a CSO diff audit ✅ · 6 test files ✅

The safety design is the right one, and it composes correctly with what just landed:

• enabled defaults to False and only a real bool arms a schedule — enabled: "no" is truthy in Python, so a loose read would arm a schedule its author meant to leave off.
• MAX_DECLARED_SCHEDULES = 20 sits in the reader, not the materializer, so the catalog surface and creation inherit one bound; name/description/message caps close the unbounded-TEXT hole (ScheduleCreate carries no Field constraints).
• _safe_echo is applied to cron/timezone only. Never echoing name/message/description is correct — those are unbounded, prompt-injection-shaped, and this list is persisted into agent_compatibility_results.checks_json and rendered in the UI.
• One private _parse behind both public functions means the reported errors and the accepted entries are structurally unable to disagree.
• The materialize call is wrapped whole — including the helper's own list_agent_schedules read — because it sits inside the destructive rollback fence; a raise there would roll back a successful agent creation over a schedule.

Worth noting the interaction: this makes a template able to mint up to 20 recurring autonomous turns, which is exactly the risk #1949 (just merged) removed by making the autonomy toggle a gate rather than a bulk edit. Landing them together is what keeps declared schedules default-off in practice — before #1949, one unrelated autonomy toggle would have armed all 20.

Conflict resolution (mine), pushed as 4e36d284. Seven conflicts. One was a real semantic conflict rather than an adjacency:

static_checks.py — #1899 flipped the per-check swallow from _skip to _fail so a crashed check is counted by _counts; this branch kept _skip and added logging. Taking this branch's side verbatim would have silently reverted #1899's HARD-count fix, restoring "broken validator reports healthy". Merged instead: _fail from #1899 plus this branch's logger.error(..., exc_info=True), which is strictly more diagnostic than the logger.warning it replaced. The docstring immediately above already asserts "a check that could not evaluate is not a check that passed", so the merged form is what that text describes.

The rest: template_service.py ×3 and crud.py ×1 were adjacent additions (both kept; template_schedules needed its own import statement since the two sides shared a closing paren, and both pre-literal computations were kept at each call site). architecture.md had both sides editing the same three bullets — 3-way merged at word granularity against the merge base rather than picked, no edit pairs overlapped, so both texts survive verbatim. registry.json's conflict opened after a bare { and closed before a bare }, so each side was an object body and a naive concatenation produced invalid JSON; re-added the },{ separator (109 → 112 entries, none dropped).

Verified: zero markers tree-wide, registry parses, all three touched modules compile, and every deletion vs origin/dev is one of this branch's own intended replacements.

⚠️ Cross-tracker: ent#89 needs status-in-dev by hand.