Skip to content

feat: apply the bundled built-in dashboard when importing a Bot - #36499

Closed
chenmingwei23 wants to merge 2 commits into
mainfrom
crewmate-import-dashboard-undo-2
Closed

chenmingwei23 wants to merge 2 commits into
mainfrom
crewmate-import-dashboard-undo-2

Conversation

@chenmingwei23

Copy link
Copy Markdown
Contributor

Draft. Replaces #36469 and #36016.

Ticket: none

Problem / Motivation

Goal: Importing a Bot file that names a built-in dashboard sets that dashboard on the new Bot in the same import card, and the card's Undo takes it back.

Today the card shows a Dashboard row and lists the page under "Not brought over", so the receiver must open the new Bot's Dashboard tab and pick the same built-in page by hand. Follow-up issue: Fixes #35701.

Why it matters

A shared Bot arrives looking different from the one that was sent. The sender chose that page on purpose, and the receiver has no hint which page to pick.

Not a goal

  • Custom (user:) dashboards: still refused at import, unchanged.
  • A built-in id the receiver does not ship: still listed under "Not brought over".
  • Any change to what a bundle carries or to export.
  • Any change to what deleting a Bot removes: a plain Bot delete leaves its dashboard instance, as today.
  • A display-name formatter for the Dashboard row: the card still shows the builtin:<id> text as before.

What changed (motivation -> approach -> change)

The import plan had no dashboard step, so the row was display-only. Approach: reuse the existing owner-only, card-only step shape (as the import-files step) for both the apply and the Undo, instead of widening any agent-facing route or changing Bot deletion.

  • crewmate_bundle.py: dashboardTemplate is added to "not imported" only when the receiver's shipped catalog lacks that id.
  • change_card_catalog_plans.py: when the page is applied, the plan gets a POST /api/members/{slug}/dashboard/template step after the files step and before the crons; the Undo gets a DELETE of the same path, placed before the files, rules and Bot steps, only when the dashboard step was applied and answered the version it adopted.
  • New handlers/member_import_dashboard.py: owner-only, answers only an admitted import-card step, accepts only a shipped template. POST calls instance.adopt and returns instance_version; DELETE calls instance.remove_adopted. Registered in mcp_routes.py, listed in HOOKED_ROUTES (no memory line) and armed by the existing card hook in change_cards.py.
  • instance.remove_adopted: holds the instance lock, removes the page only while the record still names the adopted template at the adopted version, and removes the record, the staged preview and every retained version through directory descriptors pinned one O_NOFOLLOW step at a time from the data home (never by name, never rmtree). A link anywhere on the way is refused and nothing outside is touched. If adopt landed on a leftover instance of an older Bot with the same slug, that history is removed too; accepted.
  • change_cards_readers.py: the dashboard {template_id, instance_version} is part of the import card's fingerprint in _import_state, _import_after_is_written (the step response's version must equal the after-read) and resumed_undo_is_stale. A page changed after the import makes Undo refuse with 409. A card stored before this step has no dashboard key in its after-state and is not compared.
  • Where the directory walk cannot be pinned (native Windows has no O_NOFOLLOW), remove_adopted raises a dedicated refusal; the DELETE handler answers 200 {"ok": true, "kept": true} and leaves the page, as a plain Bot delete does, so the Undo never refuses as a whole.
  • A failed dashboard step is named in the partial summary ("its dashboard").
  • Pins: MCP route table rows and digest and the two boot chain-order pins (one more deferred registration per added route), and the facade manifests that forward the new helpers.
  • Docs: feature-map row and an RFC note.

Backwards compatibility

Compatible: nothing that works today stops working. The new routes and plan steps are additive, deleting a Bot does not touch its dashboard (as before), and an import card stored before this step still undoes: it has no dashboard role and no dashboard fingerprint to compare.

Removes nothing: the only removal is of the page this card adopted, and only at the version it adopted.

Tests

Commit 1 holds only the tests and is red on its own; commit 2 holds the change and the pin updates. Tests that need a pinned directory walk are skipped where the platform lacks it.

