Skip to content

fix(instances): name the crew that is off and lock every disable - #20895

Merged
chenmingwei23 merged 1 commit into
mainfrom
fix/18661-crew-off-switch-sync
Oct 16, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
fix/18661-crew-off-switch-sync

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A crew's off switch is described with the words on screen, a refused connect names the crew that is off, and every disable closes the crew's tunnel under the manager lock.

Four gaps left after #18451 shipped the per-crew off switch:

  • The Remote Crew page says a disabled crew's sidebar group reads Disabled. The sidebar reads Off, and the switch reads Connections: On / Connections: Off.
  • Connecting a crew reached through a disabled crew answers 409 "this crew is disabled; enable it to connect", while that crew's own switch reads On.
  • PATCH {"disabled": true} on a crew the record already shows off writes the flag outside the locked teardown. The route reads that record before it takes the manager lock, so an enable and a connect landing in between leave a live forward under an Off switch.
  • The instances spec does not mention the per-crew flag: the revive skip, the PATCH field, the 409 instance_disabled.

Why it matters

A reader looks for a label the screen does not show. A refused user is pointed at the wrong crew. A retried disable can leave a tunnel open while the switch says it is closed.

Not a goal

  • Changing the switch, the sidebar, or any on-screen string or locale entry.
  • Changing which crews count as off: the connect, revive and chain checks keep their rules.

What changed (motivation → approach → change)

Where Before After
dashboard/handlers_instances.py connect, for a crew riding a disabled crew 409 "this crew is disabled; enable it to connect" 409 "crew 'cd-1', which 'kid' rides, is disabled; enable it to connect"
dashboard/handlers_instances.py update, disabled: true on a crew already off flag written, no teardown, no lock the same reconfigure() teardown as every disable
docs/remote-crew.md (the Remote Crew page) "on/off switch", Disabled Connections: On / Connections: Off, Off
modules/instances.md (the spec) no per-crew flag record field, revive skip, PATCH field, 409 instance_disabled

A refused connect names the crew that is off. InstanceDisabledError already says which crew, by id, so the connect route answers with that text plus "enable it to connect". Both places that raise it build the text from crew ids only, never a host, user, path or token.

Every disable closes the tunnel under the lock. "Already off" is read before the lock, so it can be stale; the route no longer trusts it. On a crew that is off and idle, reconfigure() changes nothing: no tunnel opens, no record field moves, its intent and its chained crews' intent stay, and other crews keep their forwards.

The Remote Crew page and the instances spec describe what the code and the screen do.

Backwards compatibility

Compatible: the 409 keeps its status and code: instance_disabled, and only its human error text changes (no code reads that text). A repeated disable answers the same 200 body.

Removes nothing: no field, route, key or function goes away; the update route runs the locked teardown on more requests, never fewer.

Tests

