Skip to content

refactor(cron): bind CronService members from cron_service/service - #20862

Merged
bolichen97 merged 1 commit into
mainfrom
refactor/linecap-g10-cron
Oct 16, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
refactor/linecap-g10-cron

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Keep the cron service's code under the repository's 2,000-line file cap without changing how any cron job is scheduled, run, cancelled or stored.

src/kiro_crew/cron.py is 5,594 lines, and the CronService class alone is 5,061. It is one of the files .github/file-line-cap-baseline.txt still lists over the cap, and it changes about 16 times a week, so every cron fix lands in a file nobody can hold in their head and that the next feature PR pushes further past the cap.

Why it matters

Every cron change today edits one 5,600-line file: reviews are slow, conflicts between unrelated cron fixes are common, and the line-cap rule (no hand-written file over 2,000 lines) cannot be met while the class is one block. Splitting it by responsibility gives each part of the service — the reaper and cancel, job writes, removal, the timer, a run, the result merge, the store — a file of its own to change.

Not a goal

  • No behaviour change: no scheduling, run, cancel, reap, merge or store logic changes; crons.json bytes and the schedule math are pinned unchanged.
  • No new feature, API or configuration.
  • Not moving the seven store-lock cores whose log lines carry code-scanning alerts keyed by cron.py's path.
  • Not changing what any existing test asserts.

What changed (motivation → approach → change)

cron.py could not shrink by moving whole definitions, because almost all of it is one class. The class's state is shared by every member, so it stays on the instance; the members move instead.

Each CronService member is now a module-level function in src/kiro_crew/cron_service/service/ whose first parameter is self (cls for create; the three static members take neither), and the class binds it by name (cancel = _run_teardown.cancel). A member is therefore the same function object on the class, on an instance and in its owner, and a patch of it on the class or an instance reaches every caller. Twelve owners each hold one responsibility:

Owner Holds
service_lifecycle.py create, start, stop
run_teardown.py the reaper and cancel
run_kill.py ending a run's processes and sessions
job_writes.py adding and changing jobs
job_removal.py removing jobs
job_ownership.py who owns a job
run_registry.py the runs in flight
wake_timer.py when the scheduler wakes
run_execution.py running one job
run_merge.py landing a run's result
stall_breaker.py the loop-stall breaker
store_sync.py the service's copy of the store

cron.py (now 1,162 lines) keeps every module-level statement, the class's state (__init__), the _claims view, the loop-safety guard, three existing static bindings, and the seven store-lock cores above. It stays a plain module, as test_cron_refactor_contract.py requires, so a moved member reads every name tests patch on kiro_crew.cron, and every name cron.py defines, through the facade on each call (from kiro_crew import cron as seams, then seams.<name>) — the rule the existing cron_service/ owners already follow. The owners sit under cron_service/ because the loop-stall classifier counts a frame there as the cron surface. They sit in a subpackage because the contract pins the seams the flat cron_service/*.py owners read.

Backwards compatibility

Compatible: every name kiro_crew.cron bound before still resolves there as the same object (test_campaign_facades_base_public_names.py, test_cron_refactor_contract.py); CronService keeps all 131 members with the same kind, coroutine-ness and signature, each the same function object on the class and its owner (test_cron_service_bindings.py); a patch on kiro_crew.cron reaches the moved code (corpus-derived check in the same file).

Removes nothing: no column-0 public function, key or record leaves a product file. Every moved member is still an attribute of CronService, and the only names cron.py stops binding are six standard-library and typing imports nothing reads (copy, ExitStack, contextmanager, Collection, Coroutine, Iterator), which are not part of its surface.

Tests

  • New test/test_cron_service_bindings.py pins the binding contract (L33): the frozen inventory of all 131 members (kind, coroutine-ness, signature digest, owner), each class attribute being its owner's function, no unbound self function left in an owner, no zero-argument super() / __class__ / name-mangled attribute in a bound function, no owner importing kiro_crew.cron at import time (call time only, as seams, as the function's first statement), no async def reaching a blocking call through seams (a spelling the sync-io gate cannot see), every name the test trees patch on kiro_crew.cron (literal-loop patches included) read by the owners through the facade (from bytecode), the owners' field docstrings, the kiro_crew.cron logger, and the cron stall surface for each owner. Each scan has a self-test that fails on a planted violation.
  • Source pins re-pointed or joined (assertions unchanged): see the table under "Source pins".
  • Determinism proof for the new test: 5 runs at -n0 and one at -n 3, 262 passed each; it reads no clock, sleeps nowhere and binds no port.