Local runs (pytest -n0): without the fix, test_crewmate_import_dashboard.py 15 failed / 3 passed and test_change_card_crewmate_import.py 1 failed; with the fix 18 passed in the first file and the second file green. test_dashboard_server_composition_contract_reach.py 17 passed (MCP route table 354 rows). The facade manifest guards pass locally (a subset of test_facade_mirror_guards.py; CI runs the full file).

New in test/test_crewmate_import_dashboard.py:

  • test_a_shipped_builtin_dashboard_gets_an_apply_step_and_leaves_not_brought_over, test_a_builtin_id_the_receiver_does_not_ship_stays_out, test_the_step_is_in_the_import_undo_roles
  • test_the_card_step_sets_the_dashboard_on_the_new_bot (also asserts instance_version), test_only_the_card_step_and_only_a_shipped_template_are_accepted
  • test_the_route_is_hooked_and_writes_no_memory_line (POST and DELETE)
  • test_the_undo_route_is_card_only_and_names_a_shipped_template (403 without the card flag, 400 for an unknown template)
  • test_remove_adopted_refuses_another_template_or_version_and_removes_nothing
  • test_remove_adopted_never_follows_a_member_directory_swapped_for_a_link
  • test_undo_removes_an_untouched_dashboard_before_the_bot_delete
  • test_undo_with_an_edited_dashboard_is_refused_and_the_page_stays
  • test_a_resumed_undo_compares_the_dashboard_only_when_the_card_recorded_one, test_an_edit_saved_while_the_import_ran_is_never_the_undo_baseline
  • test_an_old_import_card_without_a_dashboard_step_still_undoes
  • test_undo_completes_and_keeps_the_page_where_the_walk_cannot_be_pinned (supports_pinned_walk patched False: the Undo completes, the Bot is deleted, the page stays)
  • test_a_plain_bot_delete_and_a_create_undo_leave_the_dashboard (a guard: it also passes without the change)

Also: test_import_shares_the_create_state_read_and_partial_line asserts the "its dashboard" partial line; test_dashboard_server_composition_contract_reach.py pins updated for the two added routes.

Manual verification

N/A - unit coverage sufficient: the route, the plan, the Undo and the removal are exercised end to end in the tests above. The card text changes in one place (a shipped page no longer appears under "Not brought over"); it is the existing row renderer, with no new component, so no screenshot is attached.

Related Issues

Fixes #35701

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.

…t card

Red tests for an import card that adopts the bundle's built-in dashboard on
the new Bot and takes that page back on Undo, only at the version it adopted:

- the plan gets a dashboard apply step and a card-only DELETE undo step ahead
  of the Bot delete; both routes are hooked and write no memory line
- Undo with a dashboard changed after the import is refused (409) and the
  page stays; an untouched one is removed before the Bot delete
- remove_adopted refuses another template or version, and never follows a
  member directory swapped for a link
- where the directory walk cannot be pinned (native Windows) the Undo still
  completes, the Bot is deleted and the page stays
- a plain Bot delete and a create Undo leave a dashboard instance alone
- a card stored before this step still undoes
An import card whose bundle names a built-in dashboard the receiver ships
now ends its plan with a card-only step that adopts that page on the new Bot,
and the card's Undo takes it back before it deletes the Bot.

- POST/DELETE /api/members/{slug}/dashboard/template (owner-only, card-only,
  shipped templates only); POST answers the adopted instance_version
- instance.remove_adopted removes the page only while the record still names
  the adopted template at the adopted version, under the instance lock,
  through directory descriptors pinned with O_NOFOLLOW (no rmtree by name)
- where the walk cannot be pinned (native Windows) it raises PinUnsupported and
  the DELETE answers 200 with kept: true, so the Undo completes and the page
  stays, as after a plain Bot delete
- the dashboard {template_id, instance_version} joins the import card's
  fingerprint (state read, after-write check, resumed-undo check); a card
  stored before this step has no such key and is not compared
- deleting a Bot on its own does not touch its dashboard
- pins: MCP route table (354 rows), two boot chain-order pins, facade
  manifests for the new helpers; feature-map row and RFC note
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — 🔴 changes requested (blocking)

GPT 6.1 found at least one blocking issue that must be resolved before merging be7564eec7f131b53361965bd3f4365976ded32a. Adjudication upheld 1 of 1 blocking finding(s); those must be resolved before merging.

This comment is updated in place on each push.

