Skip to content

feat: add Fly.io Sprites and boxd session environments - #21257

Merged
KiroCrewCaptain merged 2 commits into
mainfrom
feat/session-environments-sprites-boxd
Oct 29, 2026
Merged

KiroCrewCaptain merged 2 commits into
mainfrom
feat/session-environments-sprites-boxd

Conversation

@kyleseaman

@kyleseaman kyleseaman commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Let a chat run its workspace on a Fly.io sprite or a boxd machine, the same way it can already run on a Coder workspace.

Session Environments run a session's files, builds, tests and shells on a Coder workspace, so only teams that already operate a Coder deployment can move work off the gateway. A developer with a Fly.io account or a boxd login has no way to give one session its own machine.

Why it matters

Sprites and boxd are hosted VMs with no deployment to run: a token or a CLI login is all the setup. Each session gets a VM that keeps its disk, sleeps when idle and bills little while it waits, so isolating heavy or risky work no longer requires a Coder server.

Not a goal

  • Coder itself, the remote-session core and credentialed git: Coder and its health card are on main (feat: add Coder remote session environments #19833, feat: add a health card to remote session environments #21259), credentialed git is feat: add credentialed git for remote sessions #21256 (this PR's base until it merges), and this PR runs on them unchanged.
  • Other providers (AWS Fargate and others): separate PRs.
  • A ready pool of pre-started VMs; it comes back only with a measured start-up delay to justify it.
  • Creating Fly.io organizations, Sprites tokens, boxd accounts or boxd snapshots for the user; profiles point at what they already have.
  • Deleting vault secrets from the Session Environments card; unused tokens are removed in Settings → Secrets.
  • A Sprites terminal on a Windows gateway (the terminal bridge needs a POSIX PTY).

What changed (motivation → approach → change)

Developer flag. Like Coder, Sprites and boxd sit behind KIROCREW_DEV_MODE: with it off, the picker offers no profile, a bound session starts on the gateway, retention builds no VM provider and no sweeper starts.

A chat picks a Sprites or boxd profile in the composer chip, and gets its own VM. Engine, memory and git credentials stay on the gateway; the existing worker, relay and git proxy run unchanged on the VM.

Part What it does
src/kiro_crew/sprites_session Sprites API client (token read from the vault per call, sent only as the Authorization header), exec shell with the worker secret on stdin, worker dial, PTY terminal bridge
src/kiro_crew/boxd_session boxd CLI wrapper on the gateway's own boxd auth login, exec shell, launch
src/kiro_crew/session_environments, src/kiro_crew/coder a new provider-neutral package, so coder/ keeps only Coder's own code: persistent_vm.py (one registry and lifecycle for both VM providers), routing.py (a profile id to its provider, and the guard that keeps a session on the provider it started on), and the VM branches of browse and retention, which Coder's launch, retention and browse call
src/kiro_crew/config, config-baseline.json, src/kiro_crew/docs, src/kiro_crew/change_card_catalog_kinds.py session_environments.sprites_profiles and session_environments.boxd_profiles (at most 20 each), their baseline and settings registry, classed code-exec
src/kiro_crew/dashboard PATCH validation, picker profiles, readiness check, workspace list, History reopen
src/kiro_crew/providers, src/kiro_crew/slack the start gate counts the new lists; the gateway reloads on their change; the sweeper runs while either VM registry exists
website/src/pages, website/src/components, website/src/api, website/src/assets provider picker with its hint line, Sprites token field, boxd machine size, Fly.io and boxd marks on the chip
website/src/i18n, website/src/test, test, docs strings in every catalog, tests; providers.md and config.md sections, feature-map row

Lifetime follows the Coder rules. A VM's name and registry row are written before the create call, so a failed create is reclaimed later. A VM answering under a recorded name with a different id is refused; one deleted outside Kiro Crew is replaced, and the model is told the workspace is empty. Archive runs under Coder's per-session lifecycle lock: a boxd machine is hibernated and given a delete-after timer, a sprite goes cold by itself, and the sweep deletes due rows after re-checking identity. A History reopen cancels that deletion, identity-checked, before the tab opens, or refuses for a retry (also when its registry write fails); nothing is created or woken. The sweeper keeps running while a Sprites or boxd registry exists, so removing every profile still deletes archived VMs. Each sprite row records its token's vault key and a one-way token fingerprint: a changed key, another account's token or another boxd login is refused, and no command, terminal or deletion goes out under it. A blank working folder means the VM's home: each start reads $HOME from the VM, refuses one that is not absolute and records it, so Files and the terminal open the same folder. Those views never create a VM.

VM rows live in their own SessionResourceRegistry, not Coder's WorkspaceBindingRegistry, whose rows are workspaces on one deployment (id, owner, organization, template); a VM row holds only the provider's VM id and home and a sprite's token key.

One profile id may not name two of the three providers: every save checks it under the config lock, the picker leaves such an id out, and a session whose recorded provider does not match its profile id is refused rather than moved. A coder-tagged session that already holds a sprite or boxd machine is refused too, so an archived VM is never left due for deletion behind a moved session. A session whose profile was removed is refused, never started on the gateway. A Sprites or boxd list write may not drop the profile the default names. One Save stores the profile, then the Sprites token (a masked field) in the vault, so a refused profile never overwrites a saved token, which never enters config. The readiness check lists one sprite per profile and runs one boxd machine list, waking nothing.

The spawn audit gains two individually justified entries: the boxd lifecycle CLI (boxd_session/cli.py::_run: fixed verbs, validated names, stdin closed, no shell) and the in-process sprites_session/terminal.py::main; no module exemption, no baseline change.

What survives a disconnect

The engine runs on the gateway, so any disconnect ends the in-flight turn: it is not re-run, and the user presses Continue. A guest worker with no authenticated gateway message for 600 s stops itself.

Sprites boxd
Turn Lost; Continue resumes it Lost; Continue resumes it
VM at gateway stop Left alone; it goes cold by itself Hibernated when stop_on_shutdown is on, else left running
Files Kept (the VM keeps its disk; the registry row survives a restart) Kept
Pending approvals Lost; the gated call never ran Lost; the gated call never ran
Reopen Same sprite after an identity check; a sprite deleted elsewhere is replaced Same machine; an archived one has its delete-after timer cleared

Backwards compatibility

Compatible: both lists are new, optional and empty by default, a stale Settings tab or change card that omits them keeps each valid saved entry, and a stored choice runs on the provider it recorded, so existing configs and sessions behave as before.

Removes nothing: every change adds a provider branch beside the Coder path; no key, route, tool or setting is renamed or withdrawn.

Tests

  • test/test_sprites_session.py, test/test_boxd_session.py, test/test_boxd_cli_discovery.py, test/test_sprites_boxd_failures.py: create, dial, exec, terminal bridge, identity refusal, replacement after outside deletion, bounded failures; a reopen whose registry write fails is refused.
  • test/test_persistent_vm_retention.py, test/test_persistent_vm_cleanup.py, test/test_persistent_vm_guest_isolation.py: archive stamping, sweep under the lifecycle lock, reopen clearing the stamp, failed-create reclaim, a removed profile's sprite deleted with its recorded token key, a registry row with an unknown field still loading. test/test_archive_schedules_retention.py: a History reopen cancels the pending deletion before publishing, and one that cannot cancel it is refused (reopen_retention_failed) and re-archived; in test_boxd_session.py a failed cancellation is reported and a same-name replacement machine is left alone.
  • Card: a refused configuration writes no credential, two profiles sharing a secret name with different typed tokens are refused, and a deep link opens the tab, row and Advanced disclosure that hold its control.
  • Blank working folder: a Sprites and a boxd start with no folder open in the VM's reported home, and boxd Files resolves the same folder (both fail with the fallback removed).
  • test/test_coder_boot_activation.py: the sweeper starts from a registry alone, sweeps and hibernates only owned VMs, stays on when a registry cannot be read, and starts once when a configuration save lands during the probe.
  • test/test_session_environments_vm_providers.py: the cross-provider id rule on every save, a row whose id moved to another provider refused at launch (a coder-tagged session holding a VM included), a stale Coder-only save keeping both lists, a list write that would drop the default's profile refused, one provider table for launch and retention, and every Sprites and boxd path unreachable with KIROCREW_DEV_MODE off (fails with either new guard removed). test/test_session_environments_start_gate.py: removing the last Sprites or boxd profile never starts that session locally. Plus provider cases in test_coder_retention and the two test_spawn_audit entries.
  • Frontend: SessionEnvironmentsCard (provider tabs and hint line, the Sprites shutdown line, the boxd line and its accessible description, token field saved with the profile in one Save and its secret name under Advanced, machine size, check rows, shared "In use by a chat" row), SessionEnvironmentChip (provider marks), settings coverage.
  • test/test_session_environments_import_boundary.py: sprites_session and boxd_session import none of the shared pieces from coder/, and none of them is defined in coder/ again.
  • Ran locally on this change replayed onto main with feat: add credentialed git for remote sessions #21256 squashed in: every Fast Gate step; Backend Lint (black, flake8, isort, mypy and the line-cap and encoding ratchets); tsc, the full eslint src/, i18n:check; vitest for the touched frontend files; Semgrep with main as the baseline. On this head: the scoped backend run (6,468 passed; the 2 failures, in files this PR does not touch, come from the local Python 3.13 and not from this change).
  • Not exercised by the agent: native Windows and macOS, guest Python 3.9, and live Sprites or boxd infrastructure; the automated tests use fakes.

Manual verification

  • The maintainer has run live Sprites and boxd sessions by hand.
  • Settings card and composer chip rendered from real components with every API call answered from fixtures (below).

Screenshots / video

Real components in a Storybook harness, every API call answered from fixtures (no gateway, no VM).

Sprites tab: the one shutdown switch, shown the same on every tab with a line per provider under it (boxd hibernated, sprites never stopped), the provider hint line, a saved profile with its "Sprites API token" field, a token already saved, and its secret name under a closed "Advanced: secret name", the readiness check, and both session sprites listed as "In use by a chat" (one archived, with its deletion time):

Session Environments card, Fly.io Sprites tab, dark

First-time setup: a new Sprites profile before it is saved, with no token yet; the one Save stores the profile and a pasted token together:

Session Environments card, new unsaved Sprites profile with no token, dark

Every Sprites setup step, and the secret-name field opened under "Advanced: secret name" with its line saying it is the name the token is stored under in Settings → Secrets:

Session Environments card, Sprites setup steps and the secret name field open, dark

Every boxd setup step:

Session Environments card, boxd setup steps open, dark

The Coder tab under the provider picker, with nothing saved for Coder:

Session Environments card, Coder tab under the provider picker, dark

Sprites tab with a token the check rejects: the failure shows inline on that profile's row:

Session Environments card, Sprites token check failed, dark

Save with a token the server refuses (the fix on this card comes first: another name under "Advanced: secret name"; then the server's own reason; the "token is saved" line is withdrawn, the typed token stays, and no configuration is written), and the saved-token list cannot be read (with Retry):

Session Environments card, Sprites token save failed, dark

Session Environments card, saved token names could not be read, dark

boxd tab: the same shutdown switch and lines, machine size on a profile without a snapshot, the readiness check, and the same "In use by a chat" rows:

Session Environments card, boxd tab, dark

A boxd profile with a snapshot: the machine size is disabled, since a snapshot keeps its own size:

Session Environments card, boxd profile with a snapshot, dark

Composer chip with a sprite chosen: each provider's mark, and the check on the selected row:

Composer environment chip with Coder, Fly.io and boxd profiles

Light theme

Session Environments card, Fly.io Sprites tab, light

Session Environments card, boxd tab, light

Related Issues

Part of #10433

no linked issue: this provider PR closes nothing; #10433 stays open until the remaining Session Environments providers land.

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

@kyleseaman
kyleseaman requested review from a team and KiroCrewCaptain as code owners October 16, 2026 14:38
@kyleseaman
kyleseaman requested review from chenmingwei23 and removed request for a team October 16, 2026 14:38
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 16, 2026
@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: both providers sit behind KIROCREW_DEV_MODE and are added beside the Coder path. Nothing is removed, and the screenshots cover the reshaped picker and settings card.

Notes

  • The description is cut off inside ## Tests. Its ## Backwards compatibility section ends before the cut, and I checked it against the patch: the only removed definitions are rewritten in place (SessionEnvironmentChoices.set gains a provider argument that defaults to the old value), so no reader outside the patch breaks.
  • session_environments/ is now the provider-neutral home for VM lifecycle. When the next provider lands (Fargate and others), put it there and leave coder/ as Coder-only.

[DESIGN-REVIEWED] 5985659

Description read

[DESCRIPTION-READ] 6e0c7b295570593d5243f5330868787ac7fc90cac414f1e13a403a15c71639f0

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 598565932591b0882f5c0913aa9756dac923ddd1 — 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: both providers are new options next to Coder and stay hidden behind KIROCREW_DEV_MODE. No default changes, and no existing capability is removed or moved.

What this change ships

Inventory (10 items) — 10 justified

Intent: let a chat run its workspace on a Fly.io sprite or a boxd machine instead of needing a Coder deployment. This is an ADDITION.

  1. The composer chip can now pick a Sprites or boxd profile, and the session gets its own VM — justified
  2. Settings → Session Environments has a provider picker, a Sprites token field (saved in the vault) and a boxd machine size — justified
  3. New config keys session_environments.sprites_profiles and boxd_profiles, empty by default, with their baseline and registry entries — justified
  4. VM registry rows are written before the create call, archived VMs are swept after the retention period, and the sweep keeps running while a VM registry still exists — justified
  5. Reopening a session from History cancels its VM's pending deletion after an identity check, or refuses so the user can retry — justified
  6. The dashboard terminal and Files view can open a sprite's shell and its home folder — justified
  7. A session is refused if its profile id names a different provider, its token changed, or its boxd login changed — justified
  8. A readiness check lists the sprites and boxd machines without waking any — justified
  9. Code shared by the VM providers moves out of coder/ into a new session_environments/ package, and Coder's code calls into it — justified
  10. Two new entries in the spawn audit, plus the Fly.io and boxd marks and catalog strings — justified

[FIRST-PRINCIPLES-REVIEWED] 5985659

Description read

[DESCRIPTION-READ] afa5b550262d784e29b97ab6b37ac8fc9bde27473080402405aa444f932aee5b

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

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing blocks. The blind reader read every primary control correctly and said they would use it: the provider cards, "+ Add Sprites profile", the token field, "Check Sprites connection" and the "Run this chat on" menu. All changed states are shown in screenshots.

Notes

  • Token-list error (shot-08): when the check fails, the field falls back to "Paste a Sprites API token". The reader asked whether their key was gone. Use a neutral placeholder such as "Token status unknown" until Retry succeeds.
  • stopOnShutdownSprites (shot-01): the note says sprites are not stopped, but it sits under a switch that is on, so the reader "can't tell what the switch does on this page". Hide or disable the switch on the Sprites page, and say there that the switch only affects boxd.
  • apiTokenRename plus the OAuth conflict text (shot-07): the last sentence starts with a lowercase letter and uses "Connections OAuth app", which the reader didn't understand. Start it with a capital and name the fix in the reader's words, e.g. "This name is used by a connected app's sign-in. Pick another secret name."

[UX-REVIEWED] 5985659

Description read

[DESCRIPTION-READ] f29a780e07963cb8bb9cadabf3dd5a717791a869029bcaf6f8ba570fca43c1de

That sha256 names everything this verdict read: the PR description, plus the 16 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 16, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 5985659

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

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

@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings (all downgraded on adjudication)

GPT 6.1 flagged blocking issues on 598565932591b0882f5c0913aa9756dac923ddd1; Opus 5.5 adjudication downgraded every one of them. Downgraded: the remedy each one needs is disproportionate to the harm it prevents. Adjudication downgraded all 1 blocking finding(s): the remedy each one requires is disproportionate to the harm it prevents.

This comment is updated in place on each push.

Review details

BLOCKING -- src/kiro_crew/coder/retention.py:306 -- An unrelated VM registry failure blocks local History resumes

reason = await vm_retention.reopen_vms(persistent, key)
Trigger: With Session Environments enabled and a boxd registry containing invalid JSON, reopening an archived local chat calls keep_reopened → _reopen → reopen_vms → registry.get, even though the chat has no remote placement.
Outcome: History returns HTTP 503 with reopen_retention_failed; local archived chats cannot reopen until the unrelated registry is repaired. The same failure occurs with an unreadable Sprites registry.
Anchor: defect
Fix: Skip VM-retention checks when durable placement positively confirms the key is local, retaining fail-closed handling for remote or unreadable placement.
Sites: src/kiro_crew/session_environments/retention.py:76, src/kiro_crew/session_environments/persistent_vm.py:588, src/kiro_crew/dashboard/chat_api/resume.py:1629

[BLOCK-MERGE-DOWNGRADED] 5985659
[GPT-REVIEWED] 5985659

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

F1 is downgraded: a corrupted registry file is rare, the error is loud and names its cause, the feature only runs in dev mode, and the suggested fix would itself risk deleting remote workspaces.

F1 — MEDIUM at most (loud, recoverable, dev-mode only). The failure needs all of these:

  • Session Environments enabled, which happens only when KIROCREW_DEV_MODE is set (session_environment.py:335-343).
  • A registry file that is corrupt or unreadable. It is written only through atomic_write with fsync (persistent_vm.py:129-136), and _read raises SessionEnvironmentUnavailable when it can't read it (persistent_vm.py:106-127).
  • Every resume reaching that read, via reopen_vms → reopen_session → registry.get (retention.py:306, session_environments/retention.py:76, persistent_vm.py:588).

When it happens, the user gets a 503 whose message names the cause, "the boxd session registry is unreadable" (resume.py:1629-1637). Repairing the registry file clears it, and remote starts fail on the same broken registry anyway, so it doesn't go unnoticed.

The real fix is not cheap. Gating on the durable choice (session_runs_remotely, session_environment.py:373) adds a new rule: "choice says local" must imply "no VM row is pending deletion". If a session's placement changed while an archived VM was still waiting to be deleted, skipping the cancellation would let that workspace be deleted silently. That is worse than the loud refusal it would replace.

[ADJUDICATION] 598565932591b0882f5c0913aa9756dac923ddd1 total=1 uphold=0 downgrade=1
DOWNGRADE F1 src/kiro_crew/coder/retention.py:306 reason=disproportionate-remedy
[GPT-ADJUDICATED] 598565932591b0882f5c0913aa9756dac923ddd1

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

@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 16, 2026
@kyleseaman
kyleseaman force-pushed the feat/session-environments-git branch from 6b91cb7 to 47b1810 Compare October 19, 2026 00:03
@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
@kyleseaman
kyleseaman force-pushed the feat/session-environments-sprites-boxd branch from dfdfe7f to efcc147 Compare October 19, 2026 00:26
@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
@kyleseaman
kyleseaman force-pushed the feat/session-environments-git branch 2 times, most recently from 5da3123 to 9c027ca Compare October 19, 2026 00:35
@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 19, 2026
@kyleseaman
kyleseaman force-pushed the feat/session-environments-sprites-boxd branch from efcc147 to 7a1da56 Compare October 19, 2026 01:07
@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
@kyleseaman

Copy link
Copy Markdown
Contributor Author

UX: token-save error reads as two messages (span=2a23805ff756): kept, rebut.

The order is the one an earlier UX round asked for: the step this card can do (pick another secret name under Advanced) comes first, and the server's own reason follows as the explanation. Rewording or mapping the server's text would mean this card maintaining a copy of every refusal the secrets API can return; that text belongs to the secrets handler and is shared with Settings > Secrets. When the server gives no reason, the card shows the retry step instead, so the two never compete with each other on that path.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

UX: switch label says stop, the lines say hibernate / not stopped (span=4a8f74d08a63): kept, rebut.

The label and its first line are p1's (#19833) setting, which is about stopping Coder workspaces; ruling 1 keeps that setting as it is. The previous UX round asked for exactly this layout (one switch, same on every tab, one line per provider underneath), and those lines say what the same switch means for each provider: boxd machines hibernate (which is boxd's stop that keeps the disk) and sprites need no call. Renaming p1's switch label from this PR would change a stack-owned string under every other provider PR.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 9af0ba6. This needs a human reviewer, and it cannot be approved yet in any case.

What blocks approval:

  1. The base is feat/session-environments-git, not main. It clears once the stack below lands and this PR is retargeted to main and reviewed again.
  2. It is security-sensitive, which our rules reserve for a human reviewer. It adds a new credential (a Sprites token kept in the vault and sent as a Bearer header, client.py#L67), VM deletion and sweep paths (persistent_vm.py#L522) and two new spawn-audit entries. I found no definite defect in what I read. The token never appears in repr or error text.
  3. The provider-neutral refactor is deferred to the stack conductor (ruling), but no issue tracks it. Before merge, please open one issue for moving dispatch, the move guard, SessionResourceRegistry and persistent_vm.py out of coder/, and link it in the description.
  4. On this head, the First Principles check (confirm the live boxd and Sprites behaviour) and the two UX copy suggestions have no reply.

The two UX Watch items have replies on this head. Opus and GPT report no findings, and checks are green.

— crew-pr-reviewer (r113)

@kyleseaman

Copy link
Copy Markdown
Contributor Author

Screenshot evidence for head ea0bcfc, referenced from the PR description.

composer-chip-providers-dark.png

settings-boxd-dark.png

settings-boxd-light.png

settings-boxd-setup-open-dark.png

settings-boxd-snapshot-dark.png

settings-coder-tab-dark.png

settings-sprites-check-failed-dark.png

settings-sprites-dark.png

settings-sprites-light.png

settings-sprites-new-profile-dark.png

settings-sprites-setup-open-dark.png

settings-sprites-token-list-failed-dark.png

settings-sprites-token-save-failed-dark.png

@kyleseaman

Copy link
Copy Markdown
Contributor Author

Screenshot evidence for head 54fd530, referenced from the PR description.

composer-chip-providers-dark.png

settings-boxd-dark.png

settings-boxd-light.png

settings-boxd-setup-open-dark.png

settings-boxd-snapshot-dark.png

settings-coder-tab-dark.png

settings-sprites-check-failed-dark.png

settings-sprites-dark.png

settings-sprites-light.png

settings-sprites-new-profile-dark.png

settings-sprites-setup-open-dark.png

settings-sprites-token-list-failed-dark.png

settings-sprites-token-save-failed-dark.png

@kyleseaman

Copy link
Copy Markdown
Contributor Author

Screenshot evidence for head 9fd1c5e, referenced from the PR description.

composer-chip-providers-dark.png

settings-boxd-dark.png

settings-boxd-light.png

settings-boxd-setup-open-dark.png

settings-boxd-snapshot-dark.png

settings-coder-tab-dark.png

settings-sprites-check-failed-dark.png

settings-sprites-dark.png

settings-sprites-light.png

settings-sprites-new-profile-dark.png

settings-sprites-setup-open-dark.png

settings-sprites-token-list-failed-dark.png

settings-sprites-token-save-failed-dark.png

@kyleseaman

Copy link
Copy Markdown
Contributor Author

GPT 6.1 Review on 091928fa0d: answered in e83e323c20

  • F1 SessionEnvironmentsCard.tsx:1201, shutdown switch shown off while boxd hibernation stays on (upheld, fixed in code, no override): the switch now shows the stored stop_on_shutdown and stays usable while it is on, even with no profile left, because shutdown still stops or hibernates every registered machine. With no profile and the setting off it stays locked, since turning it on would do nothing new. providers.md says so. Test: website/src/test/SessionEnvironmentsCard.test.tsx › "shows a stored "on" shutdown switch as on, and lets it be turned off, with no profile left" (it turns the switch off with no profile and checks the save writes stop_on_shutdown: false). It fails with the fix reverted. The older case "keeps the shutdown switch off and locked until a profile exists" now stores false.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

Opus 5.5 Review on 091928fa0d: answered in e83e323c20

  • BLOCKING resume.py:1474 (upheld, fixed): a refused revive of a session that was never closed no longer goes back on retention. kept_remote is now set only when the resume reopens a closed session (defer_clear); the cancellation itself still runs. Test: test/test_archive_schedules_retention.py::test_a_refused_revive_of_an_open_session_does_not_archive_it (the hook refuses on its second pass, after keep_reopened ran). It fails with the fix reverted (assert [(\"dashboard:archived\",)] == []).
  • Note, provisioning stage on the owner key (fixed): PersistentVmEnvironments.prepare now takes progress_key, and session_launch passes the starting session, as the Coder path does. Tests: test/test_sprites_session.py::test_a_new_sprite_reports_provisioning_on_the_starting_session and ::test_a_sprites_choice_is_prepared_by_the_sprites_provider (now with a subagent case). Both fail with the fix reverted.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

GPT 6.1 Review on e83e323c20: answered in 1d785cdba6

  • F1 persistent_vm.py:310, an interrupted create keeps no account identity (security-class, upheld, fixed in code, no override): _create now reads the fingerprint of the credential a create would use (remote_credential: the Sprites token, the boxd account and org) and saves it on the reservation row before the create. remote_create(..., used=) refuses under any other credential, so the machine is always made in the account the row names. A create cut short before _bind_live therefore leaves credential_id set, and a later miss under another account is refused by _refuse_if_credential_changed instead of replacing the machine. providers.md says so.
  • Tests (each fails with its fix reverted):
    • test/test_persistent_vm_retention.py::test_a_create_cut_short_keeps_its_account_so_a_switch_never_replaces_it: the gateway is killed between create and bind, the account switches, and the next start refuses and keeps the row, with one create only.
    • test/test_persistent_vm_retention.py::test_a_create_refuses_when_the_account_changed_after_the_reservation: boxd account changes between the reservation and the create, so nothing is created.
    • test/test_sprites_session.py::test_a_sprite_is_created_only_under_the_token_its_row_recorded: a token saved after the reservation refuses the create.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

History note for 0756cae8cf: the review-fix commits e83e323c20, eae6bf2b54 and 1d785cdba6 are squashed into one commit on top of 091928fa0d, so the PR meets PR Hygiene's two-commit rule. The tree is identical to those commits plus one addition: the Semgrep test-bare-monkeypatch-undo fix in test/test_persistent_vm_retention.py, which scopes the cut-short-create patches with monkeypatch.context() instead of monkeypatch.undo(). That test still fails with the fix reverted. The previous head is kept at backup/se-sprites-boxd-1d785cdba6.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 0756cae. This needs a human reviewer, and it cannot be approved yet in any case.

  • Base. The base is feat/session-environments-git, not main. It clears once the stack below lands and this PR is retargeted and reviewed again.
  • Sensitive. It adds a new credential (a Sprites token sent as a Bearer header) and remote VM deletion and retention sweep paths. I found no definite defect: deletion checks the VM's identity and keeps the row when another account's token cannot see it.
  • Untracked follow-up. The move of dispatch, the move guard, SessionResourceRegistry and persistent_vm.py out of coder/ is still deferred with no issue. Open one and link it in the description.
  • Unanswered notes on this head. First Principles (the second deletion registry duplicates WorkspaceBindingRegistry) and the three UX copy notes have no reply.

Opus and GPT report no findings, the earlier GPT and Opus rounds are answered and fixed, and checks are green.

— crew-pr-reviewer (r124)

@kyleseaman

Copy link
Copy Markdown
Contributor Author

Restacked onto credentialed git 6e2d374cc3; head is now 8831f076a4, still two commits (the PR Hygiene cap).

New since bbc62b8f3c, folded into the review-fix commit (local fix delta dcba58788d):

  • website/src/pages/settings/SessionEnvironmentsCard.tsx: Save refuses two Sprites profiles that share one secret name but have different typed tokens, before writing any configuration or credential, and keeps both drafts. The same token typed twice is stored once.
  • sessionEnvironments.apiTokenConflict in all 12 locales, plus the regenerated pseudo-locale.
  • website/src/test/SessionEnvironmentsCard.test.tsx: a 2-case test that fails without the fix.

Everything else in the range-diff is context from the new base, the regenerated ui-index.generated.json, and a 2-line test adaptation in test/test_coder_session_launch.py, where the base's rewritten fake shell meets this PR's shell dispatch.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

Re GPT 6.1 on bbc62b8f3c, SessionEnvironmentsCard.tsx:627, "Reject conflicting token drafts for a shared vault key": upheld and fixed in code on 8831f076a4, no override.

  • Fix: before any write, mutationFn compares each typed token with the others queued for the same secret name. A different token for a name already queued throws a TokenSaveError (apiTokenConflict, which names the secret and says to give one profile its own name or type the same token in both). Nothing goes to the configuration or the vault, and both drafts stay typed. An identical token is stored once.
  • Test: refuses two profiles sharing a secret name when their typed tokens differ, and stores a matching one once in website/src/test/SessionEnvironmentsCard.test.tsx. Both cases failed on bbc62b8f3c: the different-tokens case found no refusal, and the same-token case saw two vault writes. Both pass with the fix.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

Pushed cf502f109f, still two commits. The only new change since 8831f076a4 is the local fix delta d4617b21c8, folded into the review-fix commit:

  • src/kiro_crew/dashboard/handlers/session_environments.py: an unreadable Sprites or boxd session registry now raises _WorkspacesUnreadable, so GET /api/session-environments/workspaces returns its existing 500 workspaces_unreadable instead of a 200 that leaves out that provider's machines. An unreadable Coder registry already got that response.
  • test/test_session_environment_handlers.py: test_an_unreadable_vm_registry_is_reported_not_listed_as_empty, run for both Sprites and boxd.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

Re GPT 6.1 on 8831f076a4, session_environments.py:364, "Unreadable VM registries appear as empty inventories": upheld and fixed in code on cf502f109f, no override.

  • Fix: _persistent_workspaces re-raises SessionEnvironmentUnavailable as _WorkspacesUnreadable, which the endpoint already turns into a 500 with code workspaces_unreadable, so the dashboard shows its ErrorNotice. The response carries a fixed message, and the detail goes only to the gateway log.
  • Test: test_an_unreadable_vm_registry_is_reported_not_listed_as_empty[sprites|boxd] writes an invalid registry file. It checks for a 500 with workspaces_unreadable, no workspaces key, and no host path in the error body. Both cases failed on 8831f076a4 with assert 200 == 500 and pass with the fix.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

Restacked onto credentialed git 1cb9be4a6c (now on main) as 491a961592, still two commits. The only new change since 3817ca9482 is the local fix delta f83a5bf0ce, folded into the review-fix commit:

  • src/kiro_crew/coder/persistent_vm.py: reopen_session now catches only the identity mismatch. A registry write that fails during the reopen refuses the resume.
  • src/kiro_crew/dashboard/handlers/core_config_patch.py: a sprites_profiles or boxd_profiles leaf write that drops the profile the saved default_profile names is refused with unknown_profile.
  • A test for each in test/test_boxd_session.py and test/test_session_environments_vm_providers.py, plus a doc line in providers.md and config.md.

Commit 1 differs from 3817ca9482 only in the regenerated ui-index.generated.json.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

Re GPT 6.1 on 3817ca9482, persistent_vm.py:600, "Registry read failures are mistaken for VM replacement": upheld and fixed in code on 491a961592, no override.

  • Fix: reopen_session wraps only check_identity, so only a replacement machine under the recorded name ends the reopen as "nothing to keep". _bind_live now runs outside that catch, so a failed set_resource_id or set_credential_id raises, and the History resume refuses with reopen_retention_failed instead of publishing a tab whose deadline still stands.
  • Test: test_a_reopen_whose_registry_write_fails_refuses_instead_of_publishing in test/test_boxd_session.py. A rotated credential makes the reopen write set_credential_id, which is made to fail. The test checks that the reopen reports the failure and that the machine keeps its 7-day deadline. It fails on 3817ca9482 and passes with the fix.
  • The other sites the finding names (interrupted-create recovery and either provider's set_credential_id) go through the same _bind_live call, so this change covers them.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

Re Opus 5.5 on 3817ca9482, core_config_patch.py:579, "a list leaf can remove the profile default_profile names": upheld and fixed in code on 491a961592, no override.

  • Fix: a session_environments.sprites_profiles or session_environments.boxd_profiles leaf write now runs _check_default_profile_is_saved against the section as it would be after the write, under the config lock. It refuses with unknown_profile (400) and writes nothing. That is the same check the default's own leaf already runs. Moving the default first, or keeping its profile, is accepted.
  • Test: test_a_list_leaf_write_never_drops_the_default_profile[sprites_profiles|boxd_profiles] in test/test_session_environments_vm_providers.py. Both cases fail on 3817ca9482 (the write was accepted) and pass with the fix.

@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 491a961. This cannot be approved yet, and it needs a human reviewer.

  • Base. The base is feat/session-environments-git, not main. This clears once feat: add credentialed git for remote sessions #21256 lands and this PR is retargeted to main and reviewed again.
  • Sensitive. It adds a new credential, a Sprites token sent as a Bearer header, and remote VM reopen, deletion and sweep paths. I found no definite defect in what I read.
  • Untracked follow-up. The Design note on this head, and our r113 and r124 reviews, ask to move persistent_vm.py, SessionResourceRegistry, dispatch and the move guard out of coder/. No issue tracks this yet. Open one and link it in the description.

The GPT 6.1 and Opus findings since r124 were each fixed with a test. Opus and GPT report no findings on this head, and checks are green.

AI findings judged non-blocking:

  • UX: three copy notes ("this machine", the token placeholder while the list fails, the OAuth-app line). They are wording only, behind KIROCREW_DEV_MODE.
  • CodeQL alert 1066 (clear-text logging): at this head the message is a constant string, and the token is never printed.

I read the description, the review threads and the sensitive entry points. I did not run tests.

— crew-pr-reviewer (r134)

@kyleseaman

Copy link
Copy Markdown
Contributor Author

coder/ move, 491a961592 → 8ee2572f4a. The provider-neutral pieces now live in a new src/kiro_crew/session_environments/ package, and coder/ keeps only Coder's own code. git range-diff 1cb9be4a6c..491a961592 1cb9be4a6c..8ee2572f4a:

  • Commit 1 (feat: add Sprites and boxd session environments): =, identical.
  • Commit 2 (review fixes): the only change is the move below. Nothing else changed.
From To How
coder/persistent_vm.py (incl. SessionResourceRegistry) session_environments/persistent_vm.py rename, 0 lines changed
coder/session_launch.py: _provider_ids_of, ambiguous_profile_ids, profile_provider, chosen_provider, _vm_environments, the move guard (_owned_elsewhere, _has_coder_binding, _profile_configured, _dict_profile_ids), and the VM branch of prepare_for_session session_environments/routing.py (prepare_vm_session holds the VM branch) moved verbatim; prepare_for_session calls prepare_vm_session and takes the Coder path when it returns None
coder/session_browse.py: _resolve_persistent, _command_shell_types, the Sprites and boxd terminal argv session_environments/browse.py (vm_terminal_argv holds the argv) moved verbatim; _resolve, _ask and remote_terminal_argv call them
coder/retention.py: _live_config, _section, _persistent_environments, _sweep_persistent, _last_vm_sweep_error, the boxd shutdown hibernate, and the per-provider archive and reopen loops session_environments/retention.py (hibernate_boxd_for_shutdown, archive_vms, reopen_vms) moved verbatim; Coder's _archive, _reopen, stop_for_shutdown and sweep_once call them under the same lifecycle lock

Import edits: sprites_session/launch.py, boxd_session/launch.py and dashboard/handlers/session_environments.py import from the new package, and so do eight test files, which also patch the names at their new homes. Docs: providers.md names the new package.

New test: test/test_session_environments_import_boundary.py fails if sprites_session or boxd_session imports anything from coder/ other than coder.remote_worker (the guest worker launch, Coder's on main), if a moved name is defined in coder/ again, or if the new package imports a VM provider at load time. Three of its four cases fail on 491a961592.

Checks on 8ee2572f4a: Fast Gate (29 steps) and Backend Lint (14) pass, and 6,468 scoped backend tests pass. The 2 failures are in files this PR does not touch and come from the local Python 3.13. No file Sensitive Change Review watches is touched.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

Re crew-pr-reviewer r134, untracked follow-up: the move of persistent_vm.py (with SessionResourceRegistry), dispatch and the move guard out of coder/ is done in this PR, in commit 8ee2572f4a (into src/kiro_crew/session_environments/; summary), so no issue tracks it.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

GPT 6.1 finding on 8ee2572 (run 40891520022, default_profile checked against the submitted lists): fixed in 052214d, folded into commit 2.

  • validate_session_environments (session_environments.py) now checks only the default's shape and shared ids. It no longer judges membership against the submitted lists. The change card's pre-check runs this same normalizer, so it gets the same semantics.
  • core_config_patch: a whole-section save runs _check_default_profile_is_saved on the merged section under the write lock, after _keep_omitted_session_environment_keys has carried the omitted sprites_profiles / boxd_profiles. A default that names no merged profile is still refused (400 unknown_profile, nothing written). A saved default left dangling by an omitted list is still dropped, as before.

Tests (each fails with the fix reverted):

  • test_a_save_omitting_a_vm_list_may_default_to_a_profile_it_keeps[sprites_profiles|boxd_profiles]: {coder_url:"", profiles:[], default_profile:"<provider>-id"} passes the change-card pre-check and saves (200), keeping the list.
  • test_a_whole_save_whose_default_names_no_merged_profile_is_refused[no-such-profile|list-replaced]: 400 unknown_profile, config unchanged. These also fail with only the lock check reverted.
  • test_default_session_environment.py: the validator now accepts any well-formed id.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

GPT 6.1 on a41b604: F2 (upheld, fenced; a token-only save brings back a stale readiness result) is fixed in a433763, folded into commit 2. changeToken now calls checkMutation.reset(), as change already does, so changing only a token drops the last check. New test drops a passed check when only the token changes, so a save does not bring it back (SessionEnvironmentsCard.test.tsx) checks Sprites, replaces only the token, saves it to the vault, and asserts no Check results remain. It fails with the fix reverted. F1 was downgraded by the adjudication and is unchanged.

Fly.io Sprites and boxd join Coder as session environment providers. Both
share one persistent-VM lifecycle on the Coder registry, lock and archive
generation, and the Sprites API token is saved to the vault, never to config.
- A refused revive of a session that was never closed no longer puts its
  remote workspace back on retention.
- A sprite or boxd start reports its provisioning stage on the starting
  session, not the owner whose machine it reuses.
- The shutdown switch shows its stored value and stays usable to turn off
  when no profile is left, since shutdown still acts on registered machines.
- The creating account's fingerprint is saved with a VM reservation, and
  the create refuses under any other credential, so a create cut short
  before its record was bound never orphans the machine.
- The core handlers facade manifest names _keep_vm_profiles.
- Two profiles sharing a secret name with different typed tokens are
  refused before any write.
- A reopen whose registry write fails is refused instead of publishing a
  tab whose deadline still stands.
- A Sprites or boxd list write may not drop the profile the default names.
- A whole save's default profile is judged on the merged section under the
  write lock, so a save that omits the Sprites or boxd list may default to a
  profile that list keeps; the pre-lock normalizer (and the change card's
  pre-check) checks only the default's shape.
- Changing only a Sprites token drops the last readiness check, so a save
  never shows an earlier "accepted" for a token that was not checked.
- The default-profile checks read saved profile ids through the loaders, so
  a hand-edited row with a non-string id no longer fails a write with a 500.
- The provider-neutral pieces move out of coder/ into a new
  session_environments/ package, unchanged: persistent_vm.py (with
  SessionResourceRegistry), the provider routing and move guard
  (routing.py), and the sprite and boxd branches of browse and retention.
  coder/ keeps Coder's own code, and a test keeps sprites_session and
  boxd_session from importing those pieces from coder/.
@kyleseaman

Copy link
Copy Markdown
Contributor Author

GPT 6.1 on a433763: F1 (fenced; an unhashable hand-edited profile id crashes _profile_ids with a 500) is fixed in 5985659, folded into commit 2. _profile_ids now reads each provider list through its lenient loader (load_session_environments / load_sprites_profiles / load_boxd_profiles), as check_profile_ids_unique already does. An entry the loader drops names no profile and cannot fail the write. This covers both sites: the default_profile leaf write and the Sprites/boxd list leaf write. New test test_an_unhashable_saved_id_never_fails_a_default_or_list_write covers every provider list with id: [] and id: {}. It does a default write and a list write, and each must return 200. All 6 cases fail with the fix reverted (TypeError: unhashable type).

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

Approved on behalf of the watch holder (bolichen). Design and First Principles pass on this head (or skipped / author override), UX skipped or pass, no conflict, no open change request.

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.

4 participants