In test/test_instances_disable.py, through the real SshTunnelManager and real handlers (fake tunnel factory):

  • test_connect_route_names_the_crew_that_is_off: a chained crew under a disabled parent gets 409 instance_disabled whose error names the parent's id, keeps "enable it to connect", and carries neither crew's host.
  • test_a_repeated_disable_closes_a_forward_the_record_already_calls_off: a record that says off over a live forward is closed by a repeated disable.
  • test_a_repeated_disable_of_an_idle_crew_opens_and_forgets_nothing: a repeated disable on an idle crew spawns nothing, leaves every record byte-equal (intent and its chained crew's intent kept), and an unrelated crew stays connected.

In test/test_remote_crew_doc.py, test_the_off_switch_labels_the_page_quotes_are_the_ones_on_screen reads the four labels from en.json and requires the section to quote each.

Red before, on main ae5550c070 with only the tests applied: three fail, the idle-crew guard passes (it pins behaviour main already has).

FAILED test/test_instances_disable.py::test_connect_route_names_the_crew_that_is_off
E       assert ("'cd-1'" in 'this crew is disabled; enable it to connect')
FAILED test/test_instances_disable.py::test_a_repeated_disable_closes_a_forward_the_record_already_calls_off
E           AssertionError: assert 'connected' == 'disconnected'
FAILED test/test_remote_crew_doc.py::test_the_off_switch_labels_the_page_quotes_are_the_ones_on_screen
E           AssertionError: the section no longer quotes the label 'Connections: On'
3 failed, 22 passed

Green after, with the fix: 25 passed for both files; the 21 related backend files: 1457 passed.

Determinism, for the four new tests: 20/20 runs at -n0; 10/10 at -n 2 --dist loadgroup --max-worker-restart=2 beside test_instances_unsupported_method.py and test_instances_connect_during_restart.py (-n 2, not 4, because the host was shared); both files in a shuffled order, seed=21129, 25 passed. test_flake_pattern_ratchet.py: 56 passed.

Manual verification

N/A — unit coverage sufficient: both route changes run through the real handlers and the real tunnel manager, the same harness the off-switch tests already use, and no frontend file changes.

Screenshots / video

N/A — no frontend file changes. The one user-visible change is the 409 error text, quoted before and after in the table above.

Related Issues

Fixes #18661

Pattern harvest

Rule candidate: review-prompt
Pattern: a route decides to skip a locked section from a read it made before taking the lock

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

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners October 15, 2026 16:18
@iamwhatever
iamwhatever requested a review from CrysisDeu October 15, 2026 16:18
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 15, 2026
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 6be6f4fdc6225a77e7ff80348cc2710550592454 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 6be6f4fdc6225a77e7ff80348cc2710550592454 — 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/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The disable path no longer trusts the pre-lock read, but the transport-key comparison on the same line still decides the locked teardown from that read.

Not justified as shipped

  • Item 2 — symptom-level: the PR's own harvested pattern is "a route decides to skip a locked section from a read it made before taking the lock". One counted sibling of it stays in the expression this PR rewrites: k in transport_keys and v != getattr(current, k) (src/kiro_crew/dashboard/handlers_instances.py:691). An edit that sets a field back to the value in the stale current skips reconfigure(), even after a concurrent edit and connect have moved the live forward. This is the only other instance in the route (pattern grepped: getattr(current, inside the transport_changed computation). Moving that comparison under the manager lock is a bigger change than this PR, so it is deferred, not demanded.
    Clears when: the description says this fix covers only the disabled flag and leaves the transport-key comparison on the pre-lock read, or that comparison is removed from the pre-lock path.

What this change ships

Inventory (6 items) — 5 justified

Intent: the owner of a crew that is off sees the true labels, gets a refusal that names the crew that is off, and can trust that a disable closes the tunnel. This is a FIX.

  1. A refused connect through a disabled parent now names the parent crew by id — justified
  2. A repeated disable of a crew already off now runs the locked teardown and closes a live forward — symptom-level: the transport-key sibling still reads stale current
  3. The Remote Crew page quotes the on-screen labels Connections: On/Off and Off — justified
  4. The Remote Crew page says crews reached through an off crew stay closed and are named — justified
  5. The instances spec documents the disabled field, the revive skip, the PATCH field and 409 instance_disabled — justified
  6. A doc test checks the page's labels against en.json — justified

[FIRST-PRINCIPLES-REVIEWED] 6be6f4f

Description read

[DESCRIPTION-READ] 206300913016ee5f0a116e064b09c73317eafe444039e9ecb57cf39035da1e31

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 6be6f4fdc6225a77e7ff80348cc2710550592454 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] 6be6f4f

Description read

[DESCRIPTION-READ] 09518d5b823271556c26b4511e9bc332268dc3d85969fb1034981dbbe3e1bdec

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 6be6f4f

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 6be6f4fdc6225a77e7ff80348cc2710550592454: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6be6f4f

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 6be6f4fdc6225a77e7ff80348cc2710550592454: <one-sentence reason>

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • A repeated disabled: true and chained crews' live forwards (punchline, rebutted)