BLOCKING -- src/kiro_crew/dashboard/handlers/member_import_dashboard.py:67 -- Notify open Dashboard tabs after adopting the imported page

return web.json_response(
Trigger: Resume an import interrupted between its create and dashboard steps while the new Bot’s Dashboard is open in another window. runCardPlan calls this POST, which adopts the page without emitting dashboard_instance_changed.
Outcome: The open Dashboard continues showing its cached empty/default page after import succeeds, until the 60-second fallback poll; neither card_update nor roster invalidation refreshes its dashboard query.
Anchor: defect
Fix: Broadcast the existing dashboard_instance_changed event with the Bot’s slug after successful adoption, matching the other dashboard apply routes.

[BLOCK-MERGE] be7564e
[GPT-REVIEWED] be7564e

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

F1: The harm is LOW. If an open tab misses the event, the Dashboard shows a stale page until its next poll, and nothing is lost. I confirmed that the adopt path at member_import_dashboard.py:64-67 returns without sending dashboard_instance_changed, while the sibling apply route sends it at member_dashboard.py:1124-1126. The real fix is the same three lines (state = request.app.get("state") plus one broadcast_ws call) using a pattern that already exists, so it adds no new state or invariant and costs future readers almost nothing. The fix costs less than the harm it prevents, so a downgrade is not justified.

[ADJUDICATION] be7564eec7f131b53361965bd3f4365976ded32a total=1 uphold=1 downgrade=0
UPHOLD F1 src/kiro_crew/dashboard/handlers/member_import_dashboard.py:67 reason=harm-warrants-remedy
[GPT-ADJUDICATED] be7564eec7f131b53361965bd3f4365976ded32a

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

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 13, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision be7564eec7f131b53361965bd3f4365976ded32a touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

No design-level blocker: the dashboard step and its Undo reuse the existing owner-only, card-only import-step shape, and old cards stay readable.

Notes

  • If the slug is reused, the Undo's remove_adopted deletes the retained versions/ history of an earlier Bot's leftover dashboard as well as the version this card adopted (the description accepts this). Version files written before the adopt could be left alone.
  • A simpler option was to have the Undo leave the page in place, as a plain Bot delete does. That avoids the new pinned-walk deletion code and the Windows kept branch, but the next import that reuses the slug would land on that leftover page.

[DESIGN-REVIEWED] be7564e

Description read

[DESCRIPTION-READ] 8df8b72c5b5c4f51761e40e39098635079c537718b3afba939327e9df11203e3

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of be7564eec7f131b53361965bd3f4365976ded32a — 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. The accepted rfc-crewmate-share.md already gives an imported Bot "the builtin: template" (line 209), and every item traces to #35701 or the Undo the Goal asks for.

What this change ships

Inventory (9 items) — 9 justified

Intent: someone importing a shared Bot gets the sender's built-in dashboard without picking it again by hand, and Undo takes it back. ADDITION.

  1. Importing a Bot that names a built-in dashboard the receiver ships now sets that dashboard on the new Bot — justified
  2. A shipped built-in page no longer appears under "Not brought over" — justified
  3. The import card's Undo removes the page the import set — justified
  4. Undo refuses (409) and keeps the page if it was changed after the import — justified
  5. The import card's undo-staleness fingerprint now includes the dashboard's template and version — justified
  6. On native Windows, Undo keeps the page and still finishes the rest of the Undo — justified
  7. A partial import now names "its dashboard" when that step failed — justified
  8. Two card-only, owner-only routes: POST/DELETE /api/members/{slug}/dashboard/template — justified
  9. instance.remove_adopted, PinUnsupported and the pinned_dir parameter on _locked, each with one consumer — justified

[FIRST-PRINCIPLES-REVIEWED] be7564e

Description read

[DESCRIPTION-READ] f725dbda1b161efba81f3aae9bb88d5f34ac964a727a59634bbde9b67e25b071

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] be7564e

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable be7564eec7f131b53361965bd3f4365976ded32a 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 Nov 13, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Superseded by #36544: a new branch from current main that folds in the early review findings (broadcast on import and on Undo, history cleanup, lock test) and the AI-lane findings, in two commits. Closing this PR; the branch is kept.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 13, 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.

crewmate import applies the bundled built-in dashboard in the same change card

1 participant