Skip to content

docs(rfc): automatic stale-config session reload at the turn boundary - #15409

Closed
billygerhard wants to merge 1 commit into
kirodotdev:mainfrom
billygerhard:docs/rfc-stale-config-session-reload
Closed

billygerhard wants to merge 1 commit into
kirodotdev:mainfrom
billygerhard:docs/rfc-stale-config-session-reload

Conversation

@billygerhard

@billygerhard billygerhard commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record the design decision that a chat automatically reloads its agent process onto changed config at its next turn, so the implementation in #14810 traces to a decision on main.

A chat's agent process reads its MCP servers, agent spec, mcp.json, ACP backend and MCP gateway stubs once, when it starts. Edits made after that never reach it, and nothing tells the user. The only remedy today is the manual Reload action. #14810 makes that reload automatic at the next turn boundary, which changes a default for every chat, so per docs/request-for-change/README.md the decision has to be on main first.

Why it matters

Without a recorded decision the First Principles lane blocks #14810, which closes #10211. The document also gives maintainers one place to accept or reshape the default (for example, ask for an opt-out setting) before the code lands.

Not a goal

What changed (motivation → approach → change)

Adds docs/request-for-change/rfc-stale-config-session-reload.md (Summary, Motivation, Goals, Non-goals, Design, Migration plan with exit criteria, Backward compatibility, Security considerations, Alternatives considered, Open questions) and its index row plus audit sentence in docs/request-for-change/README.md.

Design in one paragraph: fingerprint a chat's spawn-time config inputs; at the start of its next turn, if the fingerprint is stale and the chat is idle with no sub-agents attached, reload through the Reload action's own path (conversation preserved) and show the existing session_reload notice; otherwise send the turn on the current process, mark the reload pending, and show it on the Reload menu row. Edits kiro-cli 2.21+ already hot-reloads do not trigger a reload. A session_reload MCP tool exposes the same state and lets an agent request a reload (performed at its next turn boundary) through the session-control API and its principal gates.

Status is in-progress because the implementation is live in open PR #14810, matching how other rows in the index record a decision whose implementation is in flight. Merging this PR is the maintainer acceptance of that decision; if maintainers want a different shape, I'll revise the document and #14810 together.

Backwards compatibility

Compatible: documentation only.

Tests

N/A — documentation only. python3 scripts/docs_lint.py passes.

Manual verification

Every symbol the status line and index row cite was checked on aec81410e2: api_chat_slot_reload in src/kiro_crew/dashboard/chat_handlers.py, SESSION_RELOAD_KIND in src/kiro_crew/dashboard/system_notices.py, MCP_HOT_RELOAD_MIN_KIRO_CLI_VERSION in src/kiro_crew/mcp_hot_reload.py, _reset_all_sessions in src/kiro_crew/dashboard/handlers/sessions.py and its three callers (handlers/agents.py, handlers/mcp.py, handlers/computer_use.py), session/set_model in api_chat_slot_model, and no stale_config module under src/kiro_crew/dashboard/.

Related Issues

Refs #10211. Implementation: #14810.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality (N/A, docs only)
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@billygerhard
billygerhard requested a review from a team as a code owner September 30, 2026 13:07
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 30, 2026
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — 🟡 CONCERNS

Design-level review of 59ada50a8e6ed8c56473f1edaaf67f2174e23c66 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

One exit criterion commits to withholding a user's message via a "post-spawn re-read" mechanism the Design section never defines and §2a appears to forbid.

Watch

The migration-plan criterion "A turn not run because a post-spawn re-read found an unapproved edit writes a notice that names the message as not processed" is the only place the document allows a turn to not run; §2a states "The check never fails a turn on its own account," and the pre-teardown/post-spawn re-reads appear only in a passing Security-considerations sentence ("stay as defence in depth for that press") with no definition of when they run, what an "unapproved edit" is, or why dropping the message is the right outcome. Merging this PR is, per the description, maintainer acceptance — so #14810 would trace a message-dropping behavior to a decision that was never actually specified.
Clears when: the Design section defines the pre-teardown and post-spawn re-read (trigger, scope, outcome for the queued message) and reconciles it with §2a's no-failed-turn posture, or the exit criterion is removed.

[DESIGN-REVIEWED] 59ada50

Description read

[DESCRIPTION-READ] 88fed535558096d27dedb7c2606a20704ec8519257407e22af37762b4d12ffc1

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 Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed 59ada50a8e6ed8c56473f1edaaf67f2174e23c66 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 59ada50

@billygerhard
billygerhard force-pushed the docs/rfc-stale-config-session-reload branch from dd7d3b7 to 8e304b1 Compare September 30, 2026 13:22
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed 59ada50a8e6ed8c56473f1edaaf67f2174e23c66 via the fork AI-review pipeline; updated in place on each push.

Review details

Two added doc claims contradict the code: the RFC's security analysis says the OS sandbox does not deny paths sandbox.py seals read-only, and a Phase 1 exit criterion asserts a turn-refusal the design never defines.

FINDING — docs/request-for-change/rfc-stale-config-session-reload.md:355 — "the OS sandbox does not deny these paths" (and at :364, crew config.json / config.local.json carry "the same file-edit-gate-only enforcement") is false for three of the four inputs: ~/.kiro/agents is sealed read-only via _resolved_kiro_agents_targets() into readonly_dirs (sandbox.py:8193), and config.json / config.local.json are in _CREW_READONLY_LEAVES (sandbox.py:625-626, whose own comment says is_sensitive_write_path fences only the file-edit tool "so only a kernel denial holds"), so the concluding "An agent that can run an auto-approved shell command can write these files" holds only unsandboxed → Fix: keep the file-edit-gate-only claim for ~/.kiro/settings/mcp.json alone (the one path with no sandbox entry), and say the other three are additionally sealed read-only by the OS sandbox in every sandboxed mode.

FINDING — docs/request-for-change/rfc-stale-config-session-reload.md:282 — the exit criterion "A turn not run because a post-spawn re-read found an unapproved edit writes a notice that names the message as not processed" names a mechanism the Design never defines (post-spawn re-read appears only once more, at :419 as "stay as defence in depth", and unapproved nowhere else) and asserts a turn is not run, which §2a flatly excludes ("The check never fails a turn on its own account", with every enumerated failure mode sending the message on the current process) → Fix: delete the criterion, or add the Design text defining the post-spawn re-read and its refusal condition and reconcile it with §2a.

[OPUS-REVIEWED] 59ada50

@billygerhard
billygerhard force-pushed the docs/rfc-stale-config-session-reload branch from 8e304b1 to 269b82b Compare September 30, 2026 13:39
@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 Sep 30, 2026
@billygerhard
billygerhard force-pushed the docs/rfc-stale-config-session-reload branch from 269b82b to 080b072 Compare September 30, 2026 13:55
@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 Sep 30, 2026
@billygerhard
billygerhard force-pushed the docs/rfc-stale-config-session-reload branch from 080b072 to 8736fa0 Compare September 30, 2026 14:28
@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 Sep 30, 2026
@billygerhard
billygerhard force-pushed the docs/rfc-stale-config-session-reload branch from 8736fa0 to 4a4c098 Compare September 30, 2026 14:44
@billygerhard
billygerhard force-pushed the docs/rfc-stale-config-session-reload branch from 4a4c098 to 7fc9cbd Compare September 30, 2026 15:16
@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 Sep 30, 2026
@billygerhard
billygerhard force-pushed the docs/rfc-stale-config-session-reload branch from 7fc9cbd to c28356b Compare September 30, 2026 15:47
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 30, 2026
@billygerhard
billygerhard force-pushed the docs/rfc-stale-config-session-reload branch from c28356b to 0ea64f7 Compare September 30, 2026 16:20
@billygerhard
billygerhard force-pushed the docs/rfc-stale-config-session-reload branch from 0ea64f7 to df33241 Compare September 30, 2026 17:08
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 30, 2026
@billygerhard
billygerhard force-pushed the docs/rfc-stale-config-session-reload branch 3 times, most recently from 42a3b3f to 2eef70c Compare September 30, 2026 20:33
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 30, 2026
@billygerhard
billygerhard force-pushed the docs/rfc-stale-config-session-reload branch from 2eef70c to cbd3682 Compare September 30, 2026 22:07
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 30, 2026
@billygerhard
billygerhard force-pushed the docs/rfc-stale-config-session-reload branch from cbd3682 to e282184 Compare September 30, 2026 23:45
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 1, 2026
@billygerhard
billygerhard force-pushed the docs/rfc-stale-config-session-reload branch from e282184 to 0614147 Compare October 1, 2026 00:29
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 1, 2026
@billygerhard
billygerhard force-pushed the docs/rfc-stale-config-session-reload branch from 0614147 to d7f279f Compare October 1, 2026 09:52
@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 1, 2026
Record the product-shape decision behind kirodotdev#14810: a chat whose spawn-time config changed reloads its agent process at the start of its next turn, keeping the conversation, only when idle with no sub-agents attached; otherwise the reload waits and the Reload row shows it. Refs kirodotdev#10211.
@billygerhard
billygerhard force-pushed the docs/rfc-stale-config-session-reload branch from d7f279f to 59ada50 Compare October 1, 2026 10:44
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 1, 2026
@billygerhard

Copy link
Copy Markdown
Contributor Author

Closing: the implementation PR #14810 changed scope. It no longer reloads chats automatically; it only shows a stale-config badge and leaves reloading to a manual press, as today. That is a small UI addition with no product-shape change, so this RFC for the automatic-reload design is no longer needed.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Mid-session MCP enable: rebuild a session's toolset and resume

1 participant