Skip to content

docs(rfc): hybrid local/remote execution, three open decisions - #21613

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
koenvincent:docs/rfc-hybrid-remote-execution
Oct 28, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
koenvincent:docs/rfc-hybrid-remote-execution

Conversation

@koenvincent

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Give maintainers three small, decidable rulings on hybrid local/remote execution so that #3278 can be unparked and the remaining work can proceed in phases.

#3278 is parked (tier:T4). The 2026-09-25 triage lists three things that still need a maintainer ruling: routing heavy work out of a local session, remote-authoritative memory, and falling back to local. The 2026-10-08 comment says new concepts go through docs/request-for-change/. Meanwhile, pieces of the original request have landed or are in review (Chat on a crew, the crew window, Send a copy to, the remote subagent executor #12821, fetch-back #19440, folder send #19859, file hand-off RFC #19460), so the open question is now narrow.

Why it matters

Without a written ruling, each of those PRs is reviewed against an unstated design, and the memory question in particular (docs/system-specs/modules/instances.md §14.3 says memory does not travel) blocks everything that would route work to another host. A decision record lets #12821 and the follow-ups proceed against the same position.

Not a goal

What changed (motivation → approach → change)

Goal → the RFC scopes #3278 to exactly the three open rulings, each a numbered decision with options and a recommendation, and lists what is already on main or open (verified at 2d926d926, definitions and callers) so nothing is redesigned. It orders delivery so phase 1 is #12821 as it stands, which means accepting the RFC does not block that PR.

Decision Recommendation
1. How work leaves a local session Explicit placement now; an operator-set overflow policy later as opt-in; no automatic heuristics by default
2. Whose memory remote work uses The crew's own, made explicit; an explicit per-task brief later if asked for; crew-authoritative memory is not proposed here
3. When the crew is unreachable Refuse with a typed error; later an explicit per-call local retry for placements that never started; never a silent fallback

Changes:

  • docs/request-for-change/rfc-hybrid-remote-execution.md (new, status draft).
  • docs/request-for-change/README.md: one index row with an honest "what is actually on main" cell, and the audit sentence extended the way earlier additions did.

The RFC ships as draft, so it records a proposal, not a decision. Per the index's own rule, no product-shape change may cite it until a maintainer records acceptance.

Backwards compatibility

Removes nothing: documentation only, no default, API, config key or behaviour changes.

Tests

No code. ./scripts/docs-lint.sh and ./scripts/docs-lint.sh --test both pass; every rfc-*.md in the directory still has an index row.

Manual verification

Every "on main" claim was checked with git grep in a worktree at 2d926d926; PR and issue states were read with gh pr view / gh api on 2026-10-17. Not verifiable from the repository: whether kiro-cli acp can attach a cloud session, and the live merge state of the open PRs after that date.

Screenshots / video

N/A — documentation only, no user-visible frontend surface.

Related Issues

Part of #3278
Related: #12821, #19440, #19859, #19460, #13031, #19092, #21546, #21547, #10035, #12942

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

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@koenvincent
koenvincent requested review from a team and KiroCrewCaptain as code owners October 17, 2026 13:28
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) 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 Oct 17, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

Thanks for writing this up. The RFC index has changed on main since you branched, so the branch conflicts. Could you rebase onto current main and re-add your index row?

@koenvincent
koenvincent force-pushed the docs/rfc-hybrid-remote-execution branch from ca0f16d to 60b5ef9 Compare October 17, 2026 18:40
@koenvincent

Copy link
Copy Markdown
Contributor Author

Thanks. Rebased onto current main (4be3332429); the new head is 60b5ef982a.

  • Kept main's index as is (including the new rfc-crewmate-share row and the extended audit paragraph), then re-added our two pieces: the rfc-hybrid-remote-execution table row after rfc-fold-recorded-edit-cards, and one sentence at the end of the audit paragraph.
  • Re-checked the row's "on main" claims at 4be3332429 (none of the paths it cites changed since 2d926d926), so the row now says verified at 4be3332429. The RFC document's own audited-at stays at 2d926d926, since I did not re-read every claim in it.
  • Against main the diff is the RFC file plus those two README additions. scripts/docs-lint.sh passes.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 17, 2026

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

Thanks for the rebase. The branch is now one commit on 4be3332429, and GitHub reports it as mergeable.

Head reviewed: 60b5ef982a. This is a design document for a T4 issue, so it needs a design sign-off from a maintainer. This review is a comment only.

What I checked against main:

  • Every "on main" claim in section 2 and in the index row that I sampled holds: UNREACHABLE_CODES and <fieldset disabled={!connected}> in CrewChatWindow.tsx, proxy_peer_not_connected in ssh_tunnel_manager_peer.py, compute_max_subagents returning agent.subagent_auto_max, instances.md section 14.3, api_instances_send_session and its route, createRemoteChatMutation in create.ts and its call in SidebarHeader.tsx, the 0.9.0 changelog entry, redact_peer_text on peer text, and no remote_subagents.py on main.
  • scripts/docs-lint.sh and scripts/docs-lint.sh --test pass on this head.
  • The diff matches the description: one new RFC file and two additions to the index.

The AI review lanes have not run on this head. Five fork workflows wait for maintainer approval, so PR Readiness fails for that reason only.

Two small points are inline. Neither blocks the design discussion.

| One Sessions list across crews, grouped per machine | On main, same preview | `useRemoteCrewChat` in `website/src/hooks/usePreviewFlag.ts`, called from `sessionSources.ts`; `read_peer_slots` in `src/kiro_crew/dashboard/handlers_instances.py` |
| Send a copy of a session to a crew | On main | `api_instances_send_session` in `handlers_instances.py`, route in `dashboard/routes/connections.py`; `docs/system-specs/modules/instances.md` §14 |
| The older turn relay and "bound local slot" model | Gone: `rfc-remote-crew-sidebar` wave 4 ([#17642](https://github.com/kirodotdev/KiroCrew/pull/17642), [#17662](https://github.com/kirodotdev/KiroCrew/pull/17662)). `remote_already_bound` and `remote_not_connected` have no hit under `src/` | `git grep` at the sha above. The 2026-09-25 triage cites both codes at an earlier sha; they no longer apply |
| Remote subagent executor: `spawn_run(executor="remote")` | **Open**, [#12821](https://github.com/kirodotdev/KiroCrew/pull/12821). Not on main: `instances.remote_subagents`, `remote_spawn` and `spawn_enforces` have no hit; `src/kiro_crew/dashboard/remote_subagents.py` does not exist. Reviewer `cruisercohen` re-reviewed head `026161ec5` on 2026-10-16 and found every point from his previous review met. A `CHANGES_REQUESTED` review of 2026-09-25 by `bolichen97` is still recorded, and the PR carries a merge conflict | `gh pr view 12821` on 2026-10-17 |

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.

🟡 The #12821 row records review state that will be stale soon.

The row names who re-reviewed which head, which review is still recorded, and that the PR has a merge conflict. These facts change with each push or review on #12821. This document stays in the index as the decision record, so a reader later sees a wrong state and has no date beside it except the gh pr view cell.

... re-reviewed head `026161ec5` on 2026-10-16 ... A `CHANGES_REQUESTED` review of 2026-09-25 ... is still recorded, and the PR carries a merge conflict

Why it matters: the RFC is the durable record. Review state belongs on the PR, where it stays current.

Suggestion: keep "Open" and the "Not on main" evidence, and remove the review-state sentences. If you want to keep them, start them with "As of 2026-10-17".

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Agreed, fixed in 927d68ba09. The row keeps "Open" and the not-on-main evidence (now cited as git grep at the audited sha) and says its review state lives on the PR. The reviewer, head and conflict sentences are gone.


| Phase | What | Depends on | Exit criteria |
|---|---|---|---|
| 1 | [#12821](https://github.com/kirodotdev/KiroCrew/pull/12821) as it stands: explicit remote placement, refuse when no crew is connected | Nothing in this RFC. It implements Decision 1 A, Decision 2 A and Decision 3 A as written | Merged; `spawn_run` default stays `executor="local"` and every local call behaves as before |

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.

🟡 Phase 1 depends on "nothing in this RFC", but section 1 says to decide 2 first.

Section 1 (line 29) says a routing rule is only safe once it is known whose memory the routed work uses. Phase 1 is #12821, which adds remote spawns that use the crew's memory. So merging Phase 1 puts Decision 2 A into effect for spawns before a maintainer rules on Decision 2. Decision 2 A is the status quo for sessions, so this can be correct. But the two sentences read as a contradiction.

| 1 | [#12821](...) as it stands: ... | Nothing in this RFC. It implements Decision 1 A, Decision 2 A and Decision 3 A as written |

Why it matters: a maintainer who reads section 1 can hold #12821 for a Decision 2 ruling. A maintainer who reads section 6 does not. The document should give one answer.

Suggestion: say it in one place. For example: "Phase 1 extends Decision 2 A, the status quo for sessions, to remote spawns. Accepting #12821 accepts Decision 2 A for spawns." If you intend Phase 1 to wait for Decision 2, change the Depends on cell to "Decision 2 accepted". If the intent is already the first reading, I will withdraw this point.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

The first reading is the intent: Phase 1 should not wait for a Decision 2 ruling. Fixed in 927d68ba09 so both places give that answer. Section 1 now says Decision 2 gates the routing and fallback rules (1 B, 3 B), and that explicit placement (1 A) extends Decision 2 A, the status quo for crew sessions, to remote spawns, so accepting #12821 accepts Decision 2 A for spawns. The Phase 1 "Depends on" cell says the same instead of "Nothing in this RFC".

koenvincent added a commit to koenvincent/KiroCrew that referenced this pull request Oct 17, 2026
… vs Decision 2

Review on kirodotdev#21613: the kirodotdev#12821 row no longer records review state, which
belongs on the PR; section 1 and the Phase 1 row now both say that
Phase 1 extends Decision 2 A to remote spawns, so accepting kirodotdev#12821
accepts Decision 2 A for spawns.
@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 17, 2026
@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 8a5134b6da919ac59f8149ed60bd657a962ab6b6 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 Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ⏭️ skipped

Revision 8a5134b6da919ac59f8149ed60bd657a962ab6b6 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 8a5134b6da919ac59f8149ed60bd657a962ab6b6 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

This is a draft RFC with documentation changes only. It removes nothing and changes no default, so nothing blocks.

Notes

[DESIGN-REVIEWED] 8a5134b

Description read

[DESCRIPTION-READ] b9e90ab75cf90e8001da00e3e1293a24da0cdc6daed849b0b6a5b8918ae931c5

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

Notes:

  • docs/request-for-change/rfc-hybrid-remote-execution.md:64 cites read_peer_slots in handlers_instances.py, but that file only imports it. The function is defined in src/kiro_crew/dashboard/handlers_instances_peer.py:717.

[OPUS-REVIEWED] 8a5134b

@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 8a5134b

@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 Oct 17, 2026

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

Thanks for the update. Head reviewed: 927d68ba09.

Both points from my previous review are fixed:

  • The #12821 row in section 2 no longer records review state. It keeps "Open" and the "Not on main" evidence, and says the review state lives on the PR.
  • Section 1 and the Phase 1 row in section 6 now give one answer. Explicit placement does not wait for a Decision 2 ruling, and accepting #12821 accepts Decision 2 A for spawns.

I also checked the claim the Design Review asks about. The #12821 head 026161ec5c takes the strictest of the admitted mode and the requested memory_mode, so the memory_mode on spawn is tighten-only, as the RFC says.

I have no new findings. The diff is still one new RFC file and the index row. The second commit changes only the three sentences above.

This RFC is for a tier T4 issue, so it needs a design sign-off from a maintainer. This review is a comment only.

The remaining red checks are not caused by this diff. One Windows backend shard timed out in a CI routing test, and two fork workflow runs wait for maintainer approval.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 19, 2026
@koenvincent
koenvincent force-pushed the docs/rfc-hybrid-remote-execution branch from 927d68b to 09645ce Compare October 19, 2026 05:48
koenvincent added a commit to koenvincent/KiroCrew that referenced this pull request Oct 19, 2026
… vs Decision 2

Review on kirodotdev#21613: the kirodotdev#12821 row no longer records review state, which
belongs on the PR; section 1 and the Phase 1 row now both say that
Phase 1 extends Decision 2 A to remote spawns, so accepting kirodotdev#12821
accepts Decision 2 A for spawns.
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 19, 2026

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

Thanks for the rebase. Head reviewed: 09645cefb0.

The RFC file is unchanged from 927d68ba09. The only change in this PR's own diff is in the index: the row and the provenance note now say the row was re-verified at cea787cbd5. I checked the row against that commit. The symbols it names as present are present, the ones it names as absent have no hit, and the PRs it lists as open are still open. My earlier review still applies and I have no new findings.

This RFC is for a tier T4 issue, so it needs a design sign-off from a maintainer. This review is a comment only.

@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 19, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention labels Oct 21, 2026
@koenvincent

Copy link
Copy Markdown
Contributor Author

For open question 2 (instances registry as in #12821, or the A2A provider): I've put a concrete proposal on #12821 (#12821 (comment)). Merge the instances-registry path now. Fit A2A in later as a second provider under the same executor="remote" placement. Keep the three peer contracts internal, so a later provider is free to replace them. A ruling on either PR settles it for both; this RFC's three decisions hold either way.

@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 21, 2026
koenvincent added a commit to koenvincent/KiroCrew that referenced this pull request Oct 22, 2026
… vs Decision 2

Review on kirodotdev#21613: the kirodotdev#12821 row no longer records review state, which
belongs on the PR; section 1 and the Phase 1 row now both say that
Phase 1 extends Decision 2 A to remote spawns, so accepting kirodotdev#12821
accepts Decision 2 A for spawns.
@koenvincent
koenvincent force-pushed the docs/rfc-hybrid-remote-execution branch from fa87f06 to 05a24ff Compare October 22, 2026 11:58
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision 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 22, 2026
koenvincent added a commit to koenvincent/KiroCrew that referenced this pull request Oct 22, 2026
… vs Decision 2

Review on kirodotdev#21613: the kirodotdev#12821 row no longer records review state, which
belongs on the PR; section 1 and the Phase 1 row now both say that
Phase 1 extends Decision 2 A to remote spawns, so accepting kirodotdev#12821
accepts Decision 2 A for spawns.
@koenvincent
koenvincent force-pushed the docs/rfc-hybrid-remote-execution branch from 05a24ff to 0f109ac Compare October 22, 2026 14:47
@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 readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision readiness: action required A blocking check or review needs attention labels Oct 22, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

This RFC proposes hybrid local and remote execution and leaves three product decisions open. It changes where work runs, which machine holds data, and how failures move between environments. Those decisions require explicit maintainer agreement before implementation.

design-doc-gate: Rule D — this changes a design document, so it needs a human to agree to the design. Not approved and not rejected by this review.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at cbaee78: this needs a maintainer's design decision.

This draft RFC asks for three product rulings for #3278 (tier T4). The design-doc gate requires a maintainer to agree to the design, and an approval from me would not stand in for that ruling. A maintainer recording acceptance (or a change of direction) would clear it.

Two Design Review notes on this head also have no disposition: the RFC front matter (L5) still says audited at 2d926d9 while the index row says verified at 69e016c, and the Phase 1 "Depends on" cell (L92) says "No ruling in this RFC" and then names a Decision 2 A consequence. A short reply or a wording fix would close both.

Docs only. CI is green, and the earlier inline points were fixed in 927d68b.

— crew-pr-reviewer (r123)

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

Re-reviewed at 68d3a46, incremental from cbaee78.

This push adds one commit that changes four lines of the RFC and nothing else. What I checked:

  • The front matter last-audited and audited-at, and the body's audit sentence, now name 69e016c117, which matches the index row and is on main.
  • The Phase 1 "Depends on" cell no longer says "No ruling in this RFC" and then names a Decision 2 A consequence. It now says accepting #12821 records Decision 2 A for spawns and implements Decisions 1 A and 3 A. That matches the paragraph at the top of section 1, so the two places now read the same way.
  • I spot-checked claims at 69e016c117: the dashboard module remote_subagents.py does not exist, nothing in the Python package mentions remote_subagents, remote_spawn or spawn_enforces, CrewChatWindow.tsx still renders the composer inside <fieldset disabled={!connected}>, and #12821 and #3278 are still open.

No findings. The linked issue is tier T4, and accepting this RFC is a design decision for a maintainer, so I am leaving a comment and not an approval. Readiness was still running on this head when I looked.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 4157f5d: this needs a maintainer's design decision.

The RFC is a draft that asks for three product rulings for #3278 (tier T4), and a maintainer put the design-doc gate on it (comment). An approval from me would not stand in for that ruling. A maintainer recording acceptance (or a change of direction) in section 8 would clear it.

The two wording points from my r123 review are fixed: the front matter and the index row both name 69e016c117, and the Phase 1 row no longer contradicts itself. The RFC text is unchanged from 68d3a469; this head is a rebase. One Design Review note (record only the final audit SHA in the README sentence) has no reply; it is minor and does not block on its own. Docs only, CI green.

— crew-pr-reviewer (r124)

kirodotdev#3278

Scopes kirodotdev#3278 to the three rulings still open: how work leaves a local session, whose memory remote work uses, and what happens when the crew is unreachable. Each is a numbered decision with options and a recommendation. Lists what is already on main or open (verified at 69e016c) so none of it is redesigned, and orders delivery so that kirodotdev#12821 lands as-is in phase 1.

Part of kirodotdev#3278

@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 at head 8a5134b.

This head is a rebase of the previously reviewed head 4c94be8 onto current main. The RFC file is byte identical, and the README change carries the same added sentence and table row; the only other line delta comes from main.

Design verdict: sign. The RFC records three conservative rulings for the hybrid local and remote execution issue: remote placement is explicit (overflow routing later and opt in), remote work uses the crew's own memory explicitly, and an unreachable crew refuses with a typed error instead of silently falling back to local execution. It changes no runtime behaviour, gives follow up work one written position to build on, and adds no long term tech debt. Cross instance memory and automatic routing stay deferred, as the RFC states.

Checked at this head: no blocking findings, two files changed, docs only, readiness passed, all checks green, AI review lanes not blocking, and GitHub reports the branch mergeable.

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.

3 participants