Skip to content

docs: say a script cron starts its own copy of a stubbed server - #33716

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/32996-script-cron-stub-docs
Nov 11, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/32996-script-cron-stub-docs

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A user who stubs and shares an MCP server learns from the docs that a script cron still starts its own copy of that server on every run, and what to do instead.

The recipe "A server that signs in again and again" in configuration.md says every chat, worker and helper reaches one shared backend once the server is stubbed and shared. A script cron is not covered: each run's ctx.call_tool starts its own copy of the server and stops it when the run ends. Neither doc says so, so a user who followed the recipe expects the cron to sign in once and instead sees a sign-in on every run.

Why it matters

A server that keeps its sign-in only in memory signs in again on every script cron run. A job that runs once a minute signs in 60 times an hour, and a service that throttles sign-ins starts answering HTTP 429. Today the docs give the user no way to learn that the recipe does not cover this case, or which workaround to use.

Not a goal

  • Routing a script cron's ctx.call_tool to the shared backend through the MCP gateway. That would run the server outside the script's sandbox, which cron-and-scheduling.md promises it runs inside on Linux and macOS, so it waits until shared gateway backends are sandboxed at least as tightly as a script (the hardening mcp_gateway/backend.py tracks as Phase 2).
  • Any code, spec or security-model change: the behaviour stays as it is.

What changed (motivation → approach → change)

The docs now tell a user that the stub recipe does not reach script crons, before they find out from a run of sign-ins.

The cron docs' call_tool paragraph says a run's servers stop when the run ends, a stubbed and shared server included, so a server that keeps its sign-in only in memory signs in again on every run. It lists the three ways around that: make all of its calls in one run, run the job less often, or use an agent cron, which spends a model turn on each run. The recipe in configuration.md gains one sentence saying a script cron is not covered, with a link to that section.

Backwards compatibility

Compatible: documentation only; no code, config key or behaviour changes.
Removes nothing: two statements are added and no existing text is taken away.

Tests

N/A — docs only. The statements were checked against the code on the base: cron_script_mcp.py starts each server from the agent spec in ~/.kiro/agents/, not from the broker-stub overlay the gateway hands to chat sessions, and its close() stops every kept server when the run ends. ./scripts/docs-lint.sh passes and checks that both link targets exist; it does not check anchors in this tree, so both anchors were checked by hand against their headings.

Manual verification

N/A — no runtime behaviour changes. Both paragraphs were read through as rendered Markdown, and both links land on their headings.

Screenshots / video

N/A — no frontend change.

Related Issues

Part of #32996

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

@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 1f1c4c2aa78cd2412ed4061c5d34e8392e0f2085 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 9, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 1f1c4c2aa78cd2412ed4061c5d34e8392e0f2085 — 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: this is a docs-only change, and both sentences tell users about a gap that already exists in the code.

What this change ships

Inventory (2 items) — 2 justified

Intent: a user who stubs and shares an MCP server learns that a script cron still starts its own copy of it on every run, and what to do about that. This is an ADDITION (documentation).

  1. The cron docs now say each run's servers stop when the run ends, a stubbed and shared one included, and list three workarounds — justified
  2. The stub recipe in configuration.md now says script crons are not covered, with a link to the cron section — justified

[FIRST-PRINCIPLES-REVIEWED] 1f1c4c2

Description read

[DESCRIPTION-READ] 7b5601cc18a73223fcdbb5cfacd16d50ebb4d6b5d3fce215bd796c9915632e36

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 9, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

This is a docs-only change. Both anchors resolve, and the claim that a script cron starts its own servers matches cron_script_mcp.py, which reads its specs from kiro_agents_dir() and stops them in close().

[DESIGN-REVIEWED] 1f1c4c2

Description read

[DESCRIPTION-READ] 25f727be8d9af36a74140c0395754d0ddf1226ead9ef958ca75b6f4a9e09518f

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 9, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 1f1c4c2

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

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

@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 1f1c4c2

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

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 9, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) November 9, 2026 05:48
buluoray
buluoray previously approved these changes Nov 9, 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.

Approving. Docs only: a script cron's ctx.call_tool starts its own copy of a stubbed, shared MCP server and stops it at run end, and the docs list the workarounds (src/kiro_crew/docs/cron-and-scheduling.md:150, configuration.md:812). Every claim matches source (cron_script_mcp.py:388-414, 348-357; config/integration_sections.py:471-479), and both links resolve.

@bolichen97
bolichen97 force-pushed the fix/32996-script-cron-stub-docs branch from e1642ce to 8d3970f Compare November 9, 2026 23:11
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in src/kiro_crew/docs/configuration.md, src/kiro_crew/docs/cron-and-scheduling.md since this head went green (2caa69b -> fd5d9ef); CI re-running.

The red Static Ratchet Gate on the old head was main's: test/test_pid_reader_ratchet.py::test_owner_marked_sites_match_the_recorded_count failed on the old merge base and is fixed on main by #33695, which this base carries. The other reds were network timeouts (HTTP 504) and the gates waiting on them. The diff is unchanged.

[operator: bolichen97]

@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 Nov 10, 2026
@bolichen97 bolichen97 closed this Nov 10, 2026
auto-merge was automatically disabled November 10, 2026 17:32

Pull request was closed

@bolichen97 bolichen97 reopened this Nov 10, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Closed and reopened with no code change: PR Readiness was waiting on a Code Review run that records its base (the #33337 rule), and only a new pull request event starts one. The close turned auto-merge off; it is re-armed once this re-run is green.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Nov 10, 2026
The recipe for a server that signs in again and again says every chat,
worker and helper reaches one shared backend once the server is stubbed
and shared. A script cron is not one of them: each run starts its own
copy of the server and stops it when the run ends, so a server that
keeps its sign-in only in memory signs in again on every run. Say so in
the cron docs, with the workarounds, and point the recipe at it.

Part of #32996
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in src/kiro_crew/docs/configuration.md, src/kiro_crew/docs/cron-and-scheduling.md since this head went green (fd5d9ef -> 478d13a); CI re-running.

GitHub reported this PR as conflicting: #33905 rewrote the credential-scan sentences of the same call_tool paragraph in cron-and-scheduling.md. The resolution keeps main's wording and puts this PR's sentences back where they were, right after "kirocrew cron preview uses the same lifecycle."; the diff is otherwise unchanged (+4/-1, the same two files).

The red Backend Tests shard on the old head, test/test_session_markdown.py::test_a_condition_one_opener_is_closed_as_the_parser_reads_it[long-s], was main's: markdown-it-py 4.3.0 broke it, and #34646 pinned it below 4.3 on main after the old head's run. The new base carries that fix. The CodeQL red on the old head was the CI token hitting the API rate limit.

[operator: bolichen97]

@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 11, 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.

Approve on 1f1c4c2. Rebase only since the earlier APPROVE at 8d3970f: the PR's added sentences are byte-identical, only main's surrounding call_tool paragraph changed; every claim still matches source and both anchors resolve. Decisive lines: src/kiro_crew/docs/cron-and-scheduling.md:150, src/kiro_crew/docs/configuration.md:824-825, src/kiro_crew/cron_script_mcp.py:404-411, src/kiro_crew/cron_script_mcp.py:363, src/kiro_crew/cron_script.py:301-302

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 11, 2026
@KiroCrewCaptain
KiroCrewCaptain merged commit f4369b0 into main Nov 11, 2026
103 of 105 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/32996-script-cron-stub-docs branch November 11, 2026 14:11

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approving. On this head the review checked the new text against the code. A script cron's call_tool starts each MCP server from Crew's own agent spec through KeptMcpServers, not from the gateway stub overlay. CronContext.close stops those servers when the run ends, and preview does the same. Both new anchors (#script-and-command-crons and #a-server-that-signs-in-again-and-again) resolve to real headings. A test merge with main is clean, and no doc under docs/decisions conflicts with the change.

Done well: the PR fixes an overclaim in the sign-in recipe instead of adding a mechanism. It names three concrete workarounds and keeps the promise that the server runs inside the script's sandbox, which matches the maintainer decision on #32996.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants