Skip to content

feat(cron): optional per-job project directory for agent crons - #29564

Merged
buluoray merged 1 commit into
mainfrom
fix/cron-project-path-13349
Nov 4, 2026
Merged

buluoray merged 1 commit into
mainfrom
fix/cron-project-path-13349

Conversation

@buluoray

@buluoray buluoray commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A scheduled agent job can run in a chosen project directory, so that repo's own steering rules and AGENTS.md load for the job.

An LLM-message cron has no per-job project directory. Its session runs in the bound agent's workspace, or in a per-run scratch directory (workspace_root()/cron_<job_id>_<run_id>/) when no agent alias is bound. Neither is the repo the job works on, so the repo's .kiro/steering/**/*.md never loads. The reporter's maintenance cron committed straight to the shared checkout because the repo's "worktree + PR" rule never reached it (#13349). The triage comment on the issue confirmed the gap is the session cwd.

Why it matters

A cron that does real repo work (opens a PR, builds, deploys) silently loses every policy the repo keeps in its steering files. The only workaround today is to copy the policy into the cron message, where it goes stale as the repo's rules change.

Not a goal

What changed (motivation → approach → change)

Symptom: repo steering never loads in a cron. Cause: the cron session's cwd is never the repo. Change: an optional per-job project_path that becomes the session cwd.

  • CronJob.project_path (default ""). The store reads a missing key as "" and writes the key only when it is set, so an existing crons.json keeps its bytes and an older build round-trips the key as an unknown field.
  • cron_service/fields.py:
    • resolve_project_path delegates to the chat folder's _validate_project_dir (absolute or ~, realpath, not is_sensitive_path, an existing directory), so there is one fence. It only adds a UNC refusal on the raw and resolved path. The resolved path is stored. build_job and apply_job_update run it before any assignment. A script or command job is refused, because it opens no agent session.
    • cron_session_cwd(job, resolved_cwd) is the one place that picks the cwd. An empty project_path returns the cwd _resolve_cron_agent chose, so nothing changes. A set one outranks the alias workspace: it is the per-job choice. It re-checks the path at every fire, off the loop. A directory that is gone or now sensitive fails the run with a non-transient error that names the --project-path '' fix. It never falls back to a cwd without the project's rules.
  • cron_turn.py: both dispatch paths call it right after _resolve_cron_agent (single agent, and each agent_sequence step). The agent, crew identity, model pins and capability gates still come from the alias.
  • CLI: kirocrew cron add --project-path DIR, kirocrew cron update JOB --project-path DIR ('' clears), and kirocrew cron list prints project: <dir>. The kwarg rides in the add_job call only when set, so other creates keep their call shape.
  • Spec: new learn-cron-dashboard.md § "Project Directory (project_path)". Also updated cli.md and the kirocrew-commands skill.

The field name follows the consolidation note on #13408: project_path is the one field. #9201's takeover (#8952) can build on it.

Backwards compatibility

Compatible: the field is optional with default "", and an empty value takes the exact cwd path it took before. A record without the key loads and fires unchanged (test_a_record_written_before_the_field_loads_unchanged). A store with no project directories saves to the same bytes (the test_cron_refactor_contract.py golden-bytes tests pass unchanged).

Removes nothing: the change only adds an optional field, two CLI flags and a list detail. No existing key, validator or path is narrowed.

Tests

  • test/test_cron_project_path.py:
    • a pre-change record (no key) loads with "" and keeps the resolved cwd;
    • store round trip;
    • the stored path is resolved;
    • refusals: relative, UNC, missing (a tmp_path child), sensitive, script/command job;
    • an update that sets, refuses (job untouched) and clears;
    • a fire dispatches cwd=<project> while the agent and crew_agent still come from the alias;
    • a fire without the field keeps the alias workspace;
    • a gone directory fails the run before any session is created, and the error is non-transient;
    • CLI add, list and update.
  • test/test_cron_sequence_member_alias.py::test_a_sequence_with_a_project_path_runs_every_step_there: each sequence step runs in the project directory as its own crew.
  • test_cron_service_bindings.py: the pinned signature digests for _build_job, add_job and add_job_async were updated for the new keyword. test_cron_string_field_validation.py: project_path is listed as a field with no CRON_ADD_SCHEMA entry.

Proof: PROVEN by hand-applied mutations on the committed head, each restored by path:

Mutation Reddens
drop the single-agent cron_session_cwd call test_a_fire_runs_the_session_in_the_project_directory, test_a_project_directory_that_is_gone_fails_the_run
drop the sequence-step call test_a_sequence_with_a_project_path_runs_every_step_there
store reader drops the key test_project_path_round_trips_through_the_store, test_cli_add_and_update_carry_project_path
fire-time refusal falls back to the old cwd test_a_project_directory_that_is_gone_fails_the_run, test_the_fire_time_refusal_is_not_transient
no sensitive-path check test_a_sensitive_directory_is_refused
script/command job accepts it test_script_and_command_jobs_refuse_a_project_path

Targeted runs (by path, -n0): the cron, CLI-cron and gateway-cron test files, 517 + 166 passed. The full suite was not run locally.

Manual verification

Not run on a live gateway or pod. The dispatch tests drive the real _cron_callback through _cron_run_single / _cron_run_sequence with a mocked session manager and assert the cwd kwarg it receives. That kiro-cli then loads .kiro/steering/ from the session cwd is existing, documented behaviour (src/kiro_crew/docs/steering-and-hooks.md), not something this PR changes. Windows: the UNC refusal reuses is_unc_shape. Nothing was run on a Windows host, so Windows behaviour is unverified.

Related Issues

Closes #13349
Refs #9201 #8952

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

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners November 4, 2026 10:31
@buluoray
buluoray requested a review from mbriones98 November 4, 2026 10:31
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 4, 2026
@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of ae1da87714344ab40f07102a0605cbfe9ab2c8b1 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the optional field is additive, it reuses the chat folder's project-directory check, and a directory that can't be used fails the run instead of quietly running somewhere else.

Notes

[DESIGN-REVIEWED] ae1da87

Description read

[DESCRIPTION-READ] e23d219ebe50b23f9e3d2e579e15127661adcd3f074037903a6e0665bb70e3ec

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 Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of ae1da87714344ab40f07102a0605cbfe9ab2c8b1 — 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 does not.

First-Principles-Verdict: PASS

Nothing blocks: the new field is optional and off by default, path checking reuses the existing chat-folder _validate_project_dir, and the fix lands at the cause (the cron session's working directory is never the repo).

What this change ships

Inventory (7 items) — 7 justified

Intent: let a scheduled agent job run inside a chosen repo so that repo's steering rules and AGENTS.md load (ADDITION).

  1. An agent cron can name a project directory, and its session runs there — justified
  2. kirocrew cron add --project-path DIR — justified
  3. kirocrew cron update JOB --project-path DIR, where '' clears it — justified
  4. kirocrew cron list shows project: <dir> — justified
  5. A project directory that is gone or now sensitive fails the run (non-transient) instead of falling back — justified
  6. Script and command jobs refuse a project directory — justified
  7. In an agent_sequence, every step runs in the project directory — justified

[FIRST-PRINCIPLES-REVIEWED] ae1da87

Description read

[DESCRIPTION-READ] 40070ad8545591d13b383c8ba1112284949e9cf468a2db0dac74d055aa9c5b37

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 Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] ae1da87

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable ae1da87714344ab40f07102a0605cbfe9ab2c8b1 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ae1da87

False positive or not applicable? A repository writer can comment:
/ai-review override gpt ae1da87714344ab40f07102a0605cbfe9ab2c8b1 false-positive: <reason, 20 to 500 characters>

@buluoray
buluoray force-pushed the fix/cron-project-path-13349 branch from 5c36860 to 27b98c0 Compare November 4, 2026 10:53
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 4, 2026
@buluoray
buluoray force-pushed the fix/cron-project-path-13349 branch from 27b98c0 to bbc6e43 Compare November 4, 2026 11:51
@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 readiness: checking Automated validation is still running labels Nov 4, 2026
@buluoray
buluoray force-pushed the fix/cron-project-path-13349 branch from bbc6e43 to dda7c3b Compare November 4, 2026 12:25
@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 readiness: checking Automated validation is still running labels Nov 4, 2026
An agent cron's session ran in the bound agent's workspace or a per-run
scratch directory, so a repo's own .kiro/steering/ and AGENTS.md never
loaded for a cron doing repo work (#13349).

A job may now carry `project_path`: when set, its agent session runs in
that directory on every fire (it outranks the agent alias's workspace;
every step of an agent_sequence uses it). When empty, nothing changes.

- CronJob.project_path, default "". A record without the key loads as ""
  and fires unchanged; the key is written only when set, so existing
  stores keep their bytes.
- resolve_project_path: absolute existing directory, not UNC-shaped, not
  is_sensitive_path after realpath; stored resolved. Refused on script and
  command jobs. Re-checked at every fire: a directory that can no longer
  be used fails the run (non-transient) instead of running without the
  project's rules.
- CLI: `cron add --project-path DIR`, `cron update --project-path DIR`
  ('' clears), `cron list` prints it. MCP and the dashboard form do not
  take it yet.
- Spec: learn-cron-dashboard.md "Project Directory (project_path)",
  cli.md, kirocrew-commands skill.

Closes #13349
Refs #9201 #8952
@buluoray
buluoray force-pushed the fix/cron-project-path-13349 branch from dda7c3b to ae1da87 Compare November 4, 2026 13:24
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 4, 2026
@buluoray
buluoray enabled auto-merge (squash) November 4, 2026 14:20

@bolichen97 bolichen97 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.

Approving ae1da87. I read the full product diff and the test list at this head.

  • resolve_project_path reuses the chat folder's _validate_project_dir (absolute or ~, realpath, not a sensitive path, an existing directory) and adds a network-share refusal before and after resolving. So a cron job cannot root itself anywhere a dashboard project could not.
  • The path is checked on create, on update (before any field is assigned, so a refusal leaves the job untouched) and again at every fire. A fire-time refusal is marked not transient, so it counts as a failure instead of retrying.
  • Script and command jobs refuse the field.
  • The store writes project_path only when it is set, so an existing crons.json keeps its bytes, and _KNOWN_JOB_KEYS lists it.
  • Both the single-agent and sequence paths pick the cwd through cron_session_cwd, off the event loop.
  • Tests cover the round trip, refusals, update and clear, the fire cwd, the unchanged default, a removed directory, and the CLI flags.

Non-blocking note: a live session under cron:<job id> is reused without comparing cwd. So if project_path changes while a run is still held open by pending sub-agents, that next fire runs in the old directory. Sessions are normally reset after each run, so the window is small. It could share the existing agent-mismatch defer later.

No regex, glob or case-blind matching is added. The linked issue is T2. All 96 checks pass.

@buluoray
buluoray merged commit f60aad8 into main Nov 4, 2026
97 checks passed
@buluoray
buluoray deleted the fix/cron-project-path-13349 branch November 4, 2026 18:17
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 4, 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.

cron: no per-job project directory, so LLM crons never load project-scoped .kiro/steering/

2 participants