Manual verification

N/A — this is a structural move with no user-visible surface; the behaviour is covered by the cron test suite (234 test files run locally, below) and the move/replumb audits.

Move audit

  • move_audit.py: src/kiro_crew/cron.py: 5594 -> 1162 lines; moved 13.6% (python-ast). The audit compares exact syntax trees, so a member counts as changed once it gains its self: CronService annotation or black re-indents its docstring.
  • Replumb audit (replumb_audit.py, every BASE member against its new home once the allowed transforms are undone): 0 CHANGED. Of 132 units, 42 are identical, 68 differ only in docstring indentation (black re-indented them), 20 are replumbed (51 name -> seams.name reads, 39 distinct member/name pairs, in 21 members, plus one inserted seams import each) and 2 are reworded (the comment-history gate's "no longer": _drain_pending_removals_locked docstring, _run_job_isolated comment, both now present tense).
  • Diff alignment (L36): git's default diff and --minimal add the same lines in every changed file; cron.py +163/−4,595 both.
  • Diff size: 704,443 bytes (the 32,286-byte spec line 482 that restates REAPER_MODULES accounts for about 65 KB).

Source pins

Test Change
A check that read all of cron.py (a universal or negative half) now reads cron.py joined with every cron_service/service owner; a positive pin points at the owner that holds its construct.
Test Change
test_process_identity_structural.py REAPER_MODULES: cron.py + every cron_service/service owner
test/metrics/test_business_counters.py CRON_FIRES owner → run_execution.py; bounded-attrs scan + every owner (_cron_service_modules())
test_session.py the ends_conversation=True row cron.py → cron_service/service/run_kill.py
test_sandbox_interpreter_enoent_retry.py _execute's reader: cron.py + run_execution.py; cancel's reader (_cron_source): cron.py + every owner
test_cron_remove_rows_structural.py the self._jobs writer scan: cron.py + every owner
test_spawn_admission_verdict_census.py the cron posture-gate read points at wake_timer.py
test_remove_slot_for_history_key.py the one-parser check: cron.py + every owner
test_slack_gateway_cron_exec_coverage.py the run-deadline scan: cron.py + every owner, counting a seams.<name>() callee as <name>

Each was proven to reach its construct: 21 mutations, each red with the construct broken in its new home (or a violation planted in an owner outside the construct's home) and green once restored.

CI path references

None: no workflow path filter or explicit file list names cron.py.

Notes for reviewers

Related Issues

Part of #20192

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners October 15, 2026 15:12
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 15, 2026
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision ef2184badaf561cba38b55ab5aad215826098654 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of ef2184badaf561cba38b55ab5aad215826098654 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] ef2184b

Description read

[DESCRIPTION-READ] dab2ded29af615a598aa20b65e8e68e2d9617cd52c19570ff87da74319a86287

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of ef2184badaf561cba38b55ab5aad215826098654 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Check that every future CronService member change can live with the frozen 131-entry signature-digest inventory in test_cron_service_bindings.py.

What this change ships

Inventory (8 items) — 8 justified

Intent: get the cron service under the 2,000-line file cap without changing how any job is scheduled, run, cancelled or stored. ADDITION (structural refactor).

  1. CronService members move out of cron.py (5,594 → 1,162 lines) into twelve cron_service/service/ owner modules, and the class binds each one by name. — justified
  2. The cron.py row is removed from .github/file-line-cap-baseline.txt. — justified
  3. Moved code reads names that tests patch on kiro_crew.cron through seams.<name> on each call, so those patches still reach it. — justified
  4. New test_cron_service_bindings.py: member inventory, binding, facade reach, owner docstring field lists. Same pattern as test_acp_bindings.py, test_client_bindings.py and test_artifacts_bindings.py. — justified
  5. Eight structural tests that read source now read cron.py together with the owners, or the one owner that holds their construct. Their assertions are unchanged. — justified
  6. Specs, RFC prose, the app-dev skill and comments now point at the new owner paths instead of cron.py:<line>. — justified
  7. Six rfc-perpetual-agent.md cron.py:<line> rows drop out of the docs-lint baseline, because those refs no longer exist. — justified
  8. Six stdlib and typing imports that nothing reads are dropped from cron.py. — justified

[FIRST-PRINCIPLES-REVIEWED] ef2184b

Description read

[DESCRIPTION-READ] 740209c9e7506730849bc44a749f0f9780d47696a61e66b234b8504d58499900

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed ef2184badaf561cba38b55ab5aad215826098654 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] ef2184b