Checked on this head: a repeated disable CLOSES a chained crew's live forward and keeps its intent, by design. The off switch covers every crew that rides the off one: connect() refuses a chained crew under a disabled ancestor (the ancestor check in SshTunnelManager.connect), and the first disable on main already tears chained crews down inside reconfigure() with keep_intent=True (test_editing_a_parent_tears_down_the_crews_riding_it).
Under a crew that is already off, a live chained forward can only be the stale-read leftover this PR closes. Leaving it up would keep a crew reachable through an Off switch, which remote-crew.md says cannot happen.
Probe at 29d8004 (throwaway, not committed): b and its chained c connected, record set b off, then PATCH b {"disabled": true} answers 200 with b_live=False, c_live=False, b and c was_connected still True, c's own disabled still False; reconnecting c raises crew 'b', which 'c' rides, is disabled.
A crew that is off and idle has no chained forward to touch: test_a_repeated_disable_of_an_idle_crew_opens_and_forgets_nothing pins nothing spawned and every record byte-equal.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Re-sending disabled: true to a crew with live chained crews (punchline, rebutted)

Confirmed on this head, with the opposite result to "left as they were", and that is the off switch's premise: a crew that rides an off crew stays closed. connect() refuses it (ancestor check), startup revive is refused the same way, and the first disable on main already closes chained forwards inside reconfigure() with keep_intent=True.
So under a crew already off, a live chained forward exists only as the stale-read leftover this PR is about; keeping it would leave a crew reachable while the switch reads Off.
Probe at 29d8004 (throwaway, not committed): b and chained c connected, record set b off, then PATCH b {"disabled": true} answers 200; b and c forwards closed; b and c was_connected still True; c's own disabled still False; reconnecting c raises crew 'b', which 'c' rides, is disabled.
The idle test covers the only legitimate shape (no chained forward can be up under an off crew): nothing spawned, every record byte-equal, an unrelated crew stays connected.

@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 15, 2026
A chained crew under a disabled parent was refused with "this crew is
disabled", while its own switch reads On. The connect 409 carries the
manager's own message instead, which names the crew that is off by id.

A disable PATCH on a crew the record already shows off skipped the
locked teardown. That record is read before the manager lock, so an
enable and a connect landing in between could leave a live forward
under an Off switch. Every disabled: true goes through reconfigure();
on an idle crew the teardown changes nothing.

The Remote Crew page quotes the labels on screen (Connections: On/Off,
Off), and the instances spec covers the disabled field, the revive
skip, the PATCH field and the 409 instance_disabled.

Fixes #18661
@iamwhatever
iamwhatever force-pushed the fix/18661-crew-off-switch-sync branch from 29d8004 to 6be6f4f Compare October 15, 2026 23:03
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased: the only test reds on 29d8004 were main's #20893 census failures, now fixed on main by #20902 (6d4f287 -> 99d9aa6); CI re-running.

  • Both red shards failed the same two ids, nothing else: test/test_acp_bindings.py::test_the_member_set_is_the_frozen_inventory and test_each_member_keeps_its_kind_shape_and_owner[approve_tool] (Backend Tests (3.12, 5), Backend Tests (Windows) (5)). Main failed them the same way (run 38763437454). Coverage Gate was red only because it fails closed on a red backend suite.
  • The rebase changes nothing in this PR: same patch-id, same 5 files, +121/-14. On the new base, test_acp_bindings.py plus the 21 related backend files pass (1608 passed), and mypy, flake8, isort, black, comment-history, brand, line-cap and the flake ratchet are green.

@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 15, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Agreed, and scoped: this PR moves only the disabled: true half off the pre-lock read. The transport-key half, k in transport_keys and v != getattr(current, k), is byte-for-byte main's (git show origin/main:src/kiro_crew/dashboard/handlers_instances.py, lines 688-690); this PR only reordered the or around it.
#18661 asked for the disable case alone; deciding a transport edit under the lock needs either a predicate on reconfigure() or a teardown on every built-field PATCH (a no-op save would disconnect a live tunnel). Both change transport-edit behaviour outside this PR's goal, which the lane also notes.
Tracked in #20991 (deferred-finding, owner assigned, Due 2026-10-29), with both candidate shapes, the racing test to add and the spec row to update.

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

@chenmingwei23 chenmingwei23 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: readiness: passed, all lanes green, no outstanding change requests.

@chenmingwei23
chenmingwei23 merged commit 3d862ee into main Oct 16, 2026
103 checks passed
@chenmingwei23
chenmingwei23 deleted the fix/18661-crew-off-switch-sync branch October 16, 2026 01:39
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Per-crew off switch: sync docs and refusal messages with #18451

2 participants