Verdict parsed from the review's SHA-scoped output markers for commit ef2184badaf561cba38b55ab5aad215826098654.

False positive or not applicable? A repository writer can comment:
/ai-review override fable ef2184badaf561cba38b55ab5aad215826098654: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of ef2184badaf561cba38b55ab5aad215826098654 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ef2184b

False positive or not applicable? A repository writer can comment:
/ai-review override gpt ef2184badaf561cba38b55ab5aad215826098654: <one-sentence reason>

@bolichen97
bolichen97 enabled auto-merge (squash) October 15, 2026 15:35
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 15, 2026
@bolichen97
bolichen97 force-pushed the refactor/linecap-g10-cron branch from 88b7f8c to 8d7c577 Compare October 15, 2026 16:08
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 15, 2026
Move the behaviour of the 5,061-line CronService class out of the
5,594-line cron.py into twelve owner modules under
kiro_crew/cron_service/service/, one responsibility each: the
lifecycle, the reaper and cancel, ending a run's processes, job
writes, removal, ownership, the runs in flight, the wake timer, a
run's execution, the result merge, the loop-stall breaker, and the
service's copy of the store.

Each member body moves as a module-level function whose first
parameter is self, and the class binds it by name, so every member
stays the same function object on the class, an instance and its
owner, and the service's state stays on the instance. cron.py keeps
every module-level statement, __init__, the _claims view, the
loop-safety guard, the static bindings and the seven store-lock cores
whose log lines carry code-scanning alerts keyed by its path, and it
stays a plain module: a moved member reads every name tests patch on
kiro_crew.cron, and every name cron.py defines, through the facade on
each call, as the existing cron_service owners do.

test/test_cron_service_bindings.py pins the member inventory, the
bindings and that patch reach. Source-reading tests whose construct
moved now read its owner; the spec, the docs and two baseline row sets
follow.

Part of #20192
@bolichen97
bolichen97 force-pushed the refactor/linecap-g10-cron branch from 8d7c577 to ef2184b Compare October 15, 2026 22:10
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main was red on test/test_acp_bindings.py and test_dashboard_server_composition_contract (fixed on main by #20902 and #20930), 6d4f287 -> 7f7c38b; the change itself is unchanged (range-diff "=", main touched none of this PR's files). CI re-running on ef2184b.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 15, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

rebutted

  • The frozen 131-member inventory in test_cron_service_bindings.py

Keeping it is proportional. A member change costs a one-row edit in _MEMBERS, and only when the member's set, kind, coroutine-ness, signature or owner changes. A body edit touches nothing.
The failure names the member and prints its new signature (f"{name}{inspect.signature(fn)} changed signature"), so the row to edit is obvious.
This is the same inventory shape test_acp_bindings.py, test_client_bindings.py and test_artifacts_bindings.py already hold for their bound classes. A new member goes in a new row and its owner's binding block.
What it buys: a bound member that silently changes kind (a lost staticmethod, an async def that turns sync) or moves owner fails here instead of at a caller.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 15, 2026

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed at ef2184badaf561cba38b55ab5aad215826098654 (merge-base 7f7c38b8d3), and on a local merge of this head into current main (818b437153). The merge is clean, including the overlap with #20761, which touched test/test_slack_gateway_cron_exec_coverage.py, test/test_sandbox_interpreter_enoent_retry.py, cron_dispatch.py, cron_history.py and the cron spec.

What I verified independently

No member was dropped or changed. I parsed CronService at the merge-base: 132 class-body entries, counting the _claims getter and setter separately. I resolved each one against the live class at head through CronService.__dict__ and compared ASTs. Before comparing I stripped docstrings, the self: CronService annotation and the function-local from kiro_crew import cron as seams import, and rewrote seams.X back to X.

  • 126 functions are identical after that normalisation; 0 changed; 0 missing.
  • The 6 non-function class attributes are all still present.
  • Kind (static/class/property/plain) and coroutine-ness match for every member.
  • No class attribute was added.
  • dir(kiro_crew.cron) loses only Collection, Coroutine, ExitStack, Iterator and contextmanager. Nothing in src/, test/ or apps/ reads any of them through kiro_crew.cron, on the merged tree. copy is still bound, so the PR body's list of six is one too many, which is harmless.
  • Every module-level def or class in the old cron.py is still defined there.

Name resolution in the moved code. I walked the bytecode of every moved function, nested code objects included:

  • No LOAD_GLOBAL is unresolved in its owner's globals, so there is no latent NameError.
  • All 42 distinct seams.<attr> reads resolve on kiro_crew.cron.
  • The names an owner reads bare and kiro_crew.cron also binds are all the same object in both places (60 names). The ones tests patch there, cron_script, time and random, are patched as module attributes (kiro_crew.cron.cron_script.kill_running_process, kiro_crew.cron.time.time, kiro_crew.cron.random.uniform), so those patches still reach the owners.
  • Importing an owner on its own (wake_timer, run_execution, store_sync, job_removal) does not import kiro_crew.cron, which confirms the cycle is avoided at import time.
  • Owners add no module-level state; each has only logger = logging.getLogger("kiro_crew.cron"), so nothing is duplicated.

Collected test ids. On the 11 pre-existing test files this PR edits, base collects 863 ids and head collects 888. The difference is 25 added ids: the 13 + 12 per-owner parametrisations in test/metrics/test_business_counters.py and test/test_process_identity_structural.py. One id was renamed, CRON_FIRES-cron.py → CRON_FIRES-cron_service/service/run_execution.py. No id was removed. The merged tree collects the same 888.

Patch reach, mutation-checked. I made wake_timer.py:233 read admission_check bare, imported from kiro_crew.resource_status, instead of seams.admission_check. Two tests went red:

  • test/test_cron_service_bindings.py::test_an_owner_reads_every_facade_name_through_the_facade[...wake_timer]
  • 8 behavioural tests in test/test_admission_gate.py, including TestCronExprPassthrough::test_manual_run_completed_during_await_is_not_double_fired

I restored the file and confirmed git status was clean. So the new guard and the existing behaviour tests each catch a patch that no longer reaches the code, independently of each other.

Cron security paths.

  • _vet_script_contents lives in src/kiro_crew/mcp_cron.py:1465, which this PR does not touch.
  • The secret-grant kill on removal (job_removal.py:295-320, bump_grant_epoch / grant_epoch_ids) is in the identical set above.
  • So are the expect_secret_env* compare-and-set checks in update_job (now job_writes.py) and the timeout and deadline paths (run_execution.py _execute_with_timeout, run_teardown.py _reaper_loop).
  • The six alert-keyed store-lock cores (_update_job_locked, _enable_job_locked, _remove_job_locked, _remove_job_if_locked, _delete_history_of, _audit_requested_removal) plus audit_one_shot_removal and _guard_off_event_loop stay in the class in cron.py, as described.

Spec. docs/system-specs/modules/learn-cron-dashboard.md now carries the owner table (around lines 325-344). I found no spec or RFC line that still places a moved member's body in cron.py. _sleep_out_jitter (spec line 630) is still defined in cron.py:415. The cron.py:114 / :193 references in rfc-perpetual-agent.md:999-1001 are explicitly pinned to commit 30f5d6983.

CI. On this head the latest run of each check is 88 success and 11 skipped, with no failures. There are no prior human reviews; the bot lanes report no blocking findings.

Blocking

None.

Follow-ups (non-blocking)

  • test/test_slack_gateway_cron_exec_coverage.py grows from 2,334 to 2,352 lines here, and is 2,367 after merging with main. Its baseline row is 2,303. scripts/check_file_line_cap.py only reports this ("a baselined file must not grow"); it does not fail the check. The file was already over its row on main (2,349), but this PR adds to it.
  • PR body: copy is listed as dropped from kiro_crew.cron, but it is still bound there.
  • docs/request-for-change/rfc-tips-kit.md:163 cites cron.py::CronService.create(...). That still resolves as a class attribute, but the body is now in cron_service/service/service_lifecycle.py.

What I ran / did not run

Ran on the merged tree:

  • The 11 edited test files plus test_cron_service_bindings.py, test_cron_refactor_contract.py, test_campaign_facades_base_public_names.py, test_cron_reaper_ephemeral.py, test_runtime_death_is_a_process_event.py, test_gateway_cron_exec.py, test_gateway_cron_turn.py and test_slack_gateway_composition_contract.py: 1,615 passed.
  • test/test_cron*.py plus test/test_mcp_cron*.py: 3,723 passed, 1 skipped.

Not run: the full suite, mypy and semgrep. I relied on CI for those. I did not re-run the PR's own replumb audit script; the AST comparison above is my own, done independently.

@bolichen97
bolichen97 merged commit 8954c72 into main Oct 16, 2026
103 checks passed
@bolichen97
bolichen97 deleted the refactor/linecap-g10-cron branch October 16, 2026 00:30
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants